Skip to content

03. Software build

Jump to bottom
Aregtech edited this page Aug 23, 2023 · 8 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

💡 By default, build with cmake does 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 -j8

cmake details

To 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-extend is 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=OFF

Step 2: Build the project with 10 parallel jobs:

cmake --build ./build -j 10

Example 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 cmake options, you can refer to the CMake Workflow file in the AREG SDK repository.

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 use the make tool to build the AREG sources on both Linux and Windows platforms, utilizing the POSIX API. For building on Windows, you will need to use Cygwin along with GNU compilers. Please note that the Microsoft Visual C++ (MSVC) compiler is not supported, and compatibility with other compilers has not been tested yet.

The following table summarizes the supported compilers, platforms, and APIs:

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

The default make settings include building the AREG framework as a shared library in the Release build mode. The build includes examples and the framework itself, including the areg-extend module without additional dependencies. The compiler type, platform, bitness, and CPU are automatically detected. For Linux, the compiler is set to GNU g++, and for Cygwin on Windows, it is set to Cygwin g++. The resulting binary files are located in the path <areg-sdk>/product/build/<compiler>/<platform>-<bitness>-<cpu>-release/bin, where <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. The make tool supports several command-line options that can be passed:

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_EXTENDED 0 Enables or disables extended features in the areg-extend static library.
AREG_LOGS 1 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 make with different options:

Example 1: This example demonstrates how to build only the AREG framework 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 utilizing various make options can be found in the C/C++ CI Workflow file of the AREG SDK repository.

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

Please ensure that you adjust the paths and options based on your specific setup and requirements.

💡 For more examples utilizing various msbuild options, you can refer to the MSBuild Workflow file in the AREG SDK repository.

Build 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