Prerequisites

From Visual Studio 2022 on, the FEAT build system for Windows does not support 32-bit builds anymore, so in consequence you require a x64 Windows operating system, a x64 based Visual Studio installation as well as a x64 Python environment, all of which should be standard by now, almost 20 years after AMD first released its Athlon 64 CPU...

Microsoft Visual Studio 2022

To compile and use FEAT under Windows, you (obviously) require Microsoft Visual Studio 2022 (any edition). Note that the free Community edition of Visual Studio 202 is perfectly sufficient, which can be obtained from here:

https://visualstudio.microsoft.com/downloads

Setting the Visual Studio path environment variable

Unfortunately, Visual Studio 2022 does not set any environment variable that specifies its installation path anymore, so this has to be done by hand. To do so, you have to define an environment variable called VS17PATH. If you have installed Visual Studio 2022 Community in the default location, you can run the following command in a console with administrator rights to set the environment variable:

setx VS17PATH "C:\Program Files\Microsoft Visual Studio\2022\Community"

If you have installed Visual Studio in another directory, then you have to adjust the path accordingly.

Python 3 Interpreter

Some parts of the build system are written in Python, namely the third-party library assistant script as well as the Visual Studio project file generator script. Fortunately, Visual Studo 2022 comes with a Python development package included, so just make sure to install this package when installing Visual Studio on your system. You do not need to install any additional Python packages manually, because all the scripts used by the FEAT build system require only the Python standard libraries.

Note: In theory, all scripts should work just fine in a 32-bit Python environment, but we still recommend finally arriving in the 21st century and using a 64-bit Python environment.

Microsoft MPI

If you want to make use of FEAT's parallel computing capability, 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:

https://learn.microsoft.com/en-us/message-passing-interface/microsoft-mpi
Important: You need to download and install both MSMpiSetup.exe and msmpisdk.msi.

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 a MPI implementation is available.

Nvidia CUDA

The minimum supported version of Nvidia CUDA for FEAT is version 12.0, which must be installed including its integration into Visual Studio 2022, of course. There is nothing else that has to be done manually to enable CUDA in FEAT; simply select a build configuration that contains the cuda tag to enable CUDA in FEAT.

Intel oneAPI MKL

The minimum supported version Intel oneAPI MKL is version 2024.2. Unfortunately, Intel apparently does not provide any useful environment variables to the installation directory anymore, so one has to declare one by themselves. Assuming that you have installed MKL in its default installation directory, execute the following command in a console with administrator rights:

setx ONEAPI_ROOT "C:\Program Files (x86)\Intel\oneAPI"

If you have installed Intel oneAPI in another directory, then you have to adjust the path accordingly, of course. There is nothing else that has to be done manually to enable MKL in FEAT; simply select a build configuration that contains the mkl tag to enable MKL in FEAT.

Additional Third-Party Libraries

FEAT supports a set of third-party libraries, which can be included to extend the functionality offered by FEAT. Note that all third-party libraries are opt-in, i.e. you are not forced to use any of these libraries, but you may as well use FEAT without any additional libraries (a.k.a. "naked build") – the drawback is that you will only have reduced functionality, of course.

Attention: Please note that each third-party library comes with its own license, which may or may not be suitable for you. Please consult each library's license before installing it. The license of each library can be displayed in the assistant script (see below).

Currently, all additional libraries are downloaded from the internet and built from source, i.e. it is not necessary to install the libraries manually. To manage your third-party libraries, please execute the vc17-thirdparty.py Python script, which is located in the thirdpart subdirectory of your FEAT root directory. This assistant script lists all third-party libraries, which are currently available for your FEAT checkout, and enables you to conveniently download, unpack and compile all packages without any additional manual steps. Simply execute the script (in a console) and follow the instructions.

Note: If you intend to use MPI in your FEAT builds, then tt is highly recommended that you install Microsoft MPI before compiling the third-party libraries, because some libraries require MPI to be compiled. However, you can re-run the third-party assistant script at any time and compile the additional libraries later, if you missed the MPI compilation in the first place.

Creating Visual Studio Project and Solution files

Before you can compile any FEAT application, test or tutorial with Visual Studio, you will first need generate a corresponding Visual Studio project and solution file. In contrast to the CMake-based build-system used under Linux, there is no "configure" script that will generate all required projects and solution in one step.

Instead, you need to generate VS project and solution files for each desired application, tutorial or kernel test separately by using a Python script named vc17-gen.py, which is located in the root directory of FEAT.

The usage and the behavior of the script depends on whether the desired target is a kernel test or any other sort of application (this includes tutorials and tools). The usage of the tool is also described in the following sub-sections.

Generating Empty Application Projects

To generate a new empty project and solution file pair for any sort of application (this includes tutorials and tools), open a console in the FEAT root directory and use the following command to specify the path to where the project file is to be created as well as its desired project name and, optionally, the list of all source files that are to be added to the newly created project file:

vc17-gen.py <project-path> <project-name> [<source-files...>]

Note: The script automatically detects the source file type by its file extension.

Example:
To generate a project file for the first tutorial and compile it, you will need to perform the following steps:

Open a console in the FEAT root directory.
Enter the following command to create the project file tutorial-01-poisson.vc17.vcxproj as well as the corresponding solution file tutorial-01-poisson.vc17.sln residing in the tutorials directory:
```
vc17-gen.py tutorials tutorial-01-poisson tutorials\tutorial_01_poisson.cpp
```
Open the new solution file. This solution file will contain two projects:
- The application project tutorial-01-poisson.vc17
- The FEAT kernel project kernel.vc17
Choose a build configuration, e.g. the debug configuration namend dbg for the 64-bit platform x64.
Build the solution.
The resulting executable application binary tutorial-01-poisson.vc17-dbg-x64.exe will appear in the tutorials sub-directory of the FEAT root directory.

Generating Simple Application Projects

If you are too lazy to specify paths and project names, you might also use the following command to generate a simple application project and solution file pair with the same name and path as the first of the given source files:

vc17-gen.py -app <source-paths...>

Example:
To generate a project file for the first tutorial and compile it, you will need to perform the following steps:

Open a console in the FEAT root directory.
Enter the following command to create the project file tutorial_01_poisson.vc17.vcxproj as well as the corresponding solution file tutorial_01-poisson.vc17.sln residing in the tutorials directory:
```
vc17-gen.py -app tutorials\tutorial_01_poisson.cpp
```
From here on, it's pretty much the same steps as in the previous example.

Generating Kernel Unit-Test Projects

The basic command to generate a project file for a kernel unit test is:

vc17-gen.py -test <test-source-path...>

This command will create a directory named testing in the FEAT root directory, which contains the corresponding project and solution file, possibly in a sub-directory that coincides with the path of the test source file within the kernel subdirectory.

Example:
To generate a project file for the tiny_algebra-test, which is implemented in the source file kernel\util\tiny_algebra-test.cpp, you will need to perform the following steps:

Open a console in the FEAT root directory.
Enter the following command to create the project file tiny_algebra-test.vc17.vcxproj as well as the corresponding solution file tiny_algebra-test.vc17.sln residing in the testing\util directory:
```
vc17-gen.py -test kernel\util\tiny_algebra-test.cpp
```
Open the solution file testing\util\tiny_algebra-test.vc17.sln
Note: In constrast to application projects, unit test projects also contain some additional source files which may be required by some tests, but which are not compiled into the kernel, so they have to be compiled by the unit test project instead.
Choose a build configuration, e.g. the debug configuration namend dbg for the 64-bit platform x64.
Build the solution.
The resulting executable test binary tiny_algebra-test.vc17-dbg-x64.exe will appear in the win sub-directory of the FEAT root directory.

The kernel Project file

All solution files generated by the vc17-gen.py tool contain two projects: one project for the actual target binary as well as one project for the FEAT kernel library named kernel.vc17. This kernel project file is not generated by the vc17-gen.py tool – it is a hand-written project file that is located in the kernel directory and it is shared among all target applications.

Attention: Do not add or remove files to/from the kernel project file! This project is configured to automatically include all relevant source and header files within the kernel directory, i.e. the project will detect new or deleted files automatically without any explicit modification from the user after it has been reloaded.; Furthermore, it is highly recommended to leave the compiler options specified in the kernel project unchanged.

Build Configurations and Platforms

The project and solution files generated by the vc17-gen.py script contain a set of supported build configurations and platforms, which can be selected in the Visual Studio IDE to specify the build target. Currently, the only supported platform is the x64 platform; support for the 32-bit x86 platform has been discontinued by FEAT and the ARM platform is not yet supported.

The set of supported build configurations is given as thew cross-product of various enabled features, where the name of the build configuration is a string containing tags, which represent the corresponding features. This is quite similar to the build-id concept of the configure script for Lunix systems.

The list of all supported (and currently disabled) features is:

dbg: generate a debug binary (mutually exclusive with opt)
opt: generate an optimized binary (mutually exclusive with dbg)
mpi: build with MPI support (requires MS-MPI to be installed)
cuda build with Nvidia CUDA support (requires Nvidia CUDA 12.0 or newer to be installed)
mkl: build with Intel MKL support (requires Intel oneAPI MKL 2024 or newer to be installed)
omp: build with OpenMP support

So, for example the configuration dbg represents a simple debug build without any additional features such as MPI or CUDA, whereas opt-mpi represents an optimized build including MPI support.

The filename of a compiled application binary is then concatenated of the project name, the build configuration and the target platform. This enables you to compile and use various build configurations for different target platforms side-by-side without having to recompile.

For example, the application binary filename tutorial-01-poisson.vc17-dbg-mpi-x64.exe represents:

the binary of the project tutorial-01-poisson
compiled with the vc17 compiler (aka Visual C++ 2022)
build with the dbg-mpi configuration
for the x64 target platform

Author: Peter Zajac

Table of Contents