fmtlegacy/doc/usage.rst

114 lines
3.4 KiB
ReStructuredText
Raw Normal View History

2014-10-16 14:12:43 +00:00
*****
Usage
*****
2016-04-27 15:35:59 +00:00
To use the fmt library, add :file:`format.h` and :file:`format.cc` 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>`.
2014-10-16 14:12:43 +00:00
If you are using Visual C++ with precompiled headers, you might need to add
2014-11-05 15:39:34 +00:00
the line ::
2014-10-16 14:12:43 +00:00
#include "stdafx.h"
before other includes in :file:`format.cc`.
.. _building:
Building the library
====================
2016-04-27 15:35:59 +00:00
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 http://www.cmake.org/download/.
2016-04-27 15:35:59 +00:00
__ 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::
2016-04-27 15:35:59 +00:00
mkdir build # Create a directory to hold the build output.
cd build
2016-04-27 15:35:59 +00:00
cmake <path/to/fmt> # Generate native build scripts.
2016-04-27 15:35:59 +00:00
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
2016-04-27 15:35:59 +00:00
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.
2015-05-15 06:57:22 +00:00
If you use Windows and have Visual Studio installed, a :file:`FORMAT.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 ...
__ http://en.wikipedia.org/wiki/Library_%28computing%29#Shared_libraries
2015-02-16 15:09:25 +00:00
Header-only 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 .``.
Settting up your target to use a header-only version of ``fmt`` is equaly easy::
target_link_libraries(<your-target> PRIVATE fmt-header-only)
2015-10-17 15:17:32 +00:00
Building the documentation
==========================
To build the documentation you need the following software installed on your
system:
2015-10-17 15:21:23 +00:00
* `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.
2015-10-17 15:17:32 +00:00
First generate makefiles or project files using CMake as described in
2015-10-17 15:34:58 +00:00
the previous section. Then compile the ``doc`` target/project, for example::
2015-10-17 15:17:32 +00:00
make doc
2016-05-01 10:29:21 +00:00
This will generate the HTML documentation in ``doc/html``.
2015-10-17 15:17:32 +00:00
2015-02-16 15:09:25 +00:00
Android NDK
===========
2016-04-27 15:35:59 +00:00
fmt provides `Android.mk file`__ that can be used to build the library
2015-02-16 15:25:45 +00:00
with `Android NDK <https://developer.android.com/tools/sdk/ndk/index.html>`_.
2016-04-27 15:35:59 +00:00
For an example of using fmt with Android NDK, see the
`android-ndk-example <https://github.com/fmtlib/android-ndk-example>`_
2015-02-16 15:09:25 +00:00
repository.
2016-04-27 15:35:59 +00:00
__ https://github.com/fmtlib/fmt/blob/master/Android.mk
Homebrew
========
2016-04-27 15:35:59 +00:00
fmt can be installed on OS X using `Homebrew <http://brew.sh/>`_::
brew install fmt