GEOS-5 Checkout and Build Instructions
The instructions on this page are a summary of the GEOS-5 tutorial Arlindo da Silva has been presenting. For the moment, we presume that the user has an account on sourcemotel and access to the NCCS machines (e.g., discover).
How to Check Out the Code
Find a place to store and build the code
The GEOS-5 (AGCM) source code checks out at about 40 MB of space. Once compiled, the complete package is about 500 MB. Your home space on discover may not be sufficient for checking out and building the code. You should consider either requesting either a larger quota in your home space (call the tag x6-9120 and ask, telling them you are doing GEOS-5 development work) or building in your (larger) nobackup space. But consider, nobackup is not backed up. So be careful...
Setup your environment to check out code
With the above step complete, let's get ourselves ready to check out the code. We'll be using the UNIX cvs command to check out the code. The basic syntax is:
% cvs -d $CVSROOT checkout -r TAGNAME MODULENAME
Here, $CVSROOT specifies the CVS repository we'll be getting the code from, MODULENAME is the particular module (set of code) we'll be checking out, and TAGNAME is a particular version of that module. Let's fill in the blanks:
% cvs -d :ext:c-sourcemotel.gsfc.nasa.gov:/cvsroot/esma co -r GEOSdas-2_1_6 GEOSagcm
So our module is GEOSagcm and the tag is GEOSdas-2_1_6. Note that I substituted the shortcut co for checkout in the above command.
The above command is generally valid. You ought to be able to execute it and checkout some code. If you don't have your ssh keys setup on sourcemotel then you should be prompted for your sourcemotel password. The assumption here is that your username on sourcemotel is the same as on the machine you are checking the code out on. If not, modify the command like this:
% cvs -d :ext:SOURCEMOTEL_USERNAME@c-sourcemotel.gsfc.nasa.gov:/cvsroot/esma co -r GEOSdas-2_1_6 GEOSagcm
Here's a short cuts. So that you don't have to type in the -d :ext:c-sourcemotel.gsfc.nasa.gov:/cvsroot/esma business all the time, you can add the following lines to your, e.g., .cshrc file:
setenv CVSROOT ':ext:c-sourcemotel.gsfc.nasa.gov:/cvsroot/esma' setenv CVS_RSH ssh
Modify as appropriate if you need to put your username in or if you use a different shell (i.e., put the analog of these lines into your .bashrc file or whatever).
If you set that up, you should be able now to type in:
% cvs co -r GEOSdas-2_1_6 GEOSagcm
Enter your password when prompted and the code should check out.
If you want to avoid typing in your password all the time (recommended) you need to set up your ssh keys. There are some good instructions on this here. Once you have created your keys on the local machine (i.e., discover) you want to give sourcemotel the contents of the public key file (~/.ssh/id_dsa.pub). Log on to sourcemotel in your browser and click on the "My Page" tab and then on the "Account Maintenance" heading. Scroll down the page and you'll see a little block called "Shell Account Information." Inside that is a link to "Edit Keys." Click the link and then paste the contents of your id_dsa.pub file as a new line into the window. Click "Update" and you're good to go. It may take 10-15 minutes for sourcemotel to propagate the updated keys, so until that happens you may still have to type in your password.
Setup your environment to build the code
Now you've checked out the code. Your should have a directory called GEOSagcm in front of you. You're almost ready to build the code at this point.
The model has dependencies on the so-called "Baselibs." These will generally be prepared in advance for you. You just need to tell your shell where to find them. On discover, you can set your environment up to know where the Baselibs are by setting the environment variable BASEDIR as follows:
setenv BASEDIR /home/dasilva/silo/Baselibs/x86_64-unknown-linux-gnu/ifort
In fact, it's a good idea to add this line to your .cshrc file too.
Now, with that set, navigate to the source directory:
% cd GEOSagcm/src
At this point, you can build the issuing the following command:
% gmake install
If you do that, go away and take a coffee break. A long one. This may take an hour or more to build. There are a couple of ways to speed this process up. One way is to build the code without optimization:
% gmake install FOPT=-g
The code builds faster in this instance, but be warned that without optimization any generated code will run very slowly.
A better way is to do a parallel build. To do this, start an interactive queue (on discover):
% qsub -I -W group_list=g0604 -N g5Debug -l ncpus=8 -l walltime=12:00:00 -S /bin/tcsh -V -j eo
Note that the string following "group_list=" is your group-id code. It's the project that gets charged for the computer time you use. If you're not on "g0604" that's okay, the queue system will let you know and it won't start your job. To find out which group you belong to, issue the following command:
% getsponsor
and you'll get a table of sponsor codes available to you. Enter one of those codes as the group_list string and try again.
Wait, what have we done here? We've started an interactive queue (interactive in the sense that you have a command line) where we've now go 8 cpus allocated to us (and us alone!) for the next 12 hours. We can use all those 8 cpus to speed up our build as follows:
% gmake --jobs=8 pinstall
The syntax here is that "--jobs=" specifies the number of cpus to use (up to the 8 we've requested in our queue) and "pinstall" means to do a parallel install. Don't worry, the result should be the same as "gmake install" above but take a fraction of the time.
What if something goes wrong? Sometimes the build just doesn't go right. It's useful to save the output that scrolls by on the screen to a file so you can analyze it later. Modify any of the build examples above as follows to capture the text to a file called "make.log":
% gmake --jobs=8 pinstall |& tee make.log
and now you have a record of how the build progressed. When the build completes (successfully or otherwise) you can analyze the build results by issuing the following command:
% Config/gmh.pl -v make.log
and you'll be given a list of what compiled and didn't, which will hopefull allow you to go in and find any problems.
If all goes well, you should have a brand-new build of GEOS-5. Step back up out of the src directory you should see the following sub-directories:
Config CVS Linux src
In the Linux directory you'll find:
bin Config doc etc include lib
The executables are in the bin directory.
In this example, the directory GEOSagcm is the root directory everything ends up under. You can specify another location by setting the environment variable ESMADIR to some other location and installing again.