-
Notifications
You must be signed in to change notification settings - Fork 0
Cpp Developer Setup
Simulation Development Workflow → C++ Developer Setup |
---|
Written by Connor Jakubik
Prerequisites:
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.
-
2023/09/18
Initial copy from internal developer documentation.
- For Windows:
- 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)
- (Optional) File Explorer
-
OneDrive / Backup & Sync with Google Drive
- 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.
- You might want to disable these services in their entirety.
-
Text editor / IDE of your choice
- (For lightweight editing of config files, etc)
- I recommend Visual Studio Code https://code.visualstudio.com/
- (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.
- This should install
- 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).
- (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.
- I'm guessing your OS probably already comes with
TODO ensure all python scripts in user release are using included Python executable.
-
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.
- VS Code Packages
- nano, vim, vi, EMACS, punch cards, whatever floats your boat
- Visual Studio
-
(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 typingwt
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.
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.
NOTE: These instructions are for WSL1 on Windows. WSL2 or running with native Linux are slightly different.
- Open ubuntu (can do this by typing “bash” into the Microsoft File Explorer address line at your repository directory)
- 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.
- 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
- Optional but recommended additional libraries:
sudo apt install zip openssh-server
- For graphical applications to work through WSL:
- Install xming or MobaXterm or x410 ($10, but best) or some other X-server
- (Explicit commands below) In ~/.bashrc, add
export DISPLAY=:0
- (Explicit commands for the previous step for people who don’t know Unix terminal commands):
cd ~
sudo nano .bashrc
- Nano is a text editor. IMO it’s much easier to use than vim or vi.
- At the bottom of the file (
ctrl-V
to get there faster), addexport DISPLAY=:0
-
(ctrl-X)
to exit nano -
y
to save changes -
(enter)
to confirm the filename to save with
-
source .bashrc
command restarts bash with the new settings - exit all your open bash windows now to make sure the new bashrc is used on them (when you open more)
- Use X-Launch (if using xming) to have X-Server running in the background (default options usually fine)
- Now you can open graphical applications from the Ubuntu terminal (or PuTTY or some other stuff)
Run these commands in Terminal:
- Installs Homebrew (https://brew.sh/)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- Installs MacOS command line development tools
xcode-select --install
- Installs dependency libraries
brew install gcc gdb make cmake git pkg-config tbb git-lfs
- 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):
Desktop development with C++
- (If you're going to use WSL)
Linux development with C++
- (The "Optional" components that are included with each by default are probably sufficient)
-
Individual components to add:
-
Test Adapter for Google Test
(if not already checked) - Highest version of
Windows (your Windows version) SDK
workload. C++ CMake tools for Windows
-
TODO validate that Windows SDK versions can differ between linked libraries.
- Using the
Open a Local Folder
option in Visual Studio, open theCompute_Server
directory. - 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
andCMakeSettings.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'sShow output from
should be set toShow output from: CMake
if that's one of the options.
- The
- If that dropdown menu is not there, find and open the
- 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 yourCompute_Server/out
folder.
- You can use WSL in Visual Studio by using the
- 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
orRelease
/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.
- Some random error in building of some vcpkg library:
- This will take a long time the first time you do CMake cache generation for
- Click
Build
->Build All
(Ctrl-Shift-B) to attempt to compile.- If
Build
doesn't have that option, you need to doProject
->Configure SC_Server
(orConfigure Cache
orGenerate Cache
) then try again.
- If
Click the dropdown at the green play button (Select Startup Item
), and select something withrun_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.- 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. -
In order to run unit tests, in theTest Explorer
window, openOptions
(gear icon)->Test Adapter for Google Test
and setWorking 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`.
- Also, you probably need to run
- 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.
- After compiling successfully in
-
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.)
-
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.
-
cd ..
to get back to/Compute_Server/
-
./makeSim
to try to compile all Systems -
./run_Server
to try to run the server (after displaying title text, will error as it requires a mode to be set)
General process for adding or modifying C++ behavior in a Space Teams simulation:
WORK IN PROGRESS