fmt/doc/get-started.md

Get Started

Compile and run {fmt} examples online with Compiler Explorer.

{fmt} is compatible with any build system. The next section describes its usage with CMake, while the Build Systems section covers the rest.

CMake

{fmt} provides two CMake targets: fmt::fmt for the compiled library and fmt::fmt-header-only for the header-only library. It is recommended to use the compiled library for improved build times.

There are three primary ways to use {fmt} with CMake:

• FetchContent: Starting from CMake 3.11, you can use FetchContent to automatically download {fmt} as a dependency at configure time:

    include(FetchContent)
  
    FetchContent_Declare(
      fmt
      GIT_REPOSITORY https://github.com/fmtlib/fmt
      GIT_TAG        e69e5f977d458f2650bb346dadf2ad30c5320281) # 10.2.1
    FetchContent_MakeAvailable(fmt)
  
    target_link_libraries(<your-target> fmt::fmt)
  

• Installed: You can find and use an installed version of {fmt} in your CMakeLists.txt file as follows:

    find_package(fmt)
    target_link_libraries(<your-target> fmt::fmt)
  

• Embedded: You can add the {fmt} source tree to your project and include it in your CMakeLists.txt file:

    add_subdirectory(fmt)
    target_link_libraries(<your-target> fmt::fmt)
  

Installation

Debian/Ubuntu

To install {fmt} on Debian, Ubuntu, or any other Debian-based Linux distribution, use the following command:

apt install libfmt-dev

Homebrew

Install {fmt} on macOS using Homebrew:

brew install fmt

Conda

Install {fmt} on Linux, macOS, and Windows with Conda, using its conda-forge package:

conda install -c conda-forge fmt

vcpkg

Download and install {fmt} using the vcpkg package manager:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install fmt

Building from Source

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.

run in the fmt repository.

If you are on a Unix-like system, you should now see a Makefile in the current directory. Now you can build the library by running make.

Once the library has been built you can invoke 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.

To build a shared library set the BUILD_SHARED_LIBS CMake variable to TRUE:

cmake -DBUILD_SHARED_LIBS=TRUE ..

To build a static library with position-independent code (e.g. for linking it into another shared library such as a Python extension), set the CMAKE_POSITION_INDEPENDENT_CODE CMake variable to TRUE:

cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE ..

After building the library you can install it on a Unix-like system by running sudo make install.

Building the Docs

To build the documentation you need the following software installed on your system:

• Python
• Doxygen
• MkDocs with mike, mkdocstrings and mkdocs-material

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.

Build Systems

build2

You can use build2, a dependency manager and a build system, to use {fmt}.

Currently this package is available in these package repositories:

• https://cppget.org/fmt/ for released and published versions.
• https://github.com/build2-packaging/fmt for unreleased or custom versions.

Usage:

• build2 package name: fmt
• Library target name: lib{fmt}

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 version 10):

    depends: fmt ~10.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.

Meson

Meson WrapDB includes an fmt package.

Usage:

• Install the fmt subproject from the WrapDB by running:

    meson wrap install fmt
  

  from the root of your project.

• In your project's meson.build file, add an entry for the new subproject:

    fmt = subproject('fmt')
    fmt_dep = fmt.get_variable('fmt_dep')
  

• Include the new dependency object to link with fmt:

    my_build_target = executable(
      'name', 'src/main.cc', dependencies: [fmt_dep])
  

Options:

If desired, {fmt} can be built as a static library, or as a header-only library.

For a static build, use the following subproject definition:

fmt = subproject('fmt', default_options: 'default_library=static')
fmt_dep = fmt.get_variable('fmt_dep')

For the header-only version, use:

fmt = subproject('fmt')
fmt_dep = fmt.get_variable('fmt_header_only_dep')

Android NDK

{fmt} provides Android.mk file that can be used to build the library with Android NDK.

Other

To use the {fmt} library with any other build system, add include/fmt/base.h, include/fmt/format.h, include/fmt/format-inl.h, src/format.cc and optionally other headers from a release archive or the git repository to your project, add include to include directories and make sure src/format.cc is compiled and linked with your code.