# Usage

To use the fmt library, add `format.h` and `format.cc` from a release archive or the Git repository to your project. Alternatively, you can build the library with CMake.

If you are using Visual C++ with precompiled headers, you might need to add the line

    #include "stdafx.h"

before other includes in `format.cc`.

## Building the library

The included CMake build script can be used to build the fmt library on a wide range of platforms. CMake is freely available for download from http://www.cmake.org/download/.

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 <path/to/fmt>  # Generate native build scripts.

where `<path/to/fmt>` is a path to the `fmt` repository.

If you are on a *nix 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.

If you use Windows and have Visual Studio installed, a `FORMAT.sln` file and several `.vcproj` files will be created. You can then build them using Visual Studio or msbuild.

On Mac OS X with Xcode installed, an `.xcodeproj` file will be generated.

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

    cmake -DBUILD_SHARED_LIBS=TRUE ...

## Header-only usage with CMake

In order to add `fmtlib` into an existing `CMakeLists.txt` file, you can add the `fmt` library directory into your main project, which will enable the `fmt` library:

    add_subdirectory(fmt)

If you have a project called `foo` that you would like to link against the fmt library in a header-only fashion, you can enable with with:

    target_link_libraries(foo PRIVATE fmt::fmt-header-only)

And then to ensure that the `fmt` library does not always get built, you can modify the call to `add_subdirectory` to read

    add_subdirectory(fmt EXCLUDE_FROM_ALL)

This will ensure that the `fmt` library is exluded from calls to `make`, `make all`, or `cmake --build .`.

## Building the documentation

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

- Python with pip and virtualenv

- Doxygen

- Less with `less-plugin-clean-css`. Ubuntu doesn’t package the `clean-css` plugin so you should use `npm` instead of `apt` to install both `less` and the plugin:

      sudo npm install -g less less-plugin-clean-css.

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`.

## Android NDK

fmt provides Android.mk file that can be used to build the library with Android NDK. For an example of using fmt with Android NDK, see the android-ndk-example repository.

## Homebrew

fmt can be installed on OS X using Homebrew:

    brew install fmt