STELLOPT Suite Compilation (v8.50)



stel_file_example.jpg
Typical directory structure for an installation of STELLOPT.
The STELLOPT family of codes (including VMEC) is distributed via a zip file. This zip file contains a setup script which is designed to ease installation of the family of codes on various machines. This setup script should be run the first time a new installation is compiled. Each code has it's own subdirectory and in this subdirectory one can find various files pertaining to the code (for example the VMEC code resides in the VMEC2000 subdirectory). In the code subdirectory are three additional directories (Debug, Release, and Sources) and four files (makefile, ObjectsList, xxx.zip, and makexxx, where xxx is the code name). The Debug and Release directories are the directories where the source files are compiled (with Release being the usual compilation directory and Debug being for versions with the debugging flags turned on). Each of these directories should contain a copy of an XXX.dep dependency file (where XXX is a code name), along with the object files (.o) and the compiled binary executable (library archives files .a may also be found here). The dependency file is designed to help the build system compile the various files in the correct order. The Sources directory contains either the source files which are to be compiled to subdirectories containing these files. These files are copied to the Release and Debug directories by the build system. The makefile in each code directory provides instructions for the various make commands which can be issued. These commands include 'clean' (remove all .o files), 'release' (check for modified source code and recompile and link those files), 'debug' (same as 'release' but for a debug version of the code, and 'clean_release' (remove all .o files and recompile and link all source files for that code). This makefile calls the makexxx makefile where most of the specific build commands are created. Almost all codes in this package link to the libstell.a library so the LIBSTELL directory is always checked and compiled if anything has changed in the LIBSTELL sources. The ObjectList file contains all the objects which each code must compile before linking.

For new installations users will simply unzip the zip file they received which should result in the creation of various code subdirectories and the setup script. In most cases the setup script will not need to be modified but if it is, then it will need to be re-zipped into the zip file you received. The setup script for the most parts dynamically creates the necessary make files for each code and handles ObjectList creation. It also creates a /bin/ directory where is stores symbolic links to each executable. This is usually done in the user's home directory. This directory can be changed by editing the setup script and re-zipping it into the main zip file. Upon execution of the setup script the user will receive various prompts. The first will ask the user if they'd like to compile for (R)elease or (D)ebug. The next prompt asks the user for which code they'd like to compile. The 'all' option is usually a safe choice as any missing codes from your zip file will simply be skipped. Next you will be prompted for (C)lean or (O)rdinary compilation. In general the first time you build the code, the script will do a clean build as no .o files will exist for any source code. NOTE: THE SETUP SCRIPT WILL UNZIP THE CODE ZIP FILES OVERWRITING ANY CHANGES YOU MADE TO THE SOURCE FILES WHICH HAVE NOT BEEN RE-ZIPPED INTO THE CODE ZIP FILE AND MASTER ZIP FILE. It will then ask you if you'd like a clean rebuild of the libstell library (Y)es or (N)o. Again irrelevant to the first installation as none of the libstell .o files exist. Next the script checks for various libraries not included with the codes but possibly necessary to build the various codes. You should choose Yes for them, if any error message appear at this point you should contact someone who has compiled these code on your cluster or the author of a specific code. Also at this points certain pre-processor flags may be turned on. These flags allow codes such as STELLOPTv2 to be compiled even if some secondary parts of the code were not included. The script will then proceed to compile each code in order. Once the script is done you should look at the /bin/ directory to see what symbolic links were created. These will tell you which codes successfully compiled. At the very least there should be a libstell.a and libstell_dir link. If the codes you wanted aren't there, rerun the script choosing 'all' and (C)lean along with (Y)es to rebuilding the library. Then send the screen output to whomever you received the zip file from.

Once a successful installation is made, modifying the code can being as necessary. To recompile a code simply go to a code directory and type 'make release' (or simply 'make'). This will recompile any modified source files and then re-link all the object files (.o) into the executable. It should also check if any libraries sources were updated if the dependency file is correct. Any error messages will appear on the screen in a format consistent with your machine's compiler. If you wish to add a new subroutine to a code then you must also add it to the file list in the ObjectsList file and you should add it to the XXX.dep file in the Release or Debug directory. Remember that the order in which the source files are compiled is based on the dependency file so it's crucial it be kept up to date (especially when giving modified code to others).

Specific Compilation Issues

Compiling on the PPPL Cluster
Compiling on an Apple Macintosh under OSX
Compiling at NERSC
Compiling on a Redhat/CentOS (RPM) Machine
Compiling on the RZG-MPE Cluster (Hydra, Draco)
Compiling on an Ubuntu (Debian) Machine