Install Chrono

Table of Contents

The Chrono source code can be obtained from the Chrono GitHub repository as zip files (for the current development branch or one of the official releases). Alternatively, you can use git to clone the Chrono repository.

Building Chrono from sources requires a C++ compiler and the CMake build system.

Recommended compilers

  • Windows: MSVC from Visual Studio 2019 or newer. (VS 2022 Community Edition free download)
    Note: the C++ compiler is not installed by default; make sure to install the C++ toolchain during VS setup.
  • Linux: GNU C++ compiler for Linux-based platforms (version 4.9 or newer)
  • Linux: LLVM Clang C and C++ compiler (version 1.6 or newer)
  • MacOS: Clang through Xcode Package. (Xcode free download)

Other compilers were also tested (e.g. Intel C++, PGI) but they are not officially supported and maintained. While it is likely possible to build Chrono with other toolchains, this might require changes to the CMake scripts.

Install CMake

CMake is required to configure the build toolchain before compiling Chrono.

CMake will configure and create the necessary solution files (Windows) or make files (Linux) necessary to compile and build Chrono from sources.

For Windows users: make sure to put the CMake executable in your Path environmental variable (the installer can do this for you).

On Linux, if not already installed, use the package manager to install cmake. Some distributions may need to install the package cmake-curses-gui along with cmake to use terminal based GUI for CMake.

For Xcode users: the CMake.app bundle also contains command line tools, you must set appropriate links to use it from the terminal. It is better to install a pure command line version via homebrew: brew install cmake in the terminal.

Install a GUI git client

While git can be used through command line we recommend using a GUI git client.

On Windows and MacOS, we suggest SourceTree, also used for illustration below.

Note that most modern IDEs have git integration (e.g. the free Visual Studio Code available on Windows, Linux, and Mac).

Prerequisites

The Chrono core module has a single dependency on the Eigen3 template library for linear algebra.

Since optional Chrono modules may bring in additional dependencies we recommend to enable only those that are required by your project, at least for the first installation; for their installation please refer to Installation Guides.

Install Eigen

Eigen is a headers-only library and as such it can be used immmediately as downloaded. However, it can also be configured and installed with cmake.

On Linux, Eigen is also available through the system package manager (e.g. sudo apt install eigen3-dev).

On the Mac, Eigen can be installed via homebrew: brew install eigen. Beginning with MacOS 12 Monterey, homebrew installs in /opt/homebrew.

We strongly recommend using the latest Eigen3 version 3.4.0.

Notes on 3rd-party Chrono dependencies

  • Never mix 64-bit and 32-bit binaries and libraries!
    For example, you must link the 64-bit Irrlicht library. Beginning with MacOS 10.15 Catalina there is no 32-bit support anymore.
  • Other Chrono module (e.g., the run-time visualization Chrono modules) have additional dependencies. If using shared libraries for these dependencies, you must ensure that these are found at run time.
    • On Windows, you can either copy the corresponding DLLs (e.g., Irrlicht.dll) to the same directory as the executables or else add the path to these shared libraries to the PATH environment variable.
    • On Linux, you may need to append to the LD_LIBRARY_PATH environment variable and/or run the ldconfig command.

Configuring Chrono with CMake

CMake can be used through a GUI interface, cmake-gui (note that on Linux, this requires installing a separate CMake package), from a Curses interface (ccmake), or else directly from the command prompt (cmake). Note that the latter requires passing all necessary CMake variables as arguments to cmake, or else write a script (example scripts are provided with the Chrono distribution, under the contrib/build-scripts/ directory).

Below, we describe in more details configuration of Chrono with cmake-gui and ccmake.

Using CMake through the GUI interface

Start cmake-gui to configure the build.

  • In the field "Where is the source code" set the path to your Chrono directory.
    This is the directory where you created your Git repository, in our example is C:/workspace/chrono.
  • In the field "Where to build the binaries" set the path to a directory different from the Chrono source location, as Chrono prohibits "in-source" builds. This build directory can be manually created beforehand; otherwise, CMake will ask to create it. For our example, let's use C:/workspace/chrono_build
  • Press the Configure button.
  • Set the appropriate generator (e.g. Visual Studio, Makefile, etc.) and the appropriate platform (Win32, x64, etc.)
  • Specify the location of the Eigen installation. If Eigen was itself configured and installed with CMake, set the CMake variable Eigen3_DIR to point to the Eigen installation directory that contains a project configuration script (e.g., C:/Packages/eigen/share/eigen3/cmake/). Otherwise, set the CMake variable EIGEN3_INCLUDE_DIR to point to the directory containing the subdirectory Eigen with header files (e.g., C:/Packages/eigen-3.4.0/.
  • Enable any additional module. Refer to their Installation Guides before proceeding any further.
  • Remember that you might need to press Configure after you change some setting, even multiple times, until all variable dependencies are resolved.
  • Finally, press Generate.
If using a multi-config generator (e.g., Visual Studio or ninja multi-config), CMake sets the variable CMAKE_CONFIGURATION_TYPES to include all available configurations (Debug, Release, MinSizeRel, RelWithDebInfo). Leave that unchanged.

If using a single-configuration generator (e.g., makefiles or ninja), set CMAKE_CONFIGURATION_TYPES to the desired build type (e.g., Release or Debug). Do not leave it blank (default) as this will result in a build with no optimization and no debug information.

CMake uses the slash / character for paths. Unix users are already used to this convention.
Windows users should take care to convert the default separator \ to /!

At this point you just created a project that will be later used to build Chrono. You can close CMake.

Using CMake through the Curses interface

  • Create a build directory different from the Chrono source directory (as Chrono prohibits "in-source" builds) and change your current directory to it.
  • Run ccmake <path-to-chrono-sources> from the build directory. A Curses-based GUI will appear in the terminal.

  • Enter c to Configure and continue. The interface will reload to a new screen with more options.

  • Specify the build type (unless using a multi-config generator, see above).
  • Specify the location of the Eigen installation (see above).

  • Enter c to Configure and continue until you reach the final screen. At which point enter g to Generate, CCMake will close on completion.

Build files are now available in the build directory (in this example, Makefile).

Building Chrono

Visual Studio

  1. Double-click the Chrono.sln file in the build directory to open the Visual Studio solution file. Alternatively, if using cmake-gui, click the Open Project button.
  2. In the VS toolbar, from the Solution Configurations drop-down menu select the desired build mode (e.g., **Release*).
  3. In the toolbar, click on Build > Build solution or Build > Build ALL_BUILD. This will build all Chrono projects (one per Chrono module), as well as demos and tests (if enabled during configuration). By default, shared libraries (DLLs) are generated for the Chrono modules, unless BUILD_SHARED was set to off during configuration. All DLLs and executables will be placed in a directory bin\Release of the build tree.
  4. Optionally, repeat step 2 and 3, chosing Debug as configuration type, to build debug binaries which include debugging symbols. All DLLs and executables will be placed in a directory bin\Debug of the build tree.

Linux/make

Depending on the generator used during CMake configuration, invoke the appropriate build command. For example:

  • make -j 10
    to build with Make using 10 parallel build threads.
  • ninja -j 10
    to build with ninja using 10 parallel build threads.
  • ninja -f build.Release.ninja -j 10
    for a Release build with ninja multi-config using 10 parallel build threads.

MacOS/clang

  • CMake generates a hierarchy of makefiles in the directory specified in "Where to build the binaries".
  • To build the Chrono libraries and demo executables, simply invoke make from the command line in that directory.
  • Optionally, type make install to install the Chrono libraries, data files, and demo executables in the directory specified during CMake configuration.
  • CMake can be configured to generate Xcode (cmake -G Xcode ....) configurations. You would normally use it with the Xcode IDE. The advantage is the possibilty to debug the code. Like in MS Visual Studio, you choose the build type from the IDE.
MacOS issues: clang++ does not come with OpenMP support out of the box. You will not be able to build libChrono_multicore successfully.
However, OpenMP support can be added using homebrew: brew install libomp. Having done so, you can then configure Chrono with OpenMP support. For this, you must define the right compiler flags: -Xpreprocessor -fopenmp for the compiler and -lomp for the linker. Please give the OpenMP options for both, the C compiler and the C++ compiler, otherwise the OpenMP configuration will fail.

Testing Chrono build

The Chrono distribution includes a large number of demos, unit tests, and benchmark test. These are included in the build if the corresponding CMake variables are set to on during CMake configuration: BUILD_DEMOS, BUILD_TESTING, and BUILD_BENCHAMRKING, respectively. By default, only generation of demo executabnles is enabled.

Each Chrono module adds its own set of demos and tests and these are built only if the corresponding Chrono module is enabled. Note that some demo programs depend on more than one Chrono module being available. For example, most MBD and FEA demos require a run-time visualization module (VSG or Irrlicht). Similarly, Chrono::Vehicle demos require a run-time visualization module with some other vehicle demos also requiring additional modules (e.g., Chrono::FSI, Chrono::Multicore, etc.).

Executables are available under a subdirectory bin/<config>/ (e.g., bin/Release/ or bin/Debug/) for a multi-config generator or directly under bin/ otherwise.

Unit tests do not use run-time visualization and are based on googletest. Running any of the Chrono unit tests will generate a standard report, indicating whether the test succeeded or failed. You can run all unit tests at once using ctest. For example, o run all unit tests for a Release build (mult-config generator), execute the following command from the top-level build directory:
ctest -C Release

Installing Chrono

Upon a successful build, Chrono can be installed (to the directory specified during CMake configuration through the CMAKE_INSTALL_PREFIX). This will copy Chrono libraries, headers, data files, and demo executable to the install directory.

In Visual Studio, the install process is done by building the "INSTALL" project of the Chrono.sln solution.

If using make or ninja, installation is performed with:

  • make install
  • ninja install