How to Install Chrono

📦 ACSL Chrono Simulator - Setup Guide

The acsl-chrono-simulator is a modular simulation framwork build to support Hardware-in-the-Loop (HIL), Software-in-the-Loop (SIL), and Model-in-the-Loop (MIL) simulations. It is developed and maintained by the members of ACSL (Advanced Control Systems Lab) and leverages Project Chrono as its physics engine.

Before building the simulator, the dependecies for the project must be setup. To streamline setup, a script-based installer with activity logging is provided. This document outlines a step-by-step guide to install all required packages and succsfully compile the simulator.

Important

The installer's log file is only created after the installer.sh is executed and you accept the licenses.

If you encounter any issues during the setup process with the installer.sh script, please upload the log file located at scripts/cache/ after cleaning it using the clean-installer-log.sh in the scripts/ directory. For further information see Troubleshooting.

• 📦 ACSL Chrono Simulator - Setup Guide
  • Installation Workflow
    • 0. Operating System Primer
      • WSL2 Specific setup
    • 1. Clone the repository
    • 2. Set Up the Required Packages with installer.py
    • 3. Compile acsl-chrono-simulator
  • 🛠️ Troubleshooting
    • Compilation errors?
    • Chrono build issues?
    • installer.py did not work for me. what do I do?
      • 1. Set Up the Required Packages with installer.sh
      • 2. Compile the Chrono Physics Engine
    • VSG-specific build issues (version mismatches between vsg, vsgXchange, and vsgImGui)?
    • Dependecies don't compile perfectly?

Installation Workflow

The installation is divided into four major steps and requires access to the internet:

0. Operating System Primer

Caution

This section strongly recommends using Ubuntu 24.04 LTS. The dependencies in this project have been configured for that version, and users may encounter issues on Ubuntu 26.04 LTS or newer if some required packages have been deprecated or changed.

acsl-chrono-simulator can be compiled and run on all popular operating systems: Windows via WSL2, macOS via UTM, and natively on Ubuntu.

Note

For Ubuntu, you can skip the rest of the contents in this section.

Note

For macOS, the instructions for setting up UTM with GPU passthrough are not written here for brevity, but resources are readily available online. Once set up, Ubuntu running as a virtual machine on UTM can be treated as a native install workflow, and the rest of the contents in this section can be ignored.

Note

If you are developing on Windows via WSL2, a few platform-specific quirks apply. These do not affect native Linux installs. The initial WSL2 installation and Ubuntu 24.04 LTS setup are omitted here, and the instructions below assume that WSL2 is already installed and that you are familiar with the basic setup and with using WSL2 on Windows.

Warning

macOS on UTM has some known render issues for visualizing rendered lines in Irrlicht and Vulkan. A fix is currently not known, but it will be included in the Troubleshooting section when available. All other functionalities are present.

WSL2 Specific setup

WSL2 can open and render windows for visualization, but a few configuration steps may be needed to make this reliable.

• Configure .wslconfig for memory, swap, vsyscall, and GUI applications

  WSL2 runs Linux inside a lightweight VM with its own resource limits and kernel command line, separate from Windows itself, and you might run into two potential problems:

  WSL2 defaults to allocating only about 50% of your total RAM to the Linux VM, with no swap file. Compiling the full codebase is a memory-hungry process, and sometimes the default allocation is not enough, causing the VM to OOM mid-build with cascading, confusing errors.

  Modern WSL2 kernels disable the legacy vsyscall syscall mechanism by default (vsyscall=none) for security. Some tools are old statically linked binaries that still rely on vsyscall. Without emulation enabled, they segfault instantly on launch.

  To fix this, open PowerShell (not WSL) and create or edit the file directly:

  notepad $env:UserProfile\.wslconfig

  Note that %UserProfile% is the Windows equivalent of $HOME; it expands to C:\Users\<you>. This command opens or creates C:\Users\<you>\.wslconfig in Notepad.

  Paste in:

  [wsl2]
  guiApplications=true
  memory=28GB
  processors=20
  swap=16GB
  kernelCommandLine=vsyscall=emulate

  Adjust memory and processors to leave some headroom for Windows itself; do not allocate 100% of your system RAM or cores.

  Save and close Notepad, then restart the WSL2 VM so the new config takes effect:

  wsl --shutdown

  Reopen your Ubuntu terminal and verify the kernel picked up the vsyscall setting:

  cat /proc/cmdline

  You should see vsyscall=emulate in the output.

• Install the locales package if missing and generate the locale

  sudo apt update
  sudo apt install -y locales
  sudo locale-gen en_US.UTF-8

  Set it as the system default:

  sudo update-locale LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8

  Optionally run sudo dpkg-reconfigure locales for the interactive picker if you want to double-check en_US.UTF-8 UTF-8 is selected.

  Shut down the Ubuntu machine:

  sudo shutdown -h now

  Restart WSL2 so the environment reloads cleanly. In PowerShell (not in Ubuntu), run:

  wsl --shutdown

  Reopen your Ubuntu terminal and verify:

  locale

  All fields should show en_US.UTF-8 with no "cannot open" errors.

• Fix GUI windows not showing

  Minimal rootfs images often lack:

  sudo apt install -y dbus-x11 mesa-utils libgl1-mesa-glx

  Install gedit to test:

  sudo apt install -y gedit

  Shut down WSL:

  sudo shutdown -h now

  It is important that you shut down WSL itself after this, so in PowerShell (not in Ubuntu), run:

  wsl --shutdown

  Restart WSL and try launching gedit; it should now show on screen.

  gedit

• Hardware-accelerated Vulkan (VSG) requires a newer Mesa than Ubuntu 22.04/24.04 ships by default

  Ubuntu 22.04/24.04's stock mesa-vulkan-drivers package does not include the dzn (Vulkan-over-D3D12) driver needed for WSL2 GPU acceleration. To get it:

  sudo add-apt-repository ppa:kisak/turtle
  sudo apt update
  sudo apt upgrade

  Verify with:

  vulkaninfo --summary | grep -i deviceName

  You should see your actual GPU listed, for example Microsoft Direct3D12 (NVIDIA GeForce ...), rather than only llvmpipe.

  [!CAUTION] This adds a third-party PPA and upgrades system-wide Mesa packages, which also affects your OpenGL/Irrlicht rendering path. This is not included in installer.sh automatically — it's a deliberate, manual system change. Review the PPA before adding it, and consider testing your Irrlicht-based build still works correctly afterward.

• On laptops with both an integrated and discrete GPU, Mesa's dzn driver may default to the integrated GPU. Force the discrete GPU explicitly:

  export MESA_D3D12_DEFAULT_ADAPTER_NAME=NVIDIA

  Replace NVIDIA with AMD or the appropriate vendor name for your discrete GPU. Add this to ~/.bashrc to make it persistent once confirmed working.

Note

Even with all of the above, VSG performance on WSL2 may still be slightly lower than on native Linux or native Windows, but the difference is often negligible in practice. The dzn driver still introduces some CPU-side translation overhead per Vulkan call, so the impact is present if you are trying to squeeze out the smallest possible performance gains. For most use cases this is not a major issue, but native Linux or native Windows will still offer the best peak VSG/Vulkan performance.

1. Clone the repository

This repository uses Git LFS (Large File Storage) for large binary assets such as meshes and textures, so it must be set up correctly before running the installer.

# Install Git LFS
sudo apt-get update
sudo apt-get install git-lfs

Next, fork the repository and clone your fork.

Note

We assume the user has a GitHub account and knows how to create and maintain forks.

Warning

You are strongly encouraged to fork this repository and work from your fork. This helps us maintain the main repository and makes it easier for you to contribute changes back to the project.

# Clone your fork
git clone --recurse-submodules https://github.com/<your-username>/acsl-chrono-simulator.git

After cloning, make sure the Git LFS objects are downloaded:

# Navigate to the repository
cd <path-to-acsl-chrono-simulator>/

# Pull the LFS objects
git lfs pull

Note

Replace the clone URL with your own fork or the lab’s canonical repository as appropriate. The --recurse-submodules flag is required because it pulls in the chrono, chrono-ros-messages, and other submodules that later steps depend on.

2. Set Up the Required Packages with installer.py

Caution

This python script requires root access and installs packages directly on your system. Never run scripts from the internet without reviewing them first.

By executing installer.py, you acknowledge that you do so at your own discretion and risk. The Advanced Control Systems Lab (ACSL) is not responsible for any damage, misconfiguration, or data loss resulting from the use of this script.

We strongly recommend opening scripts/installer.py in a text editor and inspecting its contents before running it.

This step installs all dependencies required for both Project Chrono and acsl-chrono-simulator. The script also sets up environment variables and system configuration. Finally, it installs ROS2, sets up the required ROS2 environment and compiles the libraries for Project Chrono.

Instructions:

# Navigate to the scripts folder in the project root directory
cd <path-to-acsl-chrono-simulator>/scripts/

# Run the installer as root
sudo python3 installer.py

Note

• This script installs common build tools (cmake, g++, python3, etc.), graphics dependencies (OpenGL, Vulkan, GLFW), and third-party libraries required by Chrono, including VulkanSceneGraph (VSG), which is built from source.
• Installation may take a while depending on your system and internet speed; the VSG dependency chain in particular can take a significant amount of time.
• After the script finishes, run it again to verify that all dependencies are installed. If anything is missing, install it manually. In some cases, the VSG installation may remove previously installed dependencies during its process. For more information, refer to the Troubleshooting section.

3. Compile acsl-chrono-simulator

After Project Chrono has been built, compile acsl-chrono-simulator.

Navigate to the build/ directory in the project root and run:

# Run ccmake: press 'c' to configure and 'g' to generate the Makefile
ccmake ..

# Build the project
make -j$(nproc)

Note

The CMakeLists.txt used for this step is located in the project root directory.

After the build completes, the executable will be located in the build/ directory at the project root and can be launched with:

./acsl_sim

🛠️ Troubleshooting

Compilation errors?

The installer.py script will display the error in its window, the corresponding error will be displayed in the terminal window. Please use the issues tab on main repository to post about it.

Chrono build issues?

Check the google group maintained by Project Chrono.

installer.py did not work for me. what do I do?

Follow the instructions below to use the legacy installer.sh bash script using whiptail. This version has some known problems and it is recommended to use installer.py as it sets up the compiliation of Project Chrono. Incase the python script does not open for you, please follow the instructions below.

1. Set Up the Required Packages with installer.sh

Caution

This script requires root access and installs packages directly on your system. Never run scripts from the internet without reviewing them first.

By executing installer.sh, you acknowledge that you do so at your own discretion and risk. The Advanced Control Systems Lab (ACSL) is not responsible for any damage, misconfiguration, or data loss resulting from the use of this script.

We strongly recommend opening scripts/installer.sh in a text editor and inspecting its contents before running it.

This step installs all dependencies required for both Project Chrono and acsl-chrono-simulator. The script also sets up environment variables and system configuration.

Instructions:

# Navigate to the scripts folder in the project root directory
cd <path-to-acsl-chrono-simulator>/scripts/

# Make the installer script executable
chmod +x ./installer.sh

# Run the installer as root
sudo ./installer.sh

Note

• This script installs common build tools (cmake, g++, python3, etc.), graphics dependencies (OpenGL, Vulkan, GLFW), and third-party libraries required by Chrono, including VulkanSceneGraph (VSG), which is built from source.
• Installation may take a while depending on your system and internet speed; the VSG dependency chain in particular can take a significant amount of time.
• After the script finishes, run it again to verify that all dependencies are installed. If anything is missing, install it manually. In some cases, the VSG installation may remove previously installed dependencies during its process. For more information, refer to the Troubleshooting section.

2. Compile the Chrono Physics Engine

Once the installer has set up the packages and compiled the ROS 2 packages for the simulator, configure and build Project Chrono.

Important

On native Ubuntu, installer.sh performs the following steps automatically and opens a new terminal window, so you do not need to run the commands below manually. On other platforms, open a new terminal window and run the following commands yourself.

# Navigate to the libraries folder
cd <path-to-acsl-chrono-simulator>/libraries/

# Source the local ROS 2 setup
source chrono-ros-messages/install/local_setup.bash

# Navigate into the build directory
cd chrono-build/

# Run CMake configuration
ccmake ../chrono/

Set these values in the ccmake configuration:

CMake Option	Value
CMAKE_BUILD_TYPE	Release
ENABLE_MODULE_CASCADE	ON
ENABLE_MODULE_IRRLICHT	ON
ENABLE_MODULE_MULTICORE	ON
ENABLE_MODULE_OPENGL	ON
ENABLE_MODULE_POSTPROCESS	ON
ENABLE_MODULE_ROS	ON
ENABLE_MODULE_VEHICLE	ON
ENABLE_MODULE_VSG	ON

Tip

Set any options that are not already populated one at a time. Press Space to toggle a setting, then c to reconfigure. Repeat c until the configuration succeeds, then press g to generate the build files. For more information, see the option list at the bottom of the ccmake window.

Once configuration is complete, compile the project:

make -j$(nproc)

Note

After a successful build, the Project Chrono example programs will be placed in libraries/chrono-build/bin/, including the VSG demos (demo_VSG_*). Running one of these demos is a good way to confirm that the VSG module built and linked correctly before continuing.

To run a demo, use:

./<name-of-demo>

VSG-specific build issues (version mismatches between vsg, vsgXchange, and vsgImGui)?

These libraries are under active development and their latest tags aren't always mutually compatible, nor necessarily compatible with the specific Chrono release you're building. installer.sh pins known-working versions for this repository's Chrono version — if you modify buildVSG.sh's version pins, verify compatibility carefully, as mismatches typically show up as find_package(vsg) version errors or missing-symbol compile errors deep in chrono_vsg source files.

Dependecies don't compile perfectly?

There is a known issue in the VSG module installation step of installer.sh. The installer does not fully configure the modules that depend on VSG. As a workaround, run the installer twice to complete the VSG dependency setup, then unselect the VSG dependency in the dependency list and reinstall the remaining packages that follow it.