diff --git a/areg-sdk.sln b/areg-sdk.sln index 58b4323d..fd95b2ea 100644 --- a/areg-sdk.sln +++ b/areg-sdk.sln @@ -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 diff --git a/docs/wiki/cmake-config.md b/docs/wiki/cmake-config.md index 84fdad0b..0965d6f2 100644 --- a/docs/wiki/cmake-config.md +++ b/docs/wiki/cmake-config.md @@ -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. diff --git a/docs/wiki/cmake-integrate.md b/docs/wiki/cmake-integrate.md index 74b51728..b50bfc62 100644 --- a/docs/wiki/cmake-integrate.md +++ b/docs/wiki/cmake-integrate.md @@ -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) @@ -26,26 +30,26 @@ 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. @@ -53,7 +57,7 @@ These components provide a robust infrastructure for integrating AREG SDK in pro ## 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" @@ -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( @@ -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) @@ -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 @@ -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=/scripts/buildsystems/vcpkg.cmake` where 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** `` with the actual path: +5. **Build with Toolchain File**: + Replace `` with the actual path, then run these command to configure, build and execute `example` application: + ```bash cmake -B ./build -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake cmake --build ./build @@ -189,7 +203,7 @@ 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"] @@ -197,15 +211,17 @@ target_link_libraries(example PRIVATE areg::areg) 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) @@ -215,30 +231,28 @@ 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.cmake` file. -> [!IMPORTANT] -> Set the settings before including `/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) @@ -246,60 +260,63 @@ include(${AREG_SDK_ROOT}/areg.cmake) ``` ### Advanced CMake Functions -The `/areg.cmake` file refers to the `functions.cmake`, which contains set of CMake functions and macro to simplify build commands: + +The `/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) +```