ceph/src/seastar/fmt/doc/usage.rst

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