RForge Documentation

Back to RForge Main Menu

How RForge works

RForge.net consists of various components that are provided for developer's convenience and can be combined in many ways. This document describes the various components and conventions that allow you to use it for your project in the most suitable way.

SVN repository

The basis for each project is a SVN repository that holds both the current project and its associated webpages. Each repository has the following standard layout:

• /trunk - project main trunk
• /branches - place to put branches
• /tags - place to put tags
• /web - place for web-content
• /files - place for custom files

So for example for a project foo you can check out the current trunk using:
svn co svn://svn.rforge.net/foo/trunk foo
Then you work on it, modify or add files and commit it. At the time of the commit RForge will check the package and create its documentation if it is told to, see details below.

Project webpages

The project webpages are fetched from the /web part of project's SVN repository. Webpages intended for viewing should be placed directly in the /web space and should have .html extension. They are embedded in the RForge look and feel. In addition, special directives of the form %XXX% are replaced dynamically, where XXX is one of the variables or commands supported by RForge (see below). Any subdirectories are directly served and can be used for static content. See customizing webpages below for further details.

R packages

RForge provides automatic checking and building of R packages and supporting documentation. There are two ways to use this facility:

• simple R packages
  If your project consists entirely of an R package without any pre-processing needs or additional files, then the repository should simply contain the package as it is to be distributed. This implies that there must be a DESCRIPTION file in the root of the project. This will cause RForge to check the package, create a snapshot and documentation on each commit automatically. The snapshot is also immediately available from the RForge R repository.
   
• package with developer files or complex project containing a package
  If you have additional files in your project repository that you don't want to include in the package or if the package is only a part of your project, you can use a shell script 'mkdist' in your project root to create a distribution tar-ball which will be subsequently used as the deployed package. This gives you absolute flexibility in how the package source tar-ball is created from your repository sources - the project trunk doesn't have to be of any specific form for this to work. See a sample script below for a very simple use or other projects such as rJava for more elaborate apporaches (e.g. running autoconf etc.). There are two requirements to keep in mind when writing the custom mkdist script:
  • the resulting tar-ball must begin with the project name, end with .tar.gz and be created in the parent directory of the package root. It is guaranteed to be run in the package directory (see below for a very simple example).
  • the scirpt should not modify any files in the repository itself! The first step should be to create a new copy in a temporary directory and work on that. Thus the simplest script could look like this:

    #!/bin/sh
    PDIR=`pwd`
    rm -rf /tmp/${PNAME}
    mkdir /tmp/${PNAME} && cp -r . /tmp/${PNAME} && \
    cd /tmp && (find ${PNAME}/ -name .svn | xargs rm -rf) && \
    tar fcz "${PDIR}/../${PNAME}_${VER}.tar.gz" ${PNAME}
    

    Here PNAME is the name of the project and VER the package version (you can also use SVNREV which is the SVN revision). Those variables are set automatically if either 1) DESCRIPTION exists and contains the Version: directive or 2) version shell script exists and returns the package version. The latter approach is used often as it allows you to keep the version number in one place, e.g. some source file.

If a project contains a NEWS file in its repository root then it is accessible (in beautified form) as "News" menu item. It is assumed to be in a form similar to R's NEWS file, but any format will do.

Customizing Webpages

RForge attempts to keep a common look and feel so users don't need to deal with different UIs. Also this simplifies the maintenance for the developers, because menus etc. are generated automatically. A project is free to use external webpages if it desires (see project administration). When using RForge's content management facilities each .html file in the web root can use following special directives:

%NAME% - name of the project
%TITLE% - project title
%VER% - package version (from DESCRIPTION or version script)
%RForge.svn.log% - last SVN log entries
%RForge.pkg.desc% - main fields from the DESCRIPTION file in tabular form
%RForge.news% - NEWS file from the package

In addition you can create a special file called map which defines the menu on the left hand side. The format for each custom entry is page.html|Menu item where page.html is the web page filename and Menu item is the text that shall appear in the menu (you can use HTML). In addition, you can use standard entries that start with a plus. The following is the contents of the default map file:

# default menu
+about
+svn
+files
+news
+check
+doc

When creating your own map file, you can combine any custom entries and default entries. In addition you can use special entries . (just a dot on a line), - (minus on a line) for space or vertical bar respectively and =|.. where .. can be any HTML code that will be inserted as-is.

Remember that only files in the web root are processed, all other files are passed as they are.

E-mail accounts

RForge offers optional e-mail accounts and aliases at RForge.net to registered developers. The RForge mail server includes virus scanner, spam filter and web-mail interface (the latter only with accounts, not aliases).

Bug reports

RForge optinally provides Bugzilla to all projects that wish to use it. Use project administration page to enable bugzilla for your project. This basically registers your account with bugzilla and creates a product with your project name. Since this Bugzilla setup is global, users reporting bugs need to register only once to report bugs to any RForge projects.

Mailing Lists

RForge optimally provides mailing lists to all projects that wish to use it. The list server is lists.rforge.net. If you want one or more lists for your project, they must start with your project name and you will be made administrator of the mailing lists.

Backup

The entire RForge (SVN, projects, repository, code ...) is backed up daily to two other servers located in the USA and Germany. Both are in locations separate from the main server. The main server and both backup servers are running on server-grade hardware with RAID. One of the backup servers can be used as a replacement for the main server in case of a hardware failure and the other one runs in a highly-protected environment for security audits.

Suggestions

If you have any suggestions on how to improve RForge, please don't hesitate to drop me a line admin@rforge.net, Simon Urbanek.