This file is part of AREG SDK
Copyright (c) 2017-2021, Aregtech
Contact: info[at]aregtech.com
Website: https://www.aregtech.com
This document replies to several howto questions.
- How to use preprocessor directives.
- How to compile.
- How to create a project or integrate in project.
- How to use logging.
- How to use multicast router
AREG SDK uses a few preprocessor directives to compile POSIX and Windows versions of codes. Here is the list:
Preprocessor | Description and meaning |
---|---|
POSIX | Compile sources with POSIX API, details are in POSIX.md. |
WINDOWS | Compile sources with Win32 API, details are in WIN32.md. |
DEBUG | Compile Debug configuration. |
NDEBUG | Compile Release configuration. |
ENABLE_TRACES | Enable logging / tracing in sources. |
EXP_AREG_LIB | Build AREG static library (also can use EXPORT_STATIC_SYMBOLS). |
EXP_AREG_DLL | Build AREG shared library (also can use EXPORT_SHARED_SYMBOLS). |
IMP_AREG_LIB | Link with AREG static library (also can use IMPORT_STATIC_SYMBOLS). |
IMP_AREG_DLL | Link with AREG shared library (also can use IMPORT_SHARED_SYMBOLS). |
A POSIX application usually is compiled with POSIX, DEBUG (NDEBUG), IMP_AREG_LIB (IMP_AREG_DLL), ENABLE_TRACES preprocessor directives.
AREG SDK provides Makefile, Eclipse and Visual Studio project files to compile sources and examples. Makefile and Eclipse projects are to build software with POSIX API, and Visual Studio project files are to build software with Win32 API. By default, there is no need to make additional changes in settings to compile projects. To run IPC examples, make sure the process mcrouter has started as a console application or as a service handled by the system.
To build the POSIX version of projects use make or Eclipse for C/C++ Developers IDE to compile with GCC or clang compilers. AREG framework and examples require C++ 17 or higher.
make and Makefile is used to build AREG framework with POSIX API. To build projects, open command line terminal in AREG SDK root directory and do one of these actions:
Description | Command |
---|---|
Compile all projects: | $ make [all] |
Compile framework only: | $ make framework |
Compile examples only: | $ make examples |
All builds are located in the created ./product/build/<compiler-platform-path>
sub-folder located in the areg-sdk root directory.
To clean an existing build call $ make clean
command terminal. This removes the entire 'product' output directory.
In all cases, parallel compilation with -j
can be used to speedup the compilation. For example, to compile areg-sdk
sources with 8 threads:$ make -j 8
Change the compiler settings:
To change compiler settings, use user.mk file and edit. Do not commit the developer specific file if other developers use different settings.
- To set the compiler, change Toolset. Supported values: g++ (default compiler), gcc, clang++-13. Example:
Toolset := clang++-13
- To set the hardware platform, change Platform. Supported values: <no value> (take default), x86, x86_64, arm, aarch64. Example:
Platform := _x86_
. - To set the cross-compile, change CrossCompile. Supported values: <no value> (take default), arm-linux-gnueabihf-g++ (Linux g++ compiler for arm32), arm-linux-gnueabihf-gcc (Linux GCC compiler for arm32), aarch64-linux-gnu-g++ (Linux g++ compiler for arm64), aarch64-linux-gnu-gcc (Linux GCC compiler for arm64). Example:
CrossCompile := arm-linux-gnueabihf-g++
. - To set the AREG framework library type, change areg. Supported values: static (build and link AREG framework as a static library), shared (build and linke AREG framework as a shared library). Example:
areg := static
. - To set build configuration, change Config. Supported values: Debug (build debug version) and Release (build release version). Example:
Config := Debug
. - To set additional compiler preprocessor directives, change UserDefines. Example:
UserDefines := -DENABLE_TRACES
. - To set additional include directories, change UserDefIncludes.
- To set additional library directories, change UserDefLibPaths.
- To set additional libraries, change UserDefLibs.
- To set the build output directory, change UserDefOutput. By default, the binaries are compiled in the
./product
sub-folder created in AREG SDK root. - To set the binary output directory, change ProjBuildPath. By default, the path includes compile, hardware, operating system and configuration information.
Examples for the command to use for different settings:
# Compile areg-sdk with clang using 8 threads
$ make -j 8 Toolset=clang++-13
# Compile areg-sdk with arm-linux-gnueabihf-g++ for arm32
$ make -j 8 CrossCompile=arm-linux-gnueabihf-
# Compile areg-sdk as Debug shared library with aarch64-linux-gnu-gcc
$ make -j 8 Config=Debug CrossCompile=aarch64-linux-gnu- Toolset=gcc
Eclipse IDE is used to build software with POSIX API in Linux or Windows OS. You need to import the existing Eclipse projects to workspace created in AREG SDK root directory and specify OS suitable Toolchain in the settings. For example, for Windows use cygwin GCC Toolchain.
How to import projects:
- Open Eclipse for C/C++ Developers IDE.
- Create a New Workspace, specify areg-sdk as workspace root.
- In Eclipse IDE select Import menu (File ==> Import) to start importing.
- In the Select dialog select General ==> Existing Projects into Workspace.
- Click the Next button, this opens the Import Projects dialog.
- In the Import Projects dialog click Select ==> Browse and set areg-sdk folder.
- After scanning, Projects contains a list of projects.
- Select either areg and mcrouter, or select all to compile all.
The Debug builds are output in Debug and the Release builds are in Release subfolders of each project. By default, AREG framework is compiled as a static library. Change the settings of the framework and project if you need the shared library.
To compile Windows versions of projects, use Visual Studio 2019 or higher to open the solution.
How to load projects:
- In Visual Studio open areg-sdk.sln file, located in areg-sdk root folder.
- In the toolbar of Visual Studio select:
- Win32 or x64 in Solution Platform to build 32- or 64-bit binaries.
- dbg_vc142 or rls_vc142 in Solution Configuration to build Debug or Release configuration.
We have taken the advantage of Visual Studio property files and have chosen this behaviour of Solution Configuration to escape changing the PlatformToolset settings in project files if a team works with different versions of Visual Studio. If you need to support newer versions of Visual Studio, register the Platform, Configuration and PlatformToolset in the config_compile.props file located in areg-sdk and update areg-sdk solution file.
💡 Note: You'll get error if you choose the compiler version, which does not exist in your system!
Example to building 64-bit Release in VS2019: in the Solution Configurations of VS2019 toolbar select rls_v142 and in the Solution Platform select x64. Compile the Solution. All projects are output in the created ./product
subfolder of the areg-sdk root.
Currently the AREG SDK does not contain project files of any other IDE or other scripts like CMake to build from the command line.
Here is information to integrate the AREG framework in the existing project.
- Include <areg-sdk-root>/framework in the include path list of the project.
- Set preprocessor directive POSIX or WINDOWS to specify POSIX or Win32 API build of
areg-sdk
. - Set preprocessor directive DEBUG for Debug or NDEBUG for Release build of applications.
- Set preprocessor directive IMP_AREG_DLL for the
areg
framework shared library or IMP_AREG_LIB for theareg
framework static library. - Optionally, set preprocessor directive ENABLE_TRACES if need logs / traces.
- Include library output directory in library search path and specify AREG framework library to link with.
Now your project is ready to use the AREG framework.
The examples of AREG SDK for POSIX in Eclipse IDE are built having following settings:
- areg-sdk/framework path is set in the include paths of projects.
- The library search path has areg-sdk/framework/areg/Debug path for Debug and areg-sdk/framework/areg/Release path for Release configuration.
- areg, pthread and rt libraries are listed in the list of libraries to link.
- Preprocessor directives for Debug build
POSIX, DEBUG, IMP_AREG_LIB, ENABLE_TRACES
and for Release buildPOSIX, NDEBUG, IMP_AREG_LIB, ENABLE_TRACES
.
Tracing / Logging MACRO are declared in the GTrace.h header file. Use predefined MACRO to configure, enable and output logs.
- To compile sources with logging, compile the application with ENABLE_TRACES preprocessor directive. If this is not specified, the logs will not exist in binaries. Example:
UserDefines := -DENABLE_TRACES
- There must be declared scopes to generate logs.
- Use MACRO DEF_TRACE_SCOPE(some_unique_name_of_scope) to declare scope. The scopes must have unique names.
- Use macro TRACE_SCOPE(some_unique_name_of_scope) in methods to prepare tracing.
- As soon as the method is executed, the scope generates an "Enter" message to log.
- Use MACRO TRACE_DBG, TRACE_INFO, TRACE_WARN, TRACE_ERR, TRACE_FATAL to log messages by priority.
- Use standard string formatting flags to log messages (similar to printf()).
- No need to set end-of-line ('\n') at the end of the message. The tracer automatically adds.
- When exit the method, the scope generates "Exit" message to log.
Example:
// A class in project 'something'
class SomeObject
{
public:
void foo();
void bar();
};
// define unique scopes
DEF_TRACE_SCOPE(something_SomeObject_foo);
DEF_TRACE_SCOPE(something_SomeObject_bar);
void SomeObject::foo()
{
TRACE_SCOPE(something_SomeObject_foo);
TRACE_DBG("Now we can output logs with arguments %s and there is no need %s.", "just like printf() method", "to set new line");
}
void SomeObject::bar()
{
TRACE_SCOPE(something_SomeObject_bar);
TRACE_WARN("You may as well output logs by priority");
}
The application(s) must be compiled with the TRACE_ENABLE preprocessor directive. The logging service is enabled in 2 steps:
- In the log initialization file (by default, log.init) set
log.enable = true
to enable logging service for all applications orlog.enable.appName = true
to enable logging only for a specific application(s). - Use
TRACER_START_LOGGING()
macro and specify the log initialization file path to start logging service. Ifnullptr
, the default relative path ./config/log.init is used. - The tracing as well is enabled by calling
Application::initApplication()
method. - You may as well filter logs by scopes and priorities in the
log.init
file.
Example of enabling logs:
In log.init
file
log.enable = true # enable global logging
log.file = %home%/logs/%appname%_%time%.log # create logs in 'log' subfolder of user home
scope.something.something_SomeObject_bar = DEBUG | SCOPE ; # enable all logs for specified scope
scope.something.something_SomeObject_foo = NOTSET ; # disable any log of specific scope
in main.cpp
file:
// main.cpp file
DEF_TRACE_SCOPE(something_main);
int main()
{
// Initialize application, enable logging, servicing and the timer.
Application::initApplication(true, true, true, true, nullptr, nullptr );
do
{
// initialize scope after logging service is started
TRACE_SCOPE(something_main);
TRACE_INFO("Now I can log!");
SomeObject obj;
obj.foo(); // <== the log scope is disabled, no logging
obj.bar(); // <== logs scope "Enter", log message, log "Exit"
} while (false);
return 0;
}
See the details of initialization in the log.init file. Browse 04_trace and other following examples to see how logs are initialized and used. Use macro TRACER_FORCE_LOGGING()
to force the logging service to start with default settings (enable all log scopes and priorities of the application).
💡 Currently logs output messages in the file. Other output settings are reserved and currently have no effect. It is planned to extend log service with more features.
The logs are configured in log.init, which syntax parser is part of the framework. Change appropriate sections to filter log priorities and log scopes, or change the name of the output log file.
An example of filtering logs and scopes:
scope.appName.some_unique_scope_name_in_method = SCOPE | DEBUG # Enable all logs for the scope
scope.appName.some_unique_scope_name_in_other_method = ERROR # Enable only error message, not scope Enter and Exit
scope.appName.some_unique_scope_name_in_somewhere = NOTSET # Disable any log
In this example:
- some_unique_scope_name_in_method scope enables all logs, including Enter and Exit messages of scope.
- some_unique_scope_name_in_other_method scope enables only ERROR and FATAL logs. All other logs, including scope Enter and Exit are filtered out.
- some_unique_scope_name_in_somewhere scope disables any log.
Multicast Router (MCR) is a part of AREG SDK and it is used for inter-process communication (IPC). The multicast router and the applications must have a configured router.init file located in the ./config
subfolder of binaries. Set the IP-address and the port number of the multicast router to connect.
connection.address.tcpip = 127.0.0.1 # the address of mcrouter host
connection.port.tcpip = 8181 # the connection port of mcrouter
When starting an application with Public service(s), make sure that the mcrouter is started. If your application uses only Local services, it does not need the multicast router.