UsingVSCode

The following summarizes our experience of using Visual Studio Code (VS Code) IDE for developing ADDA. This guide has been tested with VS Code versions 1.95.2 and 1.95.3 on Ubuntu.

• Basic Installation and Setup
  • Prerequisites
  • Install Recommended Extensions
  • Quick Recipe
• Additional Information
  • Build Configuration with Makefile
  • Debug Configuration
• Interaction with git
• Editor settings
  • Main code
  • Spell Checking
  • Terminal
  • Wiki pages

Basic Installation and Setup

Prerequisites

Before starting, ensure the following tools are installed on your system:

• VS Code: Download and install Visual Studio Code.
• C and Fortran Compilers: Install GCC and GFORTRAN.
• Make: Ensure Make is installed.
• Bear: Install Bear for generating the compile_commands.json file.
• git: Install Git for cloning repositories.
• Libraries: Install the following:libfftw3-dev, libopenmpi-dev for MPI Mode, and ocl-icd-opencl-dev libclfft-dev for OCL Mode.

sudo snap install code --classic
sudo apt install gcc gfortran make bear git
sudo apt install libfftw3-dev
sudo apt install libopenmpi-dev
sudo apt install ocl-icd-opencl-dev libclfft-dev

Install Recommended Extensions

To optimize VS Code, install these extensions:

1. C/C++ Extension Pack: Provides IntelliSense, debugging, and more.
2. Code Spell Checker: Highlights typos in code and comments.
3. Makefile Tools: Provides IntelliSense for Makefile projects.
4. Markdown Preview Enhanced: Provides many useful functionalities (PDF export, preview, etc.).
5. fortran: Adds support for Fortran, including syntax highlighting, snippets, and basic IntelliSense.
6. OpenCL: Enables syntax highlighting and basic IntelliSense for OpenCL kernel code.

You can install extensions from the Extensions view (Ctrl+Shift+X).

Quick Recipe

Follow these steps to quickly set up and start working with ADDA:

1. Download ADDA

   git clone https://github.com/adda-team/adda.git
   cd adda

2. Download the .vscode folder and open ADDA inside VS Code

   mkdir .vscode && cd .vscode
   wget https://raw.githubusercontent.com/wiki/adda-team/adda/files/{tasks.json,launch.json,c_cpp_properties.json,settings.json,adda.code-snippets}
   cd ../../ && code adda

   • This folder contains:
     • IntelliSense configuration.
     • Code analysis setup.
     • cSpell configuration for spell-checking.
     • Pre-configured build and task setups.

3. Build the Project The build tasks are pre-configured in the .vscode/tasks.json file:

   • To build the project, run the tasks Terminal → Run Task... and select the appropriate task.
   • You can also use the shortcut (Ctrl+Shift+B) to run the default task (e.g., make clean).

4. Debug the Project

   • To debug the project, select Run and Debug from the left sidebar.
   • Ensure the correct debug configuration is selected from the configuration dropdown.
   • Press F5 to start the debugging session.

Additional Information

Build Configuration with Makefile

A build configuration defines the set of instructions and parameters used to compile and build the ADDA project. It controls the tools and flags passed to the compiler, allowing you to specify various settings, such as debug or release builds, optimization levels, or specific features (like internal debugging or FFT usage). This section explains how to customize the build configuration in VS Code:

• To customize the compilation parameters, particularly the ones provided in the OPTIONS=... argument to make, modify the "args" section in the .vscode/tasks.json file.

  "args": [
      "-s",
      "OPTIONS=DEBUG"
  ]

  Common options include:
  • DEBUGFULL (to enable ADDA internal debugging)
  • DEBUG FFT_TEMPERTON (to use built-in FFT)

Debug Configuration

Configuring debugging in VS Code for ADDA allows you to execute the program directly from the editor, step through code, and inspect variables.

• To customize the debugging session, you can add command-line arguments directly to the program (e.g., "-store_int_field") by editing the args section in the .vscode/launch.json file:

  "args": [
      "-store_int_field"
  ]

  This passes "store_int_field" as a command-line argument to the ADDA program when debugging.

Using Breakpoints

To effectively debug your code, you can set breakpoints at specific lines in your source code. Follow these steps:

1. Setting a Breakpoint:

   • Open the source file where you want to set a breakpoint.
   • Click in the gutter (the left margin) next to the line number where you want to pause execution. A red dot will appear, indicating the breakpoint.

2. Start Debugging:

   • To start debugging, ensure the correct configuration is selected in the Run and Debug panel, then press F5 or click on the Start Debugging button.

3. View Breakpoint Information:

   • Once the code hits a breakpoint during execution, VS Code will pause the program.
   • You can inspect variable values, step through the code, and view the call stack in the Run and Debug panel.

4. Navigating through Code During Debugging:

   • Step Over (F10): When the program is paused at a breakpoint, press F10 to step over the current line of code. This runs the current line without going into any functions called within it.
   • Step Into (F11): Press F11 to step into the function or method being called on the current line. This allows you to debug inside the function line by line.
   • Step Out (Shift+F11): If you've stepped into a function and want to exit it, press Shift+F11 to step out and return to the caller.

5. Removing a Breakpoint:

   • To remove a breakpoint, simply click on the red dot again, or right-click and choose Remove Breakpoint.

6. Conditional Breakpoints (Optional):

   • Right-click a breakpoint and select Edit Breakpoint to add conditions (e.g., break only when a variable reaches a specific value).
   • This allows you to pause execution only under certain circumstances, helping to target specific issues.

Interaction with git

VS Code includes built-in Git support, enabling basic functionality. Files in the project tree that differ from the previous committed revision are marked by U. In the left-click menu, the Source Control window (Ctrl+Shift+G) provides options to compare files with previous revisions, revert changes, or commit and push them.

Editor settings

Main code

ADDA adheres to a specific code style, which can be enforced in VS Code using Clang-Format. However, clang-format is currently not used to enforce a code style due to incompatibilities with the existing ADDA formatting rules. Instead, developers can use visual aids in their editors to adhere to the column limit and other style preferences without automatic formatting.

Suggested Visual Aids in VS Code

To assist with maintaining the code style in a non-intrusive way, we configure VS Code to display a vertical guide for the column limit (120 characters). This is done using the following line in .vscode/settings.json:

"editor.rulers": [120]

This does not modify the code but provides a helpful visual marker for the recommended column width.

Optional: Online Clang-Format Configurator

For reference, you can use the Clang-Format Configurator to experiment with different formatting options. However, note that none of the current clang-format styles perfectly match ADDA’s code style.

Using Snippets for Automation

We propose using Snippets to replace auto code formatting while adhering to ADDA’s code style. Snippets in VS Code allow you to quickly insert predefined code templates, which can help automate repetitive tasks, maintain consistent code structure, and increase development speed.

To access and use a snippet, simply type its trigger keyword in your code and press Tab to expand it into the full snippet:

newFunc
newFile
newPreprocessor

These snippets are designed to streamline development and ensure consistent formatting and structure throughout the code.

Spell Checking

To set up user dictionary for spelling checks we used the Code Spell Checker extension to catch typos in comments and variable names. This setup includes a custom dictionary userdic.txt to handle project-specific terms and the following lines in .vscode/settings,json:

{
    "cSpell.dictionaries": ["custom"],
    "cSpell.dictionaryDefinitions": [
        {
            "name": "custom",
            "path": "${workspaceFolder}/userdic.txt"
        }
    ]
}

You can also populate userdic.txt with flagged words Spell Checker Terminal Window → words with issues → Add Word to Dictionary.

Terminal

VS Code's integrated terminal can be opened in any folder (in Project Explorer) via Terminal → New Terminal. You can also add multiple terminals and split them.

Key outputs visible in the terminal include:

• Problems: Errors and warnings from Clang-Format and the compiler.
• Debug Console: Displays debugging logs.
• Spell Checker: Highlights typos flagged by your dictionary.

Wiki pages

VS Code is suitable for editing ADDA wiki pages (Markdown files) offering live preview functionality. The Markdown Preview Enhanced extension allows for advanced features like exporting to PDF and previewing Markdown files in split windows (Ctrl+K V).