From 52f24e50e1802e7afeb8ee7d090fca1bf86b49c0 Mon Sep 17 00:00:00 2001 From: "Tom G. Huang" Date: Mon, 7 Jun 2021 13:55:40 -0700 Subject: [PATCH] docs: Describe vcpkg support --- README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 102 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index e13f848..c32dcaa 100644 --- a/README.md +++ b/README.md @@ -6,19 +6,25 @@ Introduction of Argtable3 ========================= **Argtable3** is an open source ANSI C library that parses GNU-style -command-line options. It simplifies command-line parsing by defining a -declarative-style API that you can use to specify what your command-line syntax -looks like. Argtable3 will automatically generate consistent error handling -logic and textual descriptions of the command line syntax, which are essential -but tedious to implement for a robust CLI program. +command-line options with the `getopt` library. It simplifies command-line +parsing by defining a declarative-style API that you can use to specify what +your command-line syntax looks like. Argtable3 will automatically generate +consistent error handling logic and textual descriptions of the command line +syntax, which are essential but tedious to implement for a robust CLI program. Quick Start ----------- -> We no longer provide the amalgamation source code (`argtable3.c` and -> `argtable3.h`) in the source code repository. You can get the amalgamation -> distribution either from the release page (`argtable-3.x.x-amalgamation.zip`), +You can embed the amalgamation source files in your projects, add Argtable3 as a +dependency in the vcpkg manifest, install Argtable3 as a system-wide CMake +package, or build the library from release archives. + +### Embed Amalgamation Source Files + +> We no longer provide the amalgamation source files (`argtable3.c` and +> `argtable3.h`) in the repository. You can get the amalgamation distribution +> either from the release page (`argtable--amalgamation.(zip|tar.gz)`), > or generate the distribution yourself by using the generator under the `tools` > directory: > @@ -26,12 +32,96 @@ Quick Start > 2. Run `./build dist`, which will generate the distribution under the `/dist` > directory. +Add `argtable3.c` and `argtable3.h` from the amalgamation distribution to your +projects. This is the simplest and recommended way to use Argtable3: it not only +removes the hassle of building the library, but also allows compilers to do +better inter-procedure optimization. + + +### Install for a Single Project with vcpkg Manifest + +[vcpkg](https://vcpkg.io) is an open source C/C++ package manager based on +CMake, and it supports certain stable releases of Argtable3. To add the library +to your CMake project, it's recommended to add vcpkg as a submodule to your +project repo and use it to manage project dependencies. All libraries installed +in this way can only be consumed by the project and won't impact other projects +in the system. + +If your project is under `D:/projects/demo` and the vcpkg submodule is under +`D:/projects/demo/deps/vcpkg`, first you need to add Argtable3 to the manifest, +`D:/projects/demo/vcpkg.json`: +``` +{ + "name": "demo", + "version": "0.0.1", + "dependencies": [ + { + "name": "argtable3", + "version>=": "3.2.1" + } + ], + "builtin-baseline": "a3db16a4475b963cacf0260068c497fb72c8f3c0" +} +``` + +To add Argtable3 to your CMake scripts, you need to integrate the local vcpkg to +CMake by setting the `CMAKE_TOOLCHAIN_FILE` variable. You also need to link to +the static VC runtime (`/MT` or `/MTd`) if you want to use the static library +version of Argtable3: +``` +cmake_minimum_required(VERSION 3.18) + +set(CMAKE_TOOLCHAIN_FILE ${CMAKE_CURRENT_SOURCE_DIR}/deps/vcpkg/scripts/buildsystems/vcpkg.cmake + CACHE STRING "Vcpkg toolchain file") + +project(versionstest) + +add_executable(main main.cpp) + +find_package(Argtable3 CONFIG REQUIRED) +target_link_libraries(main PRIVATE argtable3::argtable3) + +if(VCPKG_TARGET_TRIPLET STREQUAL "x64-windows-static") + set_property(TARGET main PROPERTY MSVC_RUNTIME_LIBRARY "MultiThreaded$<$:Debug>") +endif() +``` + +Now you can run `cmake` to install Argtable3, configure and generate build +scripts, and build the project: +``` +$ mkdir build +$ cd build +$ cmake .. -DVCPKG_TARGET_TRIPLET=x64-windows-static +$ cmake --build . +``` + +### Install for All Projects with vcpkg + +If you want to make Argtable3 available for all projects in the system, you can +clone vcpkg to any directory and install packages there. Assuming vcpkg has been +cloned in `D:/dev/vcpkg` and the directory has been added to `PATH`, you can +install the static library version of Argtable3 in `D:/dev/vcpkg/installed`: +``` +$ vcpkg install argtable3:x64-windows-static +``` + +Since each developer may clone vcpkg in a different place, it may not be +appropriate to specify the `CMAKE_TOOLCHAIN_FILE` variable in `CMakeLists.txt`. +Therefore, you should remove setting the `CMAKE_TOOLCHAIN_FILE` variable in the +`CMakeLists.txt` example above, and set the variable in the command line: +``` +$ mkdir build +$ cd build +$ cmake .. -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=D:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake +$ cmake --build . +``` + -Argtable3 is a single-file ANSI-C library. All you have to do is adding -`argtable3.c` to your projects, and including `argtable3.h` in your source code. +### Build from Release Archives or Source -To build the library, examples, and unit tests, use CMake to generate -out-of-source build: +If none of the methods above suits your needs, or if you want to help developing +Argtable3, you can always build from archives on the release page or from the +repository. * If you use GCC (Linux, MacOSX, MinGW, Cygwin), run: