Skip to content

Commit

Permalink
Described integration of AREG SDK using CMake
Browse files Browse the repository at this point in the history
  • Loading branch information
aregtech committed Nov 5, 2024
1 parent b1e41ab commit dc06afe
Show file tree
Hide file tree
Showing 3 changed files with 111 additions and 88 deletions.
26 changes: 16 additions & 10 deletions areg-sdk.sln
Original file line number Diff line number Diff line change
Expand Up @@ -689,17 +689,23 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "example", "example", "{31AB
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "wiki", "wiki", "{C33D0DF1-A5DB-4F6E-A526-6AA2B3C31AD3}"
ProjectSection(SolutionItems) = preProject
docs\wiki\AREG-PACKAGE.md = docs\wiki\AREG-PACKAGE.md
docs\wiki\BUILD.md = docs\wiki\BUILD.md
docs\wiki\CMAKE-INTEGRATE.md = docs\wiki\CMAKE-INTEGRATE.md
docs\wiki\LOGGER.md = docs\wiki\LOGGER.md
docs\wiki\MCROUTER.md = docs\wiki\MCROUTER.md
docs\wiki\MSVS-BUILD.md = docs\wiki\MSVS-BUILD.md
docs\wiki\MSVS-INTEGRATE.md = docs\wiki\MSVS-INTEGRATE.md
docs\wiki\areg-package.md = docs\wiki\areg-package.md
docs\wiki\build.md = docs\wiki\build.md
docs\wiki\cmake-build.md = docs\wiki\cmake-build.md
docs\wiki\cmake-config.md = docs\wiki\cmake-config.md
docs\wiki\cmake-functions.md = docs\wiki\cmake-functions.md
docs\wiki\cmake-integrate.md = docs\wiki\cmake-integrate.md
docs\wiki\logger.md = docs\wiki\logger.md
docs\wiki\logging-config.md = docs\wiki\logging-config.md
docs\wiki\logging-develop.md = docs\wiki\logging-develop.md
docs\wiki\logobserver.md = docs\wiki\logobserver.md
docs\wiki\mcrouter.md = docs\wiki\mcrouter.md
docs\wiki\msvc-build.md = docs\wiki\msvc-build.md
docs\wiki\msvc-integrate.md = docs\wiki\msvc-integrate.md
docs\wiki\persistence-syntax.md = docs\wiki\persistence-syntax.md
docs\wiki\README.md = docs\wiki\README.md
docs\wiki\USER-CMAKE.md = docs\wiki\USER-CMAKE.md
docs\wiki\VSCODE.md = docs\wiki\VSCODE.md
docs\wiki\WSL.md = docs\wiki\WSL.md
docs\wiki\vscode.md = docs\wiki\vscode.md
docs\wiki\wsl-build.md = docs\wiki\wsl-build.md
EndProjectSection
EndProject
Global
Expand Down
2 changes: 1 addition & 1 deletion docs/wiki/cmake-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## CMake Configuration Overview

The AREG SDK offers flexible build configurations via CMake, allowing users to customize compilation settings, output directories, library types, and additional features for tailored development environments. These options can be adjusted to optimize the SDK for different systems, such as Linux and Windows, and to control features like testing, logging, and package usage.
The AREG SDK offers flexible build configurations via CMake, allowing users to customize compilation settings, output directories, library types, and additional features for tailored development environments. These options can be adjusted to optimize the AREG SDK binaries for different systems, such as Linux and Windows, and to control features like testing, logging, and package usage.

> [!IMPORTANT]
> The configuration options listed above are set in the [user.cmake](./../../conf/cmake/user.cmake) file, enabling both quick setup and precise build control for various project requirements.
Expand Down
171 changes: 94 additions & 77 deletions docs/wiki/cmake-integrate.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
Here’s a refined version with improved grammar, flow, and added clarity where helpful:

---

# Integrating AREG Framework with CMake

This guide details how to integrate the AREG Framework into an existing project or to build a new project using AREG Framework. There are three primary methods for integration:
This guide covers how to integrate the AREG Framework into an existing project or create a new project using AREG Framework. There are three main methods for integration:

1. **Fetch the source code** directly from the **[AREG SDK GitHub repository](https://github.com/aregtech/areg-sdk)**;
2. **Install via `vcpkg`** as a prebuilt package;
1. **Fetch the source code** directly from the **[AREG SDK GitHub repository](https://github.com/aregtech/areg-sdk)**.
2. **Install via `vcpkg`** as a prebuilt package.
3. **Add AREG SDK as a Git submodule** to your project.

> [!TIP]:
> For a practical example of integrating AREG SDK libraries and tools, refer to the **[AREG SDK Demo](https://github.com/aregtech/areg-sdk-demo)** repository.
> [!TIP]
> For a practical example of integrating AREG SDK libraries and tools, see the **[AREG SDK Demo](https://github.com/aregtech/areg-sdk-demo)** repository.
## Table of Contents
- [AREG SDK General Requirements](#areg-sdk-general-requirements)
Expand All @@ -26,34 +30,34 @@ This guide details how to integrate the AREG Framework into an existing project

## AREG SDK General Requirements

Ensure the following dependencies are installed to integrate AREG SDK sources or binaries into your project:
Ensure the following dependencies are installed for AREG SDK integration:

- **CMake** version 3.20 or higher
- **Git** for repository management
- **Compatible Compilers**: GCC, LLVM, or MSVC (Windows only) supporting **C++17** or newer
- **Supported Compilers**: GCC, LLVM, or MSVC (Windows only) with **C++17** or newer
- **Java** version 17+ for code generation tools

---

## General Information

AREG SDK comprises several components:
AREG SDK consists of several components:

1. **AREG Framework (`areg` library)**: Core library for automations and Object RPC communication.
2. **AREG Framework Extension (`aregextend` library)**: An optional library with extended utilities and features.
1. **AREG Framework (`areg` library)**: Core library for automation and Object RPC communication.
2. **AREG Framework Extension (`aregextend` library)**: Optional library with extended utilities.
3. **AREG Log Observer API (`areglogger` library)**: Enables applications to receive and manage log messages.
4. **AREG Multicast Router (`mcrouter` executable)**: A console and OS-managed service to route RPC messages.
5. **AREG Log Collector (`logger` executable)**: A console and OS-managed service to remotely collect logs.
6. **AREG Log Observer (`logobserver` executable)**: Stand-alone console application for managing logs.
7. **AREG Code Generator (`codegen.jar` runnable)**: A Java-based tool to generate Service Interface source code.
4. **AREG Multicast Router (`mcrouter` executable)**: OS-managed service to route RPC messages.
5. **AREG Log Collector (`logger` executable)**: OS-managed service for remote log collection.
6. **AREG Log Observer (`logobserver` executable)**: Stand-alone application for managing logs.
7. **AREG Code Generator (`codegen.jar` runnable)**: Java tool for generating Service Interface source code.

These components provide a robust infrastructure for integrating AREG SDK in projects, ensuring streamlined development.

---

## Example Code

Use the following code for all integration examples. Create a `main.cpp` file in a separate directory:
Use the following code for integration examples. Create a `main.cpp` file in a separate directory:

```cpp
#include "areg/base/String.hpp"
Expand All @@ -71,23 +75,26 @@ int main() {

### Integrate by Fetching Sources

1. **Declare the Project**:
Create a `CMakeLists.txt` file with the following content, ensuring the minimum CMake version is set to 3.20:
1. **Declare the Project**:
Create a `CMakeLists.txt` file, ensuring the minimum CMake version is 3.20:

```cmake
cmake_minimum_required(VERSION 3.20.0)
project(example)
```

2. **(Optional) Disable Examples and Tests**:
To speed up builds, disable examples and tests by adding these options, and additionally disable AREG SDK specific output directories:
2. **(Optional) Disable Examples and Tests**:
Speed up builds by disabling examples, tests, and specific output directories:

```cmake
option(AREG_BUILD_EXAMPLES "Disable examples" OFF) # Disable build of examples
option(AREG_BUILD_TESTS "Disable tests" OFF) # Disable build or unit tests
option(AREG_ENABLE_OUTPUTS "Disable outputs" OFF) # Disable AREG SDK specific output directories
```

3. **Fetch AREG SDK Sources**:
Add this script to `CMakeLists.txt` to fetch the sources from `master` branch:
3. **Fetch AREG SDK Sources**:
Add this script to `CMakeLists.txt` to fetch the sources from the `master` branch:

```cmake
include(FetchContent)
FetchContent_Declare(
Expand All @@ -100,8 +107,9 @@ int main() {
include_directories("${AREG_SDK_ROOT}/framework")
```

4. **Build the Project**:
Define executable's sources and link `areg` library and build:
4. **Build the Project**:
Define the executable sources, link the `areg` library, and build:

```cmake
add_executable(example main.cpp)
target_link_libraries(example PRIVATE areg::areg)
Expand Down Expand Up @@ -135,24 +143,26 @@ add_executable (example main.cpp)
target_link_libraries(example PRIVATE areg::areg)
```

5. **Build Commands**:
Run these commands in *Terminal* or *PowerShell* to configure, build and run `example` console application:
5. **Build Commands**:
Run these commands in *Terminal* or *PowerShell* to configure, build, and run the `example` console application:

```bash
cmake -B ./build
cmake --build ./build
./build/example
```

### Integrate Using `vcpkg` Package

> [!IMPORTANT]
> Starting with AREG SDK 2.0, you can integrate it using the `vcpkg` package manager. Before that, the AREG SDK is not available in `vcpkg`.
> [!IMPORTANT]
> Starting with AREG SDK 2.0, integration via `vcpkg` is available.
1. **Install `vcpkg`**:
Follow instructions on the [vcpkg GitHub page](https://github.com/microsoft/vcpkg). Make sure to update `vcpkg` for the latest package data.

1. **Install `vcpkg`**:
Install `vcpkg` and ensure it’s updated. Follow instructions at the [vcpkg GitHub page](https://github.com/microsoft/vcpkg). If you already have `vcpkg` installed on your machine, make sure that you have latest data (*pull the data*).
2. **Install AREG SDK Package**:
Use these commands:

2. **Install AREG SDK Package**:
Use the following commands:
- **Windows (64-bit)**:
```bash
vcpkg install areg:x64-windows
Expand All @@ -161,26 +171,30 @@ target_link_libraries(example PRIVATE areg::areg)
```bash
vcpkg install areg:x64-linux
```
3. **Get Toolchain File Path**:
Use the following command to integrate AREG SDK binaries and get the path of toolchain.

3. **Get Toolchain File Path**:
Use the following to integrate AREG SDK binaries:

```bash
vcpkg integrate install
```
This will display a message with information to include toolchain file in your build `-DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake` where <vcpkg-root> is the path of `vcpkg` packet management directory.

This also displays the CMake option to use toolchain when build `areg` package. Make sure you copied the command with path to the toolchain.

4. **Integrate in CMake Script**:
Create a `CMakeLists.txt` file with the following content:

3. **Integrate in CMake script**:
Create a `CMakeLists.txt` file with the following content, ensuring that CMake will either find the `areg` package or the build will fail:
```cmake
cmake_minimum_required(VERSION 3.20.0)
project(example)
find_package(areg CONFIG REQUIRED) # Find package with option 'REQUIRED'
include_directories(${AREG_FRAMEWORK})
find_package(areg CONFIG REQUIRED)
add_executable(example main.cpp)
target_link_libraries(example PRIVATE areg::areg)
```

4. **Build with Toolchain File**:
Run these commands in *Terminal* or *PowerShell* to configure, build and run `example` console application. To build, **replace** `<vcpkg-root>` with the actual path:
5. **Build with Toolchain File**:
Replace `<vcpkg-root>` with the actual path, then run these command to configure, build and execute `example` application:

```bash
cmake -B ./build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake
cmake --build ./build
Expand All @@ -189,23 +203,25 @@ target_link_libraries(example PRIVATE areg::areg)

### Integrate as Git Submodule

1. **Define Submodule**:
1. **Define Submodule**:
Add `areg-sdk` as a submodule by creating a `.gitmodules` file:
```plaintext
[submodule "areg-sdk"]
path = areg-sdk
url = https://github.com/aregtech/areg-sdk.git
```

2. **Get AREG SDK Sources**:
2. **Get AREG SDK Sources**:
Run these commands:

```bash
git submodule update --init --recursive
git submodule update --remote --recursive
```

3. **Integrate in CMake script**:
Create a `CMakeLists.txt` file with the following content to build all projects and use AREG Framework:
3. **Integrate in CMake Script**:
Create a `CMakeLists.txt` file to build all projects and use AREG Framework:

```cmake
cmake_minimum_required(VERSION 3.20.0)
project(example)
Expand All @@ -215,91 +231,92 @@ target_link_libraries(example PRIVATE areg::areg)
target_link_libraries(example PRIVATE areg::areg)
```

4. **Build Commands**:
Run these commands in *Terminal* or *PowerShell* to configure, build and run `example` console application:
4. **Build Commands**:
Run these commands to configure, build and execute `example` application:

```bash
cmake -B ./build
cmake --build ./build
./build/example
```

In all cases, your should be able to run `./build/example` executable, which will output `Hello from AREG SDK!` message on console.

---

## Advanced Integration

### Advanced CMake Options

AREG SDK has
The AREG SDK offers flexible configurations via CMake, allowing customization of compilation settings, output directories, and additional features. For the full list, refer to the [CMake Configuration Options for Building AREG SDK](./cmake-config.md) document.

The AREG SDK offers flexible build configurations via CMake, allowing users to customize compilation settings, output directories, library types, and additional features for tailored development environments. These options can be adjusted to optimize the AREG SDK binaries for different systems and to control features like testing, logging, and package usage. For the complete list of CMake options, refer to the [CMake Configuration Options for Building AREG SDK](./cmake-config.md) document.
> [!IMPORTANT]
> Set options before including the `<areg-sdk>/areg.cmake` file.

> [!IMPORTANT]
> Set the settings before including `<areg-sdk>/areg.cmake` file in CMakeLists.txt file or before fetching the sources.
For example:

For example, if the size of binary is actual and you want to compile your projects to use AREG Framework advanced features, set these options before `areg.cmake` is included
```cmake
option(AREG_LOGS "Disable logs" OFF)
option(AREG_EXTENDED "Build extended" ON)
include(${AREG_SDK_ROOT}/areg.cmake)
```

### Advanced CMake Functions
The `<areg-sdk>/areg.cmake` file refers to the `functions.cmake`, which contains set of CMake functions and macro to simplify build commands:

The `<areg-sdk>/areg.cmake` file includes `functions.cmake`, simplifying build commands:

```cmake
macro_declare_executable(example main.cpp)
```

The following script triggers code generator to generate C++ source files from the Service Interface document `CoolServices.siml`. The sources are compiled in a static library `coolservice` to use by other projects:
For example, generating source files from `CoolServices.siml` and compiling a static library `coolservice` to link with `cool` application:

```cmake
addServiceInterface(coolservice "" CoolService)
macro_declare_executable(cool coolservice main.cpp)
```

See [AREG SDK CMake Functions and Macros](./cmake-functions.md) document for the list of reusable CMake functions and macro.
See [AREG SDK CMake Functions and Macros](./cmake-functions.md) for details.

---

## Conclusion

For integrating AREG SDK, a comprehensive `CMakeLists.txt` might look like this:
A complete `CMakeLists.txt` might look like this:

```cmake
# Step 1: Declare the project
cmake_minimum_required(VERSION 3.20.0)
project(example)
# Step 2: Find 'areg' package. If not found, fetch sources.
find_package(areg CONFIG)
if (NOT areg_FOUND)
# Step 3 (optional): Disable examples and tests, set binary directory
option(AREG_BUILD_EXAMPLES "Disable examples" OFF) # Disable build of examples
option(AREG_BUILD_TESTS "Disable tests" OFF) # Disable build or unit tests
set(AREG_BUILD_ROOT "${CMAKE_SOURCE_DIR}/product") # Set the binary build output directory
# Step 4: Fetch AREG SDK sources from master branch
option(AREG_BUILD_EXAMPLES "Disable examples" OFF)
option(AREG_BUILD_TESTS "Disable tests" OFF)
set(AREG_BUILD_ROOT "${CMAKE_SOURCE_DIR}/product")
include(FetchContent)
FetchContent_Declare(
areg-sdk
GIT_REPOSITORY https://github.com/aregtech/areg-sdk.git
GIT_TAG "master"
)
)
FetchContent_MakeAvailable(areg-sdk)
set(AREG_SDK_ROOT "${areg-sdk_SOURCE_DIR}")
set(AREG_SDK_ROOT "${areg-sdk_SOURCE_DIR}")
include_directories("${AREG_SDK_ROOT}/framework")
endif()
# Step 5: include 'areg.cmake' in configuration process
include("${AREG_SDK_ROOT}/areg.cmake")
# Step 6: Use macro to build the project
macro_declare_executable(example main.cpp)
```
This file lets you set up an `example` project with AREG SDK and link necessary libraries, accommodating the different integration methods:
- try to find `areg` package
- if not available, fetch and build sources
- include `areg.cmake` and declare `example` executable.
> [!NOTE]
> In this example, there is no need to link the project with `areg` library, because it is automatically done in the macro.
> In this script, there is no need to link the `example` project with the `areg` library. It is automatically done when call `macro_declare_executable`.
In this example:
- we try to find `areg` package
- if not available, fetch and build sources
- include `areg.cmake` file to benefit predefined CMake macro and functions, and declare `example` executable.
If you don't want to use AREG SDK CMake macro and function, alternatively the last 2 lines can be replaced:
```cmake
add_executable(example main.cpp)
target_link_libraries(example PRIVATE areg::areg)
```

0 comments on commit dc06afe

Please sign in to comment.