Update building documentation

mmahnic · Feb 10, 2023 · f876c2d · f876c2d
1 parent bae1d59
commit f876c2d
Showing 1 changed file with 169 additions and 50 deletions.
diff --git a/doc/building.md b/doc/building.md
@@ -1,137 +1,256 @@
 # Building and consuming the library
 
-The recommended way to consume the library is build and link the static
-library.  A dynamic version is planned.
+The recommended way to consume the library is to build and link the static library.
 
-The library is also available in VCPKG (`./vcpkg install argumentum`).
+If installing is not an option, the library can be used from source. The header-only library can be
+used without building. To
+It can be used a header-only or static
+library by cloning the repository and linking to the appropriate `Argumentum` target.
 
-If building is not an option, the library can be used as header-only by cloning
-the repository and using the appropriate include path.
+The library is also available through VCPKG (`./vcpkg install argumentum`).
 
 
-## Ubuntu/Debian: Build, install and use the static library
+## Build, install and use the static library
 
-```
+Build and install the library from the sources:
+
+```bash
 cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Release
 cd build
 cmake --build .
 sudo make install
 ```
 
-CMakeLists.txt:
+Use the static library in a project:
+
+```cmake
+# CMakeLists.txt
+
+cmake_minimum_required( VERSION 3.1 )
+project( Example VERSION 0.0.1 )
 
-```
 find_package( Argumentum CONFIG REQUIRED )
 set( CMAKE_CXX_STANDARD 17 )
 
 add_executable( example
    main.cpp
    )
 target_link_libraries( example
+   PRIVATE
    Argumentum::argumentum
    )
 ```
 
-main.cpp:
 
-```
+```C++
+// main.cpp:
+
 #include <argumentum/argparse.h>
 using namespace argumentum;
 ```
 
+## Install and use the header-only library
+
+Differences compared to the use of the installed static library:
+
+- Define `-DARGUMENTUM_INSTALL_HEADERONLY=ON` when calling `cmake`.
+- The static library doesn't have to be built when using `cmake`:
+  `-DARGUMENTUM_BUILD_STATIC_LIBS=OFF`.
+- Link to the target `Argumentum::headers`.
+- Use the header `<argumentum/argparse-h.h>`.
+
+Build and install the library from the sources:
+
+```bash
+cmake -H. -Bbuild -DARGUMENTUM_INSTALL_HEADERONLY=ON -DARGUMENTUM_BUILD_STATIC_LIBS=OFF
+cd build
+cmake --build .
+sudo make install
+```
+
+Use the header-only library in a project:
+
+```cmake
+# CMakeLists.txt:
+
+cmake_minimum_required( VERSION 3.1 )
+project( Example VERSION 0.0.1 )
+
+find_package( Argumentum CONFIG REQUIRED )
+set( CMAKE_CXX_STANDARD 17 )
+
+add_executable( example
+   main.cpp
+   )
+target_link_libraries( example
+   PRIVATE
+   Argumentum::headers
+   )
+```
+
+
+```C++
+// main.cpp:
+
+#include <argumentum/argparse-h.h>
+using namespace argumentum;
+```
+
 
 ## Vcpkg
 
 In `vcpkg` directory:
 
-```
+```bash
 ./vcpkg install argumentum
 ```
 
 Use in your CMake project:
 
-```
+```bash
 cmake -H. -Bbuild -DCMAKE_TOOLCHAIN_FILE=path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
 ```
 
 
-## Header-only from a cloned repository
+## Using the library from a cloned repository without installing
 
-```
-git clone https://github.com/mmahnic/argumentum.git 3rdparty/argumentum
+Download the library with `git clone`
+
+```bash
+git clone https://github.com/mmahnic/argumentum.git external/argumentum
 ```
 
-or
+or with `git submodule` inside your project's git repository
 
-```
-git submodule add https://github.com/mmahnic/argumentum.git 3rdparty/argumentum
+```bash
+git submodule add https://github.com/mmahnic/argumentum.git external/argumentum
 ```
 
-CMakeLists.txt:
+### Use the static library from a cloned repository
 
-```
-include_directories( 3rdparty/argumenutm/include )
-```
+Add the library to a project as a subdirectory:
 
+```cmake
+# CMakeLists.txt:
 
-main.cpp:
+cmake_minimum_required( VERSION 3.1 )
+project( Example VERSION 0.0.1 )
 
-```
-#include <argumentum/argparse-h.h>
-using namespace argumentum;
+add_subdirectory( external/argumentum )
+
+set( CMAKE_CXX_STANDARD 17 )
+
+add_executable( example main.cpp )
+target_link_libraries( example 
+   PRIVATE
+   Argumentum::argumentum
+   )
 ```
 
-Note that the header-only version has a separate header `<argumentum/argparse-h.h>`.
 
-Compile from the command line:
+```C++
+// main.cpp:
 
+#include <argumentum/argparse.h>
+using namespace argumentum;
 ```
-g++ -Wall -Werror -std=c++17 -o example -I $(pwd)/argumentum/include main.cpp
+
+To build the project, building of the static library must be enabled:
+
+```bash
+cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Release -DARGUMENTUM_BUILD_STATIC_LIBS=ON
+cmake --build build
 ```
 
 
-## Use the static library from a cloned repository
+### Use the Header-only version from a cloned repository
 
+Differences compared to the use of the cloned static library:
+
+- Link to the target `Argumentum::headers`.
+- Use the header `<argumentum/argparse-h.h>`.
+- The static library doesn't have to be built when using `cmake`:
+  `-DARGUMENTUM_BUILD_STATIC_LIBS=OFF`.
+
+```cmake
+# CMakeLists.txt:
+
+cmake_minimum_required( VERSION 3.1 )
+project( Example VERSION 0.0.1 )
+
+add_subdirectory( external/argumentum )
+
+set( CMAKE_CXX_STANDARD 17 )
+
+add_executable( example main.cpp )
+target_link_libraries( example 
+   PRIVATE 
+   Argumentum::headers
+   )
 ```
-git clone https://github.com/mmahnic/argumentum.git 3rdparty/argumentum
-```
 
-or
 
+```C++
+// main.cpp:
+
+#include <argumentum/argparse-h.h>
+using namespace argumentum;
 ```
-git submodule add https://github.com/mmahnic/argumentum.git 3rdparty/argumentum
+
+Build with `cmake`:
+
+```bash
+cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Release
+cmake --build build
 ```
 
-CMakeLists.txt:
+Or compile from the command line if not using CMake:
 
+```bash
+g++ -Wall -Werror -std=c++17 -o example -I $(pwd)/external/argumentum/include main.cpp
 ```
-cmake_minimum_required( VERSION 3.1 )
-project( Basic VERSION 0.0.1 )
 
-add_subdirectory( 3rdparty/argumentum )
+
+## Using the library with CMake FetchContent
+
+The library can also be used with `FetchContent` without cloning the library in advance.
+
+```cmake
+cmake_minimum_required( VERSION 3.11 )
+project( Example VERSION 0.0.1 )
 
 set( CMAKE_CXX_STANDARD 17 )
 
-include_directories( 3rdparty/argumentum/include )
+include(FetchContent)
+
+FetchContent_Declare(Argumentum
+   GIT_REPOSITORY https://github.com/mmahnic/argumentum.git
+   GIT_TAG master
+)
+FetchContent_MakeAvailable(Argumentum)
 
 add_executable( example main.cpp )
-target_link_libraries( example argumentum )
-add_dependencies( example argumentum )
+target_link_libraries( example 
+   PRIVATE 
+   Argumentum::argumentum
+   # With header-only: Argumentum::headers
+   )
 ```
 
 
-main.cpp:
+```C++
+// main.cpp:
 
-```
 #include <argumentum/argparse.h>
+// With header-only: #include <argumentum/argparse-h.h>
+
 using namespace argumentum;
 ```
 
-Compile from the command line:
+To use the static version of the library, building of the static version must be enabled with
+`-DARGUMENTUM_BUILD_STATIC_LIBS=ON`:
 
+```bash
+cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Release -DARGUMENTUM_BUILD_STATIC_LIBS=ON
+cmake --build build
 ```
-cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Release
-cd build
-cmake --build .
-```
-