Building wolfSentry
wolfSentry was written with portability in mind and should generally be easy to build on most systems. If you have difficulty building wolfSentry, please don’t hesitate to seek support through our support forums (https://www.wolfssl.com/forums) or contact us directly at support@wolfssl.com.
Getting wolfSentry Source Code
The most recent version of wolfSentry can be downloaded from the wolfSSL website as a ZIP file:
https://www.wolfssl.com/download
After downloading the ZIP file, unzip the file using the unzip
command. To use native line endings,
enable the -a
modifier when using unzip. From the unzip man page, the -a
modifier functionality is
described:
[...] The -a option causes files identified by zip as text files (those with the ‘t’ label in zipinfo listings, rather than ‘b’) to be automatically extracted as such, converting line endings, end- of-file characters and the character set itself as necessary. [...]
Dependencies
In its default build, wolfSentry depends on a POSIX runtime, specifically the heap allocator, clock_gettime, stdio, semaphore, and string APIs. However, these dependencies can be avoided with various build-time options. In paticular, the recipe
make STATIC=1 SINGLETHREADED=1 NO_STDIO=1 EXTRA_CFLAGS='-DWOLFSENTRY_NO_CLOCK_BUILTIN -DWOLFSENTRY_NO_MALLOC_BUILTIN'
generates a libwolfsentry.a that depends on only a handful of basic string functions. Allocator and time callbacks must then be set in a struct
wolfsentry_host_platform_interface
supplied to wolfsentry_init()
.
Building and testing
For platforms that support GNU Make then running make
will build wolfSentry as normal. For other platforms you will need to compile using the C files in the src
directory and its json
subdirectory.
To build and run the test suite you can use make -j test
or make V=1 -j test
verbosely.
Build Options
There are several flags that can be added to make
and flags that be used as build-time definitions in either a header file or CFLAGS
. To use the make
flags you can use:
make SINGLETHREADED=1 EXTRA_CFLAGS='-DWOLFSENTRY_NO_CLOCK_BUILTIN'
These will be stored at build time in the wolfsentry_options.h
file where wolfSentry is built. If you are not using make
then you can create this file with the following template:
#ifndef WOLFSENTRY_OPTIONS_H
#define WOLFSENTRY_OPTIONS_H
#endif /* WOLFSENTRY_OPTIONS_H */
The following table lists the possible options:
make option |
Description |
---|---|
V |
Verbose make output |
e.g. make V=1 -j test |
|
USER_MAKE_CONF |
A user-defined Makefile to include |
e.g. make -j USER_MAKE_CONF=Makefile.settings |
|
SRC_TOP |
The source code top level directory (default pwd -P ) |
BUILD_TOP |
Build with artifacts in an alternate location (outside or in a subdirectory of the source tree) |
e.g. make BUILD_TOP=./build -j test |
|
DEBUG |
Compiler debugging flag to use (default -ggdb ) |
OPTIM |
The optimizer flag to use (default -O3 ) |
C_WARNFLAGS |
The warning flags to use (default See [^1]) |
NO_STDIO |
The platform does not have STDIO |
NO_JSON |
Do not compile JSON configuration support |
USER_SETTINGS_FILE |
An additional header file to include |
SINGLETHEADED |
Do not use thread safe semantics for single threaded uses |
e.g. make -j SINGLETHREADED=1 test |
|
STATIC |
Build a static binary |
STRIPPED |
Strip binaries of debugging symbols |
BUILD_DYNAMIC |
Build dynamic library |
VERY_QUIET |
Enable a very quiet build |
TAR |
Path to GNU tar binary for make dist , should be set to gtar for macOS |
VERSION |
The version number to compile in (default See [^2]) |
[^1]: -Wall -Wextra -Werror -Wformat=2 -Winit-self -Wmissing-include-dirs -Wunknown-pragmas -Wshadow -Wpointer-arith -Wcast-align -Wwrite-strings -Wconversion -Wstrict-prototypes -Wold-style-definition -Wmissing-declarations -Wmissing-format-attribute -Wpointer-arith -Woverlength-strings -Wredundant-decls -Winline -Winvalid-pch -Wdouble-promotion -Wvla -Wno-missing-field-initializers -Wno-bad-function-cast -Wno-type-limits
and if GCC is used the additional flags of -Wjump-misses-init -Wlogical-op
are used.
[^2]: Defined as VERSION := $(shell git rev-parse --short=8 HEAD 2>/dev/null || echo xxxxxxxx)$(shell git diff --quiet 2>/dev/null || [ $$? -ne 1 ] || echo "-dirty")
Preprocesssor Macro | Description |
---|---|
WOLFSENTRY_NO_STDIO |
The platform does not have STDIO |
WOLFSENTRY_NO_JSON |
Do not compile JSON configuration support |
WOLFSENTRY_USER_SETTINGS_FILE |
An additional header file to include |
WOLFSENTRY_SINGLETHREADED |
Do not use thread safe semantics for single threaded uses |
CENTIJSON_USE_LOCALE |
JSON parser should use locale-dependent characters |
WOLFSENTRY_NO_PROTOCOL_NAMES |
Disable support for protocol names in configuration files |
DEBUG_JSON |
Add debugging printf() to the JSON parser |
WOLFSENTRY_NO_ERROR_STRINGS |
Disable error code to error string functions |
WOLFSENTRY_NO_MALLOC_BUILTINS |
Disable builtin malloc functions |
WOLFSENTRY_HAVE_NONGNU_ATOMICS |
Atomics are non-GNU (ignored if SINGLETHREADED is set) |
WOLFSENTRY_NO_CLOCK_BUILTIN |
Do not use bulitin time functions |
WOLFSENTRY_LWIP |
wolfSentry is being built against LWIP instead of BSD sockets |
FREERTOS |
Build with FreeRTOS support |
Build Option examples
Install from an alternate build location to a non-standard destination:
$make BUILD_TOP=./build INSTALL_DIR=/usr INSTALL_LIBDIR=/usr/lib64 install
Build libwolfsentry.a and test it under various analyzers (memory and thread testing under full battery of valgrind and sanitizer tests):
$make -j check
Build and test libwolfsentry.a without support for multithreading:
$make -j SINGLETHREADED=1 test
Other available make flags are STATIC=1
, STRIPPED=1
, NO_JSON=1
, and
NO_JSON_DOM=1
, and the defaults values for DEBUG
, OPTIM
, and C_WARNFLAGS
can also be usefully overridden.
Build with a user-supplied makefile preamble to override defaults:
$make -j USER_MAKE_CONF=Makefile.settings
(Makefile.settings
can contain simple settings like OPTIM := -Os
, or
elaborate makefile code including additional rules and dependency mechanisms.)
Build the smallest simplest possible library:
make -j SINGLETHREADED=1 NO_STDIO=1 DEBUG= OPTIM=-Os EXTRA_CFLAGS='-DWOLFSENTRY_NO_CLOCK_BUILTIN -DWOLFSENTRY_NO_MALLOC_BUILTIN -DWOLFSENTRY_NO_ERROR_STRINGS -Wno-error=inline -Wno-inline'
Build and test with user settings:
$make -j USER_SETTINGS_FILE=user_settings.h test