Skip to content

03. Software build

Jump to bottom
Aregtech edited this page May 27, 2023 · 10 revisions

Table of contents

  1. General Information
  2. Build with CMake
  3. Build with Make
  4. Build with MSBuild
  5. Build with IDEs
  6. Build with WSL

General information

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.
make Makefile Linux, Cygwin POSIX    - Build with make.
msbuild areg-sdk.sln Windows Win32    - Build with msbuild.
   - Open and build in MSVS.

Build with CMake (CMakeLists.txt)

cmake quick build

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 ./build

Step 2: Compile sources.

cmake --build ./build -j 8

cmake details

You can build the sources with cmake tool for Linux (POSIX API) and Windows (POSIX and Win32 API), depending on used compilers. Use Cygwin to make POSIX API build under Windows. The supported compilers are: GNU gcc / g++, LLVM clang / clang++, Microsoft Visual C++ (MSVC). The other compilers were not tested yet.

Compiler Platform API Notes
GNU gcc/g++ Linux, Cygwin (Windows) POSIX The compilation under Windows requires Cygwin
LLVM clang/clang ++ Linux POSIX Compiles only under Linux
MSVC (cl) Windows Win32 Compiles only under Windows

CMake default settings: AREG shared library, Release build, which include examples, unit tests, framework, including areg-extensions without extra dependencies. The compiler type, platform, bitness and the CPU are automatically detected, where compilers are set for for Linux it is GNU g++, for Cygwin it is Cygwin g++, and Windows it is MSVC. The binaries are located in the path <areg-sdk>/product/build/<compiler>/<platform>-<bitness>-<cpu>-release/bin, where <compiler> is one of values: gnu-g++, cygwin-g++ or msvc-cl.

It is possible to change the build settings, so that the projects may integrate areg-sdk in their codes or can start a new project based in areg-sdk. The CMake supports several options, which can be passed via command line:

Option Default Description
AREG_COMPILER_FAMILY gnu Sets the C++ and C compilers based on the selected family.
Possible values:
   - gnu: Sets g++ and gcc compilers.
   - llvm: Sets clang++ and clang compilers.
   - cygwin: Sets g++ and gcc compilers of CYGWIN for Windows.
   - msvc: Sets msvc compiler to build under Windows.
AREG_COMPILER g++ Sets the specific compiler for the C++ compiler variable (CMAKE_CXX_COMPILER). The C compiler variable (CMAKE_C_COMPILER) is set to the same compiler or from the same family.
Possible values: g++, gcc, clang++, and clang.
AREG_BINARY shared Defines the type of AREG framework library.
Possible values: shared or static.
AREG_BUILD_TYPE Release Specifies the build configuration for the sources.
Possible values: Debug or Release.
AREG_BUILD_TESTS ON Indicates whether to build the unit tests. Setting it to OFF skips building the unit tests.
Possible values: ON or OFF.
AREG_BUILD_EXAMPLES ON Indicates whether to build the examples. Setting it to OFF skips building the examples.
Possible values: ON or OFF.
AREG_EXTENDED OFF Enables or disables building the areg-extensions static library with extended features. Setting it to OFF builds the library without extended features and without extra dependencies, but some functionalities may not work as expected.
Possible values: ON or OFF.
AREG_LOGS ON Indicates whether to compile the source codes with or without logs. Setting it to OFF excludes logs from the build.
Possible values: ON or OFF.
AREG_OUTPUT_DIR product/... Specifies the full path to the folder where the output binaries will be located. The default location is <areg-sdk>/product/build/.../, with the actual path depending on the compiler, platform, CPU, bitness, and build type. Use this option to change the output directory.
AREG_OUTPUT_BIN product/... Specifies the full path to the folder where the runtime binaries will be located. The default location is <areg-sdk>/product/build/.../bin, with the actual path depending on the compiler, platform, CPU, bitness, and build type. Use this option to change the location of the runtime binaries.
AREG_OUTPUT_LIB product/... Specifies the full path to the folder where the static libraries will be located. The default location is <areg-sdk>/product/build/.../lib, with the actual path depending on the compiler, platform, CPU, bitness, and build type. Use this option to change the location of the static libraries.

Example 1: This example initializes cache and configures to make Debug build of binaries linked with static AREG framework with LLVM clang ++ / clang compilers, and no logs.
Step 1: Initialize cache and configure build:

cmake -B ./build -DAREG_COMPILER_FAMILY=llvm -DAREG_BINARY=static -DAREG_BUILD_TYPE=Debug -DAREG_LOGS:BOOL=OFF

Step 2: Run the build with 10 parallel jobs:

cmake --build build -j 10

Example 2: This example initializes cache and configures to make Debug build of binaries with gcc compiler and enabled extension features, and the resulting binaries location is changed:
Step 1: Initialize cache and configure build:

cmake -B ./build -DAREG_COMPILER=gcc -DAREG_EXTENDED:BOOL=ON -DAREG_OUTPUT_BIN="~/builds/areg/"

Step 2: Run the build with 10 parallel jobs:

cmake --build build -j 10

💡 Another example of using various cmake options can be found in CMake Workflow file.

Build with Make (Makefile)

make quick build

First, you should have clone sources. Then open command line Terminal and call these command to build applications. Default options: g++ compiler, release build, enabled examples and unit tests:

make -j8

make details

You can build the sources with make tool for Linux and Windows using POSIX API. Use Cygwin and GNU compilers to make build under Windows. The supported compilers are: GNU gcc / g++, LLVM clang / clang++. Microsoft Visual C++ (MSVC) compiler is not supported and the other compilers were not tested yet.

💡 The build with make does not support unit tests, it might be deprecated.

Compiler Platform API Notes
GNU gcc/g++ Linux, Cygwin (Windows) POSIX The compilation under Windows requires Cygwin
LLVM clang/clang ++ Linux POSIX Compiles only under Linux

Make default settings: AREG shared library, Release build, which include examples, framework, including areg-extensions without extra dependencies. The compiler type, platform, bitness and the CPU are automatically detected, where compilers are set for for Linux it is GNU g++, for Cygwin it is Cygwin g++. The binaries are located in the path <areg-sdk>/product/build/<compiler>/<platform>-<bitness>-<cpu>-release/bin, where <compiler> is a value like these: gnu-g++, cygwin-g++ or msvc-cl.

It is possible to change the build settings, so that the projects may integrate areg-sdk in their codes or can start a new project based in areg-sdk. The make supports several options, which can be passed via command line:

Option Default Description
AREG_COMPILER_FAMILY gnu Sets the C++ and C compilers based on the selected family.
Possible values:
   - gnu: Sets g++ and gcc compilers.
   - llvm: Sets clang++ and clang compilers.
   - cygwin: Sets cygwin g++ and cygwin gcc compilers.
AREG_COMPILER g++ Sets the specific compiler for the C++ compiler variable (CMAKE_CXX_COMPILER). The C compiler variable (CMAKE_C_COMPILER) is set to the same compiler or from the same family.
Possible values: g++, gcc, clang++, and clang.
AREG_BINARY shared Defines the type of AREG framework library.
Possible values: shared or static.
AREG_BUILD_TYPE Release Specifies the build configuration for the sources.
Possible values: Debug or Release.
AREG_EXTENDED 0 Enables or disables building the areg-extensions static library with extended features. Setting it to 0 builds the library without extended features and without extra dependencies, but some functionalities may not work as expected.
Possible values: 1 or 0.
AREG_LOGS 1 Indicates whether to compile the source codes with or without logs. Setting it to 0 excludes logs from the build.
Possible values: 1 or 0.
AREG_OUTPUT_DIR product/... Specifies the full path to the folder where the output binaries will be located. The default location is <areg-sdk>/product/build/.../, with the actual path depending on the compiler, platform, CPU, bitness, and build type. Use this option to change the output directory.
AREG_OUTPUT_BIN product/... Specifies the full path to the folder where the runtime binaries will be located. The default location is <areg-sdk>/product/build/.../bin, with the actual path depending on the compiler, platform, CPU, bitness, and build type. Use this option to change the location of the runtime binaries.
AREG_OUTPUT_LIB product/... Specifies the full path to the folder where the static libraries will be located. The default location is <areg-sdk>/product/build/.../lib, with the actual path depending on the compiler, platform, CPU, bitness, and build type. Use this option to change the location of the static libraries.

Example 1: This example demonstrates how to build the AREG framework (only) in Debug mode using LLVM clang++ / clang compilers, producing a static library:

make framework AREG_COMPILER_FAMILY=llvm AREG_BINARY=static AREG_BUILD_TYPE=Debug -j10

Example 2: This example demonstrates how to build all binaries in Debug mode using the gcc compiler with enabled extended features, and specifying a custom output location for the resulting binaries:

make AREG_COMPILER=gcc AREG_EXTENDED=1 AREG_OUTPUT_BIN="~/builds/areg/" -j10

💡 Another example of using various make options can be found in C/C++ CI Workflow file.

Build with MSBuild (areg-sdk.sln)

msbuild Quick Build

To quickly build the AREG SDK using msbuild, follow these steps:

  1. Make sure you have properly cloned the AREG SDK sources.
  2. Open the command line terminal.
  3. Navigate to the directory where the AREG SDK solution file (areg-sdk.sln) is located.
  4. Run the following command:
msbuild areg-sdk.sln

💡 Please note that this assumes you have msbuild properly installed and added to your system's PATH.

msbuild details

When using msbuild with the AREG SDK, you have a few options to customize the build. Here are the available options:

Option Default Description
Configuration Debug Specifies the build configuration for the sources.
Possible values: Debug or Release.
Platform Win32 Specifies the target platform architecture: 32-bit or 64-bit platforms.
Possible values: Win32 or x64.
AregExtended 0 Enables or disables building the areg-extensions static library with extended features. Setting it to 0 builds the library without extended features and without extra dependencies, but some functionalities may not work as expected.
Possible values: 1 or 0.
AregLogs 1 Indicates whether to compile the source codes with or without logs. Setting it to 0 excludes logs from the build.
Possible values: 1 or 0.

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

Example 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.sln

Make sure to adjust the paths and options according to your specific setup and requirements.

Building with IDEs

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.

Build with Microsoft Visual Studio

  1. Open the areg-sdk.sln file in Microsoft Visual Studio.
  2. Build the solution using the MSVC compiler.

Build with Visual Studio Code

  1. Open the areg-sdk folder in Visual Studio Code.
  2. In the Explorer panel, locate the CMakeLists.txt file.
  3. Right-click on the file and choose Configure All Projects from the context menu. Wait for the configuration process to complete.
  4. 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.

Build with WSL

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.

Help us to make docs greater: See something is wrong, unclear or need a help? Submit a change, open a discussion or ask AREG SDK community a question.

2023 © Aregtech, www.aregtech.com, email: info[at]aregtech.com

Quick links

  1. Clone source codes
  2. Preprocessor define symbols
  3. Software build
  4. Build with WSL
  5. AREG Logging System
  6. AREG Multicast Router
  7. Persistence Syntax
  8. Setup a Project

Help to make docs greater!

Clone this wiki locally