Wiki

Clone wiki

synergia2 / BuildInstructions

Building Synergia using CMake

Please see the build instructions for CHEF to build and install CHEF, which is a prerequisite for building Synergia2 with these instructions. Synergia2 supports the same operating systems and versions as does CHEF.

Synergia2 requires no system-level package installations except for those already required by CHEF.

Building and installing Synergia2

These instructions assume that you have already built and installed CHEF.

  1. Obtain the source code

    The Synergia2 code is in a git repository, and can be obtained by

    git clone https://bitbucket.org/fnalacceleratormodeling/synergia2.git
    cd synergia2
    git checkout devel-pre3
    

    Note that this branch is the only one currently supporting this CMake build and Python3. This procedure has has been tested and as of 2020-10 runs on the Mac and Ubuntu 16.04, 18.04, 20.04 based Linux distributions.

  2. Create the build directory

    We use an out-of-source build to prevent accidental pollution of the source code repository, and to simplify having multiple builds (e.g. debug and release) of the same source code.

    mkdir build
    cd build
    
  3. Generate makefiles

    You must tell Synergia2 where you have installed CHEF.

    In the example below, we define CHEF_INSTALL_DIR assuming that CHEF is installed under the user's home directory. PYTHONPATH must be set for the Python support to work.

    For these instructions, we choose to install Synergia in the same directory tree structure as CHEF. This will simplify executing Synergia scripts.

    export CHEF_INSTALL_DIR=$HOME/install-chef
    # To build using Python 3, replace the "python2.7" in the next line with the appropriate
    # Python version, e.g. for Python 3.6,x, replace "python2.7" with "python3.6".
    export PYTHONPATH=${CHEF_INSTALL_DIR}/lib/python2.7/site-packages${PYTHONPATH+:$PYTHONPATH}
    # LD_LIBRARY_PATH only needs to be set on Linux systems, and not on macOS.
    export LD_LIBRARY_PATH=${CHEF_INSTALL_DIR}/lib${LD_LIBRARY_PATH+:$LD_LIBRARY_PATH}
    # To build using Python 3, you must also have build CHEF with Python 3 support.
    # In addition, to build using Python 3, add -DUSE_PYTHON_3=1 to the following command line
    cmake -DCHEF_DIR=${CHEF_INSTALL_DIR}/lib/chef/cmake -DUSE_SIMPLE_TIMER=0 -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX:PATH=${CHEF_INSTALL_DIR} ..
    
  4. Build the code

    The makefiles generated by CMake support parallel builds. We find setting the level of parallelism (the argument of -j, 4 in the example below) to be equal to the number of cores on your computer generally works well.

    make -j 4
    
  5. Test the code

    The CTest system supported by CMake can support parallel tests. However, at this time, the tests of Synergia2 do not support parallel execution. It is expected that all provided tests will pass; if any test does not pass on your system, please file an issue.

    ctest
    

    Note that on macOS, the running tests may cause many pop-up dialog boxes, asking for permission for the various test programs to communicate with the system. The tests will run even if you ignore all such boxes. However, since they assume mouse focus when they appear, the result is very disruptive. We do not at this time know of a good way to get around this. A solution would be very welcome.

  6. Install the Synergia libraries and scripts.

    make install
    

To run Synergia scripts, the LD_LIBRARY_PATH and PYTHONPATH environment varaiables must be set to the point to installed locations. See Running Synergia scripts.

Updated