Developing with VS Code

This guide provides step-by-step instructions for setting up and using Visual Studio Code (VS Code) to develop the GAMER codebase.

Setup

Prerequisites

• Quick Start: Follow the Quick Start guide to download GAMER and complete at least one demo.
• Visual Studio Code: Download and install VS Code from https://code.visualstudio.com/.
• C/C++ Extension: Install the "C/C++" extension from the VS Code Marketplace.

Setting Up the Workspace

1. Launch VS Code.
2. Open the GAMER Project Folder:
   • Go to File > Open Folder....
   • Select your GAMER project directory.

Tip

When using remote-SSH, open the directory as an absolute path to avoid this issue.

Configuring VS Code for GAMER

Run the following script from the root directory of the GAMER project:

sh tool/vscode/copy_to_vscode.sh

This script copies the necessary configuration files to the .vscode directory, integrating GAMER with VS Code.

Developing with VS Code

Before running the tasks below, set the working directory by selecting Terminal > Run Task... > set-working-bin and entering the name of the working directory under bin/ where the input files are located.

Configuring GAMER

Select Terminal > Run Task... > config-GAMER to configure GAMER using the generate_make.sh script in your working directory.

Building GAMER

After configuring GAMER with configure.py or generate_make.sh, select Terminal > Run Task... > build-GAMER to start the build process. This updates the macros and enables IntelliSense highlighting.

Tip

To configure and build GAMER in one step, select Terminal > Run Build Task... or press Ctrl + Shift + B to run config-GAMER and build-GAMER sequentially.

Debugging GAMER

To start debugging, select Run > Start Debugging or press F5. After entering the working directory, the debugger will launch. See the official documentation to learn more about debugging in VS Code.

Important

Ensure the compiler flags in Makefile are set to -g -O0 for debugging. (TBD: Add an argument to configure.py to set these flags.)

Note

If gdb is not supported on macOS, you can set up lldb as the debugger. Ensure lldb-mi is installed, then select Terminal > Run Task... > updated_mac_launch. This updates the debugger path in launch.json to your lldb-mi installation. For manual setup or additional details, refer to the official documentation.

Cleaning the Working Directory

Select Terminal > Run Task... > clean-work-dir to clean the working directory using the clean.sh script in your working directory.

Understanding Configuration Files

The following configuration files are copied to the .vscode directory:

• c_cpp_properties.json: Configures IntelliSense settings, including include paths and macros. See the schema reference and IntelliSense documentation for details.
• launch.json: Defines debugging configurations such as executable paths and arguments. See the official documentation for more information.
• settings.json: Specifies editor settings, such as indentation spaces and file types for extensions. See the VS Code settings guide for details.
• tasks.json: Defines build and auxiliary tasks. Learn more about tasks in VS Code.
• gamercpp.natvis: Customizes data structure visualizations in the debugger. Learn more about customizing native object views.