YT-CPPAP-7: CMake integration

- Added the root `CMakeLists.txt` and `cmake/cpp-ap-config.cmake.in` files to enable CMake integration for the library
- Removed the example directory and added the `cpp-ap-demo` submodule 
- Modified the README file and GitHub workflows to account for the changes

.github/workflows/clang.yaml

@@ -6,27 +6,32 @@ on:
 
 jobs:
   build:
-    name: Build examples
+    name: Build and run tests
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
         uses: actions/checkout@v2
 
-      - name: Prepare
-        shell: bash
+      - name: Prepare env
         run: |
           sudo bash ./scripts/env/install_clang17_toolchain.sh
         continue-on-error: false
 
-      - name: Build
-        shell: bash
+      - name: Prepare
         env:
           CC:  clang-17
           CXX: clang++-17
         run: |
-          cd example
           cmake -B build -DCMAKE_CXX_COMPILER=clang++-17 -DCMAKE_C_COMPILER=clang-17
-          cd build
-          make
+        continue-on-error: false
+
+      - name: Build test executable
+        run: |
+          cd build && make
+        continue-on-error: false
+
+      - name: Run tests
+        run: |
+          ./build/test/run_tests
         continue-on-error: false

.github/workflows/gpp.yaml

@@ -6,21 +6,27 @@ on:
 
 jobs:
   build:
-    name: Build examples
+    name: Build and run tests
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
         uses: actions/checkout@v2
 
-      - name: Build
-        shell: bash
+      - name: Prepare
         env:
           CC:  gcc-11
           CXX: g++-11
         run: |
-          cd example
           cmake -B build -DCMAKE_CXX_COMPILER=g++-11 -DCMAKE_C_COMPILER=gcc-11
-          cd build
-          make
+        continue-on-error: false
+
+      - name: Build test executable
+        run: |
+          cd build && make
+        continue-on-error: false
+
+      - name: Run tests
+        run: |
+          ./build/test/run_tests
         continue-on-error: false

.gitignore

@@ -3,9 +3,7 @@
 
 # build files
 *.exe
-test/test
-test/build/
-example/build/
+build/
 
 # documentation files
 /documentation

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "cpp-ap-demo"]
+	path = cpp-ap-demo
+	url = git@github.com:SpectraL519/cpp-ap-demo.git

CMakeLists.txt

@@ -0,0 +1,77 @@
+cmake_minimum_required(VERSION 3.12)
+
+# Check if CPP-AP is a top level project
+if (NOT DEFINED PROJECT_NAME)
+    set(CPP_AP_IS_TOP_LEVEL_PROJECT ON)
+else()
+    set(CPP_AP_IS_TOP_LEVEL_PROJECT OFF)
+endif()
+
+project(cpp-ap
+    VERSION 1.0
+    DESCRIPTION "Command-line argument parser for C++20"
+    HOMEPAGE_URL "https://github.com/SpectraL519/cpp-ap"
+    LANGUAGES CXX
+)
+
+option(BUILD_TESTS "Build project tests" ON)
+
+# Define the library target
+add_library(cpp-ap INTERFACE)
+target_include_directories(cpp-ap INTERFACE
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+)
+set_target_properties(cpp-ap PROPERTIES
+    CXX_STANDARD 20
+    CXX_STANDARD_REQUIRED YES
+)
+
+# Installation configuration
+include(GNUInstallDirs)
+include(CMakePackageConfigHelpers)
+
+# Install the headers
+install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/
+        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+
+# Install the library target
+install(TARGETS cpp-ap EXPORT cpp-ap-targets)
+
+# Create a Config file for find_package
+configure_package_config_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/cmake/cpp-ap-config.cmake.in
+    ${CMAKE_CURRENT_BINARY_DIR}/cpp-ap-config.cmake
+    INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/cpp-ap
+)
+
+write_basic_package_version_file(
+    ${CMAKE_CURRENT_BINARY_DIR}/cpp-ap-config-version.cmake
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY ExactVersion
+)
+
+install(FILES
+    ${CMAKE_CURRENT_BINARY_DIR}/cpp-ap-config.cmake
+    ${CMAKE_CURRENT_BINARY_DIR}/cpp-ap-config-version.cmake
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/cpp-ap
+)
+
+install(EXPORT cpp-ap-targets
+    FILE cpp-ap-targets.cmake
+    NAMESPACE cpp-ap::
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/cpp-ap
+)
+
+# Include test directory if CPP-AP is a top level project
+if (CPP_AP_IS_TOP_LEVEL_PROJECT AND BUILD_TESTS)
+    add_subdirectory(test)
+endif()
+
+# Exporting from the build tree
+export(EXPORT cpp-ap-targets
+    FILE ${CMAKE_CURRENT_BINARY_DIR}/cpp-ap-targets.cmake
+    NAMESPACE cpp-ap::
+)
+
+export(PACKAGE cpp-ap)

README.md

@@ -3,7 +3,6 @@ Command-line argument parser for C++20
 
 [![g++](https://github.com/SpectraL519/cpp-ap/actions/workflows/gpp.yaml/badge.svg)](https://github.com/SpectraL519/cpp-ap/actions/workflows/g++)
 [![clang++](https://github.com/SpectraL519/cpp-ap/actions/workflows/clang.yaml/badge.svg)](https://github.com/SpectraL519/cpp-ap/actions/workflows/clang++)
-[![test](https://github.com/SpectraL519/cpp-ap/actions/workflows/test.yaml/badge.svg)](https://github.com/SpectraL519/cpp-ap/actions/workflows/test)
 [![format](https://github.com/SpectraL519/cpp-ap/actions/workflows/format.yaml/badge.svg)](https://github.com/SpectraL519/cpp-ap/actions/workflows/format)
 
 <br />
@@ -29,6 +28,10 @@ The `CPP-AP` library does not require installing any additional tools or heavy l
 ## Table of contents
 
 * [Tutorial](#tutorial)
+    * [Including CPP-AP into a project](#including-cpp-ap-into-a-project)
+        * [CMake integration](#cmake-integration)
+        * [Downloading the library](#downloading-the-library)
+        * [Downloading the single header](#downloading-the-single-header)
     * [The parser class](#the-parser-class)
     * [Adding arguments](#adding-arguments)
     * [Argument parameters](#argument-parameters)
@@ -48,13 +51,58 @@ The `CPP-AP` library does not require installing any additional tools or heavy l
 
 ## Tutorial
 
-To use the `CPP-AP` library in your project, copy the [argument_parser.hpp](include/ap/argument_parser.hpp) file into your include directory, e.g. `include/ap`. No other setup is necessary - you only need to include this header in your code:
+### Including CPP-AP into a project
 
-```c++
-#include <ap/argument_parser.hpp>
+There are 3 main ways to include the CPP-AP library into a C++ project:
+
+#### CMake integration:
+
+For CMake projects you can simply fetch the library in your `CMakeLists.txt` file:
+
+```cmake
+cmake_minimum_required(VERSION 3.12)
+
+project(my_project LANGUAGES CXX)
+
+# Include FetchContent module
+include(FetchContent)
+
+# Fetch CPP-AP library
+FetchContent_Declare(
+    cpp-ap
+    GIT_REPOSITORY https://github.com/SpectraL519/cpp-ap.git
+    GIT_TAG master # here you can specify the desired tag or branch
+)
+
+FetchContent_MakeAvailable(cpp-ap)
+
+# Define the executable for the project
+add_executable(my_project main.cpp)
+
+set_target_properties(my_project PROPERTIES
+    CXX_STANDARD 20
+    CXX_STANDARD_REQUIRED YES
+)
+
+# Link against the cpp-ap library
+target_link_libraries(my_project PRIVATE cpp-ap)
 ```
 
-If you wish to use the library across multiple projects without copying the header into each one, you can copy it into a common directory and add the `-I <argument-parser-dir>` option when compiling your project.
+#### Downloading the library
+
+If you do not use CMake you can dowload the desired [library release](https://github.com/SpectraL519/cpp-ap/releases), extract it in a desired directory and simply add the `<cpp-ap-dir>/include` to the include paths of your project.
+
+#### Downloading the single header
+
+The core of the library is a [single header file](https://github.com/SpectraL519/cpp-ap/blob/master/include/ap/argument_parser.hpp) so to be able to use the library you can simply download the `argument_parser.hpp` header and paste it into the include directory of your project.
+
+> [!IMPORTANT]
+> To actually use the library in your project simply include the single header in you `main.cpp` file:
+> ```c++
+> #include <ap/argument_parser.hpp>
+> ```
+
+<br />
 
 ### The parser class
 
@@ -418,35 +466,7 @@ int main(int argc, char* argv[]) {
 
 ## Examples
 
-If you wish to test the parser functionality with some real examples then follow these steps:
-
-Open your terminal in the project's example directory:
-```shell
-cd <project-root>/example
-```
-
-The examples' source files are in the `<project-root>/example/source` directory.
-
-> [!NOTE]
-> Each source file is a sepparate example.
-
-Building the examples:
-
-```shell
-cmake -B build
-cd build
-make
-```
-
-or
-
-```shell
-mkdir build && cd build
-cmake ..
-make
-```
-
-The compiled binaries will appear in the `<project-root>/example/build/bin` directory.
+The library usage examples / demo projects can be found in the [cpp-ap-demo](https://github.com/SpectraL519/cpp-ap-demo) repository.
 
 <br />
 <br />
@@ -458,43 +478,39 @@ The compiled binaries will appear in the `<project-root>/example/build/bin` dire
 First build the testing executable:
 
 ```shell
-cd <project-root>/test/
 cmake -B build
-cd build
-make
+cd build && make
 ```
 
 or alternatively:
 
 ```shell
-cd <project-root>/test/
 mkdir build && cd build
 cmake ..
 make
 ```
 
+This will build the test executable `run_tests` in the `<project-root>/build/test` directory.
+
 > [!TIP]
 > Building on Windows -  use the `-G "Unix Makefiles"` option when running CMake to build a GNU Make project instead of a default Visual Studio project.
 
 Run the tests:
 
-> [!NOTE]
-> The test executable is generated in the `<project-root>/test/build` directory.
-
 * All tests:
 
     ```shell
-    ./test
+    ./run_tests
     ```
 
 * A single test suite:
 
     ```shell
-    ./test -ts="<test-suite-name>"
+    ./run_tests -ts="<test-suite-name>"
     ```
 
-    > [!NOTE]
-    > Test suites in the project have the same names as the files they're in.
+> [!NOTE]
+> Test suites in the project have the same names as the files they're in.
 
 <br />
 

cmake/cpp-ap-config.cmake.in

@@ -0,0 +1,7 @@
+@PACKAGE_INIT@
+
+include(CMakeFindDependencyMacro)
+
+set_and_check(CPP_AP_INCLUDE_DIR "@PACKAGE_INSTALL_PREFIX@/@CMAKE_INSTALL_INCLUDEDIR@")
+
+include("${CMAKE_CURRENT_LIST_DIR}/cpp-ap-targets.cmake")