Skip to content

Cpp Developer Setup

Jump to bottom
Connor Jakubik edited this page Sep 1, 2025 · 22 revisions
Simulation Development Workflow → C++ Developer Setup

Up to date for Platform 0.33.0

Written by Connor Jakubik

Prerequisites:

C++ Developer Setup

NOTE: You really cannot skip any steps when going through this, besides the steps marked things like "ONLY IN PLATFORM VERSIONS _._._" when your version / OS does not apply. You need to read all of the bullet points as you are going through or you will encounter issues that make the process take longer.

The header lettering / numbering is not in a logical sequence in this page in particular; this is because we want to keep the same headers for the python setup, C++ setup, and SimDynamX internal developer setup docs.

Changelog

First, change these OS settings

  1. For Windows:
    1. Enable long path lengths (Run terminal as admin) (https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell#enable-long-paths-in-windows-10-version-1607-and-later)
    2. (Optional) File Explorer
      1. View Hidden Files (https://support.microsoft.com/en-us/windows/view-hidden-files-and-folders-in-windows-97fbc472-c603-9d90-91d0-1166d1d9f4b5)
      2. View File Extensions (https://www.howtogeek.com/205086/beginner-how-to-make-windows-show-file-extensions/)
    3. OneDrive / Backup & Sync with Google Drive
      1. Be very wary of whether these affect the directories you place Platform files in! Many developer projects are VERY MUCH NOT friendly with these file syncing programs, as they have lots of tiny files that get regenerated often, and many huge files that result in a slow sync. It's not useful to have a backup of Platform files or any other GitHub repo, because once you commit and push changes, they're already backed up in GitHub. It's often very difficult or tedious to remove these files from the sync'd data once they've been sync'd.
      2. You might want to disable these services in their entirety.

A) Download this Required Software

  1. Text editor / IDE of your choice
  2. (FOR WINDOWS ONLY) Git for Windows
    • On the "Adjusting your PATH environment" setup step, choose "Git from the command line and also from 3rd-party software".
    • Download and install git here https://git-scm.com/downloads
      • This should install git-lfs as well by default.
    • Ensure your git version is always reasonably up to date (updated in the past year or so). Otherwise, you might have problems using certain git utilities as instructed. I recommend enabling the automatic update checking.
    • This is for the usage of git in terminals like Powershell, Windows Terminal, and Git Bash. It also includes some other git tools.
    • Default settings should be fine, except for the "default text editor" - choose whatever you feel comfortable with (VS Code is a good option).
  3. (MACOS / LINUX ONLY) Other Git Stuff
    • I'm guessing your OS probably already comes with git preinstalled in the terminal.
    • Ensure the git-lfs package is installed.

TODO ensure all python scripts in user release are using included Python executable.

B) Download the following highly recommended software, unless you have a good reason not to

  1. For editing Space Teams Compute System code, use one or more of these:
    • Visual Studio 2022
      • More install instructions later in this doc.
      • This is only fully featured on Windows. It's not worth getting on MacOS.
      • Make sure to use Visual Studio's "Open a local folder" feature so the higher-level features can work their magic.
    • VS Code - modular, lightweight text editor with packages for many IDE features you would expect on a heftier IDE like Visual Studio
      • VS Code Packages
        • C++
        • JSON (basic support is already there, but you may find a good utility package)
        • CMake
        • Python
      • Make sure to use VS Code's "Open a local folder" feature so the higher-level features can work their magic.
      • alternatively, Atom or Sublime Text.
    • nano, vim, vi, EMACS, punch cards, whatever floats your boat
  2. (If using Windows) Windows Terminal
    • https://www.microsoft.com/store/productId/9N0DX20HK701
    • This is to provide a colored-text terminal in Windows.
    • You can get by with just powershell, but you're really missing out on a LOT without having colored text. The text output you see will be garbled by ANSI escape sequences.
    • Once you have this installed, you can open it by right click -> Open in Terminal in File Explorer, or typing wt in the start menu or the address bar of a File Explorer window.

D) Setup Checklist

At this point in the dev setup, we start to get into a specific tried-and-true setup process. The actual binary compatibility details of how C++ libraries should be compiled really only depend on CMake support and use of the proper compile options; you might be able to stray from this process and still have a working development environment.

D1) Set up OS libraries

a) (ONLY REQUIRED FOR LINUX) Set up Linux (instructions tested on Ubuntu on WSL)

  1. Run these commands (while connected to the internet): 
    sudo apt-get update 
sudo apt-get upgrade
sudo apt install build-essential curl zip unzip tar git pkg-config autoconf automake autoconf-archive ninja-build gcc-13 g++-13 cmake gdb
  2. Optional but recommended additional libraries: 
    sudo apt install openssh-server
  3. For graphical applications to work through WSL:
    1. Install xming or MobaXterm or x410 ($10, but best) or some other X-server
    2. (Explicit commands below) In ~/.bashrc, add export DISPLAY=:0
      1. (Explicit commands for the previous step for people who don’t know Unix terminal commands):
      2. cd ~
      3. sudo nano .bashrc
      4. Nano is a text editor. IMO it’s much easier to use than vim or vi.
      5. At the bottom of the file (ctrl-V to get there faster), add export DISPLAY=:0
      6. (ctrl-X) to exit nano
      7. y to save changes
      8. (enter) to confirm the filename to save with
    3. source .bashrc command restarts bash with the new settings
    4. exit all your open bash windows now to make sure the new bashrc is used on them (when you open more)
    5. Use X-Launch (if using xming) to have X-Server running in the background (default options usually fine)
    6. Now you can open graphical applications from the Ubuntu terminal (or PuTTY or some other stuff)

b) (ONLY REQUIRED FOR MacOS) Set up MacOS:

Run these commands in Terminal:

  1. Installs Homebrew (https://brew.sh/) 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. Installs MacOS command line development tools 
    xcode-select --install
  3. Installs dependency libraries 
    brew install gcc gdb make cmake git pkg-config tbb git-lfs
  4. Link Homebrew's gcc/g++ to Apple's gcc/g++

    WARNING: This can affect the build configuration of other programming projects on your computer! Skip this step for now if you do C/C++ programming elsewhere on your computer.

    ln -s /opt/homebrew/bin/gcc-14 usr/bin/gcc
ln -s /opt/homebrew/bin/g++-14 usr/bin/g++

c) (ONLY REQUIRED FOR WINDOWS) Set up Windows:

  1. Install Visual Studio 2022
    • https://visualstudio.microsoft.com/downloads/
    • Either Community, or Enterprise/Professional (if you already have a license for those).
    • You need to add the following Workloads (added during initial install or through Visual Studio Installer->Modify):
      1. Desktop development with C++
      2. Then also install the 14.38 compiler (matches with the one we use internally): image

TODO validate that Windows SDK versions can differ between linked libraries.

D5) Compute_Server Setup

a) (WHEN USING VISUAL STUDIO IN WINDOWS (not VS Code))

  1. Using the Open a Local Folder option in Visual Studio, open the Compute_Server directory.
  2. When it finishes opening, you should check the toolbar for a Configuration dropdown menu that says default or linux-gcc, to the right of the Target System dropdown that says Local Machine. It is possible that this does not show immediately.
    • If that dropdown menu is not there, you may need to wait a while (~30 seconds+), because Visual Studio has to load all its plugins before it processes the CMake files.
    • You may need to check if you have the right Visual Studio workloads installed (info above) if CMake stuff does not start happening (text output & dropdown).
    • Another possible troubleshooting step is needing to right click the CMakeLists.txt in the Solution Explorer and select Set as Startup Item.
    • Some CMake text output should show on the bottom Output tab as Visual Studio interprets the Compute_Server CMake configuration files.
      • The Output tab's Show output from should be set to Show output from: CMake if that's one of the options.
  3. Ensure the option in this toolbar dropdown menu is set to default. On first load (before v0.33.0), this defaults to linux-gcc for some reason. If that is not an option, wait a bit.
    • If trying to compile for WSL (Linux) using Visual Studio (not VS Code) as the editor: You can use WSL in Visual Studio by selecting WSL... instead of Local Machine for Target System then selecting the linux-gcc Configuration option; this uses your installed WSL as a sort of remote debugging target, and it works quite well! If you have CMake errors when generating cache in this mode, you can try again after deleting your Compute_Server/out folder. The first time you use WSL, it will take a long time for VS to copy source files.
  4. Wait until the Output tab at the bottom shows CMake generation finished.
    • This will take a long time the first time you do CMake cache generation for a particular Configuration (default, etc) because vcpkg is installing the dependency libraries (system-wide). Vcpkg info: https://github.com/microsoft/vcpkg.
    • CMake error troubleshooting:
      • Suitable version of CMake not found:
        • Close VS, force-delete contents of Compute_Server/externals/vcpkg, do git submodule update --init in SC_Platform directory, then try again.
      • Some random error in building of some vcpkg library:
        • Try generating CMake Cache again one more time. If issue persists, Delete CMake Cache then Generate.
  5. Click Build->Build All (Ctrl-Shift-B) to attempt to compile.
    • If Build doesn't have that option, you need to do Project->Configure SC_Server then try again.
  6. Do these steps to test-run the Compute_Server executable through the VS debugger.
    • In Solution Explorer, right click run_Server.exe. Screenshot 2025-03-29 214644
    • Click Add Debug Configuration. Default mode is probably fine. Screenshot 2025-03-29 214658
    • Now you can select run_Server.exe from the Startup Item selection. image image
    • It runs the empty sim, as you didn't set any command line arguments. This is to be expected.
    • Terminate the sim by pressing the red square button.
    • Add "args": ["-i"] to the end of this debug configuration to start Compute_Server in interactive mode instead. Screenshot 2025-03-29 214712
    • More details for command line args in the How To Start a Sim wiki page.

b) (WHEN NOT USING VISUAL STUDIO)

NOTE: non-Visual-Studio user release compiling is not as regularly tested as the Visual Studio approach. Please make an Issue if you encounter problems with the setup and build with this alternative approach.

  1. Run CMake configuration

    Run this in the command line in the /Compute_Server/ directory:

    cmake . -B build --preset <preset-name-here>

    (Building with CMake from the command line is valid for Windows (with CMake for Windows installed), but I recommend using Visual Studio instead.)

    1. Windows x64: 
      cmake . -B build --preset x64-ReleaseWithDebug
      1. Requires VS Developer Command Prompt to use this preset, as it uses the Ninja makefile generator and other tools. It may be possible to have these tools accessible from PATH or made available to CMake in another way.
    2. Linux x64: 
      cmake . -B build --preset linux-gcc
    3. MacOS x64: 
      cmake . -B build --preset macos-x64-gcc
    4. MacOS arm: 
      cmake . -B build --preset macos-arm-gcc

  2. CMake Troubleshooting

    • Make sure your CMake version is as recent as it can be (3.24 should be sufficient). Old CMake versions are usually the issue for failures in the CMake Makefile generation process.
    • If on Ubuntu WSL, you might need to upgrade your OS with sudo do-release-upgrade to get access to the latest libraries through apt.
    • Check on the FAQ.

  3. Run this in the command line in the /Compute_Server/ directory:

    cmake --build --preset <build-preset-name-here>
    1. Windows x64: 
      cmake --build --preset default
    2. Linux x64: 
      cmake --build --preset linux-gcc
    3. MacOS x64: 
      cmake --build --preset macos-x64-gcc
    4. MacOS arm: 
      cmake --build --preset macos-arm-gcc

  4. ./run_Server.exe or ./run_Server to try to run the server (will by default run Empty sim).

  5. CMake / Compile Troubleshooting:

    1. Regenerate CMake cache from scratch: 
      cmake . --fresh --preset <preset-name-here>
    2. Wipe built files: 
      cmake --build --target clean --preset <build-preset-name-here>
    3. To be extra sure that the files are actually wiped, delete all files (except for compute_serverDependencies and sc_CommonAPI.lib) in Compute_Server/build and Compute_Server/out manually.

After completing setup

General process for adding or modifying C++ behavior in a Space Teams simulation:

WORK IN PROGRESS

  1. Modify C++ code in a System in the /packages dir.

    NOTE: We are working on support for C++ Systems whose source code is kept in the user assets dir.

  2. If any Systems were added or removed, Project->Configure SC_Server to refresh the CMake.

  3. Build->Build All

  4. If desired, a sim can be started from the debugger by modifying a Debug Configuration (right-click run_Server.exe -> Open Debug and Launch Settings) to specify the sim, and clicking the green play button.

    • System C++ code can be debugged normally, with breakpoints, value inspection, profiling, etc.

  5. It should be possible to debug any Compute_Server run_Server.exe instance that was started from the SpaceCRAFT unreal client as well:

    • Start a sim in SpaceCRAFT. Optionally, alt-tab back to the VS window when the UI for picking a role is showing.
      • While the role picking UI is showing, the Compute_Server is started but still in SimState: Lobby. This means no init or update functions have been called on C++ Systems, and Python Systems are still stuck inside st.connect_to_sim(). This can be useful to allow attaching the debugger before the init() function runs.
    • Debug->Attach to Process-> Find run_Server.exe and attach.

Further Documentation

Sections

Installing Space Teams

The Fundamentals

Simulation Development Workflow

Physics and Propagation

Use Cases

Verification & Validation

Publications / Theses

Clone this wiki locally