Developing with VS Code

The general idea for this document is the following: VS-Code running on a local machine with the software/data located on a remote machine (either WSL2 on the same physical machine or a remote cluster).

This document was written with the assistance of GitHub Copilot chat. It was quite helpful in figuring out where to locate everything in the VS Code interface and how to configure VS Code project files.

Install VS Code

Download and install VS Code.

This is a fairly straightforward step. VS code is a text editor that integrates git and extensions that make it essentially a full blown IDE. For our purposes, the most useful part is VS Code can run on your local computer while editing and building source code on a remote computer through an SSH tunnel (see Remote Development).

Install required/recommended extensions

Here are the list of extensions required to use VS Code for developing ATTPCROOT. Go to the Extensions tab (or press shift+ctrl+X) and search for the following extensions.

• C/C++ Extension Pack (required)
• GitHub Copilot (recommended, free for students and educators)
• Remote - SSH (required)
• WSL (if your source code is local in a WSL2 instance)

Configure VS Code

There are a few steps. I am assuming you have cloned and setup your fork of the repository on the remote computer already. For this document, I will assume your repository lives in the folder ~/ATTPCROOTv2.

Setting up remote host

1. Setup SSH Config files for access to remote host.

   This step is performed on your local machine running VSCode, not the remote computer with the code. The SSH config file is located at ~/.ssh/config. Open the command palette (Ctrl+Shift+P), then select Remote-SSH: Open SSH Configuration File.... This will open the SSH config file in VSCode.

   Add an entry to the config file for the host that has the code. It will look like:

   Host host_name
       User username
       HostName clusterurl.edu
       PubKeyAuthentication yes
       IdentityFile ~/.ssh/id_privateKey
       ForwardAgent yes
       ForwardX11 yes
       ForwardX11Trusted yes

   Replace host_name with a memorable name for the host. User and HostName should be the username and URL you use to SSH into the remote host (i.e., ssh User@HostName). IdentityFile is the path to your SSH key used for authentication. Note that even on Windows, the Linux shortcut ~/ works, and SSH is flexible with file path delimiters, so the example above works on both Unix and Windows systems.

2. Connect to the Remote Host

   Open the command palette (Ctrl+Shift+P), then select Remote-SSH: Connect to Host.... Your newly added host_name should appear in the list. Select it to open a new VSCode window connected to the remote host. The colored bar at the bottom left of the VSCode window indicates the current host, displaying SSH:host_name.

3. Access the Terminal

   Use the SSH connection to spawn terminals on the remote host. Open a terminal with Ctrl+Shift+` or select Terminal: Create New Terminal from the command palette (Ctrl+Shift+P). You can open multiple terminals, name them, and switch between them.

4. Install Extensions on the Remote Host

   Some extensions may need to be installed on the remote host for optimal performance, such as IntelliSense.

   To install extensions, open the extension panel (Ctrl+Shift+X) in the remote host VSCode window. You'll see two tabs: LOCAL - INSTALLED and SSH:HOST_NAME - Installed. Verify that all desired extensions have been synced by the Remote - SSH extension.

Setting up the repository

1. Open the Repository Folder

   In the VSCode window attached to the remote host, open the folder containing the repository. Use Ctrl+K, Ctrl+O and navigate to the folder.

2. Configure Environment for Building

   We use CMake to configure, build, and install the project. To help CMake find all dependencies, provide additional information:

   • Set Required Environment Variables: Edit your settings.json file for the project. You can open it directly (.vscode/settings.json) or select Preferences: Open Workspace Settings (JSON) from the command palette. Add two variables (FAIRROOTPATH and SIMPATH) to the environment for when CMake configures or builds. These variables depend on where FairSoft/FairRoot is installed on your system.

     "cmake.environment": {
         "FAIRROOTPATH": "/home/faculty/aanthony/fission/fair_install/FairRootInstall",
         "SIMPATH": "/home/faculty/aanthony/fission/fair_install/FairSoftInstall"
     }

   • Set the prefix path: Often, you need to specify the version of HDF5 to build against. This can be done by setting the CMake prefix path.

     Add another entry to your settings.json file to set the path to where you installed HDF5. For example, if you're using HPU's cluster, you would add the following:

     "cmake.configureSettings": {
     "CMAKE_PREFIX_PATH": "/home/faculty/aanthony/fission/fair_install/hdf5"
     }

3. Configure the terminal enviroment.

   To run scripts, we need to set up the environment in the terminal. CMake generates a build/config.sh file that sets the required environment variables.

   To automatically source this configuration script whenever a new integrated terminal is opened, add the following to your settings.json file:

   "terminal.integrated.profiles.linux": {
        "BashWithStartup": {
            "path": "bash",
            "args": ["-c", "source ${workspaceFolder}/build/config.sh; exec bash"]
        }
    },
    "terminal.integrated.defaultProfile.linux": "BashWithStartup"
   

   This creates a new terminal configuration and sets it as the default.

   If your system requires additional setup (like loading modules), replace the source ... line with the path to the appropriate bash file. For example, on FRIB's fishtank, use:

   "args": ["-c", "source ${workspaceFolder}/env_fishtank.sh; exec bash"]

4. Optional settings

I (Adam) add a few more settings to my Workspace settings:

"terminal.integrated.scrollback": 100000,
"git.allowForcePush": true,
"git.rebaseWhenSync": false,

"cmake.parallelJobs": 10,
"editor.defaultFormatter": "xaver.clang-format",
"editor.formatOnSave": true,

These settings:

1. Increase the scrollback for the terminal (useful when ROOT craps out).
2. Setup git to use some of the settings for our workflow.
3. Limit the number of parallel jobs cmake will run (it will default to using all available cores)
4. Setup VSCode to run clang-format whenever a file is saved

X11 Forwarding and VSCode

To interact with the code beyond building it, you'll need X11 forwarding.

1. Install an X11 Server

   Choose an X11 server that suits your needs. Some options include VcXsrv or XMing. After installation, ensure the server is running.

   Consider adding the X11 server to your startup programs. This way, it launches automatically each time you restart your computer, and you won't need to remember to start it before SSH-ing.

2. Set the Display Variable

   Configure VSCode to always set the DISPLAY environment variable. Open your user settings.json by going to the command palette (Ctrl+Shift+P) and select Preferences: Open User Settings (JSON). Here you are editing your local config file. Add the following:

   "terminal.integrated.env.windows": {
       "DISPLAY": "localhost:0.0"
   }

3. Configure SSH for X11 Forwarding

   In your SSH config file (~/.ssh/config), ensure the following lines are present for the host you're connecting to:

   ForwardX11 yes
   ForwardX11Trusted yes

4. Verify it's working

   1. Restart VSCode to make sure your changes took effect
   2. Use VSCode's Remote-SSH extension to connect to the remote host.
   3. Once connected, open a terminal in VSCode (Ctrl+Shift+`) and run xclock. You should see a clock pop up.