1***** 2Usage 3***** 4 5To use the {fmt} library, add :file:`fmt/core.h`, :file:`fmt/format.h`, 6:file:`fmt/format-inl.h`, :file:`src/format.cc` and optionally other headers 7from a `release archive <https://github.com/fmtlib/fmt/releases/latest>`_ or 8the `Git repository <https://github.com/fmtlib/fmt>`_ to your project. 9Alternatively, you can :ref:`build the library with CMake <building>`. 10 11.. _building: 12 13Building the Library 14==================== 15 16The included `CMake build script`__ can be used to build the fmt 17library on a wide range of platforms. CMake is freely available for 18download from https://www.cmake.org/download/. 19 20__ https://github.com/fmtlib/fmt/blob/master/CMakeLists.txt 21 22CMake works by generating native makefiles or project files that can 23be used in the compiler environment of your choice. The typical 24workflow starts with:: 25 26 mkdir build # Create a directory to hold the build output. 27 cd build 28 cmake .. # Generate native build scripts. 29 30where :file:`{<path/to/fmt>}` is a path to the ``fmt`` repository. 31 32If you are on a \*nix system, you should now see a Makefile in the 33current directory. Now you can build the library by running :command:`make`. 34 35Once the library has been built you can invoke :command:`make test` to run 36the tests. 37 38You can control generation of the make ``test`` target with the ``FMT_TEST`` 39CMake option. This can be useful if you include fmt as a subdirectory in 40your project but don't want to add fmt's tests to your ``test`` target. 41 42If you use Windows and have Visual Studio installed, a :file:`FMT.sln` 43file and several :file:`.vcproj` files will be created. You can then build them 44using Visual Studio or msbuild. 45 46On Mac OS X with Xcode installed, an :file:`.xcodeproj` file will be generated. 47 48To build a `shared library`__ set the ``BUILD_SHARED_LIBS`` CMake variable to 49``TRUE``:: 50 51 cmake -DBUILD_SHARED_LIBS=TRUE ... 52 53__ https://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries 54 55 56To build a `static library` with position independent code (required if the main 57consumer of the fmt library is a shared library i.e. a Python extension) set the 58``CMAKE_POSITION_INDEPENDENT_CODE`` CMake variable to ``TRUE``:: 59 60 cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE ... 61 62 63Installing the Library 64====================== 65 66After building the library you can install it on a Unix-like system by running 67:command:`sudo make install`. 68 69Usage with CMake 70================ 71 72You can add the ``fmt`` library directory into your project and include it in 73your ``CMakeLists.txt`` file:: 74 75 add_subdirectory(fmt) 76 77or 78 79:: 80 81 add_subdirectory(fmt EXCLUDE_FROM_ALL) 82 83to exclude it from ``make``, ``make all``, or ``cmake --build .``. 84 85You can detect and use an installed version of {fmt} as follows:: 86 87 find_package(fmt) 88 target_link_libraries(<your-target> fmt::fmt) 89 90Setting up your target to use a header-only version of ``fmt`` is equally easy:: 91 92 target_link_libraries(<your-target> PRIVATE fmt::fmt-header-only) 93 94Usage with build2 95================= 96 97You can use `build2 <https://build2.org>`_, a dependency manager and a 98build-system combined, to use ``fmt``. 99 100Currently this package is available in these package repositories: 101 102- **https://cppget.org/fmt/** for released and published versions. 103- `The git repository with the sources of the build2 package of fmt <https://github.com/build2-packaging/fmt.git>`_ 104 for unreleased or custom revisions of ``fmt``. 105 106**Usage:** 107 108- ``build2`` package name: ``fmt`` 109- Library target name : ``lib{fmt}`` 110 111For example, to make your ``build2`` project depend on ``fmt``: 112 113- Add one of the repositories to your configurations, or in your 114 ``repositories.manifest``, if not already there:: 115 116 : 117 role: prerequisite 118 location: https://pkg.cppget.org/1/stable 119 120- Add this package as a dependency to your ``./manifest`` file 121 (example for ``v7.0.x``):: 122 123 depends: fmt ~7.0.0 124 125- Import the target and use it as a prerequisite to your own target 126 using `fmt` in the appropriate ``buildfile``:: 127 128 import fmt = fmt%lib{fmt} 129 lib{mylib} : cxx{**} ... $fmt 130 131Then build your project as usual with `b` or `bdep update`. 132 133For ``build2`` newcomers or to get more details and use cases, you can read the 134``build2`` 135`toolchain introduction <https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml>`_. 136 137Usage with Meson 138================ 139 140`Meson's WrapDB <https://mesonbuild.com/Wrapdb-projects.html>` includes a ``fmt`` 141package, which repackages fmt to be built by Meson as a subproject. 142 143**Usage:** 144 145- Install the ``fmt`` subproject from the WrapDB by running:: 146 147 meson wrap install fmt 148 149 from the root of your project. 150 151- In your project's ``meson.build`` file, add an entry for the new subproject:: 152 153 fmt = subproject('fmt') 154 fmt_dep = fmt.get_variable('fmt_dep') 155 156- Include the new dependency object to link with fmt:: 157 158 my_build_target = executable('name', 'src/main.cc', dependencies: [fmt_dep]) 159 160**Options:** 161 162If desired, ``fmt`` may be built as a static library, or as a header-only 163library. 164 165For a static build, use the following subproject definition:: 166 167 fmt = subproject('fmt', default_options: 'default_library=static') 168 fmt_dep = fmt.get_variable('fmt_dep') 169 170For the header-only version, use:: 171 172 fmt = subproject('fmt') 173 fmt_dep = fmt.get_variable('fmt_header_only_dep') 174 175Building the Documentation 176========================== 177 178To build the documentation you need the following software installed on your 179system: 180 181* `Python <https://www.python.org/>`_ with pip and virtualenv 182* `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ 183* `Less <http://lesscss.org/>`_ with ``less-plugin-clean-css``. 184 Ubuntu doesn't package the ``clean-css`` plugin so you should use ``npm`` 185 instead of ``apt`` to install both ``less`` and the plugin:: 186 187 sudo npm install -g less less-plugin-clean-css. 188 189First generate makefiles or project files using CMake as described in 190the previous section. Then compile the ``doc`` target/project, for example:: 191 192 make doc 193 194This will generate the HTML documentation in ``doc/html``. 195 196Conda 197===== 198 199fmt can be installed on Linux, macOS and Windows with 200`Conda <https://docs.conda.io/en/latest/>`__, using its 201`conda-forge <https://conda-forge.org>`__ 202`package <https://github.com/conda-forge/fmt-feedstock>`__, as follows:: 203 204 conda install -c conda-forge fmt 205 206Vcpkg 207===== 208 209You can download and install fmt using the `vcpkg 210<https://github.com/Microsoft/vcpkg>`__ dependency manager:: 211 212 git clone https://github.com/Microsoft/vcpkg.git 213 cd vcpkg 214 ./bootstrap-vcpkg.sh 215 ./vcpkg integrate install 216 ./vcpkg install fmt 217 218The fmt port in vcpkg is kept up to date by Microsoft team members and community 219contributors. If the version is out of date, please `create an issue or pull 220request <https://github.com/Microsoft/vcpkg>`__ on the vcpkg repository. 221 222LHelper 223======= 224 225You can download and install fmt using 226`lhelper <https://github.com/franko/lhelper>`__ dependency manager:: 227 228 lhelper activate <some-environment> 229 lhelper install fmt 230 231All the recipes for lhelper are kept in the 232`lhelper's recipe <https://github.com/franko/lhelper-recipes>`__ repository. 233 234Android NDK 235=========== 236 237fmt provides `Android.mk file`__ that can be used to build the library 238with `Android NDK <https://developer.android.com/tools/sdk/ndk/index.html>`_. 239For an example of using fmt with Android NDK, see the 240`android-ndk-example <https://github.com/fmtlib/android-ndk-example>`_ 241repository. 242 243__ https://github.com/fmtlib/fmt/blob/master/support/Android.mk 244 245Homebrew 246======== 247 248fmt can be installed on OS X using `Homebrew <https://brew.sh/>`_:: 249 250 brew install fmt 251