]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
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 | ||
eafe8130 TL |
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:: | |
11fdf7f2 TL |
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 |