FEAT 3
Finite Element Analysis Toolbox
Loading...
Searching...
No Matches
FEAT for Visual Studio Code on Unix and Windows Systems

Table of Contents

This page describes the setup and use of FEAT with the Visual Studio Code editor.

Prerequisites for using FEAT with VScode

Prerequisites under unix

In addition to a working build toolchain, i.e. a compiler toolchain, e.g. gcc or LLVM/clang, and a generator, e.g. make or ninja, in your path, you need at least a version of CMake 3.28 or higher and a version of python(3) installed, both of which should also be in your path. Of course you will also need VScode installed. To also use MPI, etc., see the configure script, but basically certain packages, such as MPI or CUDA, need to be pre-installed and findable on your system, i.e. in your path or you are able to pass the location, others like UMFPACK, Zoltan, ... will be automatically installed in a FEAT subdirectory if you pass the flag to the configure system, more on this later.

Special case: Module based enviroment

In the case of a module-based software distribution, first load the modules you need, then open VScode from the terminal by changing the current directory to the FEAT source folder and run 

  code .

You should also consider running VScode from a compute server so that the building and IntelliSense shenanigans are performed on the server's resources.

Prerequisites under Windows

For a number of reasons, FEAT in VScode can only be fully compiled (i.e. with (all) third party libraries) using the Visual Studio 2022 clang/llvm toolchain, which has the side-effect that, due to a bug in the VS22 implementation, no address sanitiser can be used for the time being. Hopefully this will be fixed in the next major release. You will also need at least a CMake 3.9 version, preferably at least a CMake 3.15 version, and a python3 version. While VS22 provides ninja as a build generator, you can of course provide your own (e.g. MinGW's make). All of these need to be included in your path, see standard Windows documentation on how to do this.

Attention
A few notes on installing VS22: To use clang with GNU-style command-line arguments (which is currently the only supported compilation toolchain), you need to add the corresponding option in your VS22 installation. You will also need a relatively new Windows SDK that your compiler can find. An easy way to archive this is to also select the option to install the latest Windows SDK in your VS22 installation. If VS22 is in your path, you should then be able to find the GNU style Clang toolchain.

Microsoft MPI

If you want to make use of FEAT's parallel computing capabilities, you will also need to install the Microsoft MPI library as well as the corresponding SDK. Note that installing MPI is not mandatory, however, without this library, FEAT is limited to its "single-process" functionality.

Note
Previous attempts to support other MPI implementations such as MPICH or OpenMPI in combination with Visual Studio have not been successful, so these (and other) implementations are officially unsupported by the FEAT Visual Studio build-system. Sorry for the inconvenience.

You can download the latest version of the MS-MPI library here:

Note
From MS-MPI Version 7 on, you will need to enable the MS-MPI Launch Service to start automatically on your windows machine, as otherwise MPI-based applications may not start. The easiest way to do so is to execute the following command in a console (with administrator rights): 
sc config MsMpiLaunchSvc start= auto

Once you have installed MS-MPI and setup the launch service, there is nothing more to do, as the build-system will automatically detect that an MPI implementation is available.

Nvidia CUDA

Nvidia CUDA is not currently supported by the FEAT Visual Studio build system. This will be enabled at a later date.

Intel MKL

Intel MKL is not currently supported by the FEAT Visual Studio build system. This will be enabled at a later date.

VScode setup

Before configuring FEAT with VScode for the first time, we need to set up a few things in VScode. First of all, you need to install (by Microsoft recommended) the C/C++ toolset extension , which consists of C/C++ language support, in particular debugger, AutoComplete and IntelliSense support, CMake language support and, very importantly, the CMake Tools extension, which handles the configuration of CMake projects as well as building and project support for IntelliSense.

After starting VScode it will prompt you to select a compiler kit. Select any kit for now. We will give VScode more specific instructions on how to configure and build FEAT later.

Note
A few things to keep in mind: FEAT's ctesting does not work with multiple threads. For this reason, with 
 CTRL + Shift + P   -> Preferences: Open Settings(UI)
set 
 Extensions ->  CMake Tools -> Ctest: Parallel Jobs
0 to 1.

You can also change some parameters here, such as the name and path of your build directory and so on. Just use the defaults for now.

Note
For now, ignore any recommandation prompts VScode gives.

Configuration Setup

The CMake Toolse extension uses CMake presets to determine how to configure and build FEAT. Whenever you execute the configure script the generated configuration gets appended to the CMakeUserPresets.json file in the root of your FEAT repository. If a configuration with the same build-id already exists, it will be overwritten. Whenever you run the configure script, VScode should automatically pick up any new or changed presets. You can select the preset you want to use in the CMake tab of the sidebar or via

 CTRL + Shift + P   -> CMake: Select Configure Preset

VScode will then create its own independent build directory in out/${presetName} and configure FEAT.

Note
If you do not want your own build directory and only want to use the one managed by VScode you can run the configure script with the –preset-only flag.
Attention
If a third-party library is not found in your third-party folder, it will be downloaded automatically. For this reason (and others) you should place your FEAT source directory somewhere where you do not need root or admin rights to write/modify files.

Working with CMake Tools

Configuring FEAT

After choosing your preset, VScode will automatically start a (shallow) CMake configuration and you should be able to build your first programs.

Attention
If something does not work, or you get a configuration warning, you should do a clean configuration using 
 CTRL + Shift + P -> Cmake delete cache and reconfigure

Building FEAT

You could now navigate to the build directory in out/${presetName} and build executables from the command line, but you can also use CMake Tools to build executables in FEAT. As an example, let us build the first tutorial. With 

 CTRL + Shift + P -> Build target -> tutorial-01

you can compile the first tutorial executable. Of course, this will take a moment as FEAT has to be built from scratch. Once this is done (successfully), we can run our tutorial.

Note
After the first configuration, you can run ctest with 
 CTRL + Shift + P -> CMake: Run Tests
to verify that everything is working. Note that you need to set the number of ctest threads to 1 as described above.
Attention
Ctest in combination with MPI is currently broken with the WINMPI implementation.

Running FEAT

You can either run from the command line in your build directory, or via CMake run. If you want to provide command line arguments, you need to edit the settings.json file with 

 "cmake.debugConfig": {
        "args": [
            "MyArgument"
        ]
    }

Working with VScode

For a good introduction, refer to CMake Tools' Github page.

Problems with file discovery

The file detection process and subsequent file parsing can be a bit temperamental, especially if the files are not local to the running process (e.g. a shared file system). While there are still a few things to optimise, it helps to wait until the parsing process has finished before opening any C/C++ files, to avoid the IntelliSense process from trying to parse the current file, as this seems to interact with the detection/parsing process. You can see if file detection/parsing is currently running by hovering over the "container" icon, which is aligned to the left of the right status icons of the blue CMake tools status bar, see the image.

If there is no change or it reports as halted, reload your window and do a clean reconfigure.

Note
IntelliSense parses every folder in the PATH variable, so it is advisable not to allow discovery of large folders that are not needed to compile FEAT. If detection is slow, it may help to exclude the /usr/include folder (especially on a shared file system). To do this, open the VScode settings menu, select the workspace settings and search for 
 C_cpp files: exclude
Click on the Edit in settings.json option and add to the list in "C_Cpp.files.exclude" 
 "/usr/include": true
The entry in the json file should be as follows 
 "C_Cpp.files.exclude": {
        "/usr/include": true,
        "**/.vscode": true,
        "**/.vs": true
    }
If you want to see, which folders are included in your PATH, check 
 C/Cpp: Log Diagnostics
Attention
If you create a new header file which is not included anywhere in the project, you will see an include error generated by IntelliSense for any header file. To fix this, simply add the new header file, i.e. the file where you see the error, not the include target, to any source list of an executable. While this does not change the build process, it fixes the bug.
Note
You should also add ms-vscode.cmake-tools to the default configuration provider setting of IntelliSense.

Using clangd as Language Server

Instead of using the C/C++ extension of Microsoft, using clangd as language server can improve performance espacially on the side of file disovery. While there are a few disadvanteges, mainly the missing parsing of doxygen comments (which is a feature request momentarily under review ), it should be considered if you are running into problems with the IntelliSense setup.

Setup of clangd

First of all, you should have a clangd installed in your system. Since clangd is part of the LLVM project, it should be part of your clang installation. To test this, and get the path to yopu clangd installation, simply type into a terminal 

which clangd

After you have confirmed the location of your clangd installation, search in VScode extentions the clangd plug-in, which handles the configuration of the language server. You will also see a prompt asking which language server should be your default provider, choose clangd. Then, add to your settings file: 

"C_Cpp.intelliSenseEngine": "disabled", //disable intellisense lsp
"cmake.copyCompileCommands": "${workspaceFolder}/compile_commands.json",
"clangd.path": "/usr/bin/clangd",
"clangd.arguments": ["-log=verbose",
                     "-pretty",
                     "--background-index",
                     "--compile-commands-dir=${workspaceFolder}"]

which disables IntelliSense, adds a few options to the clangd language server, and instructs the CMake extension to copy the current compile_commands.json file to the project root for clangd to find. The compile_commands.json file provides the building information clangd needs to correctly parse your project. It is automatically generated by CMake each time you (re-)configure FEAT.

To reduce the load IntelliSense has on the system, you can also add to your settings file 

"C_Cpp.intelliSenseCacheSize": 0,
"C_Cpp.intelliSenseMemoryLimit": 256,
"C_Cpp.autocomplete": "disabled",
"C_Cpp.hover": "disabled"
Note
If you do not require debugging capabilities, for which we still need IntelliSense, you can deactivate the C/C++ extension complettly, since everything else should be handled by clangd.

Configuring clangd

It can be very helpful to provide clangd with extra information in you sourcefiles (for example extra include or typedefs), which are unecessary or even wrong in the actual build process. This can very well happen, if for example a header file depends on a prior include of another header, which is done on application level (as for example done in the new ccnd applications). To differentiate between clangd compilation and any other, we add an additional compile flag to our clangd setup. For this create a file under the local config directory ~/.config/clangd(if it does not exist, create it) named config.yaml. Here simply add 

CompileFlags:
  Add: [-D_CLANGD=1]

Which adds a compiler definition _CLANGD which can be checked with a #ifdef pre-compiler call.

/TODO: Add additional configuration options and information regarding cland-tidy .

Author
Maximilian Esser