Skip to content

08. Setup a project

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

Table of contents

  1. General Information
  2. Integration Guide of AREG Framework
  3. Demo project

General Information

When working on a project, it is common to utilize third-party frameworks or libraries. Integration methods typically involve using compiled binaries along with include files or integrating complete source codes into the build process. In some cases, the flexibility of the third-party component may limit integration options, necessitating the use of compiled binaries and header files instead of the source codes.

The AREG Framework has been developed with the utmost flexibility, allowing it to be seamlessly integrated into any project. Follow the instructions below to create a project based on the AREG SDK, referring to the areg-sdk-demo repository as a practical implementation example.

Integration Guide of AREG Framework

This integration guide provides an instructions on seamlessly integrating the AREG (Automated Real-time Event Grid) Framework into your project. The AREG Framework is designed to be flexible and can be integrated into various project structures. To assist you in the process, we have created the areg-sdk-demo repository as a practical example.

Step 1: Clone AREG SDK

Start by cloning the AREG SDK repository, following the detailed instructions provided in the Wiki page. Ensure that the submodules are properly cloned. Set the source codes of the AREG SDK in a separate folder, or alternatively, include the AREG SDK as a submodule in your project.

Step 2: Incorporate the AREG Framework

You have two options for incorporating the AREG Framework into your project:

Option 1: Using Pre-built Binaries

  • Build the AREG SDK as a separate project to generate the required binaries.
  • Specify the <areg-sdk>/framework folder in your project's include path.
  • Link against the AREG Framework's libraries during the linking stage of your project.

Option 2: Integrating Source Codes

  • Integrate the AREG Framework's source codes directly into your project's build process.
  • Additional configuration steps are required before building your software.

Step 3: Configure the AREG Framework

Before building your software with any build tool, configure the AREG SDK builds to set the output folder and other flags.

Configure for CMake

To build the AREG SDK Demo project source codes and AREG Framework with CMake:

  1. Before including the areg-sdk/CMakeLists.txt in your build, ensure you set the values of the following parameters:

    • AREG_BUILD_ROOT: Specify the desired output folder for the AREG SDK build.
    • AREG_BUILD_EXAMPLES: Optionally set this parameter to exclude building examples, if desired.

  2. For more details on available configuration parameters, refer to the cmake details section in the Software build Wiki page of AREG SDK.

Configure for Microsoft Visual Studio

To build the AREG SDK Demo project source codes and AREG Framework with Microsoft Visual Studio or MSBuild, follow these steps:

  1. Create a solution file in your project's file structure.
  2. In the same location, create the msvc_setup.props file.
  3. Set the location of AREG SDK sources in the AregSdkRoot property. For example: 
    <AregSdkRoot>$(SolutionDir)\thirdparty\areg-sdk</AregSdkRoot>
  4. Optionally, set other locations based on your project's file structure. Choose all or one of the following options:
    • Set the location of the project build folder where binaries and generated files will be outputted: 
      <AregBuildRoot>$(SolutionDir)\product</AregBuildRoot>
    • Set the location to output only compiled and built binaries: 
      <AregOutputDir>$(SolutionDir)\Bin\$(Configuration)</AregOutputDir>
      This directory will contain three subdirectories: bin, lib, and obj.
    • Set the locations to output static libraries, binaries, and intermediate object files. It is recommended to set all three properties: 
      <AregOutputLib>$(SolutionDir)\lib</AregOutputLib>
<AregOutputBin>$(SolutionDir)\bin</AregOutputBin>
<AregOutputObj>$(SolutionDir)\$(Configuration)\$(ProjectName)</AregOutputObj>
    If these properties are not set, the default output directory is $(SolutionDir)\product.
  5. Include the following three Visual Studio project files in the solution file:
  6. Include your own projects or create new ones within the solution.
  7. Set the project dependencies to establish the correct build order.
  8. Compile the Solution.

For configuration steps with other build tools, refer to the AREG SDK documentation.

💡 Please note that there is an open issue Integrate Makefile to build with make #11 in the areg-sdk-demo repository to build the Demo project with the make tool. Any contributions to resolve this issue would be greatly appreciated.

Step 4: Utilize the AREG Framework

Utilizing the AREG Framework involves developing Local and/or Public services for multithreading and/or multiprocessing applications. Follow these steps:

  1. Create a Service Interface document (currently only available manually). The Service Interface document in the AREG SDK provides a detailed description of creating this document. Use XML format to define Data Types, Attributes, and Methods of the service.

  2. Whenever you modify the Service Interface document, use the codegen.jar located in the tools folder of the AREG SDK to generate codes. Alternatively, create script files to run scripts instead of manually typing commands in the command line.

  3. Once the codes are generated, build them as a static library. You can create one or more static libraries to include all generated codes or split them into modules. Compiling the generated codes as a static library will facilitate building Provider and Consumer components. Alternatively, you may build them as a shared library, but it may contain unnecessary objects when Providers and Consumers run in different processes.

Step 5: Test and Debug

During software development, it is recommended to enable logging, especially for Debug builds. To enable or disable logging during builds, refer to the appropriate section of the Preprocessor define symbols Wiki page of AREG SDK.

Once logging is enabled, you can configure the logging settings and run your applications. Testing and debugging can be performed by analyzing the logs.

By following these steps, you will be able to seamlessly integrate the AREG Framework into your project or start a new project based on AREG Framework. For further information and additional steps, please refer to the AREG SDK documentation.

Demo Project

The areg-sdk-demo repository serves as a showcase project demonstrating the integration of the AREG SDK into an existing project or as a foundation for creating a new project based on the AREG Framework. You can utilize this repository as a template and adapt it to suit your project structure. Below is an explanation of the configuration for compilation using the CMake tool.

The areg-sdk-demo repository has the following structure:

  • The AREG SDK source codes are included as a submodule in the thirdparty directory of the project.
  • The demo directory contains the source codes of several demo projects, which have been copied from the examples directory of the areg-sdk repository.
  • The root of the Demo Project contains the CMakeLists.txt file, which configures and prepares the AREG Framework compilation and demo applications.
  • To prevent any collisions between the demo applications in the Demo Project and the examples from areg-sdk, the examples in areg-sdk are disabled from building. After compiling the Demo Project, the bin folder will only contain the projects that exist in the demo directory. This is achieved by setting option(AREG_BUILD_EXAMPLES "Build AREG SDK examples" OFF).

Here is the content of the CMakeLists.txt file in the Demo Project:

cmake_minimum_required(VERSION 3.16.0)

set(AREG_SDK_DEMO_ROOT  "${CMAKE_SOURCE_DIR}")
set(AREG_DEMO_SOURCES   "${AREG_SDK_DEMO_ROOT}/demo")
set(AREG_SDK_SOURCES    "${AREG_SDK_DEMO_ROOT}/thirdparty/areg-sdk")

# Configure AREG SDK build
# Set the root path to output compiled binaries.
set(AREG_BUILD_ROOT     "${AREG_SDK_DEMO_ROOT}/product")
# Disable building examples, instead, demo applications should be compiled.
option(AREG_BUILD_EXAMPLES  "Build AREG SDK examples"   OFF)

# Include areg-sdk files. This will initialize the options and compilers.
# You may include it after your project(s), but make sure that areg-sdk
# is properly configured.
include(${AREG_SDK_SOURCES}/CMakeLists.txt)

set(PROJECT_NAME "areg-sdk-demo")
set(PROJECT_VERSION "1.0.0")
project(${PROJECT_NAME} VERSION ${PROJECT_VERSION} LANGUAGES C CXX)

# Start building Demo applications
include("${AREG_DEMO_SOURCES}/CMakeLists.txt")

To adapt the CMakeLists.txt file to your project structure, make the following changes:

  • Rename the AREG_SDK_DEMO_ROOT variable and set the desired value, or leave it as ${CMAKE_SOURCE_DIR}.
  • Rename the AREG_DEMO_SOURCES variable and specify the folder location of your development source code (e.g., sources or develop).
  • Specify the location of the areg-sdk source

code in the AREG_SDK_SOURCES variable.

  • Set the folder name in the AREG_BUILD_ROOT variable to determine the output directory for binaries.
  • Optionally, you can set the values of:
    • AREG_OUTPUT_BIN to specify the output directory for libraries and binaries.
    • AREG_OUTPUT_LIB to specify the output directory for libraries.
    • AREG_OUTPUT_BIN to specify the output directory for binaries. Note: The AREG_OUTPUT_LIB and AREG_OUTPUT_BIN directories are automatically included in the library search path.
  • In most cases, you may not need to compile the examples provided by areg-sdk since they might not be relevant to your project. Disable the building of examples by setting the AREG_BUILD_EXAMPLES variable to OFF like option(AREG_BUILD_EXAMPLES "Build AREG SDK examples" OFF). It is easier to set this value directly in your project's CMakeLists.txt file.
  • Optionally, you may need to disable the compilation and execution of unit tests. To do so, set the AREG_BUILD_TESTS variable directly in the CMakeLists.txt file or pass it via the command line.
  • Additionally, you can set other options such as the compiler, build configuration, etc., either directly in the CMakeLists.txt file or through command-line parameters.

After making these changes, you should be able to compile your project successfully.

Please refer to the AREG SDK documentation for further details and instructions.

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