]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | ***** |
2 | Usage | |
3 | ***** | |
4 | ||
9f95a23c TL |
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. | |
11fdf7f2 TL |
9 | Alternatively, you can :ref:`build the library with CMake <building>`. |
10 | ||
11fdf7f2 TL |
11 | .. _building: |
12 | ||
f67539c2 | 13 | Building the Library |
11fdf7f2 TL |
14 | ==================== |
15 | ||
16 | The included `CMake build script`__ can be used to build the fmt | |
17 | library on a wide range of platforms. CMake is freely available for | |
18 | download from http://www.cmake.org/download/. | |
19 | ||
20 | __ https://github.com/fmtlib/fmt/blob/master/CMakeLists.txt | |
21 | ||
22 | CMake works by generating native makefiles or project files that can | |
23 | be used in the compiler environment of your choice. The typical | |
24 | workflow starts with:: | |
25 | ||
26 | mkdir build # Create a directory to hold the build output. | |
27 | cd build | |
f67539c2 | 28 | cmake .. # Generate native build scripts. |
11fdf7f2 TL |
29 | |
30 | where :file:`{<path/to/fmt>}` is a path to the ``fmt`` repository. | |
31 | ||
32 | If you are on a \*nix system, you should now see a Makefile in the | |
33 | current directory. Now you can build the library by running :command:`make`. | |
34 | ||
35 | Once the library has been built you can invoke :command:`make test` to run | |
36 | the tests. | |
37 | ||
38 | You can control generation of the make ``test`` target with the ``FMT_TEST`` | |
39 | CMake option. This can be useful if you include fmt as a subdirectory in | |
40 | your project but don't want to add fmt's tests to your ``test`` target. | |
41 | ||
9f95a23c | 42 | If you use Windows and have Visual Studio installed, a :file:`FMT.sln` |
11fdf7f2 TL |
43 | file and several :file:`.vcproj` files will be created. You can then build them |
44 | using Visual Studio or msbuild. | |
45 | ||
46 | On Mac OS X with Xcode installed, an :file:`.xcodeproj` file will be generated. | |
47 | ||
48 | To build a `shared library`__ set the ``BUILD_SHARED_LIBS`` CMake variable to | |
49 | ``TRUE``:: | |
50 | ||
51 | cmake -DBUILD_SHARED_LIBS=TRUE ... | |
52 | ||
53 | __ http://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries | |
54 | ||
f67539c2 TL |
55 | Installing the Library |
56 | ====================== | |
9f95a23c TL |
57 | |
58 | After building the library you can install it on a Unix-like system by running | |
59 | :command:`sudo make install`. | |
60 | ||
61 | Usage with CMake | |
62 | ================ | |
11fdf7f2 TL |
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 | ||
f67539c2 | 82 | Setting up your target to use a header-only version of ``fmt`` is equally easy:: |
11fdf7f2 | 83 | |
f67539c2 | 84 | target_link_libraries(<your-target> PRIVATE fmt::fmt-header-only) |
11fdf7f2 | 85 | |
f67539c2 | 86 | Building the Documentation |
11fdf7f2 TL |
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``. | |
f67539c2 TL |
106 | |
107 | Conda | |
108 | ===== | |
109 | ||
110 | fmt can be installed on Linux, macOS and Windows with | |
111 | `Conda <https://docs.conda.io/en/latest/>`__, using its | |
112 | `conda-forge <https://conda-forge.org>`__ | |
113 | `package <https://github.com/conda-forge/fmt-feedstock>`__, as follows:: | |
114 | ||
115 | conda install -c conda-forge fmt | |
116 | ||
117 | Vcpkg | |
118 | ===== | |
119 | ||
120 | You can download and install fmt using the `vcpkg | |
121 | <https://github.com/Microsoft/vcpkg>`__ dependency manager:: | |
122 | ||
123 | git clone https://github.com/Microsoft/vcpkg.git | |
124 | cd vcpkg | |
125 | ./bootstrap-vcpkg.sh | |
126 | ./vcpkg integrate install | |
127 | ./vcpkg install fmt | |
128 | ||
129 | The fmt port in vcpkg is kept up to date by Microsoft team members and community | |
130 | contributors. If the version is out of date, please `create an issue or pull | |
131 | request <https://github.com/Microsoft/vcpkg>`__ on the vcpkg repository. | |
132 | ||
11fdf7f2 TL |
133 | Android NDK |
134 | =========== | |
135 | ||
136 | fmt provides `Android.mk file`__ that can be used to build the library | |
137 | with `Android NDK <https://developer.android.com/tools/sdk/ndk/index.html>`_. | |
138 | For an example of using fmt with Android NDK, see the | |
139 | `android-ndk-example <https://github.com/fmtlib/android-ndk-example>`_ | |
140 | repository. | |
141 | ||
142 | __ https://github.com/fmtlib/fmt/blob/master/Android.mk | |
143 | ||
144 | Homebrew | |
145 | ======== | |
146 | ||
147 | fmt can be installed on OS X using `Homebrew <http://brew.sh/>`_:: | |
148 | ||
149 | brew install fmt |