]>
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 | |
20effc67 | 18 | download from https://www.cmake.org/download/. |
11fdf7f2 TL |
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 | ||
20effc67 TL |
53 | __ https://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries |
54 | ||
55 | ||
56 | To build a `static library` with position independent code (required if the main | |
57 | consumer of the fmt library is a shared library i.e. a Python extension) set the | |
58 | ``CMAKE_POSITION_INDEPENDENT_CODE`` CMake variable to ``TRUE``:: | |
59 | ||
60 | cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE ... | |
61 | ||
11fdf7f2 | 62 | |
f67539c2 TL |
63 | Installing the Library |
64 | ====================== | |
9f95a23c TL |
65 | |
66 | After building the library you can install it on a Unix-like system by running | |
67 | :command:`sudo make install`. | |
68 | ||
69 | Usage with CMake | |
70 | ================ | |
11fdf7f2 TL |
71 | |
72 | You can add the ``fmt`` library directory into your project and include it in | |
73 | your ``CMakeLists.txt`` file:: | |
74 | ||
75 | add_subdirectory(fmt) | |
76 | ||
77 | or | |
78 | ||
79 | :: | |
80 | ||
81 | add_subdirectory(fmt EXCLUDE_FROM_ALL) | |
82 | ||
83 | to exclude it from ``make``, ``make all``, or ``cmake --build .``. | |
84 | ||
eafe8130 TL |
85 | You can detect and use an installed version of {fmt} as follows:: |
86 | ||
87 | find_package(fmt) | |
88 | target_link_libraries(<your-target> fmt::fmt) | |
89 | ||
f67539c2 | 90 | Setting up your target to use a header-only version of ``fmt`` is equally easy:: |
11fdf7f2 | 91 | |
f67539c2 | 92 | target_link_libraries(<your-target> PRIVATE fmt::fmt-header-only) |
11fdf7f2 | 93 | |
20effc67 TL |
94 | Usage with build2 |
95 | ================= | |
96 | ||
97 | You can use `build2 <https://build2.org>`_, a dependency manager and a | |
98 | build-system combined, to use ``fmt``. | |
99 | ||
100 | Currently this package is available in these package repositories: | |
101 | ||
102 | - **https://cppget.org/fmt/** for released and published versions. | |
103 | - `The git repository with the sources of the build2 package of fmt <https://github.com/build2-packaging/fmt.git>`_ | |
104 | for unreleased or custom revisions of ``fmt``. | |
105 | ||
106 | **Usage:** | |
107 | ||
108 | - ``build2`` package name: ``fmt`` | |
109 | - Library target name : ``lib{fmt}`` | |
110 | ||
111 | For example, to make your ``build2`` project depend on ``fmt``: | |
112 | ||
113 | - Add one of the repositories to your configurations, or in your | |
114 | ``repositories.manifest``, if not already there:: | |
115 | ||
116 | : | |
117 | role: prerequisite | |
118 | location: https://pkg.cppget.org/1/stable | |
119 | ||
120 | - Add this package as a dependency to your ``./manifest`` file | |
121 | (example for ``v7.0.x``):: | |
122 | ||
123 | depends: fmt ~7.0.0 | |
124 | ||
125 | - Import the target and use it as a prerequisite to your own target | |
126 | using `fmt` in the appropriate ``buildfile``:: | |
127 | ||
128 | import fmt = fmt%lib{fmt} | |
129 | lib{mylib} : cxx{**} ... $fmt | |
130 | ||
131 | Then build your project as usual with `b` or `bdep update`. | |
132 | ||
133 | For ``build2`` newcomers or to get more details and use cases, you can read the | |
134 | ``build2`` | |
135 | `toolchain introduction <https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml>`_. | |
136 | ||
f67539c2 | 137 | Building the Documentation |
11fdf7f2 TL |
138 | ========================== |
139 | ||
140 | To build the documentation you need the following software installed on your | |
141 | system: | |
142 | ||
143 | * `Python <https://www.python.org/>`_ with pip and virtualenv | |
144 | * `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ | |
145 | * `Less <http://lesscss.org/>`_ with ``less-plugin-clean-css``. | |
146 | Ubuntu doesn't package the ``clean-css`` plugin so you should use ``npm`` | |
147 | instead of ``apt`` to install both ``less`` and the plugin:: | |
148 | ||
149 | sudo npm install -g less less-plugin-clean-css. | |
150 | ||
151 | First generate makefiles or project files using CMake as described in | |
152 | the previous section. Then compile the ``doc`` target/project, for example:: | |
153 | ||
154 | make doc | |
155 | ||
156 | This will generate the HTML documentation in ``doc/html``. | |
f67539c2 TL |
157 | |
158 | Conda | |
159 | ===== | |
160 | ||
161 | fmt can be installed on Linux, macOS and Windows with | |
162 | `Conda <https://docs.conda.io/en/latest/>`__, using its | |
163 | `conda-forge <https://conda-forge.org>`__ | |
164 | `package <https://github.com/conda-forge/fmt-feedstock>`__, as follows:: | |
165 | ||
166 | conda install -c conda-forge fmt | |
167 | ||
168 | Vcpkg | |
169 | ===== | |
170 | ||
171 | You can download and install fmt using the `vcpkg | |
172 | <https://github.com/Microsoft/vcpkg>`__ dependency manager:: | |
173 | ||
174 | git clone https://github.com/Microsoft/vcpkg.git | |
175 | cd vcpkg | |
176 | ./bootstrap-vcpkg.sh | |
177 | ./vcpkg integrate install | |
178 | ./vcpkg install fmt | |
179 | ||
180 | The fmt port in vcpkg is kept up to date by Microsoft team members and community | |
181 | contributors. If the version is out of date, please `create an issue or pull | |
182 | request <https://github.com/Microsoft/vcpkg>`__ on the vcpkg repository. | |
183 | ||
20effc67 TL |
184 | LHelper |
185 | ======= | |
186 | ||
187 | You can download and install fmt using | |
188 | `lhelper <https://github.com/franko/lhelper>`__ dependency manager:: | |
189 | ||
190 | lhelper activate <some-environment> | |
191 | lhelper install fmt | |
192 | ||
193 | All the recipes for lhelper are kept in the | |
194 | `lhelper's recipe <https://github.com/franko/lhelper-recipes>`__ repository. | |
195 | ||
11fdf7f2 TL |
196 | Android NDK |
197 | =========== | |
198 | ||
199 | fmt provides `Android.mk file`__ that can be used to build the library | |
200 | with `Android NDK <https://developer.android.com/tools/sdk/ndk/index.html>`_. | |
201 | For an example of using fmt with Android NDK, see the | |
202 | `android-ndk-example <https://github.com/fmtlib/android-ndk-example>`_ | |
203 | repository. | |
204 | ||
20effc67 | 205 | __ https://github.com/fmtlib/fmt/blob/master/support/Android.mk |
11fdf7f2 TL |
206 | |
207 | Homebrew | |
208 | ======== | |
209 | ||
20effc67 | 210 | fmt can be installed on OS X using `Homebrew <https://brew.sh/>`_:: |
11fdf7f2 TL |
211 | |
212 | brew install fmt |