usage.html 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335
  1. <!DOCTYPE html>
  2. <html lang="en">
  3. <head>
  4. <meta charset="utf-8">
  5. <meta http-equiv="X-UA-Compatible" content="IE=edge">
  6. <meta name="viewport" content="width=device-width, initial-scale=1">
  7. <meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
  8. <title>Usage &mdash; fmt 9.1.0 documentation</title>
  9. <link rel="stylesheet" href="_static/basic.css" type="text/css" />
  10. <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  11. <link rel="stylesheet" href="_static/breathe.css" type="text/css" />
  12. <script type="text/javascript">
  13. var DOCUMENTATION_OPTIONS = {
  14. URL_ROOT: './',
  15. VERSION: '9.1.0',
  16. COLLAPSE_INDEX: false,
  17. FILE_SUFFIX: '.html',
  18. LINK_SUFFIX: '.html',
  19. SOURCELINK_SUFFIX: '.txt',
  20. HAS_SOURCE: true,
  21. SOURCELINK_SUFFIX: '.txt'
  22. };
  23. </script>
  24. <script src="_static/jquery.js"></script>
  25. <script src="_static/underscore.js"></script>
  26. <script src="_static/doctools.js"></script>
  27. <script src="_static/language_data.js"></script>
  28. <link rel="index" title="Index" href="genindex.html" />
  29. <link rel="search" title="Search" href="search.html" />
  30. <meta name="description" content="Small, safe and fast formatting library">
  31. <meta name="keywords" content="C++, formatting, printf, string, library">
  32. <meta name="author" content="Victor Zverovich">
  33. <link rel="stylesheet" href="_static/fmt.css">
  34. <script async src="https://www.googletagmanager.com/gtag/js?id=UA-20116650-4"></script>
  35. <script>
  36. window.dataLayer = window.dataLayer || [];
  37. function gtag(){dataLayer.push(arguments);}
  38. gtag('js', new Date());
  39. gtag('config', 'UA-20116650-4');
  40. </script>
  41. </head>
  42. <body role="document">
  43. <nav class="navbar navbar-inverse">
  44. <div class="tb-container">
  45. <div class="row">
  46. <div class="navbar-content">
  47. <div class="navbar-header">
  48. <button type="button" class="navbar-toggle collapsed"
  49. data-toggle="collapse" data-target=".navbar-collapse">
  50. <span class="sr-only">Toggle navigation</span>
  51. <span class="icon-bar"></span>
  52. <span class="icon-bar"></span>
  53. <span class="icon-bar"></span>
  54. </button>
  55. <a class="navbar-brand" href="index.html">{fmt}</a>
  56. </div>
  57. <div class="collapse navbar-collapse">
  58. <ul class="nav navbar-nav">
  59. <li class="dropdown">
  60. <a href="#" class="dropdown-toggle" data-toggle="dropdown"
  61. role="button" aria-expanded="false">9.1.0
  62. <span class="caret"></span></a>
  63. <ul class="dropdown-menu" role="menu">
  64. <li><a href="https://fmt.dev/9.1.0">9.1.0</a></li>
  65. <li><a href="https://fmt.dev/9.0.0">9.0.0</a></li>
  66. <li><a href="https://fmt.dev/8.1.1">8.1.1</a></li>
  67. </ul>
  68. </li>
  69. <li><a href="contents.html">Contents</a></li>
  70. <li class="active"><a href="usage.html">Usage
  71. <span class="sr-only">(current)</span></a></li>
  72. <li><a href="api.html">API</a></li>
  73. <li><a href="syntax.html">Syntax</a></li>
  74. </ul>
  75. <form class="navbar-form navbar-right" role="search" action="search.html"
  76. method="get">
  77. <div class="form-group">
  78. <input type="text" name="q" class="form-control"
  79. placeholder="Search" >
  80. </div>
  81. <input type="hidden" name="check_keywords" value="yes" />
  82. <input type="hidden" name="area" value="default" />
  83. </form>
  84. </div>
  85. </div>
  86. </div>
  87. </div>
  88. </nav>
  89. <div class="tb-container">
  90. <div class="row">
  91. <div class="content">
  92. <section id="usage">
  93. <h1>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h1>
  94. <p>To use the {fmt} library, add <code class="file docutils literal notranslate"><span class="pre">fmt/core.h</span></code>, <code class="file docutils literal notranslate"><span class="pre">fmt/format.h</span></code>,
  95. <code class="file docutils literal notranslate"><span class="pre">fmt/format-inl.h</span></code>, <code class="file docutils literal notranslate"><span class="pre">src/format.cc</span></code> and optionally other headers
  96. from a <a class="reference external" href="https://github.com/fmtlib/fmt/releases/latest">release archive</a> or
  97. the <a class="reference external" href="https://github.com/fmtlib/fmt">Git repository</a> to your project.
  98. Alternatively, you can <a class="reference internal" href="#building"><span class="std std-ref">build the library with CMake</span></a>.</p>
  99. <section id="building-the-library">
  100. <span id="building"></span><h2>Building the Library<a class="headerlink" href="#building-the-library" title="Permalink to this headline">¶</a></h2>
  101. <p>The included <a class="reference external" href="https://github.com/fmtlib/fmt/blob/master/CMakeLists.txt">CMake build script</a> can be used to build the fmt
  102. library on a wide range of platforms. CMake is freely available for
  103. download from <a class="reference external" href="https://www.cmake.org/download/">https://www.cmake.org/download/</a>.</p>
  104. <p>CMake works by generating native makefiles or project files that can
  105. be used in the compiler environment of your choice. The typical
  106. workflow starts with:</p>
  107. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span>mkdir build # Create a directory to hold the build output.
  108. cd build
  109. cmake .. # Generate native build scripts.
  110. </pre></div>
  111. </div>
  112. <p>where <code class="file docutils literal notranslate"><em><span class="pre">&lt;path/to/fmt&gt;</span></em></code> is a path to the <code class="docutils literal notranslate"><span class="pre">fmt</span></code> repository.</p>
  113. <p>If you are on a *nix system, you should now see a Makefile in the
  114. current directory. Now you can build the library by running <strong class="command">make</strong>.</p>
  115. <p>Once the library has been built you can invoke <strong class="command">make test</strong> to run
  116. the tests.</p>
  117. <p>You can control generation of the make <code class="docutils literal notranslate"><span class="pre">test</span></code> target with the <code class="docutils literal notranslate"><span class="pre">FMT_TEST</span></code>
  118. CMake option. This can be useful if you include fmt as a subdirectory in
  119. your project but don’t want to add fmt’s tests to your <code class="docutils literal notranslate"><span class="pre">test</span></code> target.</p>
  120. <p>If you use Windows and have Visual Studio installed, a <code class="file docutils literal notranslate"><span class="pre">FMT.sln</span></code>
  121. file and several <code class="file docutils literal notranslate"><span class="pre">.vcproj</span></code> files will be created. You can then build them
  122. using Visual Studio or msbuild.</p>
  123. <p>On Mac OS X with Xcode installed, an <code class="file docutils literal notranslate"><span class="pre">.xcodeproj</span></code> file will be generated.</p>
  124. <p>To build a <a class="reference external" href="https://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries">shared library</a> set the <code class="docutils literal notranslate"><span class="pre">BUILD_SHARED_LIBS</span></code> CMake variable to
  125. <code class="docutils literal notranslate"><span class="pre">TRUE</span></code>:</p>
  126. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">cmake</span><span class="w"> </span><span class="o">-</span><span class="n">DBUILD_SHARED_LIBS</span><span class="o">=</span><span class="n">TRUE</span><span class="w"> </span><span class="p">...</span><span class="w"></span>
  127. </pre></div>
  128. </div>
  129. <p>To build a <code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">static</span> <span class="pre">library</span></code> with position independent code (required if the main
  130. consumer of the fmt library is a shared library i.e. a Python extension) set the
  131. <code class="docutils literal notranslate"><span class="pre">CMAKE_POSITION_INDEPENDENT_CODE</span></code> CMake variable to <code class="docutils literal notranslate"><span class="pre">TRUE</span></code>:</p>
  132. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">cmake</span><span class="w"> </span><span class="o">-</span><span class="n">DCMAKE_POSITION_INDEPENDENT_CODE</span><span class="o">=</span><span class="n">TRUE</span><span class="w"> </span><span class="p">...</span><span class="w"></span>
  133. </pre></div>
  134. </div>
  135. </section>
  136. <section id="installing-the-library">
  137. <h2>Installing the Library<a class="headerlink" href="#installing-the-library" title="Permalink to this headline">¶</a></h2>
  138. <p>After building the library you can install it on a Unix-like system by running
  139. <strong class="command">sudo make install</strong>.</p>
  140. </section>
  141. <section id="usage-with-cmake">
  142. <h2>Usage with CMake<a class="headerlink" href="#usage-with-cmake" title="Permalink to this headline">¶</a></h2>
  143. <p>You can add the <code class="docutils literal notranslate"><span class="pre">fmt</span></code> library directory into your project and include it in
  144. your <code class="docutils literal notranslate"><span class="pre">CMakeLists.txt</span></code> file:</p>
  145. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">add_subdirectory</span><span class="p">(</span><span class="n">fmt</span><span class="p">)</span><span class="w"></span>
  146. </pre></div>
  147. </div>
  148. <p>or</p>
  149. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">add_subdirectory</span><span class="p">(</span><span class="n">fmt</span><span class="w"> </span><span class="n">EXCLUDE_FROM_ALL</span><span class="p">)</span><span class="w"></span>
  150. </pre></div>
  151. </div>
  152. <p>to exclude it from <code class="docutils literal notranslate"><span class="pre">make</span></code>, <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">all</span></code>, or <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--build</span> <span class="pre">.</span></code>.</p>
  153. <p>You can detect and use an installed version of {fmt} as follows:</p>
  154. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">find_package</span><span class="p">(</span><span class="n">fmt</span><span class="p">)</span><span class="w"></span>
  155. <span class="n">target_link_libraries</span><span class="p">(</span><span class="o">&lt;</span><span class="n">your</span><span class="o">-</span><span class="n">target</span><span class="o">&gt;</span><span class="w"> </span><span class="n">fmt</span><span class="o">::</span><span class="n">fmt</span><span class="p">)</span><span class="w"></span>
  156. </pre></div>
  157. </div>
  158. <p>Setting up your target to use a header-only version of <code class="docutils literal notranslate"><span class="pre">fmt</span></code> is equally easy:</p>
  159. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">target_link_libraries</span><span class="p">(</span><span class="o">&lt;</span><span class="n">your</span><span class="o">-</span><span class="n">target</span><span class="o">&gt;</span><span class="w"> </span><span class="n">PRIVATE</span><span class="w"> </span><span class="n">fmt</span><span class="o">::</span><span class="n">fmt</span><span class="o">-</span><span class="n">header</span><span class="o">-</span><span class="n">only</span><span class="p">)</span><span class="w"></span>
  160. </pre></div>
  161. </div>
  162. </section>
  163. <section id="usage-with-build2">
  164. <h2>Usage with build2<a class="headerlink" href="#usage-with-build2" title="Permalink to this headline">¶</a></h2>
  165. <p>You can use <a class="reference external" href="https://build2.org">build2</a>, a dependency manager and a
  166. build-system combined, to use <code class="docutils literal notranslate"><span class="pre">fmt</span></code>.</p>
  167. <p>Currently this package is available in these package repositories:</p>
  168. <ul class="simple">
  169. <li><p><strong>https://cppget.org/fmt/</strong> for released and published versions.</p></li>
  170. <li><p><a class="reference external" href="https://github.com/build2-packaging/fmt.git">The git repository with the sources of the build2 package of fmt</a>
  171. for unreleased or custom revisions of <code class="docutils literal notranslate"><span class="pre">fmt</span></code>.</p></li>
  172. </ul>
  173. <p><strong>Usage:</strong></p>
  174. <ul class="simple">
  175. <li><p><code class="docutils literal notranslate"><span class="pre">build2</span></code> package name: <code class="docutils literal notranslate"><span class="pre">fmt</span></code></p></li>
  176. <li><p>Library target name : <code class="docutils literal notranslate"><span class="pre">lib{fmt}</span></code></p></li>
  177. </ul>
  178. <p>For example, to make your <code class="docutils literal notranslate"><span class="pre">build2</span></code> project depend on <code class="docutils literal notranslate"><span class="pre">fmt</span></code>:</p>
  179. <ul>
  180. <li><p>Add one of the repositories to your configurations, or in your
  181. <code class="docutils literal notranslate"><span class="pre">repositories.manifest</span></code>, if not already there:</p>
  182. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="o">:</span><span class="w"></span>
  183. <span class="nl">role</span><span class="p">:</span><span class="w"> </span><span class="n">prerequisite</span><span class="w"></span>
  184. <span class="nl">location</span><span class="p">:</span><span class="w"> </span><span class="n">https</span><span class="o">:</span><span class="c1">//pkg.cppget.org/1/stable</span>
  185. </pre></div>
  186. </div>
  187. </li>
  188. <li><p>Add this package as a dependency to your <code class="docutils literal notranslate"><span class="pre">./manifest</span></code> file
  189. (example for <code class="docutils literal notranslate"><span class="pre">v7.0.x</span></code>):</p>
  190. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="nl">depends</span><span class="p">:</span><span class="w"> </span><span class="n">fmt</span><span class="w"> </span><span class="o">~</span><span class="mf">7.0.0</span><span class="w"></span>
  191. </pre></div>
  192. </div>
  193. </li>
  194. <li><p>Import the target and use it as a prerequisite to your own target
  195. using <code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">fmt</span></code> in the appropriate <code class="docutils literal notranslate"><span class="pre">buildfile</span></code>:</p>
  196. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">import</span><span class="w"> </span><span class="n">fmt</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">fmt</span><span class="o">%</span><span class="n">lib</span><span class="p">{</span><span class="n">fmt</span><span class="p">}</span><span class="w"></span>
  197. <span class="n">lib</span><span class="p">{</span><span class="n">mylib</span><span class="p">}</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">cxx</span><span class="p">{</span><span class="o">**</span><span class="p">}</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="n">$fmt</span><span class="w"></span>
  198. </pre></div>
  199. </div>
  200. </li>
  201. </ul>
  202. <p>Then build your project as usual with <code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">b</span></code> or <code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">bdep</span> <span class="pre">update</span></code>.</p>
  203. <p>For <code class="docutils literal notranslate"><span class="pre">build2</span></code> newcomers or to get more details and use cases, you can read the
  204. <code class="docutils literal notranslate"><span class="pre">build2</span></code>
  205. <a class="reference external" href="https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml">toolchain introduction</a>.</p>
  206. </section>
  207. <section id="building-the-documentation">
  208. <h2>Building the Documentation<a class="headerlink" href="#building-the-documentation" title="Permalink to this headline">¶</a></h2>
  209. <p>To build the documentation you need the following software installed on your
  210. system:</p>
  211. <ul>
  212. <li><p><a class="reference external" href="https://www.python.org/">Python</a> with pip and virtualenv</p></li>
  213. <li><p><a class="reference external" href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a></p></li>
  214. <li><p><a class="reference external" href="http://lesscss.org/">Less</a> with <code class="docutils literal notranslate"><span class="pre">less-plugin-clean-css</span></code>.
  215. Ubuntu doesn’t package the <code class="docutils literal notranslate"><span class="pre">clean-css</span></code> plugin so you should use <code class="docutils literal notranslate"><span class="pre">npm</span></code>
  216. instead of <code class="docutils literal notranslate"><span class="pre">apt</span></code> to install both <code class="docutils literal notranslate"><span class="pre">less</span></code> and the plugin:</p>
  217. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">sudo</span><span class="w"> </span><span class="n">npm</span><span class="w"> </span><span class="n">install</span><span class="w"> </span><span class="o">-</span><span class="n">g</span><span class="w"> </span><span class="n">less</span><span class="w"> </span><span class="n">less</span><span class="o">-</span><span class="n">plugin</span><span class="o">-</span><span class="n">clean</span><span class="o">-</span><span class="n">css</span><span class="p">.</span><span class="w"></span>
  218. </pre></div>
  219. </div>
  220. </li>
  221. </ul>
  222. <p>First generate makefiles or project files using CMake as described in
  223. the previous section. Then compile the <code class="docutils literal notranslate"><span class="pre">doc</span></code> target/project, for example:</p>
  224. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">make</span><span class="w"> </span><span class="n">doc</span><span class="w"></span>
  225. </pre></div>
  226. </div>
  227. <p>This will generate the HTML documentation in <code class="docutils literal notranslate"><span class="pre">doc/html</span></code>.</p>
  228. </section>
  229. <section id="conda">
  230. <h2>Conda<a class="headerlink" href="#conda" title="Permalink to this headline">¶</a></h2>
  231. <p>fmt can be installed on Linux, macOS and Windows with
  232. <a class="reference external" href="https://docs.conda.io/en/latest/">Conda</a>, using its
  233. <a class="reference external" href="https://conda-forge.org">conda-forge</a>
  234. <a class="reference external" href="https://github.com/conda-forge/fmt-feedstock">package</a>, as follows:</p>
  235. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span><span class="w"> </span><span class="n">install</span><span class="w"> </span><span class="o">-</span><span class="n">c</span><span class="w"> </span><span class="n">conda</span><span class="o">-</span><span class="n">forge</span><span class="w"> </span><span class="n">fmt</span><span class="w"></span>
  236. </pre></div>
  237. </div>
  238. </section>
  239. <section id="vcpkg">
  240. <h2>Vcpkg<a class="headerlink" href="#vcpkg" title="Permalink to this headline">¶</a></h2>
  241. <p>You can download and install fmt using the <a class="reference external" href="https://github.com/Microsoft/vcpkg">vcpkg</a> dependency manager:</p>
  242. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">git</span><span class="w"> </span><span class="n">clone</span><span class="w"> </span><span class="n">https</span><span class="o">:</span><span class="c1">//github.com/Microsoft/vcpkg.git</span>
  243. <span class="n">cd</span><span class="w"> </span><span class="n">vcpkg</span><span class="w"></span>
  244. <span class="p">.</span><span class="o">/</span><span class="n">bootstrap</span><span class="o">-</span><span class="n">vcpkg</span><span class="p">.</span><span class="n">sh</span><span class="w"></span>
  245. <span class="p">.</span><span class="o">/</span><span class="n">vcpkg</span><span class="w"> </span><span class="n">integrate</span><span class="w"> </span><span class="n">install</span><span class="w"></span>
  246. <span class="p">.</span><span class="o">/</span><span class="n">vcpkg</span><span class="w"> </span><span class="n">install</span><span class="w"> </span><span class="n">fmt</span><span class="w"></span>
  247. </pre></div>
  248. </div>
  249. <p>The fmt port in vcpkg is kept up to date by Microsoft team members and community
  250. contributors. If the version is out of date, please <a class="reference external" href="https://github.com/Microsoft/vcpkg">create an issue or pull
  251. request</a> on the vcpkg repository.</p>
  252. </section>
  253. <section id="lhelper">
  254. <h2>LHelper<a class="headerlink" href="#lhelper" title="Permalink to this headline">¶</a></h2>
  255. <p>You can download and install fmt using
  256. <a class="reference external" href="https://github.com/franko/lhelper">lhelper</a> dependency manager:</p>
  257. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">lhelper</span><span class="w"> </span><span class="n">activate</span><span class="w"> </span><span class="o">&lt;</span><span class="n">some</span><span class="o">-</span><span class="n">environment</span><span class="o">&gt;</span><span class="w"></span>
  258. <span class="n">lhelper</span><span class="w"> </span><span class="n">install</span><span class="w"> </span><span class="n">fmt</span><span class="w"></span>
  259. </pre></div>
  260. </div>
  261. <p>All the recipes for lhelper are kept in the
  262. <a class="reference external" href="https://github.com/franko/lhelper-recipes">lhelper’s recipe</a> repository.</p>
  263. </section>
  264. <section id="android-ndk">
  265. <h2>Android NDK<a class="headerlink" href="#android-ndk" title="Permalink to this headline">¶</a></h2>
  266. <p>fmt provides <a class="reference external" href="https://github.com/fmtlib/fmt/blob/master/support/Android.mk">Android.mk file</a> that can be used to build the library
  267. with <a class="reference external" href="https://developer.android.com/tools/sdk/ndk/index.html">Android NDK</a>.
  268. For an example of using fmt with Android NDK, see the
  269. <a class="reference external" href="https://github.com/fmtlib/android-ndk-example">android-ndk-example</a>
  270. repository.</p>
  271. </section>
  272. <section id="homebrew">
  273. <h2>Homebrew<a class="headerlink" href="#homebrew" title="Permalink to this headline">¶</a></h2>
  274. <p>fmt can be installed on OS X using <a class="reference external" href="https://brew.sh/">Homebrew</a>:</p>
  275. <div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">brew</span><span class="w"> </span><span class="n">install</span><span class="w"> </span><span class="n">fmt</span><span class="w"></span>
  276. </pre></div>
  277. </div>
  278. </section>
  279. </section>
  280. </div>
  281. </div>
  282. </div>
  283. <div class="footer" role="contentinfo">
  284. &copy; Copyright 2012-present, Victor Zverovich.
  285. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 3.3.0.
  286. </div>
  287. <script src="_static/bootstrap.min.js"></script>
  288. </body>
  289. </html>