FACETS build Instructions
Back to the documentation Documentation home page.
See the dynamically updated build status or the old static Build status.
Forward to the Performance build instructions.
See build instruction modifications for particular machines below.
Reference
If you understand svn and know how to build software, just skip ahead and check your pre-requisites.
Getting started with subversion (SVN)
Some software installation instructions
Bilder
Bilder is the system used to make a complete and consistent build of all packages. It will be checked out automatically when obtaining the packages below. We introduce this now, as we will refer to files such as bilder/README, which means the README file in the bilder sub-directory.
Compilers
Your compilers must be right before you do anything else. The key thing is to have the right version number.
- gfortran-4.3 or greater. For OS X, this was obtainable from http://hpc.sourceforge.net. For obtaining or building gfortran, see below.
- C and C++ compilers (typically gcc on OS X and Linux). On OS X, gcc can be obtained with the download of XCODE, at http://developer.apple.com/tools/xcode/. gcc-4.0.1 is sufficient.
- Parallel compilers are provided at the leadership class facilities. For clusters we recommend openmpi.
The file, bilder/README-gfortran, gives more details on how to build gfortran.
The file, bilder/README-openmpi, shows how to install openmpi. We do not do this automatically, as users may wish to use an mpi that is already installed on their systems. One must take care that the set of compilers invoked by the mpi compilers are the same as those invoked regular in one's path.
Required Python version
Python must be version 2.5 at least. For OS X 10.4 (which does not have 2.5), one must build Python-2.5, as the .dmg file from python.org does not have the shared libraries required by Babel. If Bilder detects an older Python, it will attempt to build a more recent version.
Subversion
Subversion is used throughout FACETS for version control and package management. Version 1.5.0 or later is recommended. This version allows more selective check outs so that one need not download all files in a repository. This makes package management more convenient, as one downloads only what one needs.
Obtaining and building the FACETS external packages
Non developers and even most developers can skip this section, as facetspkgs will be maintained by the FACETS team at major sites.
The external packages are a set of packages needed by FACETS that are regularly released as tarballs.
The external packages are managed by the repository, facetspkgs, which can be obtained by.
svn co https://ice.txcorp.com/svnrepos/code/facetspkgs/trunk facetspkgs
This gets a the script, mkfcpkgs.sh, and the bilder subdirectory, which has utilities for controlling the builds and various README files.
Before building, you should decide whether to build the autotools packages, m4, autoconf, automake, libtool. This is typically a good idea.
The end of the README shows how to use the mkfcpkgs.sh script to build all of the dependencies. To install in one's personal area, simply do
./mkfcpkgs.sh [-a]
The argument -a causes the autotools packages to be built. All builds are done in the builds subdirectory and then installed in your $HOME/software directory. The full build can take more than an hour.
Messages from this script will tell you how to modify your environment variables, PATH, LD_LIBRARY_PATH, and PYTHONPATH, in order to make use of these packages.
If the compilation of parallel packages fails, some items to check are:
- Your PATH must point to the same compilers as those used by MPI
- Your LD_LIBRARY_PATH must point to any shared libraries needed by MPI
- MPI requires certain ports open for communication
- MPI may require changes to your .rhosts file
- MPI might need to be configured to reflect the MPI hosts and communication mechanism (rsh or ssh)
Configuring your environment
After module load or other actions specific to various machines, you should modify your environment by sourcing either facetspkgs.sh or facetspkgs.csh as appropriate. These are found in the facetspkgs installation directory, $CONTRIB_DIR as defined at the Documentation home page. Other package collections will provide other source files that you may find useful. Make sure that your compiler environment from your path or modules is consistent with your choice of CONTRIB_DIR.
Obtaining and building the FACETS development packages
The packages we are developing for the FACETS project can be obtained from the SVN repository by the command,
svn co https://ice.txcorp.com/svnrepos/code/facetsall/trunk facetsall
These are the packages that are being rapidly updated, and so they are available from svn only.
The FACETS development packages are those under the svn repo, facetsall. They are built by first going to the facetsall directory created by the Subversion checkout, above, and then doing
./mkfcall.sh
Various optional arguments can set the installation location as well as the path under which to look for the external packages.
The script tries to configure and build each of the packages under facets, if the version is newer than that previously installed or if the previous installation was built before a dependency of that package. It does many builds simultaneously, taking advantage of multiple core capabilities. If one runs into any problems, one can run the above script with the option -c to configure all the packages. One can then go into any individual package, examine config.log files for the various builds to see the configuration parameters. One can then configure with modified parameters to reflect your particular system setup.
All builds are done in the builds subdirectory and then installed in your $HOME/software directory. The full build can take more than an hour. If the package (like FACETS) has both serial and parallel builds, the serial build will be done under a subdirectory, ser, while the parallel build will be under a subdirectory, par. If the package is not parallel, it is built under the ser subdirectory. We also have a special nopetsc build for UEDGE. We find that these so-called out-of-place builds are convenient, as for a rebuild, one can remove everything under the build directory to ensure a clean build.
Example (versions will vary) of what gets installed into your $HOME/software:
[sveta@oxygen software]$ ls bhssolver fluxgrid installations.txt uedge-r1112-nopetsc bhssolver-r413-ser fluxgrid-r56-ser nubeam uedge-r1112-par facets fmcfm-0_9 nubeammpi uedge-r1112-ser facets-r2590 fmcfm-0_9-r1233-ser nubeam-r580-par wallpsi facets-r2590-uenopetsc fmcfm-par nubeam-r580-ser wallpsi-r65-ser facets-uenopetsc fmcfm-r1233-par uedge fcsetup.csh fmcfm-r1233-ser uedgempi fcsetup.sh fmcfm-ser
Rebuilding FACETS
Generally any one package can be rebuilt by simply going into the build subdirectory (e.g., serial, parallel, nopetsc) and doing:
make clean all
However, if any of the Makefile.am or configure.ac files have changed, one must go to the top or source directory and first do
config/cleanconf.sh
The pure C and C++ modules (bhssolver, wallpsi, and facets) have a dependency system built in. So as long as one is only modifying files and not adding any, one can do
make depend
which will generate a list of dependencies so that files will be recompiled only if they or some file they depend on is changed.
To rebuild all packages from the top, remove them from the file installations.txt, which is in the installation directory, and rerun mkfcall.sh.
Performance analysis builds
The performance analysis tools are now under the facetspkgs system.
Individual builds
If for some reason you want to not use the above script, you can configure individually. Easiest is to see what the above script gives as a configure line, which one can see from "head config.log" at the top of the build directory. E.g., on Franklin:
nid00163.franklin$ head builds/uedge/ser/config.log This file contains any messages produced by compilers while running configure, to aid debugging if configure makes a mistake. It was created by uedge configure 4.9.1, which was generated by GNU Autoconf 2.63. Invocation command line was $ ../configure --prefix=/project/projectdirs/facets/franklin/internal/uedge-r973-ser --with-supra-search-path=/project/projectdirs/facets/franklin/contrib:/project/projectdirs/facets/franklin/internal CC=/opt/pgi/default/linux86-64/default/bin/pgcc CXX=/opt/pgi/default/linux86-64/default/bin/pgCC FC=/opt/pgi/default/linux86-64/default/bin/pgf90 F77=/opt/pgi/default/linux86-64/default/bin/pgf90
Dealing with build failures
If you request email notification, you will receive a copy of mkfcall.log, which summarizes the full build at the end. If any builds fail, you can see how they were configured by doing head config.log in the build directory, which is a subdirectory of the source directory. Sometimes a build stops but will restart and complete by simply going into the build directory and typing make then make install.
Successful builds along with machine specific build instructions
FACETS should be portable across many UNIX flavors. The build dashboard provides machine specific build instructions along with build status for specific machines.
