Introduction

The Stellarator-Tools suite of codes is designed as an umbrella project. The main build system is locacted in the Stellarator-Tools GitHub repository. The build system in build around cmake and requires a version greater than 3.14. This build system is designed to automatically download dependent projects when a tool is enabled. Cmake can be configured by setting various variables on the command line

-DVARIABLE=value

-DOTHER_VARIABLE="value1 value2 value3"

or by using the ccmake interactive tool. Once a variable has been set on the cmake command line, that value is cached and it is no longer necessary to reset it for subsequent Cmake commands. This build system is also designed to obtain the latest sources evertime the code is recompiled.

Obtaining the code.

The Stellarator-Tools is the main project from which all subprojects are compiled. To obtain the code use the command

git clone https://github.com/ORNL-Fusion/Stellarator-Tools.git

Configuring Build

In this section we will focus on the \fixed_with{ccmake} tool. First navigate to root directory of the repository. Then create a build directory. Typically this is created at the root directory of the repository however it can be anywhere. From inside the build directory run the ccmake command.

cd Stellarator-Tools
mkdir build
ccmake ../

Initialially there will be no options.

At the bottom of the screen, there are various command. Pressing the c key begins the configure process. Once initally configured, there will be several options. Different tools in the Stellarator-Tools suite of codes can be configured to be built by toggling the BUILD_code from off to on.

After changing settings, keep pressing the c key until the g options appears.

After hitting the g option ccmake will exit and a Makefile will be generated. The codes can then be build using make command.

Makefile

For Stellarator-Tools, Cmake generates makefiles that can be used to build various components. The resulting makefiles contain a bunch of tasks. These tasks can be displayed using the

make help

command. For debugging purposes, the full build commandline commands can be displaced using.

make VERBOSE=1

Dependencies

Dependencies on any software project fall under three types. When enableing a code dependend codes are also automatrically enabled. By default, all codes build from the master branch. To build specific branches or tags, set the BUILD_TAG_code variables. Subprojects are registered using the register_project Cmake macro.

The next type of dependecy is external libraies that provide functionality that the code uses must be found for the build system to use. The third type of dependency is determining the proper build order. Cmake automatically handles this step.

Libraries

The codes in the Stellarator-Tools suite requires a few external libraries to build. LAPACK and BLAS provide linear algebra routines. Optimized version of these libraies are typically included by an OS or compiler vendor. These packages are found automatically by Cmake using the

find_package

function. If for some reason Cmake cannot find working copies of these libraries an error message should instruct the correct variables to set. If libraries can be found in non standard paths, setting the CMAKE_PREFIX_PATH variable will allow the automated search functions to find these files.

The NetCDF library provides routines for reading and writting binary files. Unlike the LAPACK/BLAS libraries, Cmake does not come with a built in package to find the netcdf routines. Routines for automatically locating these in standard paths can be found are provided. If the path is not standard, set the CMAKE_PREFIX_PATH. Should both this methods fail the

-DNetCDF_C_INCLUDE_DIR="/path/to/the/netcdf/include"
-DNetCDF_C_LIBRARY="/path/to/the/netcdf/lib/libnetcdf.a"
-DNetCDF_Fortran_LIBRARY="/path/to/the/netcdf/lib/libnetcdff.a"

can be set manually.

The codes also may use the ScaLAPACK library. Routines for finding these are also included. If the path is not standard, set the CMAKE_PREFIX_PATH. Should both this methods fail the

-DSCALAPACK_LIBRARY="/path/to/the/scalack/lib/libscalapack.a"
-DBLACS_LIBRARY="/path/to/the/scalack/lib/libblacs.a"
-DBLACS_INIT_LIBRARY="/path/to/the/scalack/lib/libblacsinit.a"

can be set manually.

Sources

Cmake parses all the sources file to determine the proper source code level dependencies. The source is specified in the CMakeLists.txt file or source directory. When adding new files to be build, the appropiate CMakeLists.txt needs to be updated aswell. It is not necessary to rerun Cmake at this stage. Instead the build system will automatically detect the change and rerun the depenency generation.

Documentation

This documentation was generated using the Doxygen tool. If the doxygen tool is detected, and extra task is added to the make file.

make doc

More on the Doxygen generated documentation is avalable on the Doxygen Documentation page.

Testing

Using CMake a testing frame work has been implmented. Tests maybe run by

make test

or by running

ctest

Individual or ranges of tests maybe run by using the ctest -R &ltregex&gt command. As an example to run all the tests for diagnostic rotation use the command

ctest -R ^diagnostic_rotation

Note that the executables need to be generated already and tests need to be configured. Typically tests should be run using the sequence of commands

make

make test

The results from tests and log file is found in Testing/Temporary.

Running Cmake

Cmake can be invoked manually using the command line or using the setup_cmake. This script, acts like the old setup script. It detects the current build machine and runs the appropiate cmake command line. Otherwise the cmake command may be invoked directly.

Once the makefile has been generated, the cmake command never needs to be run again except to reconfigure a build variable. When a CMakeList.txt file is altered, the cmake command is rerun using cached values for the variables.

Cmake Variables

Variable Values Discription

Built In Variables

`CMAKE_Fortran_COMPILER`	Path	Path or command name for the fortran compiler.
`CMAKE_Fortran_FLAGS`	String	Flags to pass to the fortran compiler.
`CMAKE_C_COMPILER`	Path	Path or command name for the C compiler. While V3FIT and VMEC are all written in Fortran, some of the Cmake find packages use C compilers.
`CMAKE_CXX_COMPILER`	Path	Path or command name for the C++ compiler. While V3FIT and VMEC are all written in Fortran, some of the Cmake find packages use C++ compilers.
`CMAKE_BUILD_TYPE`	String Release Debug	Sets weither to generate build files for release or debug versions.
`CMAKE_PREFIX_PATH`	Path	Paths to use when searching for libraries and executables.

Defined Variables

`NETCDF_INC_PATH`	Path	Path to the NetCDF include directory.
`NETCDF_LIB_PATH`	Path	Path to the NetCDF include directory.
`EXTRA_FLAGS`	String	Extra flags to pass to the compiler for all build modes.
`EXTRA_RELEASE_FLAGS`	String	Extra flags to pass to the compiler for Release builds.
`EXTRA_DEBUG_FLAGS`	String	Extra flags to pass to the compiler for Debug builds.
`USE_PROFILER`	String On Off	Controls if code profiling is turned on or off.

Build Directory

CMake is configured to generate all build products in the build directory. The build products can be found in the _deps/code-build/xcode. Optionally the tools can be installed using the

make install

command. Install location is controlled by the CMAKE_INSTALL_PREFIX variable.

Trouble Shooting

If problems are encountered with the build system it is recommened to first try a clean build. Clean builds may be generated by running

make clean