How to checkout, update, modify, and commit devel-version of the GenABEL suite

by Lennart Karssen, Yurii Aulchenko for the GenABEL-devel team (building upon the "How to install devel-version of GenABEL suite" by YA, William Astle and LK)

Here are instructions on how to checkout/update, modify, compile and commit the devel-version of GenABEL packages. It is assumed that you use Linux or Mac OS.

Register at R-forge and GenABEL

Go to the R-forge and register (follow the link "New Account" at upper right corner). After registering, send request to join the GenABEL project; for that, go to the GenABEL project page, and follow the link "Request to join" (bottom of the "Project members" list). Note that in general, you need to submit some patches before you can be accepted as a commit-member.

Setting up the environment and checking out the project for the first time

To get GenABEL & Co. running in devel-setting, you need to do a number of things. Plan to spend about 30 minutes on that. You will need good Inet connection and you also will need to have Subversion (svn) installed.

1) Check if Subversion is installed. For that, try 'svn help'. If you do get help, everyting must be all right. If Subversion is not there, here is the link, which may help: http://subversion.apache.org/packages.html

2) In order to be able to compile devel-version, you need to set an environmental variable R_HOME to point the location, where R is installed. We assume that you use Bash (most people do); if not, try to figure out how you can set environmental variables for your particular environment (and let us know so we can add it here :) ).

You can check where R is installed by running 'dirname $(which R)' on Bash command prompt. Assuming R is installed at '/usr/bin', add the following lines to your ~/.bashrc file (with Mac OS X, use ~/.bash_profile).

R_HOME=/usr/bin
export R_HOME

or, you can try

R_HOME=$(dirname $(which R))
export R_HOME

log out and log in again, or start a new terminal/console window.

3) It is recommended (though not 100% necessary) that you install the latest development version of R. You can obtain it from CRAN ftp; after downloading, follow included instructions.

4) Install _stable_ GenABEL et al., 'roxygen2', and 'RUnit' from CRAN; for that on R command line type

install.packages("GenABEL",dependencies=c("Depends","Suggests"))
install.packages("roxygen2")
install.packages("RUnit")

5) Change to a place, where you want the source code to go. Get to the latest code by

svn checkout svn+ssh://your-user-name@svn.r-forge.r-project.org/svnroot/genabel/

This should create directory called 'genabel' with all SVN data, the subdirectory 'pkg' will contain the packages.

6) Compile and install latest code by

cd pkg
R CMD INSTALL DatABEL
R CMD INSTALL GenABEL
... etc.

Note some packages (e.g. ProbABEL) are not R packages; to compile these use specific Makefile's, e.g.

cd ProbABEL
autoreconf -i
./configure
make

(See also the ProbABEL/doc/INSTALL file.)

Updating, making modifications, compiling, checking and committing the changes

Before you attempt to modify the code, please always update your local version with

svn update [PATH-to-local-genabel-directory]

Now you are ready to make modifications to the code. Ideally, when you fix a bug or add functionality, a (regression) RUnit test should be added (see examples of these in e.g. GenABEL/inst/unitTests).

In case you add new functionality/files, please make sure that your new procedures are registered in the NAMESPACE and are documented using Roxygen. To make automatic generation of help-files possible, you will also need to update the ''generate_documentation.R'' file.

Before you commit the changes, always make sure that the package documentation is updated (Roxygen), the package compiles and passes R checks. To make sure you generate the documentation, ''cd'' to WITHIN the package and run

R -f generate_documentation.R

To run checks, follow the instructions outlined in "Writing R Extensions" (section "Checking packages"), here is the link to the R Manuals page.

Commit the changes only if all checks pass! To make sure that you only commit the changes you really want check with

svn status

to see if indeed the only the files you want to commit are marked with a ''M''. To commit changes:

svn commit [PATH-to-local-genabel-files-you-have-modified] -m "what-is-change-about-message"

We ask you to please always summarize introduced changes after the ''-m'' flag. If you don't specify the ''-m'' flag your default editor will open (in most cases this is vi). If you accidentally forget the ''-m'' flag and are not used to vi type '':q!'' to exit.

If you need to add some (new) files, first use syntax

svn add [PATH-to-local-genabel-file-you-have-added]

... and then perform the commit.