mirror of
https://github.com/fmtlib/fmt.git
synced 2024-12-25 15:51:05 +00:00
Convert usage to Markdown
This commit is contained in:
Victor Zverovich
parent
d903460137
commit
b6638f9c29
242
doc/usage.md
Normal file
242
doc/usage.md
Normal file
@ -0,0 +1,242 @@
|
||||
# Usage
|
||||
|
||||
To use the {fmt} library, add `fmt/core.h`, `fmt/format.h`, `fmt/format-inl.h`,
|
||||
`src/format.cc` and optionally other headers from a [release archive](
|
||||
https://github.com/fmtlib/fmt/releases/latest) or the [git repository](
|
||||
https://github.com/fmtlib/fmt) to your project. Alternatively, you can
|
||||
[build the library with CMake](#building).
|
||||
|
||||
## Building the Library {#building}
|
||||
|
||||
The included [CMake build
|
||||
script](https://github.com/fmtlib/fmt/blob/master/CMakeLists.txt) can be
|
||||
used to build the fmt library on a wide range of platforms. CMake is
|
||||
freely available for download from <https://www.cmake.org/download/>.
|
||||
|
||||
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:
|
||||
|
||||
mkdir build # Create a directory to hold the build output.
|
||||
cd build
|
||||
cmake .. # Generate native build scripts.
|
||||
|
||||
run in the `fmt` repository.
|
||||
|
||||
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
|
||||
`make`{.interpreted-text role="command"}.
|
||||
|
||||
Once the library has been built you can invoke
|
||||
`make test`{.interpreted-text role="command"} to run the tests.
|
||||
|
||||
You can control generation of the make `test` target with the `FMT_TEST`
|
||||
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 `test` target.
|
||||
|
||||
If you use Windows and have Visual Studio installed, a
|
||||
`FMT.sln` file and several `.vcproj` files will be created. You can
|
||||
then build them using Visual Studio or msbuild.
|
||||
|
||||
On Mac OS X with Xcode installed, an `.xcodeproj`{.interpreted-text
|
||||
role="file"} file will be generated.
|
||||
|
||||
To build a [shared
|
||||
library](https://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries)
|
||||
set the `BUILD_SHARED_LIBS` CMake variable to `TRUE`:
|
||||
|
||||
cmake -DBUILD_SHARED_LIBS=TRUE ..
|
||||
|
||||
To build a [static library]{.title-ref} with position independent code
|
||||
(required if the main consumer of the fmt library is a shared library
|
||||
i.e. a Python extension) set the `CMAKE_POSITION_INDEPENDENT_CODE` CMake
|
||||
variable to `TRUE`:
|
||||
|
||||
cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE ..
|
||||
|
||||
## Installing the Library
|
||||
|
||||
After building the library you can install it on a Unix-like system by
|
||||
running `sudo make install`{.interpreted-text role="command"}.
|
||||
|
||||
## Usage with CMake
|
||||
|
||||
You can add the `fmt` library directory into your project and include it
|
||||
in your `CMakeLists.txt` file:
|
||||
|
||||
add_subdirectory(fmt)
|
||||
|
||||
or
|
||||
|
||||
add_subdirectory(fmt EXCLUDE_FROM_ALL)
|
||||
|
||||
to exclude it from `make`, `make all`, or `cmake --build .`.
|
||||
|
||||
You can detect and use an installed version of {fmt} as follows:
|
||||
|
||||
find_package(fmt)
|
||||
target_link_libraries(<your-target> fmt::fmt)
|
||||
|
||||
Setting up your target to use a header-only version of `fmt` is equally
|
||||
easy:
|
||||
|
||||
target_link_libraries(<your-target> PRIVATE fmt::fmt-header-only)
|
||||
|
||||
## Usage with build2
|
||||
|
||||
You can use [build2](https://build2.org), a dependency manager and a
|
||||
build-system combined, to use `fmt`.
|
||||
|
||||
Currently this package is available in these package repositories:
|
||||
|
||||
- **https://cppget.org/fmt/** for released and published versions.
|
||||
- [The git repository with the sources of the build2 package of
|
||||
fmt](https://github.com/build2-packaging/fmt.git) for unreleased or
|
||||
custom revisions of `fmt`.
|
||||
|
||||
**Usage:**
|
||||
|
||||
- `build2` package name: `fmt`
|
||||
- Library target name : `lib{fmt}`
|
||||
|
||||
For example, to make your `build2` project depend on `fmt`:
|
||||
|
||||
- Add one of the repositories to your configurations, or in your
|
||||
`repositories.manifest`, if not already there:
|
||||
|
||||
:
|
||||
role: prerequisite
|
||||
location: https://pkg.cppget.org/1/stable
|
||||
|
||||
- Add this package as a dependency to your `./manifest` file (example
|
||||
for `v7.0.x`):
|
||||
|
||||
depends: fmt ~7.0.0
|
||||
|
||||
- Import the target and use it as a prerequisite to your own target
|
||||
using [fmt]{.title-ref} in the appropriate `buildfile`:
|
||||
|
||||
import fmt = fmt%lib{fmt}
|
||||
lib{mylib} : cxx{**} ... $fmt
|
||||
|
||||
Then build your project as usual with [b]{.title-ref} or [bdep
|
||||
update]{.title-ref}.
|
||||
|
||||
For `build2` newcomers or to get more details and use cases, you can
|
||||
read the `build2` [toolchain
|
||||
introduction](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml).
|
||||
|
||||
## Usage with Meson
|
||||
|
||||
[Meson\'s WrapDB
|
||||
\<https://mesonbuild.com/Wrapdb-projects.html\>]{.title-ref} includes a
|
||||
`fmt` package, which repackages fmt to be built by Meson as a
|
||||
subproject.
|
||||
|
||||
**Usage:**
|
||||
|
||||
- Install the `fmt` subproject from the WrapDB by running:
|
||||
|
||||
meson wrap install fmt
|
||||
|
||||
from the root of your project.
|
||||
|
||||
- In your project\'s `meson.build` file, add an entry for the new
|
||||
subproject:
|
||||
|
||||
fmt = subproject('fmt')
|
||||
fmt_dep = fmt.get_variable('fmt_dep')
|
||||
|
||||
- Include the new dependency object to link with fmt:
|
||||
|
||||
my_build_target = executable('name', 'src/main.cc', dependencies: [fmt_dep])
|
||||
|
||||
**Options:**
|
||||
|
||||
If desired, `fmt` may be built as a static library, or as a header-only
|
||||
library.
|
||||
|
||||
For a static build, use the following subproject definition:
|
||||
|
||||
fmt = subproject('fmt', default_options: 'default_library=static')
|
||||
fmt_dep = fmt.get_variable('fmt_dep')
|
||||
|
||||
For the header-only version, use:
|
||||
|
||||
fmt = subproject('fmt')
|
||||
fmt_dep = fmt.get_variable('fmt_header_only_dep')
|
||||
|
||||
## Building the Documentation
|
||||
|
||||
To build the documentation you need the following software installed on
|
||||
your system:
|
||||
|
||||
- [Python](https://www.python.org/) with pip and virtualenv
|
||||
|
||||
- [Doxygen](http://www.stack.nl/~dimitri/doxygen/)
|
||||
|
||||
- [Less](http://lesscss.org/) with `less-plugin-clean-css`. Ubuntu
|
||||
doesn\'t package the `clean-css` plugin so you should use `npm`
|
||||
instead of `apt` to install both `less` and the plugin:
|
||||
|
||||
sudo npm install -g less less-plugin-clean-css.
|
||||
|
||||
First generate makefiles or project files using CMake as described in
|
||||
the previous section. Then compile the `doc` target/project, for
|
||||
example:
|
||||
|
||||
make doc
|
||||
|
||||
This will generate the HTML documentation in `doc/html`.
|
||||
|
||||
## Conda
|
||||
|
||||
fmt can be installed on Linux, macOS and Windows with
|
||||
[Conda](https://docs.conda.io/en/latest/), using its
|
||||
[conda-forge](https://conda-forge.org)
|
||||
[package](https://github.com/conda-forge/fmt-feedstock), as follows:
|
||||
|
||||
conda install -c conda-forge fmt
|
||||
|
||||
## Vcpkg
|
||||
|
||||
You can download and install fmt using the
|
||||
[vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
|
||||
|
||||
git clone https://github.com/Microsoft/vcpkg.git
|
||||
cd vcpkg
|
||||
./bootstrap-vcpkg.sh
|
||||
./vcpkg integrate install
|
||||
./vcpkg install fmt
|
||||
|
||||
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 [create an
|
||||
issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg
|
||||
repository.
|
||||
|
||||
## LHelper
|
||||
|
||||
You can download and install fmt using
|
||||
[lhelper](https://github.com/franko/lhelper) dependency manager:
|
||||
|
||||
lhelper activate <some-environment>
|
||||
lhelper install fmt
|
||||
|
||||
All the recipes for lhelper are kept in the [lhelper\'s
|
||||
recipe](https://github.com/franko/lhelper-recipes) repository.
|
||||
|
||||
## Android NDK
|
||||
|
||||
fmt provides [Android.mk
|
||||
file](https://github.com/fmtlib/fmt/blob/master/support/Android.mk) that
|
||||
can be used to build the library with [Android
|
||||
NDK](https://developer.android.com/tools/sdk/ndk/index.html). For an
|
||||
example of using fmt with Android NDK, see the
|
||||
[android-ndk-example](https://github.com/fmtlib/android-ndk-example)
|
||||
repository.
|
||||
|
||||
## Homebrew
|
||||
|
||||
fmt can be installed on OS X using [Homebrew](https://brew.sh/):
|
||||
|
||||
brew install fmt
|
||||
250
doc/usage.rst
250
doc/usage.rst
@ -1,250 +0,0 @@
|
||||
*****
|
||||
Usage
|
||||
*****
|
||||
|
||||
To use the {fmt} library, add :file:`fmt/core.h`, :file:`fmt/format.h`,
|
||||
:file:`fmt/format-inl.h`, :file:`src/format.cc` and optionally other headers
|
||||
from a `release archive <https://github.com/fmtlib/fmt/releases/latest>`_ or
|
||||
the `Git repository <https://github.com/fmtlib/fmt>`_ to your project.
|
||||
Alternatively, you can :ref:`build the library with CMake <building>`.
|
||||
|
||||
.. _building:
|
||||
|
||||
Building the Library
|
||||
====================
|
||||
|
||||
The included `CMake build script`__ can be used to build the fmt
|
||||
library on a wide range of platforms. CMake is freely available for
|
||||
download from https://www.cmake.org/download/.
|
||||
|
||||
__ https://github.com/fmtlib/fmt/blob/master/CMakeLists.txt
|
||||
|
||||
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::
|
||||
|
||||
mkdir build # Create a directory to hold the build output.
|
||||
cd build
|
||||
cmake .. # Generate native build scripts.
|
||||
|
||||
where :file:`{<path/to/fmt>}` is a path to the ``fmt`` repository.
|
||||
|
||||
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 :command:`make`.
|
||||
|
||||
Once the library has been built you can invoke :command:`make test` to run
|
||||
the tests.
|
||||
|
||||
You can control generation of the make ``test`` target with the ``FMT_TEST``
|
||||
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 ``test`` target.
|
||||
|
||||
If you use Windows and have Visual Studio installed, a :file:`FMT.sln`
|
||||
file and several :file:`.vcproj` files will be created. You can then build them
|
||||
using Visual Studio or msbuild.
|
||||
|
||||
On Mac OS X with Xcode installed, an :file:`.xcodeproj` file will be generated.
|
||||
|
||||
To build a `shared library`__ set the ``BUILD_SHARED_LIBS`` CMake variable to
|
||||
``TRUE``::
|
||||
|
||||
cmake -DBUILD_SHARED_LIBS=TRUE ..
|
||||
|
||||
__ https://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries
|
||||
|
||||
|
||||
To build a `static library` with position independent code (required if the main
|
||||
consumer of the fmt library is a shared library i.e. a Python extension) set the
|
||||
``CMAKE_POSITION_INDEPENDENT_CODE`` CMake variable to ``TRUE``::
|
||||
|
||||
cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE ..
|
||||
|
||||
|
||||
Installing the Library
|
||||
======================
|
||||
|
||||
After building the library you can install it on a Unix-like system by running
|
||||
:command:`sudo make install`.
|
||||
|
||||
Usage with CMake
|
||||
================
|
||||
|
||||
You can add the ``fmt`` library directory into your project and include it in
|
||||
your ``CMakeLists.txt`` file::
|
||||
|
||||
add_subdirectory(fmt)
|
||||
|
||||
or
|
||||
|
||||
::
|
||||
|
||||
add_subdirectory(fmt EXCLUDE_FROM_ALL)
|
||||
|
||||
to exclude it from ``make``, ``make all``, or ``cmake --build .``.
|
||||
|
||||
You can detect and use an installed version of {fmt} as follows::
|
||||
|
||||
find_package(fmt)
|
||||
target_link_libraries(<your-target> fmt::fmt)
|
||||
|
||||
Setting up your target to use a header-only version of ``fmt`` is equally easy::
|
||||
|
||||
target_link_libraries(<your-target> PRIVATE fmt::fmt-header-only)
|
||||
|
||||
Usage with build2
|
||||
=================
|
||||
|
||||
You can use `build2 <https://build2.org>`_, a dependency manager and a
|
||||
build-system combined, to use ``fmt``.
|
||||
|
||||
Currently this package is available in these package repositories:
|
||||
|
||||
- **https://cppget.org/fmt/** for released and published versions.
|
||||
- `The git repository with the sources of the build2 package of fmt <https://github.com/build2-packaging/fmt.git>`_
|
||||
for unreleased or custom revisions of ``fmt``.
|
||||
|
||||
**Usage:**
|
||||
|
||||
- ``build2`` package name: ``fmt``
|
||||
- Library target name : ``lib{fmt}``
|
||||
|
||||
For example, to make your ``build2`` project depend on ``fmt``:
|
||||
|
||||
- Add one of the repositories to your configurations, or in your
|
||||
``repositories.manifest``, if not already there::
|
||||
|
||||
:
|
||||
role: prerequisite
|
||||
location: https://pkg.cppget.org/1/stable
|
||||
|
||||
- Add this package as a dependency to your ``./manifest`` file
|
||||
(example for ``v7.0.x``)::
|
||||
|
||||
depends: fmt ~7.0.0
|
||||
|
||||
- Import the target and use it as a prerequisite to your own target
|
||||
using `fmt` in the appropriate ``buildfile``::
|
||||
|
||||
import fmt = fmt%lib{fmt}
|
||||
lib{mylib} : cxx{**} ... $fmt
|
||||
|
||||
Then build your project as usual with `b` or `bdep update`.
|
||||
|
||||
For ``build2`` newcomers or to get more details and use cases, you can read the
|
||||
``build2``
|
||||
`toolchain introduction <https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml>`_.
|
||||
|
||||
Usage with Meson
|
||||
================
|
||||
|
||||
`Meson's WrapDB <https://mesonbuild.com/Wrapdb-projects.html>` includes a ``fmt``
|
||||
package, which repackages fmt to be built by Meson as a subproject.
|
||||
|
||||
**Usage:**
|
||||
|
||||
- Install the ``fmt`` subproject from the WrapDB by running::
|
||||
|
||||
meson wrap install fmt
|
||||
|
||||
from the root of your project.
|
||||
|
||||
- In your project's ``meson.build`` file, add an entry for the new subproject::
|
||||
|
||||
fmt = subproject('fmt')
|
||||
fmt_dep = fmt.get_variable('fmt_dep')
|
||||
|
||||
- Include the new dependency object to link with fmt::
|
||||
|
||||
my_build_target = executable('name', 'src/main.cc', dependencies: [fmt_dep])
|
||||
|
||||
**Options:**
|
||||
|
||||
If desired, ``fmt`` may be built as a static library, or as a header-only
|
||||
library.
|
||||
|
||||
For a static build, use the following subproject definition::
|
||||
|
||||
fmt = subproject('fmt', default_options: 'default_library=static')
|
||||
fmt_dep = fmt.get_variable('fmt_dep')
|
||||
|
||||
For the header-only version, use::
|
||||
|
||||
fmt = subproject('fmt')
|
||||
fmt_dep = fmt.get_variable('fmt_header_only_dep')
|
||||
|
||||
Building the Documentation
|
||||
==========================
|
||||
|
||||
To build the documentation you need the following software installed on your
|
||||
system:
|
||||
|
||||
* `Python <https://www.python.org/>`_ with pip and virtualenv
|
||||
* `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_
|
||||
* `Less <http://lesscss.org/>`_ with ``less-plugin-clean-css``.
|
||||
Ubuntu doesn't package the ``clean-css`` plugin so you should use ``npm``
|
||||
instead of ``apt`` to install both ``less`` and the plugin::
|
||||
|
||||
sudo npm install -g less less-plugin-clean-css.
|
||||
|
||||
First generate makefiles or project files using CMake as described in
|
||||
the previous section. Then compile the ``doc`` target/project, for example::
|
||||
|
||||
make doc
|
||||
|
||||
This will generate the HTML documentation in ``doc/html``.
|
||||
|
||||
Conda
|
||||
=====
|
||||
|
||||
fmt can be installed on Linux, macOS and Windows with
|
||||
`Conda <https://docs.conda.io/en/latest/>`__, using its
|
||||
`conda-forge <https://conda-forge.org>`__
|
||||
`package <https://github.com/conda-forge/fmt-feedstock>`__, as follows::
|
||||
|
||||
conda install -c conda-forge fmt
|
||||
|
||||
Vcpkg
|
||||
=====
|
||||
|
||||
You can download and install fmt using the `vcpkg
|
||||
<https://github.com/Microsoft/vcpkg>`__ dependency manager::
|
||||
|
||||
git clone https://github.com/Microsoft/vcpkg.git
|
||||
cd vcpkg
|
||||
./bootstrap-vcpkg.sh
|
||||
./vcpkg integrate install
|
||||
./vcpkg install fmt
|
||||
|
||||
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 `create an issue or pull
|
||||
request <https://github.com/Microsoft/vcpkg>`__ on the vcpkg repository.
|
||||
|
||||
LHelper
|
||||
=======
|
||||
|
||||
You can download and install fmt using
|
||||
`lhelper <https://github.com/franko/lhelper>`__ dependency manager::
|
||||
|
||||
lhelper activate <some-environment>
|
||||
lhelper install fmt
|
||||
|
||||
All the recipes for lhelper are kept in the
|
||||
`lhelper's recipe <https://github.com/franko/lhelper-recipes>`__ repository.
|
||||
|
||||
Android NDK
|
||||
===========
|
||||
|
||||
fmt provides `Android.mk file`__ that can be used to build the library
|
||||
with `Android NDK <https://developer.android.com/tools/sdk/ndk/index.html>`_.
|
||||
For an example of using fmt with Android NDK, see the
|
||||
`android-ndk-example <https://github.com/fmtlib/android-ndk-example>`_
|
||||
repository.
|
||||
|
||||
__ https://github.com/fmtlib/fmt/blob/master/support/Android.mk
|
||||
|
||||
Homebrew
|
||||
========
|
||||
|
||||
fmt can be installed on OS X using `Homebrew <https://brew.sh/>`_::
|
||||
|
||||
brew install fmt
|
||||
Loading…
Reference in New Issue
Block a user