aboutsummaryrefslogtreecommitdiff
path: root/thirdparty/fmt/doc/get-started.md
diff options
context:
space:
mode:
authorStefan Boberg <[email protected]>2025-11-07 14:49:13 +0100
committerGitHub Enterprise <[email protected]>2025-11-07 14:49:13 +0100
commit24e43a913f29ac3b314354e8ce5175f135bcc64f (patch)
treeca442937ceeb63461012b33a4576e9835099f106 /thirdparty/fmt/doc/get-started.md
parentget oplog attachments (#622) (diff)
downloadzen-24e43a913f29ac3b314354e8ce5175f135bcc64f.tar.xz
zen-24e43a913f29ac3b314354e8ce5175f135bcc64f.zip
switch to xmake for package management (#611)
This change removes our dependency on vcpkg for package management, in favour of bringing some code in-tree in the `thirdparty` folder as well as using the xmake build-in package management feature. For the latter, all the package definitions are maintained in the zen repo itself, in the `repo` folder. It should now also be easier to build the project as it will no longer depend on having the right version of vcpkg installed, which has been a common problem for new people coming in to the codebase. Now you should only need xmake to build. * Bumps xmake requirement on github runners to 2.9.9 to resolve an issue where xmake on Windows invokes cmake with `v144` toolchain which does not exist * BLAKE3 is now in-tree at `thirdparty/blake3` * cpr is now in-tree at `thirdparty/cpr` * cxxopts is now in-tree at `thirdparty/cxxopts` * fmt is now in-tree at `thirdparty/fmt` * robin-map is now in-tree at `thirdparty/robin-map` * ryml is now in-tree at `thirdparty/ryml` * sol2 is now in-tree at `thirdparty/sol2` * spdlog is now in-tree at `thirdparty/spdlog` * utfcpp is now in-tree at `thirdparty/utfcpp` * xmake package repo definitions is in `repo` * implemented support for sanitizers. ASAN is supported on windows, TSAN, UBSAN, MSAN etc are supported on Linux/MacOS though I have not yet tested it extensively on MacOS * the zencore encryption implementation also now supports using mbedTLS which is used on MacOS, though for now we still use openssl on Linux * crashpad * bumps libcurl to 8.11.0 (from 8.8.0) which should address a rare build upload bug
Diffstat (limited to 'thirdparty/fmt/doc/get-started.md')
-rw-r--r--thirdparty/fmt/doc/get-started.md233
1 files changed, 233 insertions, 0 deletions
diff --git a/thirdparty/fmt/doc/get-started.md b/thirdparty/fmt/doc/get-started.md
new file mode 100644
index 000000000..6bcefe7d0
--- /dev/null
+++ b/thirdparty/fmt/doc/get-started.md
@@ -0,0 +1,233 @@
+# Get Started
+
+Compile and run {fmt} examples online with [Compiler Explorer](
+https://godbolt.org/z/P7h6cd6o3).
+
+{fmt} is compatible with any build system. The next section describes its usage
+with CMake, while the [Build Systems](#build-systems) section covers the rest.
+
+## 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 improved build times.
+
+There are three primary ways to use {fmt} with CMake:
+
+* **FetchContent**: Starting from CMake 3.11, you can use [`FetchContent`](
+ https://cmake.org/cmake/help/v3.30/module/FetchContent.html) 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](#installation) 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)
+
+## Installation
+
+### Debian/Ubuntu
+
+To install {fmt} on Debian, Ubuntu, or any other Debian-based Linux
+distribution, use the following command:
+
+ apt install libfmt-dev
+
+### Homebrew
+
+Install {fmt} on macOS using [Homebrew](https://brew.sh/):
+
+ brew install fmt
+
+### Conda
+
+Install {fmt} 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
+
+Download and install {fmt} using the 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. -->
+
+### Conan
+
+You can download and install {fmt} using the [Conan](https://conan.io/) package manager:
+
+ conan install -r conancenter --requires="fmt/[*]" --build=missing
+
+<!-- The {fmt} package in Conan Center is maintained by
+[ConanCenterIndex](https://github.com/conan-io/conan-center-index) community.
+If the version is out of date or the package does not work,
+please create an issue or pull request on the Conan Center Index 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
+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 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` 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.
+
+To build a shared library set the `BUILD_SHARED_LIBS` CMake variable to `TRUE`:
+
+ cmake -DBUILD_SHARED_LIBS=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 ..
+
+After building the library you can install it on a Unix-like system by
+running `sudo make install`.
+
+### Building the Docs
+
+To build the documentation you need the following software installed on
+your system:
+
+- [Python](https://www.python.org/)
+- [Doxygen](http://www.stack.nl/~dimitri/doxygen/)
+- [MkDocs](https://www.mkdocs.org/) with `mkdocs-material`, `mkdocstrings`,
+ `pymdown-extensions` and `mike`
+
+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`.
+
+## Build Systems
+
+### build2
+
+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.
+- <https://github.com/build2-packaging/fmt> for unreleased or custom versions.
+
+**Usage:**
+
+- `build2` package name: `fmt`
+- Library target name: `lib{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:
+
+ :
+ role: prerequisite
+ location: https://pkg.cppget.org/1/stable
+
+- Add this package as a dependency to your `manifest` file (example
+ for version 10):
+
+ depends: fmt ~10.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`.
+
+### Meson
+
+[Meson WrapDB](https://mesonbuild.com/Wrapdb-projects.html) includes an `fmt`
+package.
+
+**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} can 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', default_options: ['header-only=true'])
+ fmt_dep = fmt.get_variable('fmt_header_only_dep')
+
+### 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.