Developing with VS Code - hyschive/gamer-fork GitHub Wiki
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
- Launch VS Code.
- Open the GAMER Project Folder:
- Go to
File
>Open Folder...
. - Select your GAMER project directory.
- Go to
[!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 pressCtrl + Shift + B
to runconfig-GAMER
andbuild-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 toconfigure.py
to set these flags.)
[!NOTE] If
gdb
is not supported on macOS, you can set uplldb
as the debugger. Ensurelldb-mi
is installed, then selectTerminal
>Run Task...
>updated_mac_launch
. This updates the debugger path inlaunch.json
to yourlldb-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.