Building emNet PC tools with CMake

This guide covers the steps to build the PC tools shipped with emNet as well as other related products such as emWeb. To provide cross-platform support for our projects we use the build file generator CMake that is capable of providing you with make files and projects for various other command line build tools and like nmake or projects for IDEs such as Visual Studio and a series of compiler toolchains that can be used with them.

The emNet PC tools aim for cross-platform compatibility and being able to be built and modified without requiring additional costly licenses like a Visual Studio license or being dependent on a specific IDE or compiler toolchain at all if you are already used to work with your preferred solution. This guide focuses on using freely available tools only. The following instructions can however be used with almost no effort to cover a wide variety of other tools.

While targeting mainly Windows (32-bit) usage in this guide, the steps apply in similar fashion to other platforms like Linux as well. All tools referenced in this guide are typically available for the major Linux distributions such as Ubuntu, Debian, Red Hat and others, often directly from their respective packet managers.

Requirements

The following tools are used in this guide:

• CMake as build file generator.
• mingw-w64 (prebuilt binaries) as free compiler toolchain.
  Version used in this guide: i686-15.2.0-release-win32-dwarf-ucrt-rt_v13-rev1.7z mingw-w64 prebuilt binaries by GitHub user niXman.
• Visual Studio Code (VS Code) as free code editor and IDE (using free extensions and external compiler toolchain).
• C/C++ Extension Pack for VS Code.

Generic preparations

The following steps are required regardless of choosing the command line way or using VS Code to generate and build a CMake project.

Install CMake

Download CMake (for example the "Windows x64 Installer" package).

Install CMake and let the installer add CMake to the PATH environment variable.

This allows you to call it from everywhere by simply using the command

cmake

Test your CMake installation by executing the following command in a terminal:

cmake --version

This should give you an output similar to this one:

Install mingw-w64

Download mingw-64 and extract/install it to your disk, preferably to a path without spaces.

Add the "bin" folder of the extracted mingw-w64 toolchain to your user or system PATH variable to allow you to simply call it from everywhere.

For this to do, open your System Properties dialog for example by searching for "environment variables" in the start menu.

In the System Properties dialog click the "Environment Variables..." buttons.

Edit the "Path" variable for all users ("System variables") or your own user only, either by double clicking it or selecting it and clicking the "Edit..." button.

Click the "New" button and add the path to your extracted mingw-w64 "bin" folder.

Test your mingw-w64 installation by executing the following command in a terminal:

i686-w64-mingw32-gcc --version

This should give you an output similar to this one:

Creating a project with CMake on the command line

Open a terminal for a folder that contains a "CMakeLists.txt" file. Please be aware that a prebuilt binary might already be shipped.
Despite the new binary will be built in a subfolder, you might prefer to delete the prebuilt one to avoid any confusion which one is old and which one has been recently built by you.

In the terminal, execute the following CMake command to create build files to be used with mingw-w64.

cmake -B ./build_cmdline -S . -G "MinGW Makefiles"

This should give you an output similar to this one:

The parameters used in the example are as follows:

-B <build folder>
-S <source folder>
-G <type of build/project files to generate>

If omitting the "-G" parameter, CMake will choose the first toolchain/IDE on your system it detects, such as a Microsoft Visual Studio installation and create a project for it.

Please be aware that using CMake from an IDE such as VS Code might be using the build folder "./build" by default. To not overwrite it when using CMake from such an IDE, it is therefore suggested to specific a build folder other than "./build".
This should result in the folder containing the "CMakeLists.txt" file to look similar to this:

Building a project with CMake and mingw-w64 on the command line

If not open anymore, open a terminal for the folder that contains the "CMakeLists.txt" file as well as the generated build files in the "build_cmdline" folder.

In the terminal, execute the following CMake command to build the project using the make files in the folder "./build_cmdline".

cmake --build ./build_cmdline

This should give you an output similar to this one:

This should result in an executable being successfully built in the "build_cmdline" folder.

Using CMake with VS Code

Download and install VS Code.

Open VS Code and open the "Extensions" sidebar.

Search for the extension package C/C++ Extension Pack officially provided by Microsoft and install it.
Besides C/C++ related extensions this package also contains the CMake Tools extension provided by Microsoft.

Now open a project folder using "File"->"Open Folder..." from the menu and select a folder that contains a "CMakeLists.txt" file.

When being asked if you trust the files in this folder, select "Yes, I trust the authors". This is necessary to allow CMake to be executed for this folder.

CMake should automatically detect the "CMakeLists.txt" file and ask you for the compiler toolchain to use.

After this, CMake should automatically generate all files necessary for building the project.

Switch to the "CMake" sidebar for an overview of the project from CMake's perspective.

The "PROJECT OUTLINE" section shows you the build targets generated by CMake.
You can either right click a specific target and click "Build". Alternative you can press [F7] to build the default target of the project.

To debug the project, it is advised to right click the target you want to debug and select "Debug" from the popup menu.
This way you do not need a "launch.json" that tells VS Code what to launch and debug and you can start right away.

You might have to manually switch to the "TERMINAL" output tab to see outputs from the program.

Debugging in VS Code works similar to other Visual Studio IDEs or other IDEs in general, by opening a source file used by the built project and setting a breakpoint (shortcut [F9]).