Skip to content

Latest commit

 

History

History
266 lines (203 loc) · 15 KB

HOWTO.md

File metadata and controls

266 lines (203 loc) · 15 KB

How To

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.

Table of content

  1. How to use preprocessor directives.
  2. How to compile.
  3. How to create a project or integrate in project.
  4. How to use logging.
  5. How to use multicast router

How to use preprocessor directives

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.

How to compile

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.

POSIX build

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

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 for C/C++ Developer

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.

Windows build

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.

Other builds

Currently the AREG SDK does not contain project files of any other IDE or other scripts like CMake to build from the command line.

How to create a project or integrate in project

Here is information to integrate the AREG framework in the existing project.

  1. Include <areg-sdk-root>/framework in the include path list of the project.
  2. Set preprocessor directive POSIX or WINDOWS to specify POSIX or Win32 API build of areg-sdk.
  3. Set preprocessor directive DEBUG for Debug or NDEBUG for Release build of applications.
  4. Set preprocessor directive IMP_AREG_DLL for the areg framework shared library or IMP_AREG_LIB for the areg framework static library.
  5. Optionally, set preprocessor directive ENABLE_TRACES if need logs / traces.
  6. 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 build POSIX, NDEBUG, IMP_AREG_LIB, ENABLE_TRACES.

How to use logging

Creating logs

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");
}

Enable logging

The application(s) must be compiled with the TRACE_ENABLE preprocessor directive. The logging service is enabled in 2 steps:

  1. In the log initialization file (by default, log.init) set log.enable = true to enable logging service for all applications or log.enable.appName = true to enable logging only for a specific application(s).
  2. Use TRACER_START_LOGGING() macro and specify the log initialization file path to start logging service. If nullptr, the default relative path ./config/log.init is used.
  3. The tracing as well is enabled by calling Application::initApplication() method.
  4. 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.

Configure logging

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.

How to use multicast router

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.