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
• Build and Launch Configuration
  • 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 Compiler: Install GCC (sudo apt install gcc).
• Make: Ensure Make is installed (sudo apt install make).

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).

Build and Launch Configuration

Open the ADDA Project Folder:

1. Launch VS Code.
2. Use File → Open Folder... to select the root directory of the ADDA project.

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 set up and customize the build configuration in VS Code:

1. Create a tasks.json file in the .vscode folder.
   • Use the menu: Terminal → Configure Tasks → Create tasks.json file from template.
   • Select Others from the prompt.
   • Copy the following tasks.json file inside.
2. Run the tasks Terminal → Run Task... and select one.
3. The Terminal → Run Build Task... menu runs the default task (e.g., make clean).
4. To customize the compilation parameters, particularly the ones provided in the OPTIONS=... argument to make, modify the "args" section in the tasks.json file. 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.

1. Open the Command Palette (Ctrl+Shift+P) → C/C++: Edit Configurations (JSON).
   • Set "cStandard": to "c99".
2. Create a launch.json file in the .vscode folder.
   • Use the menu: Run → Add Configuration...
   • Select C++ (GDB/LLDB)
   • Copy the following launch.json file inside.
3. Run and debug the configurations:
   • Open the Run and Debug view in the left bar (Ctrl+Shift+D).
   • Select the desired configuration.
   • Start debugging (F5)
4. 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 launch.json file:

   "args": [
       "-store_int_field"
       ]

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

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, you can configure VS Code to display a vertical guide for the column limit.

1. Open the Command Palette (Ctrl+Shift+P).
2. Select Preferences: Open Settings (JSON).
3. Add the following line to create a guide at the 120-character column limit:

   "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 use snippets in your code:

1. Open the Command Palette (Ctrl+Shift+P), search for Snippets: Configure User Snippets, select New Snippets file for 'adda'..., and name it adda.
2. Go to the file in the .vscode folder.
3. Copy the provided snippet file into it. This will automatically enable the snippets to be used within your project.
4. 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:

1. Use the Code Spell Checker extension to catch typos in comments and variable names.
2. Add a custom dictionary file userdic.txt:
   • Open Settings,json.
   • Edit the path to your custom dictionary file:

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

3. Populate userdic.txt with one word per line:

ADDA
crosssec
userdic
electricField

4. To reduce clutter in the Problems window by lowering the visibility of spelling-related issues:
   • Navigate to File → Preferences → Settings → Extensions and search for Code Spell Checker → Reporting and Display → Diagnostic Level.
   • Set the Diagnostic Level to Hint.
     • This ensures that spelling-related information will still be visible but less intrusive compared to warnings or errors.

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).