 |
Version: SMASH-3.1
|
|
|
Version: SMASH-3.1
|
|
In the following, whenever the make command is used, you can specify the -j option followed by the number of CPU cores that should be used in parallel, e.g. -j3 to use three cores. This will speed up compilation considerably.
All UNIX-like operating systems offer package managers and it is highly encouraged to use these whenever possible. To mention a couple, you might use Homebrew on Apple machines or APT on Debian/Ubuntu distributions. The installation of required compilers, CMake, GSL and Eigen3 libraries (just to mention some) should be straightforward with a package manager.
It is very likely that a compiler among those supported is available out of the box on your operating system. However, some of the SMASH prerequisites are less likely to be already available, Pythia first of all.
SMASH is tightly coupled to Pythia and thus requires a specific version, which is currently 8.310. If the required version is not already installed or if there are issues with the available one, it is recommended to build Pythia with similar flags as used for SMASH, like in the example below.
To download and build the needed version of Pythia, use the following commands:
To tell cmake where to find Pythia while building SMASH see the Building SMASH section.
Note that although Pythia is statically linked into SMASH, access to share/Pythia8/xmldoc is required at runtime.
If you plan to build SMASH using the LLVM implementation of the standard C++ library, you should make sure that Pythia is built so as well, passing -stdlib=libc++ together with the other flags to the --cxx-common option of the configure script. Of course, you should then use Clang compiler to build Pythia and this can either be achieved via the CXX environment variable (set via export CXX=/path/to/clang++) or by setting the variable for the Pythia configuration, e.g.
wget command is not directly available on OSX. Although this can be easily installed e.g. via brew install wget, to download Pythia it is enough to use the curl command (see example below).gcc compiler is available and clang is to be used. The compiler flag -march=native is not defined and has to be dropped.The commands to build Pythia on a M1 Apple machine become:
Usually it is possible to install Eigen with a package manager (it requires admin privileges) and in this case CMake should be able to find the header files without the need of any additional option. For example, on an Apple machine you have the possibility to install Eigen via brew install eigen, while, under GNU/Linux Ubuntu, via sudo apt-get install libeigen3-dev.
If for some reason this is not a viable approach, then you can still proceed to a manual installation as described in the following.
Let's assume Eigen headers will be unpacked in ${HOME}. Download the latest stable release of Eigen from the official website and unpack it via
To tell CMake where to find Eigen header files while building SMASH, pass the path to them adding the option -DCMAKE_PREFIX_PATH=$HOME/[latest-eigen]/ to the cmake command in the SMASH setup (cf. Building SMASH section).
Rivet website is pretty complete and general information can be found there. Since the interface with SMASH has been tested with version 3.1.4, if possible, this version should be installed and used.
An installation script exists and can be downloaded e.g. via
It provides a convenient way to install Rivet and its dependencies (HepMC3 is among those, but, if you have already installed it, you can edit the script so that Rivet uses your installation).
Please note that, every time Rivet is used, some environment variables must be set in advance. The rivetenv.sh script, in the Rivet installation directory, takes care of this step, if sourced
where [...] is not a command, but a shorthand for the path of the directory in which Rivet is installed.
If Rivet (with all its dependencies) is installed and the environment variables are set, it will be automatically detected by CMake during SMASH setup.
Download and unpack the latest GSL version via e.g.
This creates a folder named gsl-[version_number], which is called ${GSL} here. To build and install the downloaded source use
When setting up SMASH, use the -DGSL_ROOT_DIR=${GSL} CMake option to let CMake find your custom GSL installation.
The bare minimum needed to build SMASH from within its repository reads:
However, CMake offers plenty of possible customizations, partly natively and partly created ad-hoc for SMASH. In the following, the relevant explanation about these can be found and users should collect the relevant information for their case and build the appropriate cmake command according to their needs.
A few GNU/Linux distributions provide pre-built Pythia binaries without pythia8-config binary. In this case, using the -DPythia_CONFIG_EXECUTABLE option as shown above is not possible and the top installation directory of Pythia containing lib has to be specified in either of the following ways:
PYTHIA8 or PYTHIA_ROOT_DIR (e.g. export PYTHIA_ROOT_DIR=/opt/pythia8310) or-DPYTHIA_ROOT_DIR option (e.g. cmake -DPYTHIA_ROOT_DIR=/opt/pythia8310 ..).If no variables are set and no options are passed, CMake searches for Pythia under the default path /usr. To check which environment variables related to PYTHIA are currently set, use e.g. printenv | grep PYTHIA.
Installing SMASH gives the advantage that it is possible to simply use the smash command from anywhere in order to run SMASH (provided that the installation bin directory is contained in the PATH system environment variable). Users planning to use SMASH as a library are encouraged to install SMASH, in order to disentangle the SMASH codebase source code from the version used as a library from other software.
The default installation done via make install installs SMASH into /usr/local. If you want to change the installation directory, use the CMAKE_INSTALL_PREFIX CMake option to specify a new location. For example, if you want to install SMASH in ~/.local, use
You might need to use sudo for a system-wide installation.
By specifying -DCMAKE_INSTALL_PREFIX=prefix,
prefix/bin will contain programs - e.g., smash,prefix/lib/smash-X.Y-suffix will contain libraries - e.g., libsmash.so,prefix/include/smash-X.Y-suffix will contain headers, andprefix/share/smash-X.Y-suffix will contain data files.The string X.Y-suffix refers to the SMASH version and the -suffix to the Git commit at which the codebase was installed. This won't appear for SMASH stable releases. Such a suffix is also used for the executable, but a symbolic link to it named smash is also created in the binary folder, so that the smash command can be used after the installation.
On Unix OS you might be used to use the DESTDIR mechanism to relocate the whole installation, but refer to the CMake documentation to be sure that this is what you want.
NOTE: CMake does not always support multi-core builds using the installation target and, on some machines, make -jN install results in a warning similar to
gmake[1]: warning: jobserver unavailable: using -j1. Add '+' to parent make rule.
which, in turn, informs you that the build for the installation will be done with one single core. It is likely that future CMake versions will fix this, but a simple work around is to first build SMASH and then install it: make -jN smash && make install.
If you do not find help in the following answers, feel free to browse closed issues or open a new one on GitHub.
If compilation fails (especially after changing a library), using a fresh build folder can sometimes fix the problem.
If running SMASH fails with "illegal instruction", it is likely due to running SMASH on a different platform than the one where it was compiled. By default, SMASH is compiled with platform-specific optimizations, implying that the binary only works on such platforms.
There are various possible ways to fix this issue:
-DCMAKE_CXX_FLAGS="-march=x86-64" -DCMAKE_C_FLAGS="-march=x86-64".-march=native from CMakeLists.txt. This is the easiest solution, however it results in a less efficient executable. Note that the same applies to any other libraries you compile with -march=native, for instance Pythia.By default, SMASH is compiled optimizing for the native architecture, i.e. that where the compilation is done. If hardware supports different optimizations on different machines, the default compilation of SMASH can indeed lead to (physically irrelevant) differences in the outcome of the same identical run. The major (and possibly only) source of discrepancy that is worth mentioning is the usage of contracted mathematical expressions, which in SMASH default compilation are allowed, if the hardware supports them. How to permit the compiler to form fused floating-point operations, such as fused multiply-add (FMA), depends on the compiler in use and you should check out which is the default value of the -ffp-contract flag in your compiler documentation. Allowing contracted expression will produce slightly more precise results, since there is usually one rounding less operation. However, exact (bit-wise) reproducibility of results is then not guaranteed and you will likely have (physically irrelevant) discrepancies across different platforms.
If this is not acceptable for your use case (as it is not for SMASH tests, where this feature is disabled), when setting up SMASH compilation, you can disable this feature, by passing the correct flag to CMake e.g. via
If compilation of SMASH in combination with a pre-compiled ROOT binary fails, please install and compile ROOT locally from source (see http://root.cern.ch) and compile SMASH again in a clean build directory.
Please note that after compilation the smash directory (including build) might have a size of some GB. By default, the unit tests are always compiled, which requires a lot of the disk space. If disk space is restricted, consider to just run make smash, which will only compile the SMASH binary. However, it is still recommended to run the unit tests at least once when compiling in a new environment to ensure that everything works as expected. To see how to run the tests, see CONTRIBUTING.
In order to use a particular compiler, e.g. Clang, you can permanently set the following environment variables
or simply set them for the cmake command only via
Alternatively, the compiler can also be specified using CMake dedicated options,
It is worth noticing that, when a GCC system-wide installation is present (e.g. under GNU/Linux Ubuntu), Clang compiler is by default locating it, in order to use its include files and its STL library implementation. If several GCC installations are found, the most recent version is selected. You can check which installation is selected by running clang++ -v. It is important to be aware of this mechanism to possibly explain unexpected (but also unlikely) failures or simply different behavior. For example, if the system default GCC compiler is not the latest among the available installations, Clang will use a different version of the STL from the GCC compiler. Furthermore, if the most recent GCC compiler installation were lacking some needed file(s), Clang would simply fail either at compilation or at linking time.
NOTE: The FPE environment only works with GCC, so e.g. you won't get back-traces from floating point traps with Clang.
In case the system default implementation of the C++ standard library is e.g. that shipped with GCC, this will still be used even when requesting CMake to use Clang as compiler. However, it is possible to request to use the LLVM implementation using the CMake CLANG_USE_LIBC++ option, e.g.
Still, when CMake performs some preliminary checks on the compiler, these are done using the default STL implementation found by Clang (i.e. that of the most recent GCC system-wide installation). If you want to go 100% LLVM or in case some default file looked for by Clang is missing, you also need to set the corresponding CMake flag via
which can also given as -DCXXFLAGS="-stdlib=libc++" argument to the cmake command.
If the installation of the LLVM implementation is not in a standard place, you either need to set and export your LD_LIBRARY_PATH environment variable to the correct value, e.g.
or pass to the cmake command the option
where, of course, the path to clang installation must be a valid path. All of this is needed to let the executable find the library ABI at run time.
NOTE: Remember to compile Pythia using LLVM implementation, too, as previously described.
The recommended way to use SMASH as a library in another software is to first install it according to the instructions above. This will build and copy all necessary SMASH files to the installation folder and, therefore, prevent unexpected surprises in your software behavior in case the SMASH source code changes (e.g. because of git operations). In your software you can then use the files in the SMASH installation directory and manually pass them to the compiler. However, we encourage you to set up your project with CMake, too. In that case, you can use the FindSMASH.cmake module shipped in the cmake folder. Refer to the examples/using_SMASH_as_library/CMakeLists.txt file for an example. There are two important aspects to mention, in order to let the CMake find_package(SMASH) command succeed:
CMAKE_MODULE_PATH CMake variable;SMASH_INSTALL_DIR environment variable must be correctly set.By default, if SMASH setup finds ROOT and/or HepMC, it will use them. However, this feature can be disabled by using the CMake options -DTRY_USE_ROOT=OFF and/or -DTRY_USE_HEPMC=OFF. For example,
will setup SMASH without ROOT and without HepMC support.
If the ROOT or HepMC installation is not found, provide a hint to CMake about the install destination with
Note that if multiple CMAKE_PREFIX_PATHs are necessary, a semicolon-separated list of directories can be specified.