1# Get Started 2 3Compile and run {fmt} examples online with [Compiler Explorer]( 4https://godbolt.org/z/P7h6cd6o3). 5 6{fmt} is compatible with any build system. The next section describes its usage 7with CMake, while the [Build Systems](#build-systems) section covers the rest. 8 9## CMake 10 11{fmt} provides two CMake targets: `fmt::fmt` for the compiled library and 12`fmt::fmt-header-only` for the header-only library. It is recommended to use 13the compiled library for improved build times. 14 15There are three primary ways to use {fmt} with CMake: 16 17* **FetchContent**: Starting from CMake 3.11, you can use [`FetchContent`]( 18 https://cmake.org/cmake/help/v3.30/module/FetchContent.html) to automatically 19 download {fmt} as a dependency at configure time: 20 21 include(FetchContent) 22 23 FetchContent_Declare( 24 fmt 25 GIT_REPOSITORY https://github.com/fmtlib/fmt 26 GIT_TAG e69e5f977d458f2650bb346dadf2ad30c5320281) # 10.2.1 27 FetchContent_MakeAvailable(fmt) 28 29 target_link_libraries(<your-target> fmt::fmt) 30 31* **Installed**: You can find and use an [installed](#installation) version of 32 {fmt} in your `CMakeLists.txt` file as follows: 33 34 find_package(fmt) 35 target_link_libraries(<your-target> fmt::fmt) 36 37* **Embedded**: You can add the {fmt} source tree to your project and include it 38 in your `CMakeLists.txt` file: 39 40 add_subdirectory(fmt) 41 target_link_libraries(<your-target> fmt::fmt) 42 43## Installation 44 45### Debian/Ubuntu 46 47To install {fmt} on Debian, Ubuntu, or any other Debian-based Linux 48distribution, use the following command: 49 50 apt install libfmt-dev 51 52### Homebrew 53 54Install {fmt} on macOS using [Homebrew](https://brew.sh/): 55 56 brew install fmt 57 58### Conda 59 60Install {fmt} on Linux, macOS, and Windows with [Conda]( 61https://docs.conda.io/en/latest/), using its [conda-forge package]( 62https://github.com/conda-forge/fmt-feedstock): 63 64 conda install -c conda-forge fmt 65 66### vcpkg 67 68Download and install {fmt} using the vcpkg package manager: 69 70 git clone https://github.com/Microsoft/vcpkg.git 71 cd vcpkg 72 ./bootstrap-vcpkg.sh 73 ./vcpkg integrate install 74 ./vcpkg install fmt 75 76<!-- The fmt package in vcpkg is kept up to date by Microsoft team members and 77community contributors. If the version is out of date, please [create an 78issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg 79repository. --> 80 81## Building from Source 82 83CMake works by generating native makefiles or project files that can be 84used in the compiler environment of your choice. The typical workflow 85starts with: 86 87 mkdir build # Create a directory to hold the build output. 88 cd build 89 cmake .. # Generate native build scripts. 90 91run in the `fmt` repository. 92 93If you are on a Unix-like system, you should now see a Makefile in the 94current directory. Now you can build the library by running `make`. 95 96Once the library has been built you can invoke `make test` to run the tests. 97 98You can control generation of the make `test` target with the `FMT_TEST` 99CMake option. This can be useful if you include fmt as a subdirectory in 100your project but don't want to add fmt's tests to your `test` target. 101 102To build a shared library set the `BUILD_SHARED_LIBS` CMake variable to `TRUE`: 103 104 cmake -DBUILD_SHARED_LIBS=TRUE .. 105 106To build a static library with position-independent code (e.g. for 107linking it into another shared library such as a Python extension), set the 108`CMAKE_POSITION_INDEPENDENT_CODE` CMake variable to `TRUE`: 109 110 cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE .. 111 112After building the library you can install it on a Unix-like system by 113running `sudo make install`. 114 115### Building the Docs 116 117To build the documentation you need the following software installed on 118your system: 119 120- [Python](https://www.python.org/) 121- [Doxygen](http://www.stack.nl/~dimitri/doxygen/) 122- [MkDocs](https://www.mkdocs.org/) with `mkdocs-material`, `mkdocstrings`, 123 `pymdown-extensions` and `mike` 124 125First generate makefiles or project files using CMake as described in 126the previous section. Then compile the `doc` target/project, for example: 127 128 make doc 129 130This will generate the HTML documentation in `doc/html`. 131 132## Build Systems 133 134### build2 135 136You can use [build2](https://build2.org), a dependency manager and a build 137system, to use {fmt}. 138 139Currently this package is available in these package repositories: 140 141- <https://cppget.org/fmt/> for released and published versions. 142- <https://github.com/build2-packaging/fmt> for unreleased or custom versions. 143 144**Usage:** 145 146- `build2` package name: `fmt` 147- Library target name: `lib{fmt}` 148 149To make your `build2` project depend on `fmt`: 150 151- Add one of the repositories to your configurations, or in your 152 `repositories.manifest`, if not already there: 153 154 : 155 role: prerequisite 156 location: https://pkg.cppget.org/1/stable 157 158- Add this package as a dependency to your `manifest` file (example 159 for version 10): 160 161 depends: fmt ~10.0.0 162 163- Import the target and use it as a prerequisite to your own target 164 using `fmt` in the appropriate `buildfile`: 165 166 import fmt = fmt%lib{fmt} 167 lib{mylib} : cxx{**} ... $fmt 168 169Then build your project as usual with `b` or `bdep update`. 170 171### Meson 172 173[Meson WrapDB](https://mesonbuild.com/Wrapdb-projects.html) includes an `fmt` 174package. 175 176**Usage:** 177 178- Install the `fmt` subproject from the WrapDB by running: 179 180 meson wrap install fmt 181 182 from the root of your project. 183 184- In your project's `meson.build` file, add an entry for the new subproject: 185 186 fmt = subproject('fmt') 187 fmt_dep = fmt.get_variable('fmt_dep') 188 189- Include the new dependency object to link with fmt: 190 191 my_build_target = executable( 192 'name', 'src/main.cc', dependencies: [fmt_dep]) 193 194**Options:** 195 196If desired, {fmt} can be built as a static library, or as a header-only library. 197 198For a static build, use the following subproject definition: 199 200 fmt = subproject('fmt', default_options: 'default_library=static') 201 fmt_dep = fmt.get_variable('fmt_dep') 202 203For the header-only version, use: 204 205 fmt = subproject('fmt') 206 fmt_dep = fmt.get_variable('fmt_header_only_dep') 207 208### Android NDK 209 210{fmt} provides [Android.mk file]( 211https://github.com/fmtlib/fmt/blob/master/support/Android.mk) that can be used 212to build the library with [Android NDK]( 213https://developer.android.com/tools/sdk/ndk/index.html). 214 215### Other 216 217To use the {fmt} library with any other build system, add 218`include/fmt/base.h`, `include/fmt/format.h`, `include/fmt/format-inl.h`, 219`src/format.cc` and optionally other headers from a [release archive]( 220https://github.com/fmtlib/fmt/releases) or the [git repository]( 221https://github.com/fmtlib/fmt) to your project, add `include` to include 222directories and make sure `src/format.cc` is compiled and linked with your code. 223