03. Software build
Before building the sources, clone the sources and submodules properly. The source codes of AREG SDK can be build with following tools:
| Tool | Solution | Platforms | API | Quick actions to compile |
|---|---|---|---|---|
cmake |
CMakeLists.txt |
Linux, Cygwin, Windows | POSIX, Win32 | - Build with cmake.- Build in VSCode; - Build in MSVS. |
msbuild |
areg-sdk.sln |
Windows | Win32 | - Build with msbuild.- Open and build in MSVS. |
First, you should have clone sources. Then open command line Terminal and call these commands:
Step 1: Initialize cache and build configuration in folder './build' folder. Default options: g++ compiler, release build, enabled examples and unit tests
cmake -B ./buildStep 2: Compile sources.
cmake --build ./build -j 8💡 By default, build with
cmakedoes not include examples and unit test. To enable the build of examples and unit test, the developer should set additional options when configure the build as it is shown bellow:
cmake -B ./build -DAREG_BUILD_EXAMPLES:BOOL=ON -DAREG_BUILD_TESTS:BOOL=ON
cmake --build ./build -j8To build the sources using the cmake tool, you have the flexibility to choose between Linux (POSIX API) and Windows (POSIX and Win32 API) depending on the compilers used. For building the POSIX API on Windows, you can utilize Cygwin. The supported compilers include GNU gcc/g++, LLVM clang/clang++, and Microsoft Visual C++ (MSVC). Please note that other compilers have not been tested yet.
The following table provides an overview of the compilers, platforms, APIs, and their respective compatibility:
| Compiler | Platform | API | Notes |
|---|---|---|---|
| GNU gcc/g++ | Linux, Cygwin (Windows) | POSIX | Compilation under Windows requires Cygwin |
| LLVM clang/clang++ | Linux | POSIX | Compiles only under Linux |
| MSVC (cl) | Windows | Win32 | Compiles only under Windows |
By default, cmake is configured with the following settings:
- Build the framework and multi-cast router.
- A shared library for AREG framework.
- Release build mode.
- Build of examples and unit tests are disabled.
-
areg-extendis included without extra dependencies.
The compiler type, platform, bitness, and CPU are automatically detected. The compiler is set to GNU g++ for Linux, Cygwin g++ for Cygwin on Windows, and MSVC for Windows. The binary files are located in the path <areg-sdk>/product/build/<compiler>/<platform>-<bitness>-<cpu>-release/bin. Here, <compiler> can have one of the following values: gnu-g++, cygwin-g++, or msvc-cl.
You have the option to customize the build settings according to your project requirements. CMake supports several command-line options that can be used:
| Option | Default | Description |
|---|---|---|
| AREG_COMPILER_FAMILY | gnu |
Sets the C++ and C compilers based on the selected family. |
| AREG_COMPILER | g++ |
Sets the specific compiler for the C++ compiler variable (CMAKE_CXX_COMPILER). |
| AREG_BINARY | shared |
Defines the type of AREG framework library. |
| AREG_BUILD_TYPE | Release |
Specifies the build configuration for the sources. |
| AREG_BUILD_TESTS | OFF |
Indicates whether to build the unit tests. |
| AREG_BUILD_EXAMPLES | OFF |
Indicates whether to build the examples. |
| AREG_EXTENDED | OFF |
Enables or disables extended features in the areg-extend static library. |
| AREG_LOGS | ON |
Indicates whether to compile the source codes with or without logs. |
| AREG_BUILD_ROOT | product |
The root directory for project(s) to build. |
| AREG_OUTPUT_DIR | product/... |
Specifies the path to the folder where the output binaries will be located. |
| AREG_OUTPUT_BIN | product/... |
Specifies the path to the folder where the runtime binaries will be located. |
| AREG_OUTPUT_LIB | product/... |
Specifies the path to the folder where the static libraries will be located. |
Here are a couple of examples demonstrating the usage of cmake with different options:
Example 1: Initializes cache and configures a Debug build of binaries linked with a static AREG framework using LLVM clang++/clang compilers, and disables logs.
Step 1: Initialize cache and configure the build:
cmake -B ./build -DAREG_COMPILER_FAMILY=llvm -DAREG_BINARY=static -DAREG_BUILD_TYPE=Debug -DAREG_LOGS:BOOL=OFFStep 2: Build the project with 10 parallel jobs:
cmake --build ./build -j 10Example 2: Initializes cache and configures a Debug build of binaries with the gcc compiler, enables extension features, and changes the location of the resulting binaries:
Step 1: Initialize cache and configure the build:
cmake -B ./build -DAREG_COMPILER=gcc -DAREG_EXTENDED:BOOL=ON -DAREG_OUTPUT_BIN="~/builds/areg/"Step 2: Build the project with 10 parallel jobs:
cmake --build ./build -j 10💡 For additional examples demonstrating various
cmakeoptions, you can refer to the CMake Workflow file in the AREG SDK repository.
To quickly build the AREG SDK using msbuild, follow these steps:
- Make sure you have properly cloned the AREG SDK sources.
- Open the command line terminal.
- Navigate to the directory where the AREG SDK solution file (
areg-sdk.sln) is located. - Run the following command:
msbuild areg-sdk.sln💡 Please note that this assumes you have
msbuildproperly installed and added to your system's PATH.
When using msbuild with the AREG SDK, you have the flexibility to customize the build process by utilizing the available options. Here are the options that you can use:
| Option | Default | Description |
|---|---|---|
| Configuration | Debug |
Specifies the build configuration for the sources. |
| Platform | Win32 |
Specifies the target platform architecture: 32-bit or 64-bit platforms. |
| AregExtended | 0 |
Enables or disables extended features in the areg-extend static library. |
| AregLogs | 1 |
Indicates whether to compile the source codes with or without logs. |
Here are a couple of examples demonstrating the usage of msbuild with different configurations:
Example 1: This example builds a 64-bit Debug build with enabled extended features and no logs:
msbuild /m /property:Configuration=Debug /property:Platform=x64 /property:AregExtended=1 /property:AregLogs=0 ./areg-sdk.slnExample 2: This example builds a 32-bit Release build with disabled extended features and no logs:
msbuild /m /property:Configuration=Release /property:Platform=Win32 /property:AregExtended=0 /property:AregLogs=0 ./areg-sdk.slnPlease ensure that you adjust the paths and options based on your specific setup and requirements.
💡 For more examples utilizing various
msbuildoptions, you can refer to the MSBuild Workflow file in the AREG SDK repository.
If you prefer using an IDE for building the AREG SDK and examples, you can follow the instructions below to build with Microsoft Visual Studio or Visual Studio Code. Please note that currently, other IDEs are not supported by the AREG SDK. After compilation you may run and/or debug examples and unit tests.
- Open the
areg-sdk.slnfile in Microsoft Visual Studio. - Build the solution using the MSVC compiler.
- Open the
areg-sdkfolder in Visual Studio Code. - In the Explorer panel, locate the
CMakeLists.txtfile. - Right-click on the file and choose Configure All Projects from the context menu. Wait for the configuration process to complete.
- Right-click on the file again and select Build All Projects to build the sources using the default options.
By following these instructions, you will be able to successfully build the AREG SDK and examples using your preferred IDE.
The Windows Subsystem for Linux (WSL) provides developers with the ability to use Linux applications directly on Windows machines. This enables developers to clone, compile, and use the AREG engine in popular Linux distributions. To install and update WSL on your Windows machine, and to clone, compile, and run examples using the AREG SDK sources, please follow the step-by-step instructions provided in the "Compile in Windows Subsystem for Linux (WSL)" Wiki page. This page contains detailed instructions to help you set up and configure WSL, clone the AREG SDK sources, and compile source codes and run examples within the Linux environment.