doc/usage.rst - platform/external/fmtlib - Git at Google

 *****
 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
	*****
	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