Skip to content

02. Preprocessor define symbols

Jump to bottom
Aregtech edited this page Aug 23, 2023 · 10 revisions

Table of contents

  1. General Information
  2. POSIX define
  3. WINDOWS define
  4. DEBUG and NDEBUG defines
  5. EXP_AREG_DLL and EXP_AREG_LIB defines
  6. IMP_AREG_DLL and IMP_AREG_LIB defines
  7. AREG_EXTENDED define
  8. AREG_LOGS define

General Information

The AREG SDK utilizes preprocessor-defined symbols to configure the compilation of the framework and applications in a clear and professional manner. These symbols allow for easy customization and adjustment of the compilation process. Here is a description of the available preprocessor defines and their meanings:

Preprocessor Description and Meaning
POSIX Compiles the sources with the POSIX API. Further details can be found in POSIX.md.
WINDOWS Compiles the sources with the Win32 API. Further details can be found in WIN32.md.
DEBUG Compiles the Debug configuration.
NDEBUG Compiles the Release configuration.
EXP_AREG_LIB Builds the AREG framework as a static library (equivalent to EXPORT_STATIC_SYMBOLS).
EXP_AREG_DLL Builds the AREG framework as a shared library (equivalent to EXPORT_SHARED_SYMBOLS).
IMP_AREG_LIB Links with the static AREG framework library (equivalent to IMPORT_STATIC_SYMBOLS).
IMP_AREG_DLL Links with the shared AREG framework library (equivalent to IMPORT_SHARED_SYMBOLS).
AREG_EXTENDED Builds the areg-extend static library with or without extended features.
AREG_LOGS Compiles the source codes with logs.

These preprocessor-define symbols can be set in multiple ways:

  • In the Makefile or CMakeLists.txt files.
  • In the project properties of Microsoft Visual Studio.
  • In the user.props, user.cmake, or user.mk files, depending on the chosen toolchain. Changes made in these files have a global effect.

💡 Before proceeding with any example, open the command line Terminal in the root folder of the areg-sdk.

POSIX define

The POSIX preprocessor define is utilized to compile the AREG Framework sources using the POSIX API. This define is compatible with all compilers except Microsoft Visual C++ (MSVC). The POSIX preprocessor define is indirectly set when configuring the compiler. This can be achieved by selecting the compiler through options such as the AREG_COMPILER_FAMILY parameter or by directly modifying the configuration file, such as the user.cmake file.

For instance, here's an example of how to set the POSIX define when building with CMake and utilizing the LLVM (Clang) compiler family:

cmake -B ./build -DAREG_COMPILER_FAMILY=llvm
cmake --build ./build -j8

Similarly, when building with Make and employing the GCC compiler, the POSIX define can be set as follows:

make AREG_COMPILER=gcc all -j8

The POSIX build is also possible in Microsoft Visual Studio and Visual Studio Code when the GNU, LLVM, or Cygwin compiler family is selected. It is important to remember that the POSIX and WINDOWS preprocessor defines are mutually exclusive, and only one of them can be set at a time.

WINDOWS define

The WINDOWS preprocessor define is used to compile the AREG Framework sources with the Win32 API. It is specifically set when compiling with the Microsoft Visual C++ (MSVC) compiler. The WINDOWS define is automatically established when compiling with Microsoft Visual Studio, or it is automatically configured by selecting the compiler options such as the AREG_COMPILER_FAMILY parameter, or by modifying the configuration file, such as the user.cmake file.

Here's an example of how to set the WINDOWS define when building with CMake and utilizing the Microsoft Visual C++ (MSVC) compiler:

cmake -B ./build -DAREG_COMPILER_FAMILY=msvc
cmake --build ./build -j8

Please note that the WINDOWS define is only applicable when compiling with the Microsoft Visual C++ compiler. It's important to remember that the WINDOWS and POSIX preprocessor defines are mutually exclusive, and only one of them can be set at a time.

DEBUG and NDEBUG defines

The DEBUG and NDEBUG preprocessor define symbols are used to specify the build type, either Debug or Release, and they are mutually exclusive.

DEBUG and NDEBUG Build with CMake

In CMake, the DEBUG and NDEBUG preprocessor defines are set indirectly by specifying the build type as either Debug or Release using the AREG_BUILD_TYPE compile option. This compile option can be set either through the command line or in the user.cmake file.

Example: The DEBUG define is set due to a Debug build:

cmake -B ./build -DAREG_BUILD_TYPE=Debug
cmake --build ./build

DEBUG and NDEBUG Build with Make

In Make, the DEBUG and NDEBUG preprocessor defines are set indirectly by specifying the build type as either Debug or Release using the AREG_BUILD_TYPE compile option. This compile option can be set either through the command line or in the user.make file.

Example: The NDEBUG define is set due to a Debug build:

make AREG_BUILD_TYPE=Release all -j 8

DEBUG and NDEBUG Build with Microsoft Visual Studio

In Microsoft Visual Studio, the various build configurations are set in the areg-sdk.sln solution file. When opening the areg-sdk.sln file, the developer should select the desired configuration in the Configuration Manager or in the Toolbar.

Select configuration in Microsoft Visual Studio

Another way to set the build type is to use CMake in Microsoft Visual Studio and specify the AREG_BUILD_TYPE parameter as either Debug or Release, following the same steps described in the DEBUG and NDEBUG Build with CMake section of this documentation.

DEBUG and NDEBUG Build with Visual Studio Code

In Visual Studio Code, the DEBUG and NDEBUG defines are set in the same way as described in the DEBUG and NDEBUG Build with CMake section of this documentation.

EXP_AREG_DLL and EXP_AREG_LIB defines

The preprocessor defines EXP_AREG_DLL and EXP_AREG_LIB are specific to the AREG Framework and are used to ensure the proper export of classes and functions when building the areg library as either a shared library or a static library. These symbols are set indirectly in the configuration file when specifying the binary type of the AREG Framework. It is important to note that these symbols are mutually exclusive, and only one of them should be set at a time.

💡 Similar to EXP_AREG_DLL and EXP_AREG_LIB, there are preprocessor defines EXPORT_SHARED_SYMBOLS and EXPORT_STATIC_SYMBOLS that can be used in project configurations.

EXP_AREG_DLL and EXP_AREG_LIB with CMake

In CMake, the EXP_AREG_DLL and EXP_AREG_LIB preprocessor define symbols are set for the areg library when specifying the binary type of the AREG Framework. By default, the library is built as a shared library (check the AREG_BINARY parameter in user.cmake).

Example: Configure the areg library as shared, which will automatically set the value EXP_AREG_DLL=1

cmake -B ./build -DAREG_BINARY=shared

EXP_AREG_DLL and EXP_AREG_LIB with Make

In Make, the EXP_AREG_DLL and EXP_AREG_LIB preprocessor define symbols are set when specifying the binary type of the AREG Framework. By default, the library is built as a shared library (check the AREG_BINARY parameter in user.make).

Example: Configure the areg library as shared, which will automatically set the value EXP_AREG_LIB=1

make AREG_BINARY=static

EXP_AREG_DLL and EXP_AREG_LIB with Microsoft Visual Studio

In Microsoft Visual Studio, the EXP_AREG_DLL and EXP_AREG_LIB preprocessor define symbols are set directly in the areg project when compiling using the areg-sdk.sln solution file (compiler set as shared), or indirectly when using CMake, as described in the EXP_AREG_DLL and EXP_AREG_LIB with CMake section.

EXP_AREG_DLL and EXP_AREG_LIB with Visual Studio Code

In Visual Studio Code, the EXP_AREG_DLL and EXP_AREG_LIB preprocessor define symbols are set in the same way as described in the EXP_AREG_DLL and EXP_AREG_LIB with CMake section.

IMP_AREG_DLL and IMP_AREG_LIB defines

The preprocessor defines IMP_AREG_DLL and IMP_AREG_LIB are specific to projects that utilize the AREG Framework and are used to ensure the proper import of classes and functions from the areg shared or static library when building the target executable. These symbols are set indirectly in the configuration file when specifying the binary type of the AREG Framework. It is important to note that these symbols are mutually exclusive, and only one of them should be set at a time.

💡 Similar to IMP_AREG_DLL and IMP_AREG_LIB, there are preprocessor defines IMPORT_SHARED_SYMBOLS and IMPORT_STATIC_SYMBOLS that can be used in project configurations.

IMP_AREG_DLL and IMP_AREG_LIB with CMake

In CMake, the IMP_AREG_DLL and IMP_AREG_LIB preprocessor define symbols are set for the target executables when specifying the binary type of the AREG Framework. By default, the library is built as a shared library (check the AREG_BINARY parameter in user.cmake).

Example: Set the areg binary as shared so that the executables can properly import symbols. This automatically sets EXP_AREG_DLL=1

cmake -B ./build -DAREG_BINARY=shared

IMP_AREG_DLL and IMP_AREG_LIB with Make

In Make, the IMP_AREG_DLL and IMP_AREG_LIB preprocessor define symbols are set for the target executables when specifying the binary type of the AREG Framework. By default, the library is built as a shared library (check the AREG_BINARY parameter in user.make).

Example: Set the areg binary as static so that the executables can link the symbols properly. This automatically sets EXP_AREG_LIB=1

make AREG_BINARY=static

IMP_AREG_DLL and IMP_AREG_LIB with Microsoft Visual Studio

In Microsoft Visual Studio, the IMP_AREG_DLL and IMP_AREG_LIB preprocessor define symbols are set directly in the project files when compiling using the areg-sdk.sln solution file, or indirectly when using CMake, as described in the IMP_AREG_DLL and IMP_AREG_LIB with CMake section.

IMP_AREG_DLL and IMP_AREG_LIB with Visual Studio Code

In Visual Studio Code, the IMP_AREG_DLL and IMP_AREG_LIB preprocessor define symbols are set in the same way as described in the IMP_AREG_DLL and IMP_AREG_LIB with CMake section.

AREG_EXTENDED define

The AREG_EXTENDED preprocessor define symbol is used to control the inclusion of extended features in the areg-extend static library. By default, the library is built without enabled extended features. The possible values for AREG_EXTENDED are 0 or 1, where 0 disables the extended features and 1 enables them. It's important to note that enabling extended features may introduce additional dependencies.

For instance, on Linux, the extended feature requires the ncurses library, while on Windows, it requires minimum Windows 2000 Professional Desktop Apps only. Due to these dependencies, extended features are disabled by default. Building the library without extended features and additional dependencies (setting AREG_EXTENDED to 0) may cause certain functionalities to not work as expected.

AREG_EXTENDED with CMake

By default, extended features are disabled in CMake. To enable them, you have two options. You can manually modify the AREG_EXTENDED option in the user.cmake file, or you can pass it as a compile option via the command line during the configuration process.

Here's an example of using CMake to build applications with enabled extended features:

cmake -B ./build -DAREG_EXTENDED:BOOL=ON
cmake --build build

AREG_EXTENDED with Make

By default, extended features are disabled in Make. To enable them, you can either manually modify the AREG_EXTENDED parameter in the user.mk file or pass the parameter through the command line during the build process.

Here's an example of compiling applications with enabled extended features using Make:

make AREG_EXTENDED=1

AREG_EXTENDED with Microsoft Visual Studio

By default, the extended features of AREG SDK are disabled. To enable the extended features of the AREG Framework when compile with Microsoft Visual Studio, follow these steps:

  1. Open the msvc_setup.props file in the AREG SDK root directory. If you are integrating AREG SDK into your project, create the file in your project's Solution directory instead.
  2. Locate the AregExtended property in the file and set its value based on your requirements. For example: 
    <AregExtended>1</AregExtended>
  3. Save the msvc_setup.props file either in the AREG SDK root directory or your project's Solution directory.

No further changes are necessary. In the user.props file the AREG_EXTENDED preprocessor define symbol is set as follows:

<AregExtended Condition="'$(AregExtended)'==''">0</AregExtended>
<AregCommonDefines>AREG_EXTENDED=$(AregExtended);$(AregCommonDefines)</AregCommonDefines>

Alternatively, you can enable the extended features via the command line when running MSBuild. Use the following example command:

msbuild /m /property:Configuration=Release /property:Platform=x64 /property:AregExtended=1 ./areg-sdk.sln

Make sure to adjust the command according to your specific requirements.

Please note that enabling the extended features may have certain prerequisites or dependencies that need to be met for proper functionality.

AREG_EXTENDED with Visual Studio Code

In Visual Studio Code, the AREG_EXTENDED preprocessor define symbol is set in the same way as described in the AREG_EXTENDED with CMake section.

AREG_LOGS define

The AREG_LOGS preprocessor define symbol is used to control the inclusion of logs in the compiled binaries. When AREG_LOGS is not set or set to 1, the application source codes are compiled with logs, allowing developers to configure the log.init file for runtime logging. On the other hand, if AREG_LOGS is set to 0, the applications are compiled without logs.

AREG_LOGS with CMake

By default, CMake compiles the application source codes with logs. To compile the sources without logs, developers need to either modify the AREG_LOGS option in the user.cmake file or pass it as a compile option through the command line during the build configuration.

Here's an example of building applications without logs using CMake:

cmake -B ./build -DAREG_LOGS:BOOL=OFF
cmake --build ./build

AREG_LOGS with Make

By default, Make compiles the application source codes with logs. To compile the sources without logs, developers need to either modify the AREG_LOGS parameter in the user.mk file or pass it as a parameter through the command line during the build process.

Here's an example of building applications without logs using Make:

make AREG_LOGS=0

AREG_LOGS with Microsoft Visual Studio

By default, the source codes are compiled with logs. To disable logs in binaries when using Microsoft Visual Studio, follow these steps:

  1. Open the msvc_setup.props file located in the AREG SDK root directory. If you are integrating AREG SDK into your project, create the file in your project's Solution directory instead.

  2. Locate the AregLogs property in the file and set its value to disable logs. For example:

    <AregLogs>0</AregLogs>

  3. Save the msvc_setup.props file in the AREG SDK root directory or your project's Solution directory.

No further changes are required in the user.props file. The AREG_LOGS preprocessor define symbol is set as follows:

<AregLogs Condition="'$(AregLogs)'==''">1</AregLogs>
<AregCommonDefines>AREG_LOGS=$(AregLogs);$(AregCommonDefines)</AregCommonDefines>

Alternatively, you can disable logs via the command line when running MSBuild in the Solution directory. Use the following example command:

msbuild /m /property:Configuration=Release /property:Platform=x64 /property:AregLogs=0 .

Adjust the command based on your specific requirements.

Please note that disabling logs may impact the debugging and troubleshooting capabilities of your application.

AREG_LOGS with Visual Studio Code

In Visual Studio Code, the AREG_LOGS preprocessor define symbol is set in the same way as described in the AREG_LOGS with CMake section.

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