mirror of
https://github.com/fmtlib/fmt.git
synced 2025-01-30 15:32:36 +00:00
Update docs
This commit is contained in:
Victor Zverovich
parent
e845fc572e
commit
d6ec6b7e27
@ -1,17 +1,85 @@
|
||||
# Get Started
|
||||
|
||||
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.
|
||||
You can compile and run {fmt} examples online with [Compiler Explorer](
|
||||
https://godbolt.org/z/P7h6cd6o3).
|
||||
|
||||
## Building the Library
|
||||
{fmt} can be used with any build system. The next section describes usage with
|
||||
CMake and [Build Systems](#build-systems) covers the rest.
|
||||
|
||||
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
|
||||
|
||||
{fmt} provides two CMake targets, `fmt::fmt` for the compiled library and
|
||||
`fmt::fmt-header-only` for the header-only library. It is recommended to use
|
||||
the compiled library for better build times.
|
||||
|
||||
There are three main ways to consume {fmt} from CMake:
|
||||
|
||||
* **FetchContent**: Since CMake v3.11, [`FetchContent`](
|
||||
https://cmake.org/cmake/help/v3.30/module/FetchContent.html) can be used to
|
||||
automatically download {fmt} as a dependency at configure time:
|
||||
|
||||
include(FetchContent)
|
||||
|
||||
FetchContent_Declare(
|
||||
fmt
|
||||
GIT_REPOSITORY https://github.com/fmtlib/fmt
|
||||
GIT_TAG e69e5f977d458f2650bb346dadf2ad30c5320281) # 10.2.1
|
||||
FetchContent_MakeAvailable(fmt)
|
||||
|
||||
target_link_libraries(<your-target> fmt::fmt)
|
||||
|
||||
* **Installed**: You can find and use an [installed](#install) version of {fmt}
|
||||
in your `CMakeLists.txt` file as follows:
|
||||
|
||||
find_package(fmt)
|
||||
target_link_libraries(<your-target> fmt::fmt)
|
||||
|
||||
* **Embedded**: You can add the `fmt` source tree to your project and include it
|
||||
in your `CMakeLists.txt` file:
|
||||
|
||||
add_subdirectory(fmt)
|
||||
target_link_libraries(<your-target> fmt::fmt)
|
||||
|
||||
## Install
|
||||
|
||||
### Debian/Ubuntu
|
||||
|
||||
Use the following command to install {fmt} on Debian, Ubuntu or any other
|
||||
Debian-based Linux distribution:
|
||||
|
||||
apt install libfmt-dev
|
||||
|
||||
### Homebrew
|
||||
|
||||
{fmt} can be installed on macOS using [Homebrew](https://brew.sh/):
|
||||
|
||||
brew install fmt
|
||||
|
||||
### Conda
|
||||
|
||||
{fmt} can be installed on Linux, macOS and Windows with [Conda](
|
||||
https://docs.conda.io/en/latest/), using its [conda-forge package](
|
||||
https://github.com/conda-forge/fmt-feedstock):
|
||||
|
||||
conda install -c conda-forge fmt
|
||||
|
||||
### Vcpkg
|
||||
|
||||
You can download and install {fmt} using the [vcpkg](
|
||||
https://github.com/Microsoft/vcpkg) package manager:
|
||||
|
||||
git clone https://github.com/Microsoft/vcpkg.git
|
||||
cd vcpkg
|
||||
./bootstrap-vcpkg.sh
|
||||
./vcpkg integrate install
|
||||
./vcpkg install fmt
|
||||
|
||||
<!-- The fmt package 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. -->
|
||||
|
||||
## Building from Source
|
||||
|
||||
CMake works by generating native makefiles or project files that can be
|
||||
used in the compiler environment of your choice. The typical workflow
|
||||
@ -23,83 +91,46 @@ starts with:
|
||||
|
||||
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"}.
|
||||
If you are on a Unix-like system, you should now see a Makefile in the
|
||||
current directory. Now you can build the library by running `make`.
|
||||
|
||||
Once the library has been built you can invoke
|
||||
`make test`{.interpreted-text role="command"} to run the tests.
|
||||
Once the library has been built you can invoke `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.
|
||||
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`:
|
||||
To build a shared library 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`:
|
||||
To build a static library with position-independent code, e.g. for
|
||||
linking it into another shared library such as 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"}.
|
||||
running `sudo make install`.
|
||||
|
||||
## Usage with CMake
|
||||
## Build Systems
|
||||
|
||||
You can add the `fmt` library directory into your project and include it
|
||||
in your `CMakeLists.txt` file:
|
||||
### build2
|
||||
|
||||
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`.
|
||||
You can use [build2](https://build2.org), a dependency manager and a build
|
||||
system, 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`.
|
||||
- <https://cppget.org/fmt/> for released and published versions.
|
||||
- <https://github.com/build2-packaging/fmt> for unreleased or custom versions.
|
||||
|
||||
**Usage:**
|
||||
|
||||
- `build2` package name: `fmt`
|
||||
- Library target name: `lib{fmt}`
|
||||
|
||||
For example, to make your `build2` project depend on `fmt`:
|
||||
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:
|
||||
@ -108,30 +139,23 @@ For example, to make your `build2` project depend on `fmt`:
|
||||
role: prerequisite
|
||||
location: https://pkg.cppget.org/1/stable
|
||||
|
||||
- Add this package as a dependency to your `./manifest` file (example
|
||||
for `v7.0.x`):
|
||||
- Add this package as a dependency to your `manifest` file (example
|
||||
for version 10):
|
||||
|
||||
depends: fmt ~7.0.0
|
||||
depends: fmt ~10.0.0
|
||||
|
||||
- Import the target and use it as a prerequisite to your own target
|
||||
using [fmt]{.title-ref} in the appropriate `buildfile`:
|
||||
using `fmt` 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}.
|
||||
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).
|
||||
### Meson
|
||||
|
||||
## 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.
|
||||
[Meson WrapDB](https://mesonbuild.com/Wrapdb-projects.html) includes an `fmt`
|
||||
package.
|
||||
|
||||
**Usage:**
|
||||
|
||||
@ -141,20 +165,19 @@ subproject.
|
||||
|
||||
from the root of your project.
|
||||
|
||||
- In your project\'s `meson.build` file, add an entry for the new
|
||||
subproject:
|
||||
- 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])
|
||||
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.
|
||||
If desired, {fmt} can be built as a static library, or as a header-only library.
|
||||
|
||||
For a static build, use the following subproject definition:
|
||||
|
||||
@ -166,21 +189,30 @@ For the header-only version, use:
|
||||
fmt = subproject('fmt')
|
||||
fmt_dep = fmt.get_variable('fmt_header_only_dep')
|
||||
|
||||
## Building the Documentation
|
||||
### 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).
|
||||
|
||||
### Other
|
||||
|
||||
To use the {fmt} library with any other build system, add
|
||||
`include/fmt/base.h`, `include/fmt/format.h`, `include/fmt/format-inl.h`,
|
||||
`src/format.cc` and optionally other headers from a [release archive](
|
||||
https://github.com/fmtlib/fmt/releases) or the [git repository](
|
||||
https://github.com/fmtlib/fmt) to your project, add `include` to include
|
||||
directories and make sure `src/format.cc` is compiled and linked with your code.
|
||||
|
||||
## Building the Docs
|
||||
|
||||
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:
|
||||
@ -188,55 +220,3 @@ 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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user