mirrors/CLI11
1
0
Fork 0
mirror of https://github.com/CLIUtils/CLI11.git synced 2025-04-30 12:43:52 +00:00
Code Issues Releases Wiki Activity

docs: move and update installation (#901)

Browse Source 
This PR includes updates from #774 and #613.  
It updates the readme and docbook with some additional installation
instructions.

---------

Co-authored-by: Owen Parkins <oparkins@users.noreply.github.com>
Co-authored-by: Mengna Li <Adela0814@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
This commit is contained in:
Philip Top 2023-07-11 05:43:16 -07:00 committed by GitHub
parent bf4bdcaf39
commit ccf141c49d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 139 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
README.md
View File

@ -172,7 +172,8 @@ this library:
## Install
To use, there are several methods:
To use, the most common methods are described here additional methods and
details are available at [installation][]:
- All-in-one local header: Copy `CLI11.hpp` from the [most recent
release][github releases] into your include directory, and you are set. This
@ -183,98 +184,8 @@ To use, there are several methods:
- All-in-one global header: Like above, but copying the file to a shared folder
location like `/opt/CLI11`. Then, the C++ include path has to be extended to
point at this folder. With CMake 3.5+, use `include_directories(/opt/CLI11)`
- Local headers and target: Use `CLI/*.hpp` files. You could check out the
repository as a git submodule, for example. With CMake, you can use
`add_subdirectory` and the `CLI11::CLI11` interface target when linking. If
not using a submodule, you must ensure that the copied files are located
inside the same tree directory than your current project, to prevent an error
with CMake and `add_subdirectory`.
- Global headers: Use `CLI/*.hpp` files stored in a shared folder. You could
check out the git repository to a system-wide folder, for example `/opt/`.
With CMake, you could add to the include path via:
```bash
if(NOT DEFINED CLI11_DIR)
set (CLI11_DIR "/opt/CLI11" CACHE STRING "CLI11 git repository")
endif()
include_directories(${CLI11_DIR}/include)
```
And then in the source code (adding several headers might be needed to prevent
linker errors):
```cpp
#include "CLI/App.hpp"
#include "CLI/Formatter.hpp"
#include "CLI/Config.hpp"
```
- Global headers and target: configuring and installing the project is required
for linking CLI11 to your project in the same way as you would do with any
other external library. With CMake, this step allows using
`find_package(CLI11 CONFIG REQUIRED)` and then using the `CLI11::CLI11` target
when linking. If `CMAKE_INSTALL_PREFIX` was changed during install to a
specific folder like `/opt/CLI11`, then you have to pass
`-DCLI11_DIR=/opt/CLI11` when building your current project. You can also use
[Conan.io][conan-link] or [Hunter][]. (These are just conveniences to allow
you to use your favorite method of managing packages; it's just header only so
including the correct path and using C++11 is all you really need.)
- Via FetchContent in CMake 3.14+ (or 3.11+ with more work): you can add this
with fetch-content, then use the `CLI11::CLI11` target as above, and CMake
will download the project in the configure stage:
```cmake
include(FetchContent)
FetchContent_Declare(
cli11
GIT_REPOSITORY https://github.com/CLIUtils/CLI11
GIT_TAG v2.3.2
)
FetchContent_MakeAvailable(cli11)
```
It is highly recommended that you use the git hash for `GIT_TAG` instead of a
tag or branch, as that will both be more secure, as well as faster to
reconfigure - CMake will not have to reach out to the internet to see if the tag
moved. You can also download just the single header file from the releases using
`file(DOWNLOAD`.
To build the tests, checkout the repository and use CMake:
```bash
cmake -S . -B build
cmake --build build
CTEST_OUTPUT_ON_FAILURE=1 cmake --build build -t test
```
<details><summary>Note: Special instructions for GCC 8</summary><p>
If you are using GCC 8 and using it in C++17 mode with CLI11. CLI11 makes use of
the `<filesystem>` header if available, but specifically for this compiler, the
`filesystem` library is separate from the standard library and needs to be
linked separately. So it is available but CLI11 doesn't use it by default.
Specifically `libstdc++fs` needs to be added to the linking list and
`CLI11_HAS_FILESYSTEM=1` has to be defined. Then the filesystem variant of the
Validators could be used on GCC 8. GCC 9+ does not have this issue so the
`<filesystem>` is used by default.
There may also be other cases where a specific library needs to be linked.
Defining `CLI11_HAS_FILESYSTEM=0` which will remove the usage and hence any
linking issue.
In some cases certain clang compilations may require linking against `libc++fs`.
These situations have not been encountered so the specific situations requiring
them are unknown yet.
If building with WASI it is necessary to add the flag
`-lc-printscan-long-double` to the build to allow long double support. See #841
for more details.
</p></details>
</br>
- For other methods including using CMake or vcpkg and some specific
instructions for GCC 8 or WASI see [installation][].
## Usage
@ -1491,8 +1402,6 @@ need to convert to. Some examples of some new parsers for `complex<double>` that
support all of the features of a standard `add_options` call are in
[one of the tests](./tests/NewParseTest.cpp). A simpler example is shown below:
#### Example
```cpp
app.add_option("--fancy-count", [](std::vector<std::string> val){
std::cout << "This option was given " << val.size() << " times." << std::endl;
@ -1908,3 +1817,4 @@ try! Feedback is always welcome.
[argparse]: https://github.com/p-ranav/argparse
[toml]: https://toml.io
[lyra]: https://github.com/bfgroup/Lyra
[installation]: https://cliutils.github.io/CLI11/book/chapters/installation.html

143
book/chapters/installation.md
View File

@ -9,7 +9,8 @@
This example uses the single file edition of CLI11. You can download `CLI11.hpp`
from the latest release and put it into the same folder as your source code,
then compile this with C++ enabled. For a larger project, you can just put this
in an include folder and you are set.
in an include folder and you are set. This is the simplest and most
straightforward means of including CLI11 with a project.
## Full edition
@ -46,6 +47,83 @@ necessary `lib/cmake/CLI11/CLI11Config.cmake` files, so
If you use conan.io, CLI11 supports that too. CLI11 also supports Meson and
pkg-config if you are not using CMake.
If the CMake option `CLI11_PRECOMPILED` is set then the library is compiled into
a static library. This can be used to improve compile times if CLI11 is included
in many different parts of a project.
### Global Headers
Use `CLI/*.hpp` files stored in a shared folder. You could check out the git
repository to a system-wide folder, for example `/opt/`. With CMake, you could
add to the include path via:
```bash
if(NOT DEFINED CLI11_DIR)
set (CLI11_DIR "/opt/CLI11" CACHE STRING "CLI11 git repository")
endif()
include_directories(${CLI11_DIR}/include)
```
And then in the source code (adding several headers might be needed to prevent
linker errors):
```cpp
#include "CLI/App.hpp"
#include "CLI/Formatter.hpp"
#include "CLI/Config.hpp"
```
#### Global Headers with Target
configuring and installing the project is required for linking CLI11 to your
project in the same way as you would do with any other external library. With
CMake, this step allows using `find_package(CLI11 CONFIG REQUIRED)` and then
using the `CLI11::CLI11` target when linking. If `CMAKE_INSTALL_PREFIX` was
changed during install to a specific folder like `/opt/CLI11`, then you have to
pass `-DCLI11_DIR=/opt/CLI11` when building your current project. You can also
use [Conan.io](https://conan.io/center/cli11) or
[Hunter](https://docs.hunter.sh/en/latest/packages/pkg/CLI11.html). (These are
just conveniences to allow you to use your favorite method of managing packages;
it's just header only so including the correct path and using C++11 is all you
really need.)
#### Using Fetchcontent
If you do not want to add cmake as a submodule or include it with your code the
project can be added using `FetchContent`. This capability requires CMake 3.14+
(or 3.11+ with more work).
An example CMake file would include:
```cmake
include(FetchContent)
FetchContent_Populate(
cli11_proj
QUIET
GIT_REPOSITORY https://github.com/CLIUtils/CLI11.git
GIT_TAG v2.3.2
SOURCE_DIR cli11_proj
)
FetchContent_MakeAvailable(cli11)
# And now you can use it
add_subdirectory(${cli11_proj_SOURCE_DIR} ${cli11_proj_SOURCE_DIR}/build)
target_link_libraries(<your project> CLI11::CLI11)
```
And use
```c++
#include <CLI/CLI.hpp>
```
in your project. It is highly recommended that you use the git hash for
`GIT_TAG` instead of a tag or branch, as that will both be more secure, as well
as faster to reconfigure - CMake will not have to reach out to the internet to
see if the tag moved. You can also download just the single header file from the
releases using `file(DOWNLOAD)`.
### Running tests on the full edition
CLI11 has examples and tests that can be accessed using a CMake build on any
@ -100,16 +178,63 @@ Total Test time (real) = 0.34 sec
For the curious, the CMake options and defaults are listed below. Most options
default to off if CLI11 is used as a subdirectory in another project.
| Option | Description |
| ----------------------------- | ----------------------------------------------------------------------------------------------- |
| `CLI11_SINGLE_FILE=ON` | Build the `CLI11.hpp` file from the sources. Requires Python (version 3 or 2.7). |
| `CLI11_SINGLE_FILE_TESTS=OFF` | Run the tests on the generated single file version as well |
| `CLI11_EXAMPLES=ON` | Build the example programs. |
| `CLI11_TESTING=ON` | Build the tests. |
| `CLI11_CLANG_TIDY=OFF` | Run `clang-tidy` on the examples and headers. Requires CMake 3.6+. |
| `CLI11_CLANG_TIDY_OPTIONS=""` | Options to pass to `clang-tidy`, such as `-fix` (single threaded build only if applying fixes!) |
| Option | Description |
| ------------------------------ | -------------------------------------------------------------------------------- |
| `CLI11_SINGLE_FILE=ON` | Build the `CLI11.hpp` file from the sources. Requires Python (version 3 or 2.7). |
| `CLI11_PRECOMPILED=OFF` | generate a precompiled static library instead of header-only |
| `CLI11_SINGLE_FILE_TESTS=OFF` | Run the tests on the generated single file version as well |
| `CLI11_BUILD_DOCS=ON` | build CLI11 documentation and book |
| `CLI11_BUILD_EXAMPLES=ON` | Build the example programs. |
| `CLI11_BUILD_EXAMPLES_JSON=ON` | Build some additional example using json libraries |
| `CLI11_INSTALL=ON` | install CLI11 to the install folder during the install process |
| `CLI11_FORCE_LIBCXX=OFF` | use libc++ instead of libstdc++ if building with clang on linux |
| `CLI11_CUDA_TESTS=OFF` | build the tests with NVCC |
| `CLI11_BUILD_TESTS=ON` | Build the tests. |
[^1]:
Docker is being used to create a pristine disposable environment; there is
nothing special about this container. Alpine is being used because it is
small, modern, and fast. Commands are similar on any other platform.
## Installing cli11 using vcpkg
You can download and install cli11 using the
[vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
```bash
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install cli11
```
The cli11 port in vcpkg is kept up to date by Microsoft team members and
community contributors. If the version is out of date, please
[create an issue or pull request](https://github.com/Microsoft/vcpkg) on the
vcpkg repository.
## Special instructions for GCC 8, Some clang, and WASI
If you are using GCC 8 and using it in C++17 mode with CLI11. CLI11 makes use of
the `<filesystem>` header if available, but specifically for this compiler, the
`filesystem` library is separate from the standard library and needs to be
linked separately. So it is available but CLI11 doesn't use it by default.
Specifically `libstdc++fs` needs to be added to the linking list and
`CLI11_HAS_FILESYSTEM=1` has to be defined. Then the filesystem variant of the
Validators could be used on GCC 8. GCC 9+ does not have this issue so the
`<filesystem>` is used by default.
There may also be other cases where a specific library needs to be linked.
Defining `CLI11_HAS_FILESYSTEM=0` which will remove the usage and hence any
linking issue.
In some cases certain clang compilations may require linking against `libc++fs`.
These situations have not been encountered so the specific situations requiring
them are unknown yet.
If building with WASI it is necessary to add the flag
`-lc-printscan-long-double` to the build to allow long double support. See #841
for more details.