Mercurial > minori
diff dep/fmt/doc/html/usage.html @ 343:1faa72660932
*: 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 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dep/fmt/doc/html/usage.html Thu Jun 20 05:56:06 2024 -0400 @@ -0,0 +1,373 @@ +<!DOCTYPE html> + + +<html lang="en"> + <head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + + <meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Usage — fmt 10.2.1 documentation</title> + + <link rel="stylesheet" href="_static/basic.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="_static/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: './', + VERSION: '10.2.1', + COLLAPSE_INDEX: false, + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + SOURCELINK_SUFFIX: '.txt', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt' + }; + </script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <script src="_static/language_data.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> +<meta name="description" content="Small, safe and fast formatting library"> +<meta name="keywords" content="C++, formatting, printf, string, library"> +<meta name="author" content="Victor Zverovich"> +<link rel="stylesheet" href="_static/fmt.css"> + +<script async src="https://www.googletagmanager.com/gtag/js?id=UA-20116650-4"></script> +<script> + window.dataLayer = window.dataLayer || []; + function gtag(){dataLayer.push(arguments);} + gtag('js', new Date()); + + gtag('config', 'UA-20116650-4'); +</script> + + </head> + <body role="document"> +<nav class="navbar navbar-inverse"> + <div class="tb-container"> + <div class="row"> + <div class="navbar-content"> + + <div class="navbar-header"> + <button type="button" class="navbar-toggle collapsed" + data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="index.html">{fmt}</a> + </div> + + + <div class="collapse navbar-collapse"> + <ul class="nav navbar-nav"> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown" + role="button" aria-expanded="false">10.2.1 + <span class="caret"></span></a> + <ul class="dropdown-menu" role="menu"> + + <li><a href="https://fmt.dev/10.2.1">10.2.1</a></li> + + <li><a href="https://fmt.dev/10.2.0">10.2.0</a></li> + + <li><a href="https://fmt.dev/10.1.1">10.1.1</a></li> + + </ul> + </li> + + + <li><a href="contents.html">Contents</a></li> + + + + <li class="active"><a href="usage.html">Usage + <span class="sr-only">(current)</span></a></li> + + + + <li><a href="api.html">API</a></li> + + + + <li><a href="syntax.html">Syntax</a></li> + + + </ul> + + +<form class="navbar-form navbar-right" role="search" action="search.html" + method="get"> + <div class="form-group"> + <input type="text" name="q" class="form-control" + placeholder="Search" > + </div> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + +</form> + + </div> + </div> + </div> + </div> +</nav> + + + +<div class="tb-container"> + <div class="row"> + + + <div class="content"> + + <section id="usage"> +<h1>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h1> +<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>, +<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 +from a <a class="reference external" href="https://github.com/fmtlib/fmt/releases/latest">release archive</a> or +the <a class="reference external" href="https://github.com/fmtlib/fmt">Git repository</a> to your project. +Alternatively, you can <a class="reference internal" href="#building"><span class="std std-ref">build the library with CMake</span></a>.</p> +<section id="building-the-library"> +<span id="building"></span><h2>Building the Library<a class="headerlink" href="#building-the-library" title="Permalink to this headline">¶</a></h2> +<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 +library on a wide range of platforms. CMake is freely available for +download from <a class="reference external" href="https://www.cmake.org/download/">https://www.cmake.org/download/</a>.</p> +<p>CMake works by generating native makefiles or project files that can +be used in the compiler environment of your choice. The typical +workflow starts with:</p> +<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span>mkdir build # Create a directory to hold the build output. +cd build +cmake .. # Generate native build scripts. +</pre></div> +</div> +<p>where <code class="file docutils literal notranslate"><em><span class="pre"><path/to/fmt></span></em></code> is a path to the <code class="docutils literal notranslate"><span class="pre">fmt</span></code> repository.</p> +<p>If you are on a *nix system, you should now see a Makefile in the +current directory. Now you can build the library by running <strong class="command">make</strong>.</p> +<p>Once the library has been built you can invoke <strong class="command">make test</strong> to run +the tests.</p> +<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> +CMake option. This can be useful if you include fmt as a subdirectory in +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> +<p>If you use Windows and have Visual Studio installed, a <code class="file docutils literal notranslate"><span class="pre">FMT.sln</span></code> +file and several <code class="file docutils literal notranslate"><span class="pre">.vcproj</span></code> files will be created. You can then build them +using Visual Studio or msbuild.</p> +<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> +<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 +<code class="docutils literal notranslate"><span class="pre">TRUE</span></code>:</p> +<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> +</pre></div> +</div> +<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 +consumer of the fmt library is a shared library i.e. a Python extension) set the +<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> +<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> +</pre></div> +</div> +</section> +<section id="installing-the-library"> +<h2>Installing the Library<a class="headerlink" href="#installing-the-library" title="Permalink to this headline">¶</a></h2> +<p>After building the library you can install it on a Unix-like system by running +<strong class="command">sudo make install</strong>.</p> +</section> +<section id="usage-with-cmake"> +<h2>Usage with CMake<a class="headerlink" href="#usage-with-cmake" title="Permalink to this headline">¶</a></h2> +<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 +your <code class="docutils literal notranslate"><span class="pre">CMakeLists.txt</span></code> file:</p> +<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> +</pre></div> +</div> +<p>or</p> +<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> +</pre></div> +</div> +<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> +<p>You can detect and use an installed version of {fmt} as follows:</p> +<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="n">target_link_libraries</span><span class="p">(</span><span class="o"><</span><span class="n">your</span><span class="o">-</span><span class="n">target</span><span class="o">></span><span class="w"> </span><span class="n">fmt</span><span class="o">::</span><span class="n">fmt</span><span class="p">)</span> +</pre></div> +</div> +<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> +<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"><</span><span class="n">your</span><span class="o">-</span><span class="n">target</span><span class="o">></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> +</pre></div> +</div> +</section> +<section id="usage-with-build2"> +<h2>Usage with build2<a class="headerlink" href="#usage-with-build2" title="Permalink to this headline">¶</a></h2> +<p>You can use <a class="reference external" href="https://build2.org">build2</a>, a dependency manager and a +build-system combined, to use <code class="docutils literal notranslate"><span class="pre">fmt</span></code>.</p> +<p>Currently this package is available in these package repositories:</p> +<ul class="simple"> +<li><p><strong>https://cppget.org/fmt/</strong> for released and published versions.</p></li> +<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> +for unreleased or custom revisions of <code class="docutils literal notranslate"><span class="pre">fmt</span></code>.</p></li> +</ul> +<p><strong>Usage:</strong></p> +<ul class="simple"> +<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> +<li><p>Library target name : <code class="docutils literal notranslate"><span class="pre">lib{fmt}</span></code></p></li> +</ul> +<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> +<ul> +<li><p>Add one of the repositories to your configurations, or in your +<code class="docutils literal notranslate"><span class="pre">repositories.manifest</span></code>, if not already there:</p> +<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="o">:</span> +<span class="nl">role</span><span class="p">:</span><span class="w"> </span><span class="n">prerequisite</span> +<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> +</pre></div> +</div> +</li> +<li><p>Add this package as a dependency to your <code class="docutils literal notranslate"><span class="pre">./manifest</span></code> file +(example for <code class="docutils literal notranslate"><span class="pre">v7.0.x</span></code>):</p> +<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> +</pre></div> +</div> +</li> +<li><p>Import the target and use it as a prerequisite to your own target +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> +<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="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> +</pre></div> +</div> +</li> +</ul> +<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> +<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 +<code class="docutils literal notranslate"><span class="pre">build2</span></code> +<a class="reference external" href="https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml">toolchain introduction</a>.</p> +</section> +<section id="usage-with-meson"> +<h2>Usage with Meson<a class="headerlink" href="#usage-with-meson" title="Permalink to this headline">¶</a></h2> +<p><code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">Meson's</span> <span class="pre">WrapDB</span></code> includes a <code class="docutils literal notranslate"><span class="pre">fmt</span></code> +package, which repackages fmt to be built by Meson as a subproject.</p> +<p><strong>Usage:</strong></p> +<ul> +<li><p>Install the <code class="docutils literal notranslate"><span class="pre">fmt</span></code> subproject from the WrapDB by running:</p> +<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">meson</span><span class="w"> </span><span class="n">wrap</span><span class="w"> </span><span class="n">install</span><span class="w"> </span><span class="n">fmt</span> +</pre></div> +</div> +<p>from the root of your project.</p> +</li> +<li><p>In your project’s <code class="docutils literal notranslate"><span class="pre">meson.build</span></code> file, add an entry for the new subproject:</p> +<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span>fmt = subproject('fmt') +fmt_dep = fmt.get_variable('fmt_dep') +</pre></div> +</div> +</li> +<li><p>Include the new dependency object to link with fmt:</p> +<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span>my_build_target = executable('name', 'src/main.cc', dependencies: [fmt_dep]) +</pre></div> +</div> +</li> +</ul> +<p><strong>Options:</strong></p> +<p>If desired, <code class="docutils literal notranslate"><span class="pre">fmt</span></code> may be built as a static library, or as a header-only +library.</p> +<p>For a static build, use the following subproject definition:</p> +<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span>fmt = subproject('fmt', default_options: 'default_library=static') +fmt_dep = fmt.get_variable('fmt_dep') +</pre></div> +</div> +<p>For the header-only version, use:</p> +<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span>fmt = subproject('fmt') +fmt_dep = fmt.get_variable('fmt_header_only_dep') +</pre></div> +</div> +</section> +<section id="building-the-documentation"> +<h2>Building the Documentation<a class="headerlink" href="#building-the-documentation" title="Permalink to this headline">¶</a></h2> +<p>To build the documentation you need the following software installed on your +system:</p> +<ul> +<li><p><a class="reference external" href="https://www.python.org/">Python</a> with pip and virtualenv</p></li> +<li><p><a class="reference external" href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a></p></li> +<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>. +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> +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> +<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> +</pre></div> +</div> +</li> +</ul> +<p>First generate makefiles or project files using CMake as described in +the previous section. Then compile the <code class="docutils literal notranslate"><span class="pre">doc</span></code> target/project, for example:</p> +<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> +</pre></div> +</div> +<p>This will generate the HTML documentation in <code class="docutils literal notranslate"><span class="pre">doc/html</span></code>.</p> +</section> +<section id="conda"> +<h2>Conda<a class="headerlink" href="#conda" title="Permalink to this headline">¶</a></h2> +<p>fmt can be installed on Linux, macOS and Windows with +<a class="reference external" href="https://docs.conda.io/en/latest/">Conda</a>, using its +<a class="reference external" href="https://conda-forge.org">conda-forge</a> +<a class="reference external" href="https://github.com/conda-forge/fmt-feedstock">package</a>, as follows:</p> +<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> +</pre></div> +</div> +</section> +<section id="vcpkg"> +<h2>Vcpkg<a class="headerlink" href="#vcpkg" title="Permalink to this headline">¶</a></h2> +<p>You can download and install fmt using the <a class="reference external" href="https://github.com/Microsoft/vcpkg">vcpkg</a> dependency manager:</p> +<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> +<span class="n">cd</span><span class="w"> </span><span class="n">vcpkg</span> +<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="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="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> +</pre></div> +</div> +<p>The fmt port in vcpkg is kept up to date by Microsoft team members and community +contributors. If the version is out of date, please <a class="reference external" href="https://github.com/Microsoft/vcpkg">create an issue or pull +request</a> on the vcpkg repository.</p> +</section> +<section id="lhelper"> +<h2>LHelper<a class="headerlink" href="#lhelper" title="Permalink to this headline">¶</a></h2> +<p>You can download and install fmt using +<a class="reference external" href="https://github.com/franko/lhelper">lhelper</a> dependency manager:</p> +<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"><</span><span class="n">some</span><span class="o">-</span><span class="n">environment</span><span class="o">></span> +<span class="n">lhelper</span><span class="w"> </span><span class="n">install</span><span class="w"> </span><span class="n">fmt</span> +</pre></div> +</div> +<p>All the recipes for lhelper are kept in the +<a class="reference external" href="https://github.com/franko/lhelper-recipes">lhelper’s recipe</a> repository.</p> +</section> +<section id="android-ndk"> +<h2>Android NDK<a class="headerlink" href="#android-ndk" title="Permalink to this headline">¶</a></h2> +<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 +with <a class="reference external" href="https://developer.android.com/tools/sdk/ndk/index.html">Android NDK</a>. +For an example of using fmt with Android NDK, see the +<a class="reference external" href="https://github.com/fmtlib/android-ndk-example">android-ndk-example</a> +repository.</p> +</section> +<section id="homebrew"> +<h2>Homebrew<a class="headerlink" href="#homebrew" title="Permalink to this headline">¶</a></h2> +<p>fmt can be installed on OS X using <a class="reference external" href="https://brew.sh/">Homebrew</a>:</p> +<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> +</pre></div> +</div> +</section> +</section> + + + </div> + </div> +</div> + + + + <div class="footer" role="contentinfo"> + © Copyright 2012-present, Victor Zverovich. + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 3.3.0. + </div> + +<script src="_static/bootstrap.min.js"></script> + + </body> +</html> \ No newline at end of file