Header-only or static library
The header-only variant has shown better performance on clang and gcc [1] and does not necessarily make the generated binaries bigger — it depends on how much Strf is invoked in your code.[2]
To use Strf as a header-only all you need to do is to add
to the include paths of your project the include directory
that is inside root directory of Strf.
To use Strf as a static library you need also to define
the macro STRF_SEPARATE_COMPILATION.
To genereate the static library you only need to compile
one source file: src/strf.cpp.
Or, you can use CMake.
If you are using CMake
If you use CMake, you are probably already know with the proccess. Anyway:
Option 1: The simple way ( using add_subdirectory )
I don’t see the CMake documentation recomending this approach, but
I also don’t see any problem in it when importing a library that is
small and has no dependencies, which is the case of Strf.
The idea is that you copy the whole Strf folder ( the one that
is created by the command git clone https://github.com/robhz786/strf )
somewhere inside your project directory ( like in a external/
or third_party/ subdirectory ), and then, in your CMakeLists.txt file,
you add the command:
add_subdirectory(<strf-dir>)This adds two targets in your project: Strf::StrfHeaderOnly
and Strf::StrfStatic.
Option 2: Export and import
First you install Strf in some location:
git clone https://github.com/robhz786/strf
mkdir build_strf
cd build_strf
cmake ../strf
cmake --build .
cmake --install . --prefix <installation-directory>The <installation-directory> used above must added to
the CMAKE_PREFIX_PATH variable used in your CMake project.
cmake -G <generator-name> -DCMAKE_PREFIX_PATH=<installation-directory> … <path-to-source>Then, the command find_package(Strf) will bring into your
project the targets Strf::StrfHeaderOnly and
Strf::StrfStatic.
# In your CMake project file:
# ...
find_package(Strf)
target_link_libraries(your_target Strf::StrfHeaderOnly)
# or
# target_link_libraries(your_target Strf::StrfStatic)Running the unit tests
To build the unit test, just turn on the STRF_BUILD_TEST CMake option:
cmake -G <generator-name> -DSTRF_BUILD_TEST=ON … <Strf-root-dir>
cmake --build . && ctestFreestanding Strf
There is an experimental variant of the Strf library: if you use the CMake option
STRF_FREESTANDING ( through the cmake command option -DSTRF_FREESTANDING=ON ), then
Strf will only depend on freestanding
parts of the C++ Standard Library. Not even the functions declared in <cstring>
header ( like memcpy and strcpy ) are used, unless you use the CMake option
STRF_WITH_CSTRING ( by passing the command option -DSTRF_WITH_CSTING=ON ).
This options causes Strf to use <cstring> functions even when STRF_FREESTANDING
is on, which is highly recommended when such functions are available ( because
Strf will otherwise use slow loop-based alternatives )
If you are not using CMake, you instead define the macros:
// Make sure these defines come before including any of the library's header
#define STRF_FREESTANDING
#define STRF_WITH_CSTRING
#include <strf.hpp>