mirror/fmt
1
0
Fork 0
mirror of https://github.com/fmtlib/fmt.git synced 2025-01-30 15:32:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Victor Zverovich 2024-06-09 10:16:19 -07:00
parent e845fc572e
commit d6ec6b7e27
1 changed files with 132 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

266
doc/get-started.md
View File

@ -1,17 +1,85 @@
# Get Started # Get Started
To use the {fmt} library, add `fmt/core.h`, `fmt/format.h`, `fmt/format-inl.h`, You can compile and run {fmt} examples online with [Compiler Explorer](
`src/format.cc` and optionally other headers from a [release archive]( https://godbolt.org/z/P7h6cd6o3).
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 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 ## CMake
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 {fmt} provides two CMake targets, `fmt::fmt` for the compiled library and
freely available for download from <https://www.cmake.org/download/>. `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 CMake works by generating native makefiles or project files that can be
used in the compiler environment of your choice. The typical workflow used in the compiler environment of your choice. The typical workflow
@ -23,83 +91,46 @@ starts with:
run in the `fmt` repository. run in the `fmt` repository.
If you are on a \*nix system, you should now see a Makefile in the 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 current directory. Now you can build the library by running `make`.
`make`{.interpreted-text role="command"}.
Once the library has been built you can invoke Once the library has been built you can invoke `make test` to run the tests.
`make test`{.interpreted-text role="command"} to run the tests.
You can control generation of the make `test` target with the `FMT_TEST` 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 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 To build a shared library set the `BUILD_SHARED_LIBS` CMake variable to `TRUE`:
`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 .. cmake -DBUILD_SHARED_LIBS=TRUE ..
To build a [static library]{.title-ref} with position independent code To build a static library with position-independent code, e.g. for
(required if the main consumer of the fmt library is a shared library linking it into another shared library such as a Python extension, set the
i.e. a Python extension) set the `CMAKE_POSITION_INDEPENDENT_CODE` CMake `CMAKE_POSITION_INDEPENDENT_CODE` CMake variable to `TRUE`:
variable to `TRUE`:
cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE .. cmake -DCMAKE_POSITION_INDEPENDENT_CODE=TRUE ..
## Installing the Library
After building the library you can install it on a Unix-like system by 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 ### build2
in your `CMakeLists.txt` file:
add_subdirectory(fmt) You can use [build2](https://build2.org), a dependency manager and a build
system, to use {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: Currently this package is available in these package repositories:
- **https://cppget.org/fmt/** for released and published versions. - <https://cppget.org/fmt/> for released and published versions.
- [The git repository with the sources of the build2 package of - <https://github.com/build2-packaging/fmt> for unreleased or custom versions.
fmt](https://github.com/build2-packaging/fmt.git) for unreleased or
custom revisions of `fmt`.
**Usage:** **Usage:**
- `build2` package name: `fmt` - `build2` package name: `fmt`
- Library target name: `lib{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 - Add one of the repositories to your configurations, or in your
`repositories.manifest`, if not already there: `repositories.manifest`, if not already there:
@ -108,30 +139,23 @@ For example, to make your `build2` project depend on `fmt`:
role: prerequisite role: prerequisite
location: https://pkg.cppget.org/1/stable location: https://pkg.cppget.org/1/stable
- Add this package as a dependency to your `./manifest` file (example - Add this package as a dependency to your `manifest` file (example
for `v7.0.x`): 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 - 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} import fmt = fmt%lib{fmt}
lib{mylib} : cxx{**} ... $fmt lib{mylib} : cxx{**} ... $fmt
Then build your project as usual with [b]{.title-ref} or [bdep Then build your project as usual with `b` or `bdep update`.
update]{.title-ref}.
For `build2` newcomers or to get more details and use cases, you can ### Meson
read the `build2` [toolchain
introduction](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml).
## Usage with Meson [Meson WrapDB](https://mesonbuild.com/Wrapdb-projects.html) includes an `fmt`
package.
[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:** **Usage:**
@ -141,20 +165,19 @@ subproject.
from the root of your project. from the root of your project.
- In your project\'s `meson.build` file, add an entry for the new - In your project's `meson.build` file, add an entry for the new subproject:
subproject:
fmt = subproject('fmt') fmt = subproject('fmt')
fmt_dep = fmt.get_variable('fmt_dep') fmt_dep = fmt.get_variable('fmt_dep')
- Include the new dependency object to link with fmt: - 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:** **Options:**
If desired, `fmt` may be built as a static library, or as a header-only If desired, {fmt} can be built as a static library, or as a header-only library.
library.
For a static build, use the following subproject definition: For a static build, use the following subproject definition:
@ -166,21 +189,30 @@ For the header-only version, use:
fmt = subproject('fmt') fmt = subproject('fmt')
fmt_dep = fmt.get_variable('fmt_header_only_dep') 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 To build the documentation you need the following software installed on
your system: your system:
- [Python](https://www.python.org/) with pip and virtualenv - [Python](https://www.python.org/) with pip and virtualenv
- [Doxygen](http://www.stack.nl/~dimitri/doxygen/) - [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 First generate makefiles or project files using CMake as described in
the previous section. Then compile the `doc` target/project, for the previous section. Then compile the `doc` target/project, for
example: example:
@ -188,55 +220,3 @@ example:
make doc make doc
This will generate the HTML documentation in `doc/html`. 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