ceph/src/fmt/doc/usage.rst

   1 *****
   2 Usage
   3 *****
   4
   5 To use the {fmt} library, add :file:`fmt/core.h`, :file:`fmt/format.h`,
   6 :file:`fmt/format-inl.h`, :file:`src/format.cc` and optionally other headers
   7 from a `release archive <https://github.com/fmtlib/fmt/releases/latest>`_ or
   8 the `Git repository <https://github.com/fmtlib/fmt>`_ to your project.
   9 Alternatively, you can :ref:`build the library with CMake <building>`.
  10
  11 If you are using Visual C++ with precompiled headers, you might need to add
  12 the line ::
  13
  14    #include "stdafx.h"
  15
  16 before other includes in :file:`format.cc`.
  17
  18 .. _building:
  19
  20 Building the library
  21 ====================
  22
  23 The included `CMake build script`__ can be used to build the fmt
  24 library on a wide range of platforms. CMake is freely available for
  25 download from http://www.cmake.org/download/.
  26
  27 __ https://github.com/fmtlib/fmt/blob/master/CMakeLists.txt
  28
  29 CMake works by generating native makefiles or project files that can
  30 be used in the compiler environment of your choice. The typical
  31 workflow starts with::
  32
  33   mkdir build          # Create a directory to hold the build output.
  34   cd build
  35   cmake <path/to/fmt>  # Generate native build scripts.
  36
  37 where :file:`{<path/to/fmt>}` is a path to the ``fmt`` repository.
  38
  39 If you are on a \*nix system, you should now see a Makefile in the
  40 current directory. Now you can build the library by running :command:`make`.
  41
  42 Once the library has been built you can invoke :command:`make test` to run
  43 the tests.
  44
  45 You can control generation of the make ``test`` target with the ``FMT_TEST``
  46 CMake option. This can be useful if you include fmt as a subdirectory in
  47 your project but don't want to add fmt's tests to your ``test`` target.
  48
  49 If you use Windows and have Visual Studio installed, a :file:`FMT.sln`
  50 file and several :file:`.vcproj` files will be created. You can then build them
  51 using Visual Studio or msbuild.
  52
  53 On Mac OS X with Xcode installed, an :file:`.xcodeproj` file will be generated.
  54
  55 To build a `shared library`__ set the ``BUILD_SHARED_LIBS`` CMake variable to
  56 ``TRUE``::
  57
  58   cmake -DBUILD_SHARED_LIBS=TRUE ...
  59
  60 __ http://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries
  61
  62 Installing the library
  63 ====================
  64
  65 After building the library you can install it on a Unix-like system by running
  66 :command:`sudo make install`.
  67
  68 Usage with CMake
  69 ================
  70
  71 You can add the ``fmt`` library directory into your project and include it in
  72 your ``CMakeLists.txt`` file::
  73
  74    add_subdirectory(fmt)
  75
  76 or
  77
  78 ::
  79
  80    add_subdirectory(fmt EXCLUDE_FROM_ALL)
  81
  82 to exclude it from ``make``, ``make all``, or ``cmake --build .``.
  83
  84 You can detect and use an installed version of {fmt} as follows::
  85
  86    find_package(fmt)
  87    target_link_libraries(<your-target> fmt::fmt)
  88
  89 Setting up your target to use a header-only version of ``fmt`` is equaly easy::
  90
  91    target_link_libraries(<your-target> PRIVATE fmt-header-only)
  92
  93 Building the documentation
  94 ==========================
  95
  96 To build the documentation you need the following software installed on your
  97 system:
  98
  99 * `Python <https://www.python.org/>`_ with pip and virtualenv
 100 * `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_
 101 * `Less <http://lesscss.org/>`_ with ``less-plugin-clean-css``.
 102   Ubuntu doesn't package the ``clean-css`` plugin so you should use ``npm``
 103   instead of ``apt`` to install both ``less`` and the plugin::
 104
 105     sudo npm install -g less less-plugin-clean-css.
 106
 107 First generate makefiles or project files using CMake as described in
 108 the previous section. Then compile the ``doc`` target/project, for example::
 109
 110   make doc
 111
 112 This will generate the HTML documentation in ``doc/html``.
 113
 114 Android NDK
 115 ===========
 116
 117 fmt provides `Android.mk file`__ that can be used to build the library
 118 with `Android NDK <https://developer.android.com/tools/sdk/ndk/index.html>`_.
 119 For an example of using fmt with Android NDK, see the
 120 `android-ndk-example <https://github.com/fmtlib/android-ndk-example>`_
 121 repository.
 122
 123 __ https://github.com/fmtlib/fmt/blob/master/Android.mk
 124
 125 Homebrew
 126 ========
 127
 128 fmt can be installed on OS X using `Homebrew <http://brew.sh/>`_::
 129
 130   brew install fmt