INSTALL

Install via pip or conda
------------------------

First of all note that NCrystal might be available for installation via various
distribution channels such as pip ("pip install ncrystal") and conda ("conda
install -c conda-forge ncrystal"), Debian packages, FreeBSD packages, or even
shipped with your application (e.g. McStas).

The rest of this file contains instructions for performing a custom build and
installation from the source code. The official and supported way in which to
build and install files in the NCrystal source distribution is via CMake, which
will make it possible to use standalone NCrystal functionality from either the
command-line, via C++, C or Python code, or by using NCrystal in the context of
a third-party simulation framework for which the appropriate plugins are
available.



Building via CMake
------------------

The NCrystal distribution requires CMake version 3.10.0 or later. If you do not
have CMake installed, or if your platform has an older version installed, you
have to visit http://cmake.org/ and acquire a recent version. Note that on most
platforms you can simply do a "pip install cmake" to get it installed. CMake is
a very powerful cross-platform configuration and build tool and a complete
discussion of it is beyond the scope of the present instructions. Further
in-depth instructions and tutorials are available at http://cmake.org/ and
elsewhere online. The following is a quick recipe using the command-line cmake
tool (and using an in-source build for simplicity although that is not really
best practice):

1. Since you are reading this INSTALL file, it is assumed you have already
   unpacked the NCrystal source distribution somewhere. Assuming this is in a
   directory called /path/to/ncrystalsource, step into this directory with:

   $> cd /path/to/ncrystalsource

2. Now, configure with CMake (assuming you wish to install the result into a
   directory called /path/to/ncrystalinstall):

   $> cmake . -DCMAKE_INSTALL_PREFIX=/path/to/ncrystalinstall

   This will fail if your system is missing basic build tools, such as a C/C++
   capable compiler. In addition to generic CMake options, you can fine-tune
   what will be build by adding flags to the command. For instance
   -DNCRYSTAL_ENABLE_EXAMPLES=ON would cause the included examples to be built,
   or -DNCRYSTAL_ENABLE_DATA=EMBED would embed the shipped NCMAT files directly
   into the NCrystal binary library rather than installing them as actual files
   on the file system. For a full list of available high-level options, one can
   simply peek into the file cmake/modules/ncrystal_options.cmake, although
   depending on your CMake client the options might also be available there.

3. Next, perform the build and install in one step with:

   cmake --build . --target install --config Release

4. Setup runtime environment:

   Depending on where you installed NCrystal, it might be necessary to setup
   your environment (e.g. PATH, PYTHONPATH, etc. variables) in order to actually
   use the NCrystal installation. One way to do that is to first source the
   ncrystal_setup.sh file from it, however this will require you to add
   -DNCRYSTAL_ENABLE_SETUPSH=ON in step #2 above.

   $> . /path/to/ncrystalinstall/ncrystal_setup.sh

   Or alternatively use the ncrystal-config command to do the same (this is
   actually recommended since ncrystal-config should always be available,
   unlike the ncrystal_setup.sh file):

   $> $(/path/to/ncrystalinstall/bin/ncrystal-config --setup)

   This is mainly needed in order to modify environment variables like PATH,
   LD_LIBRARY_PATH, PYTHONPATH and CMAKE_PREFIX_PATH, but also sets up a
   variable NCRYSTALDIR, pointing to /path/to/ncrystalinstall. It is recommended
   to place one of the lines above in your login files (like .bashrc), so your
   environment will always be prepared for you.

   For reference, it is possible to completely undo the effects of the above
   setup by one of:

   $> $(/path/to/ncrystalinstall/bin/ncrystal-config --unsetup)
   $> . /path/to/ncrystalinstall/ncrystal_unsetup.sh

5. Test runtime environment

   You can quickly verify that your NCrystal installation is sound, by running
   the following small unit tests:

   $> nctool --test
   $> python3 -c 'import NCrystal; NCrystal.test()'

6. Use the installation.

   Refer to the README file for more information.



Building on Windows
-------------------

The NCrystal developers do not themselves have access to Windows, but thanks to
patches, debugging and feedback from Andrey Morozov (LIP-Coimbra), Matteo Busi
(PSI), Anders Kaestner (PSI), and Peter Willendrup (DTU/ESS), it has been
confirmed to work in that environment. The GitHub issue at
https://github.com/mctools/ncrystal/issues/38 contains a specific recipe
concerning Windows 10 with Visual Studio. Note that NCrystal release v2.2.0
contains many CMake-code changes, and it is unclear if the recipes still work
for windows (feedback/fixes/recipes will be appreciated!).