From e6918187568dbd01842d8d1d2c808ce16a894239 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 21 Apr 2024 13:54:28 +0200 Subject: Adding upstream version 18.2.2. Signed-off-by: Daniel Baumann --- src/fmt/doc/usage.rst | 212 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 src/fmt/doc/usage.rst (limited to 'src/fmt/doc/usage.rst') diff --git a/src/fmt/doc/usage.rst b/src/fmt/doc/usage.rst new file mode 100644 index 000000000..f9f818584 --- /dev/null +++ b/src/fmt/doc/usage.rst @@ -0,0 +1,212 @@ +***** +Usage +***** + +To use the {fmt} library, add :file:`fmt/core.h`, :file:`fmt/format.h`, +:file:`fmt/format-inl.h`, :file:`src/format.cc` and optionally other headers +from a `release archive `_ or +the `Git repository `_ to your project. +Alternatively, you can :ref:`build the library with CMake `. + +.. _building: + +Building the Library +==================== + +The included `CMake build script`__ can be used to build the fmt +library on a wide range of platforms. CMake is freely available for +download from https://www.cmake.org/download/. + +__ https://github.com/fmtlib/fmt/blob/master/CMakeLists.txt + +CMake works by generating native makefiles or project files that can +be used in the compiler environment of your choice. The typical +workflow starts with:: + + mkdir build # Create a directory to hold the build output. + cd build + cmake .. # Generate native build scripts. + +where :file:`{}` is a path to the ``fmt`` repository. + +If you are on a \*nix system, you should now see a Makefile in the +current directory. Now you can build the library by running :command:`make`. + +Once the library has been built you can invoke :command:`make test` to run +the tests. + +You can control generation of the make ``test`` target with the ``FMT_TEST`` +CMake option. This can be useful if you include fmt as a subdirectory in +your project but don't want to add fmt's tests to your ``test`` target. + +If you use Windows and have Visual Studio installed, a :file:`FMT.sln` +file and several :file:`.vcproj` files will be created. You can then build them +using Visual Studio or msbuild. + +On Mac OS X with Xcode installed, an :file:`.xcodeproj` file will be generated. + +To build a `shared library`__ set the ``BUILD_SHARED_LIBS`` CMake variable to +``TRUE``:: + + cmake -DBUILD_SHARED_LIBS=TRUE ... + +__ https://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries + + +To build a `static library` with position independent code (required if the main +consumer of the fmt library is a shared library i.e. a Python extension) set the +``CMAKE_POSITION_INDEPENDENT_CODE`` CMake variable to ``TRUE``:: + + cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE ... + + +Installing the Library +====================== + +After building the library you can install it on a Unix-like system by running +:command:`sudo make install`. + +Usage with CMake +================ + +You can add the ``fmt`` library directory into your project and include it in +your ``CMakeLists.txt`` file:: + + add_subdirectory(fmt) + +or + +:: + + add_subdirectory(fmt EXCLUDE_FROM_ALL) + +to exclude it from ``make``, ``make all``, or ``cmake --build .``. + +You can detect and use an installed version of {fmt} as follows:: + + find_package(fmt) + target_link_libraries( fmt::fmt) + +Setting up your target to use a header-only version of ``fmt`` is equally easy:: + + target_link_libraries( PRIVATE fmt::fmt-header-only) + +Usage with build2 +================= + +You can use `build2 `_, a dependency manager and a +build-system combined, to use ``fmt``. + +Currently this package is available in these package repositories: + +- **https://cppget.org/fmt/** for released and published versions. +- `The git repository with the sources of the build2 package of fmt `_ + for unreleased or custom revisions of ``fmt``. + +**Usage:** + +- ``build2`` package name: ``fmt`` +- Library target name : ``lib{fmt}`` + +For example, to make your ``build2`` project depend on ``fmt``: + +- Add one of the repositories to your configurations, or in your + ``repositories.manifest``, if not already there:: + + : + role: prerequisite + location: https://pkg.cppget.org/1/stable + +- Add this package as a dependency to your ``./manifest`` file + (example for ``v7.0.x``):: + + depends: fmt ~7.0.0 + +- Import the target and use it as a prerequisite to your own target + using `fmt` in the appropriate ``buildfile``:: + + import fmt = fmt%lib{fmt} + lib{mylib} : cxx{**} ... $fmt + +Then build your project as usual with `b` or `bdep update`. + +For ``build2`` newcomers or to get more details and use cases, you can read the +``build2`` +`toolchain introduction `_. + +Building the Documentation +========================== + +To build the documentation you need the following software installed on your +system: + +* `Python `_ with pip and virtualenv +* `Doxygen `_ +* `Less `_ with ``less-plugin-clean-css``. + Ubuntu doesn't package the ``clean-css`` plugin so you should use ``npm`` + instead of ``apt`` to install both ``less`` and the plugin:: + + sudo npm install -g less less-plugin-clean-css. + +First generate makefiles or project files using CMake as described in +the previous section. Then compile the ``doc`` target/project, for example:: + + make doc + +This will generate the HTML documentation in ``doc/html``. + +Conda +===== + +fmt can be installed on Linux, macOS and Windows with +`Conda `__, using its +`conda-forge `__ +`package `__, as follows:: + + conda install -c conda-forge fmt + +Vcpkg +===== + +You can download and install fmt using the `vcpkg +`__ dependency manager:: + + git clone https://github.com/Microsoft/vcpkg.git + cd vcpkg + ./bootstrap-vcpkg.sh + ./vcpkg integrate install + ./vcpkg install fmt + +The fmt 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 `__ on the vcpkg repository. + +LHelper +======= + +You can download and install fmt using +`lhelper `__ dependency manager:: + + lhelper activate + lhelper install fmt + +All the recipes for lhelper are kept in the +`lhelper's recipe `__ repository. + +Android NDK +=========== + +fmt provides `Android.mk file`__ that can be used to build the library +with `Android NDK `_. +For an example of using fmt with Android NDK, see the +`android-ndk-example `_ +repository. + +__ https://github.com/fmtlib/fmt/blob/master/support/Android.mk + +Homebrew +======== + +fmt can be installed on OS X using `Homebrew `_:: + + brew install fmt -- cgit v1.2.3