Mercurial > minori

comparison dep/fmt/doc/html/_sources/usage.rst.txt @ 343:1faa72660932

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
*: transfer back to cmake from autotools autotools just made lots of things more complicated than they should have and many things broke (i.e. translations)
author Paper <paper@paper.us.eu.org>
date Thu, 20 Jun 2024 05:56:06 -0400
parents
children
comparison
equal deleted inserted replaced
342:adb79bdde329 343:1faa72660932
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 .. _building:
12
13 Building the Library
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 https://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
28 cmake .. # Generate native build scripts.
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
42 If you use Windows and have Visual Studio installed, a :file:`FMT.sln`
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 __ 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
62
63 Installing the Library
64 ======================
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 ================
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
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
90 Setting up your target to use a header-only version of ``fmt`` is equally easy::
91
92 target_link_libraries(<your-target> PRIVATE fmt::fmt-header-only)
93
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
137 Usage with Meson
138 ================
139
140 `Meson's WrapDB <https://mesonbuild.com/Wrapdb-projects.html>` includes a ``fmt``
141 package, which repackages fmt to be built by Meson as a subproject.
142
143 **Usage:**
144
145 - Install the ``fmt`` subproject from the WrapDB by running::
146
147 meson wrap install fmt
148
149 from the root of your project.
150
151 - In your project's ``meson.build`` file, add an entry for the new subproject::
152
153 fmt = subproject('fmt')
154 fmt_dep = fmt.get_variable('fmt_dep')
155
156 - Include the new dependency object to link with fmt::
157
158 my_build_target = executable('name', 'src/main.cc', dependencies: [fmt_dep])
159
160 **Options:**
161
162 If desired, ``fmt`` may be built as a static library, or as a header-only
163 library.
164
165 For a static build, use the following subproject definition::
166
167 fmt = subproject('fmt', default_options: 'default_library=static')
168 fmt_dep = fmt.get_variable('fmt_dep')
169
170 For the header-only version, use::
171
172 fmt = subproject('fmt')
173 fmt_dep = fmt.get_variable('fmt_header_only_dep')
174
175 Building the Documentation
176 ==========================
177
178 To build the documentation you need the following software installed on your
179 system:
180
181 * `Python <https://www.python.org/>`_ with pip and virtualenv
182 * `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_
183 * `Less <http://lesscss.org/>`_ with ``less-plugin-clean-css``.
184 Ubuntu doesn't package the ``clean-css`` plugin so you should use ``npm``
185 instead of ``apt`` to install both ``less`` and the plugin::
186
187 sudo npm install -g less less-plugin-clean-css.
188
189 First generate makefiles or project files using CMake as described in
190 the previous section. Then compile the ``doc`` target/project, for example::
191
192 make doc
193
194 This will generate the HTML documentation in ``doc/html``.
195
196 Conda
197 =====
198
199 fmt can be installed on Linux, macOS and Windows with
200 `Conda <https://docs.conda.io/en/latest/>`__, using its
201 `conda-forge <https://conda-forge.org>`__
202 `package <https://github.com/conda-forge/fmt-feedstock>`__, as follows::
203
204 conda install -c conda-forge fmt
205
206 Vcpkg
207 =====
208
209 You can download and install fmt using the `vcpkg
210 <https://github.com/Microsoft/vcpkg>`__ dependency manager::
211
212 git clone https://github.com/Microsoft/vcpkg.git
213 cd vcpkg
214 ./bootstrap-vcpkg.sh
215 ./vcpkg integrate install
216 ./vcpkg install fmt
217
218 The fmt port in vcpkg is kept up to date by Microsoft team members and community
219 contributors. If the version is out of date, please `create an issue or pull
220 request <https://github.com/Microsoft/vcpkg>`__ on the vcpkg repository.
221
222 LHelper
223 =======
224
225 You can download and install fmt using
226 `lhelper <https://github.com/franko/lhelper>`__ dependency manager::
227
228 lhelper activate <some-environment>
229 lhelper install fmt
230
231 All the recipes for lhelper are kept in the
232 `lhelper's recipe <https://github.com/franko/lhelper-recipes>`__ repository.
233
234 Android NDK
235 ===========
236
237 fmt provides `Android.mk file`__ that can be used to build the library
238 with `Android NDK <https://developer.android.com/tools/sdk/ndk/index.html>`_.
239 For an example of using fmt with Android NDK, see the
240 `android-ndk-example <https://github.com/fmtlib/android-ndk-example>`_
241 repository.
242
243 __ https://github.com/fmtlib/fmt/blob/master/support/Android.mk
244
245 Homebrew
246 ========
247
248 fmt can be installed on OS X using `Homebrew <https://brew.sh/>`_::
249
250 brew install fmt