02d CMake Configuration Options

CMake Configuration Options for Areg SDK

This guide describes all CMake configuration options for building Areg SDK, including compiler selection, build customization, output directories, and installation settings.

Important

Configuration options are set in user.cmake or via command-line arguments. Command-line options take precedence.

---

Table of Contents

1. Quick Configuration Examples
2. Complete Options Reference
3. Options by Category
4. Detailed Option Descriptions
5. Advanced Configuration
6. Integration Examples

---

Quick Configuration Examples

Common Build Configurations

1. Default build (GCC, Release, all features):

cmake -B ./build
cmake --build ./build -j20

2. Debug build with Clang:

cmake -B ./build -DAREG_COMPILER_FAMILY=llvm -DAREG_BUILD_TYPE=Debug
cmake --build ./build -j20

3. Release build without examples or tests:

cmake -B ./build -DAREG_BUILD_TYPE=Release -DAREG_BUILD_EXAMPLES=OFF -DAREG_BUILD_TESTS=OFF
cmake --build ./build -j20

4. Static library build:

cmake -B ./build -DAREG_BINARY=static -DAREG_LOGGER_BINARY=static
cmake --build ./build -j20

5. Cross-compile for ARM:

cmake -B ./build -DAREG_PROCESSOR=arm -DAREG_COMPILER_FAMILY=gnu
cmake --build ./build -j20

6. Build and install to custom location:

cmake -B ./build -DAREG_INSTALL=ON -DAREG_INSTALL_PATH=/opt/areg
cmake --build ./build -j20
sudo cmake --install ./build

↑ Back to top ↑

---

Complete Options Reference

All 22 CMake configuration options for Areg SDK:

#	Option	Values	Default	Description
1	AREG_COMPILER_FAMILY	gnu, llvm, msvc, cygwin	System default	Compiler family selection
2	AREG_COMPILER	Compiler name/path	System default	Specific compiler executable
3	AREG_TARGET	Architecture string	System default	Compiler architecture target
4	AREG_PROCESSOR	x86, x64, arm, aarch64	System default	Target CPU architecture
5	AREG_BINARY	shared, static	shared	Areg framework library type
6	AREG_LOGGER_BINARY	shared, static	shared	Logger library type
7	AREG_BUILD_TYPE	Debug, Release	Release	Build configuration
8	AREG_BUILD_TESTS	ON, OFF	ON	Build unit tests
9	AREG_BUILD_EXAMPLES	ON, OFF	ON	Build example applications
10	AREG_EXTENDED	ON, OFF	OFF	Build extended library
11	AREG_LOGS	ON, OFF	ON	Enable logging
12	AREG_USE_PACKAGES	ON, OFF	ON	Use system packages
13	AREG_SQLITE_PACKAGE	ON, OFF	ON	Use system SQLite3
14	AREG_GTEST_PACKAGE	ON, OFF	ON	Use system Google Test
15	AREG_ENABLE_OUTPUTS	ON, OFF	ON	Use Areg output paths
16	AREG_BUILD_ROOT	Directory path	<areg-sdk>/product	Root build directory
17	AREG_OUTPUT_DIR	Directory path	Auto-generated	Output directory
18	AREG_OUTPUT_BIN	Directory path	{AREG_OUTPUT_DIR}/bin	Executable output
19	AREG_OUTPUT_LIB	Directory path	{AREG_OUTPUT_DIR}/lib	Library output
20	AREG_PACKAGES	Directory path	{CMAKE_BINARY_DIR}/packages	Packages directory
21	AREG_INSTALL	ON, OFF	ON	Enable installation
22	AREG_INSTALL_PATH	Directory path	<user-profile>/areg-sdk	Installation directory

↑ Back to top ↑

---

Options by Category

For easier navigation, options are grouped by purpose:

Compiler and Processor Options

#	Option	Short Description
1	AREG_COMPILER_FAMILY	Select C++ compiler by family
2	AREG_COMPILER	Select C++ compiler by name
3	AREG_TARGET	Compiler architecture target
4	AREG_PROCESSOR	Target processor and bitness

Build Configuration Options

#	Option	Short Description
5	AREG_BINARY	areg library type (shared/static)
6	AREG_LOGGER_BINARY	areglogger library type
7	AREG_BUILD_TYPE	Debug or Release build
8	AREG_BUILD_TESTS	Build or skip unit tests
9	AREG_BUILD_EXAMPLES	Build or skip examples
10	AREG_EXTENDED	Build aregextend library
11	AREG_LOGS	Build binaries with logs

Package Management Options

#	Option	Short Description
12	AREG_USE_PACKAGES	Use installed packages when possible
13	AREG_SQLITE_PACKAGE	Try using installed SQLite3
14	AREG_GTEST_PACKAGE	Try using installed Google Test

Output Directory Options

#	Option	Short Description
15	AREG_ENABLE_OUTPUTS	Allow Areg-specific output paths
16	AREG_BUILD_ROOT	Build root directory
17	AREG_OUTPUT_DIR	Output directory for binaries
18	AREG_OUTPUT_BIN	Executable output directory
19	AREG_OUTPUT_LIB	Static library output directory
20	AREG_PACKAGES	Third-party packages directory

Installation Options

#	Option	Short Description
21	AREG_INSTALL	Enable install target
22	AREG_INSTALL_PATH	Installation location

↑ Back to top ↑

---

Detailed Option Descriptions

1. AREG_COMPILER_FAMILY

Description: Select compiler family for C++ and C sources.

Possible Values:

• gnu - GCC compiler family (g++, gcc)
• llvm - LLVM/Clang compiler family (clang++, clang)
• msvc - Microsoft Visual C++ (cl)
• cygwin - GCC for Cygwin on Windows

Default: gnu on Linux/Cygwin, msvc on Windows
Example:

cmake -B ./build -DAREG_COMPILER_FAMILY=llvm

Note

This option is ignored if CMAKE_CXX_COMPILER is set and user.cmake is included after the first project() call.

↑ Back to options ↑

---

2. AREG_COMPILER

Description: Specify exact compiler executable by name or full path.
Possible Values: g++, gcc, clang++, clang, c++, cc, cl, clang-cl, or full path
Default: System default compiler
Example:

cmake -B ./build -DAREG_COMPILER=/usr/bin/clang++-14

Note

Setting CMAKE_CXX_COMPILER directly achieves the same effect. If CMAKE_CXX_COMPILER is set and user.cmake is included after project(), this option is ignored.

↑ Back to options ↑

---

3. AREG_TARGET

Description: Specify compiler architecture target for cross-compilation.
Possible Values: i386-linux-gnu, x86_64-linux-gnu, arm-linux-gnueabihf, arm-linux-gnueabi, aarch64-linux-gnu, and other compiler-specific targets
Default: System-defined
Example:

cmake -B ./build -DAREG_TARGET=arm-linux-gnueabihf -DAREG_PROCESSOR=arm

Note

This value is identical to CMAKE_CXX_COMPILER_TARGET and affects package and library location paths.

↑ Back to options ↑

---

4. AREG_PROCESSOR

Description: Target processor architecture and bitness for compiled applications.
Possible Values:

• x86 - 32-bit x86
• x64 (or x86_64, amd64) - 64-bit x86
• arm (or arm32) - 32-bit ARM
• aarch64 (or arm64) - 64-bit ARM

Default: System-defined
Example:

cmake -B ./build -DAREG_PROCESSOR=x86

Note

The value may be ignored depending on compiler selection and when user.cmake is included. For instance, setting AREG_PROCESSOR=arm with AREG_COMPILER_FAMILY=gnu when user.cmake is included after project() may build for the host processor using default compiler settings.

Tip

To verify binary architecture, navigate to build directory and run:

file ./mtrouter.elf

Example output for 32-bit:

./mtrouter.elf: ELF 32-bit LSB pie executable, Intel 80386, version 1 (GNU/Linux), ...

Or check ELF header:

od -t x1 -t c ./mtrouter | head -n 2

The 5th byte indicates bitness: 01 = 32-bit, 02 = 64-bit

0000000  7f  45  4c  46  01  01  01  00  00  00  00  00  00  00  00  00
        177   E   L   F 001 001 001  \0  \0  \0  \0  \0  \0  \0  \0  \0

For more information, see ELF Header documentation.

↑ Back to options ↑

---

5. AREG_BINARY

Description: Specify Areg framework library type.
Possible Values:

• shared - Dynamic library (.so, .dll)
• static - Static library (.a, .lib)

Default: shared
Example:

cmake -B ./build -DAREG_BINARY=static

↑ Back to options ↑

---

6. AREG_LOGGER_BINARY

Description: Specify log observer API library type.
Possible Values:

• shared - Dynamic library
• static - Static library

Default: shared
Example:

cmake -B ./build -DAREG_LOGGER_BINARY=static

↑ Back to options ↑

---

7. AREG_BUILD_TYPE

Description: Build configuration type, equivalent to CMAKE_BUILD_TYPE.
Possible Values:

• Release - Optimized build, no debug symbols
• Debug - Debug symbols, no optimization

Default: Release
Example:

cmake -B ./build -DAREG_BUILD_TYPE=Debug

Note

If CMAKE_BUILD_TYPE is set and user.cmake is included after project(), this option is ignored and CMAKE_BUILD_TYPE takes precedence.

↑ Back to options ↑

---

8. AREG_BUILD_TESTS

Description: Enable or disable building unit tests.
Possible Values: ON, OFF
Default: ON
Dependencies: Requires Google Test (fetched automatically if AREG_GTEST_PACKAGE=OFF)
Example:

cmake -B ./build -DAREG_BUILD_TESTS=OFF

↑ Back to options ↑

---

9. AREG_BUILD_EXAMPLES

Description: Enable or disable building example applications.
Possible Values: ON, OFF
Default: ON
Dependencies: Some examples require MFC (Microsoft Foundation Classes) on Windows
Example:

cmake -B ./build -DAREG_BUILD_EXAMPLES=OFF

↑ Back to options ↑

---

10. AREG_EXTENDED

Description: Build aregextend library with extended features.
Possible Values: ON, OFF
Default: OFF
Dependencies: Requires ncurses library on Linux/Cygwin platforms
Example:

cmake -B ./build -DAREG_EXTENDED=ON

↑ Back to options ↑

---

11. AREG_LOGS

Description: Enable logging capabilities in Areg framework.
Possible Values: ON, OFF
Default: ON
Example:

cmake -B ./build -DAREG_LOGS=OFF

Use case: Disable logging to reduce overhead in production builds where logging isn't needed.

↑ Back to options ↑

---

12. AREG_USE_PACKAGES

Description: Enable using pre-installed system packages for dependencies.
Possible Values: ON, OFF
Default: ON
Example:

cmake -B ./build -DAREG_USE_PACKAGES=OFF

Behavior:

• ON - Use system packages if found, otherwise fetch from source
• OFF - Always build dependencies from source

↑ Back to options ↑

---

13. AREG_SQLITE_PACKAGE

Description: Use system-installed SQLite3 package.
Possible Values: ON, OFF
Default: ON
Example:

cmake -B ./build -DAREG_SQLITE_PACKAGE=OFF

Behavior:

• ON - Try system package first, fall back to thirdparty/ source
• OFF - Always use thirdparty/ source

↑ Back to options ↑

---

14. AREG_GTEST_PACKAGE

Description: Use system-installed Google Test package.
Possible Values: ON, OFF
Default: ON
Example:

cmake -B ./build -DAREG_GTEST_PACKAGE=OFF

Behavior:

• ON - Try system package first, fetch from Google repository if not found
• OFF - Always fetch from Google repository

↑ Back to options ↑

---

15. AREG_ENABLE_OUTPUTS

Description: Enable Areg-specific output directory structure.
Possible Values: ON, OFF
Default: ON
Example:

cmake -B ./build -DAREG_ENABLE_OUTPUTS=OFF

Behavior:

• ON - Use Areg-specific output paths (organized by compiler/platform)
• OFF - Use CMake default output directories

Use case: Set to OFF when integrating Areg into third-party builds with existing output structure.

↑ Back to options ↑

---

16. AREG_BUILD_ROOT

Description: Main directory for all build artifacts, third-party dependencies, and generated code.
Default: <areg-sdk>/product
Example:

cmake -B ./build -DAREG_BUILD_ROOT=/tmp/areg-build

Note: This directory and its contents can be safely deleted without affecting source code.

↑ Back to options ↑

---

17. AREG_OUTPUT_DIR

Description: Base directory for all build outputs, including binaries and libraries.
Default: {AREG_BUILD_ROOT}/build/<compiler>/<os>-<bits>-<cpu>-<build-type>-<linkage>
Example:

cmake -B ./build -DAREG_OUTPUT_DIR=/custom/output

Default structure example:

product/build/gnu-g++/linux-64-x86_64-release-shared/

↑ Back to options ↑

---

18. AREG_OUTPUT_BIN

Description: Output directory for runtime binaries and shared libraries.
Default: {AREG_OUTPUT_DIR}/bin
Example:

cmake -B ./build -DAREG_OUTPUT_BIN=/custom/bin

Corresponds to: CMAKE_RUNTIME_OUTPUT_DIRECTORY and CMAKE_LIBRARY_OUTPUT_DIRECTORY

↑ Back to options ↑

---

19. AREG_OUTPUT_LIB

Description: Output directory for static libraries.
Default: {AREG_OUTPUT_DIR}/lib
Example:

cmake -B ./build -DAREG_OUTPUT_LIB=/custom/lib

Corresponds to: CMAKE_ARCHIVE_OUTPUT_DIRECTORY

↑ Back to options ↑

---

20. AREG_PACKAGES

Description: Directory for fetched third-party packages.
Default: {CMAKE_BINARY_DIR}/packages
Example:

cmake -B ./build -DAREG_PACKAGES=/custom/packages

Contains: Google Test, SQLite3 (when fetched from source)

↑ Back to options ↑

---

21. AREG_INSTALL

Description: Enable SDK installation process.
Possible Values: ON, OFF
Default: ON
Example - Disable installation:

cmake -B ./build -DAREG_INSTALL=OFF

Example - Custom location install:

cmake -B ./build -DAREG_INSTALL=ON -DAREG_INSTALL_PATH=/opt/areg
cmake --build ./build -j20
sudo cmake --install ./build

Example - Default location install:

cmake -B ./build
cmake --build ./build -j20
sudo cmake --install ./build

↑ Back to options ↑

---

22. AREG_INSTALL_PATH

Description: Directory where Areg SDK will be installed.
Default: <user-profile>/areg-sdk
Example:

cmake -B ./build -DAREG_INSTALL_PATH=/usr/local
cmake --build ./build -j20
sudo cmake --install ./build

Installed components:

• Headers → {AREG_INSTALL_PATH}/include/
• Libraries → {AREG_INSTALL_PATH}/lib/
• Executables → {AREG_INSTALL_PATH}/bin/
• CMake config → {AREG_INSTALL_PATH}/lib/cmake/areg/

↑ Back to options ↑

---

Advanced Configuration

Print Configuration Status

Use printAregConfigStatus() to display current configuration:

include(<areg-sdk>/conf/cmake/setup.cmake)
printAregConfigStatus()

Example output:

-- =======================================================================================
-- ----------------------> AREG project CMake Status Report Begin <-----------------------
-- =======================================================================================
-- AREG: >>> CMAKE_SOURCE_DIR    = '/home/user/areg-sdk', build type 'Debug'
-- AREG: >>> Build Environment ..: System 'Linux', 64-bit 'x86_64' platform, Env 'Posix'
-- AREG: >>> Used CXX-Compiler ..: '/usr/bin/clang++'
-- AREG: >>> Used C-Compiler ....: '/usr/bin/clang'
-- AREG: >>> Compiler Version ...: C++ standard 'c++17', compiler family 'llvm'
-- AREG: >>> AREG SDK Root ......: '/home/user/areg-sdk'
-- AREG: >>> CMake Build Dir ....: '/home/user/areg-sdk/build'
-- AREG: >>> Binary Output Dir ..: '/home/user/areg-sdk/product/build/llvm-clang++/linux-64-x86_64-debug-shared/bin'
-- AREG: >>> Build Modules ......: areg = 'shared', aregextend = 'static', areglogger = 'shared'
-- AREG: >>> Java Version .......: '17.0.16', minimum version required = 17
-- AREG: >>> Packages Use .......: SQLite3 package = 'ON', GTest package = 'OFF'
-- AREG: >>> Other Options ......: Examples = 'ON', Unit Tests = 'ON', Extended = 'OFF', Logs = 'ON'
-- AREG: >>> Installation .......: Enabled = 'ON', location = '/usr/local'
-- =======================================================================================
-- -----------------------> AREG project CMake Status Report End <------------------------
-- =======================================================================================

Integration Variables

When integrating Areg SDK into other projects:

AREG_SDK_ROOT:

• Set to Areg SDK root directory before including user.cmake or setup.cmake
• In Areg SDK project, defaults to CMAKE_CURRENT_LIST_DIR

AREG_FRAMEWORK:

• When using Areg as package (e.g., vcpkg), set to include directory
• Required for header file locations

Example:

set(AREG_SDK_ROOT "/path/to/areg-sdk")
include(${AREG_SDK_ROOT}/conf/cmake/setup.cmake)

Complete Configuration Example

Build and install with all options explicitly set:

cmake -B ./build \
  -DAREG_COMPILER_FAMILY=llvm \
  -DAREG_BUILD_TYPE=Release \
  -DAREG_BUILD_TESTS=OFF \
  -DAREG_BUILD_EXAMPLES=OFF \
  -DAREG_BINARY=shared \
  -DAREG_LOGGER_BINARY=shared \
  -DAREG_EXTENDED=OFF \
  -DAREG_LOGS=ON \
  -DAREG_USE_PACKAGES=ON \
  -DAREG_INSTALL=ON \
  -DAREG_INSTALL_PATH=/usr/local

cmake --build ./build -j20

sudo cmake --install ./build

↑ Back to top ↑

---

Integration Examples

Using Areg SDK in Your Project

Option 1: System Installation

After installing Areg SDK system-wide:

find_package(areg CONFIG REQUIRED)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE areg::areg)

Option 2: Source Integration

Include Areg SDK sources directly:

set(AREG_SDK_ROOT "/path/to/areg-sdk")
include(${AREG_SDK_ROOT}/conf/cmake/setup.cmake)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE areg::areg)

Option 3: FetchContent

Fetch Areg SDK automatically:

include(FetchContent)
FetchContent_Declare(
    areg
    GIT_REPOSITORY https://github.com/aregtech/areg-sdk.git
    GIT_TAG        v1.5.0
)
FetchContent_MakeAvailable(areg)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE areg::areg)

Additional Notes

Root Directory:

• To integrate Areg SDK in other projects, set AREG_SDK_ROOT before including user.cmake or setup.cmake
• In Areg SDK project, AREG_SDK_ROOT defaults to CMAKE_CURRENT_LIST_DIR (i.e., <areg-sdk root>)

Integrating as Package:

• When using Areg via package manager (e.g., vcpkg), set AREG_SDK_ROOT to package's share directory
• Set AREG_FRAMEWORK to include directory for headers

Compiler Configuration:

• AREG_COMPILER_FAMILY automatically selects default compilers (e.g., llvm → clang++ and clang)

Target Processor:

• AREG_PROCESSOR enables cross-compilation
• See Cross-Compiling Guide for details

Custom Output Directories:

• AREG_BUILD_ROOT sets location for all build artifacts
• Aids in project organization and build cleanup

Disable Areg Outputs:

• Set AREG_ENABLE_OUTPUTS=OFF to use CMake defaults or custom output locations

↑ Back to top ↑

---

Additional Resources

Build Guides:

• CMake Build Guide - Step-by-step build instructions
• CMake Integration - Using Areg in your projects
• vcpkg Installation - Package manager installation

Configuration Files:

• user.cmake - Default configuration values
• setup.cmake - Setup utilities and functions

Examples:

• Areg SDK Demo - Integration examples
• Examples Directory - Sample applications

Help: For questions or issues, open a discussion or issue on GitHub.

↑ Back to top ↑