fmt-11.0.2/doc/get-started.md

   1 # Get Started
   2
   3 Compile and run {fmt} examples online with [Compiler Explorer](
   4 https://godbolt.org/z/P7h6cd6o3).
   5
   6 {fmt} is compatible with any build system. The next section describes its usage
   7 with 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
  13 the compiled library for improved build times.
  14
  15 There 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
  47 To install {fmt} on Debian, Ubuntu, or any other Debian-based Linux
  48 distribution, use the following command:
  49
  50     apt install libfmt-dev
  51
  52 ### Homebrew
  53
  54 Install {fmt} on macOS using [Homebrew](https://brew.sh/):
  55
  56     brew install fmt
  57
  58 ### Conda
  59
  60 Install {fmt} on Linux, macOS, and Windows with [Conda](
  61 https://docs.conda.io/en/latest/), using its [conda-forge package](
  62 https://github.com/conda-forge/fmt-feedstock):
  63
  64     conda install -c conda-forge fmt
  65
  66 ### vcpkg
  67
  68 Download 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
  77 community contributors. If the version is out of date, please [create an
  78 issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg
  79 repository. -->
  80
  81 ## Building from Source
  82
  83 CMake works by generating native makefiles or project files that can be
  84 used in the compiler environment of your choice. The typical workflow
  85 starts with:
  86
  87     mkdir build  # Create a directory to hold the build output.
  88     cd build
  89     cmake ..     # Generate native build scripts.
  90
  91 run in the `fmt` repository.
  92
  93 If you are on a Unix-like system, you should now see a Makefile in the
  94 current directory. Now you can build the library by running `make`.
  95
  96 Once the library has been built you can invoke `make test` to run the tests.
  97
  98 You can control generation of the make `test` target with the `FMT_TEST`
  99 CMake option. This can be useful if you include fmt as a subdirectory in
 100 your project but don't want to add fmt's tests to your `test` target.
 101
 102 To build a shared library set the `BUILD_SHARED_LIBS` CMake variable to `TRUE`:
 103
 104     cmake -DBUILD_SHARED_LIBS=TRUE ..
 105
 106 To build a static library with position-independent code (e.g. for
 107 linking 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
 112 After building the library you can install it on a Unix-like system by
 113 running `sudo make install`.
 114
 115 ### Building the Docs
 116
 117 To build the documentation you need the following software installed on
 118 your 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
 125 First generate makefiles or project files using CMake as described in
 126 the previous section. Then compile the `doc` target/project, for example:
 127
 128     make doc
 129
 130 This will generate the HTML documentation in `doc/html`.
 131
 132 ## Build Systems
 133
 134 ### build2
 135
 136 You can use [build2](https://build2.org), a dependency manager and a build
 137 system, to use {fmt}.
 138
 139 Currently 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
 149 To 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
 169 Then 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`
 174 package.
 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
 196 If desired, {fmt} can be built as a static library, or as a header-only library.
 197
 198 For 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
 203 For 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](
 211 https://github.com/fmtlib/fmt/blob/master/support/Android.mk) that can be used
 212 to build the library with [Android NDK](
 213 https://developer.android.com/tools/sdk/ndk/index.html).
 214
 215 ### Other
 216
 217 To 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](
 220 https://github.com/fmtlib/fmt/releases) or the [git repository](
 221 https://github.com/fmtlib/fmt) to your project, add `include` to include
 222 directories and make sure `src/format.cc` is compiled and linked with your code.