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 http://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__ http://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 137Building the Documentation 138========================== 139 140To build the documentation you need the following software installed on your 141system: 142 143* `Python <https://www.python.org/>`_ with pip and virtualenv 144* `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ 145* `Less <http://lesscss.org/>`_ with ``less-plugin-clean-css``. 146 Ubuntu doesn't package the ``clean-css`` plugin so you should use ``npm`` 147 instead of ``apt`` to install both ``less`` and the plugin:: 148 149 sudo npm install -g less less-plugin-clean-css. 150 151First generate makefiles or project files using CMake as described in 152the previous section. Then compile the ``doc`` target/project, for example:: 153 154 make doc 155 156This will generate the HTML documentation in ``doc/html``. 157 158Conda 159===== 160 161fmt can be installed on Linux, macOS and Windows with 162`Conda <https://docs.conda.io/en/latest/>`__, using its 163`conda-forge <https://conda-forge.org>`__ 164`package <https://github.com/conda-forge/fmt-feedstock>`__, as follows:: 165 166 conda install -c conda-forge fmt 167 168Vcpkg 169===== 170 171You can download and install fmt using the `vcpkg 172<https://github.com/Microsoft/vcpkg>`__ dependency manager:: 173 174 git clone https://github.com/Microsoft/vcpkg.git 175 cd vcpkg 176 ./bootstrap-vcpkg.sh 177 ./vcpkg integrate install 178 ./vcpkg install fmt 179 180The fmt port in vcpkg is kept up to date by Microsoft team members and community 181contributors. If the version is out of date, please `create an issue or pull 182request <https://github.com/Microsoft/vcpkg>`__ on the vcpkg repository. 183 184LHelper 185======= 186 187You can download and install fmt using 188`lhelper <https://github.com/franko/lhelper>`__ dependency manager:: 189 190 lhelper activate <some-environment> 191 lhelper install fmt 192 193All the recipes for lhelper are kept in the 194`lhelper's recipe <https://github.com/franko/lhelper-recipes>`__ repository. 195 196Android NDK 197=========== 198 199fmt provides `Android.mk file`__ that can be used to build the library 200with `Android NDK <https://developer.android.com/tools/sdk/ndk/index.html>`_. 201For an example of using fmt with Android NDK, see the 202`android-ndk-example <https://github.com/fmtlib/android-ndk-example>`_ 203repository. 204 205__ https://github.com/fmtlib/fmt/blob/master/Android.mk 206 207Homebrew 208======== 209 210fmt can be installed on OS X using `Homebrew <http://brew.sh/>`_:: 211 212 brew install fmt 213