Skip to content

Cpp Developer Setup

Jump to bottom
Connor Jakubik edited this page Jan 30, 2024 · 9 revisions
Simulation Development Workflow → C++ Developer Setup

Up to date for Platform 0.18.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

  • 2023/09/18 Initial copy from internal developer documentation.

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
      • 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.

TODO validate behavior of VS 2022 linking with libraries built using toolchain available to VS 2019.

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 WSL Ubuntu:

NOTE: These instructions are for WSL1 on Windows. WSL2 or running with native Linux are slightly different.

  1. Open ubuntu (can do this by typing “bash” into the Microsoft File Explorer address line at your repository directory)
  2. First-time Ubuntu setup if you haven't opened it before:
  • Make a short, easy username and password. You will be prompted for it when you do 'sudo' commands. Since this is contained within Windows, there is no security risk from setting your Ubuntu password to the same as your computer's password, or just something short and memorable like the last 4 digits of your student ID.
  1. Run these commands (while connected to the internet):
sudo apt-get update 
sudo apt-get upgrade
sudo apt install gcc g++ gdb make cmake build-essential libssl-dev git freeglut3-dev xterm libncurses5-dev libncursesw5-dev autoconf libtool libtool-bin libtbb-dev pkg-config ninja-build
  1. Optional but recommended additional libraries:
sudo apt install zip openssh-server
  1. 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

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

  1. Install Visual Studio 2022 or Visual Studio 2019 16.8+
    • https://visualstudio.microsoft.com/downloads/
    • Either Community, or Enterprise/Professional (if you already have a license for those).
    • For the time being, we use VS 2019 internally, so there may be slight differences in button names, etc.
    • You need to add the following Workloads (added during initial install or through Visual Studio Installer->Modify):
      1. Desktop development with C++
      2. (If you're going to use WSL) Linux development with C++
      3. (The "Optional" components that are included with each by default are probably sufficient)
      4. Individual components to add:
        1. Test Adapter for Google Test (if not already checked)
        2. Highest version of Windows (your Windows version) SDK workload.
        3. C++ CMake tools for Windows

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 dropdown menu that says "No Configuration", or something like "x64-Debug" or "WSL-GCC-Debug". It is possible that this does not show immediately.
    • If that dropdown menu is not there, find and open the CMakeLists.txt and CMakeSettings.json files in the Compute_Server directory (in the Solution Explorer tab). 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).
    • 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. Set the option in this toolbar dropdown menu to x64-ReleaseWithDebug. If that is not an option, wait a bit.
    • You can use WSL in Visual Studio by using the WSL-GCC-_____ build configurations; 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.
  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 Debug or Release/ReleaseWithDebug because vcpkg is installing the dependency libraries (system-wide). Vcpkg info: vcpkg wiki doc.
    • CMake error troubleshooting:
      • 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 (or Configure Cache or Generate Cache) then try again.
  6. Click the dropdown at the green play button (Select Startup Item), and select something with run_Server. Now click this button, and the SpaceCRAFT Compute_Server should start. It probably immediately stops, as you didn't set any command line arguments. This is to be expected.
  7. If trying to compile for Linux using Visual Studio (not VS Code) as the editor, follow the instructions above but select WSL-GCC-Debug as the build configuration to use.
  8. In order to run unit tests, in the Test Explorer window, open Options(gear icon)->Test Adapter for Google Test and set Working directory to $(SolutionDir).
    • Also, you probably need to run Project->Configure SC_Server again after any compile in order for newly added tests to show up in the Test Explorer`.
  9. Compute_Server Python API
    • After compiling successfully in ReleaseWithDebug, the Compute_Server Python API is built.
    • You can now go to Compute_Server/tools and do .\win_sc_python_setup.bat, or the equivalent for your OS / CPU, to do the setup script setup for sc_python.
    • After doing this setup (which needs to happen after any time the python vcpkg library gets rebuilt from scratch), you can use Python systems in SpaceCRAFT sims, and use Python scripts that import the SC_Compute_Server python library.

b) (WHEN NOT USING VISUAL STUDIO)

  1. Run CMake configuration Run this in the command line in the /Compute_Server/build/ directory:

    cmake ..

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

  2. CMake Troubleshooting

    • Make sure your CMake version is as recent as it can be (3.16 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. cd .. to get back to /Compute_Server/

  4. ./makeSim to try to compile all Systems

  5. ./run_Server to try to run the server (after displaying title text, will error as it requires a mode to be set)

After completing setup

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

WORK IN PROGRESS

Further Documentation

Sections

Installing Space Teams

The Fundamentals

Publications / Theses

Simulation Development Workflow

Physics and Propagation

Clone this wiki locally