fmt/doc/get-started.md

Get Started

You can compile and run {fmt} examples online with Compiler Explorer.

{fmt} can be used with any build system. The next section describes usage with CMake and Build Systems 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 better build times.

There are three main ways to consume {fmt} from CMake:

• FetchContent: Since CMake v3.11, FetchContent can be used 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)
  

Install

Debian/Ubuntu

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

apt install libfmt-dev

Homebrew

{fmt} can be installed on macOS using Homebrew:

brew install fmt

Conda

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

conda install -c conda-forge fmt

Vcpkg

You can 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.

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.

Building the Docs

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

• Python with pip and virtualenv
• Doxygen

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.