Build and Installation Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide describes the procedures for building and installing libfastjson, a high-performance JSON handling library. It covers environment preparation, the build process for both release tarballs and git clones, and instructions for integrating the library into downstream projects.
libfastjson is a fork of json-c focused on speed and a reduced feature set to provide essential JSON handling functions for projects requiring high throughput.
Sources: README.md:1-13, README.html:12-15
Prerequisites
Before building libfastjson, ensure the following tools and compilers are available on your system:
| Tool | Requirement |
|---|---|
| C Compiler | gcc, clang, or any standard C compiler. |
| libtool | Required for shared library management (must include libtoolize). |
| autoconf | Required if building from a git clone (autoreconf). |
| automake | Required if building from a git clone. |
| pkgconfig | Recommended for linking the library to other projects. |
Sources: README.md:21-31, README.md:61-64
Standard Build Process
The build system utilizes autotools. The workflow varies slightly depending on whether the source was obtained via a release tarball or a direct repository clone.
Initializing the Build Environment
If you are working from a git repository, you must first generate the configure script. This is handled by the autogen.sh script, which wraps autoreconf.
$ sh autogen.sh
Sources: README.md:37-40, autogen.sh:1-2
Configuration and Compilation
Once the environment is initialized, the standard configure, make, and make install sequence is used to build and install the library.
$ ./configure
$ make
$ make install
Sources: README.md:43-47, README.html:18-19
Build Logic Flow
The following diagram illustrates the sequence of commands required to move from source code to an installed library.
Advanced Build Options
Continuous Integration and Sanitizers
For development and debugging, libfastjson supports Address Sanitizers (ASan) to detect memory errors. This is typically configured via environment variables before running the build scripts.
$ export CC=gcc
$ export CFLAGS="-g -fsanitize=address"
$ ./autogen.sh
$ ./configure
$ make clean
$ make check
Sources: CI/clang-check-sanitizer.sh:1-9
Internal Build Macros
The project utilizes specialized macros for specific compiler flags, such as AX_APPEND_COMPILE_FLAGS, which are managed through a local copy of the Autoconf Archive.
Sources: autoconf-archive/README.txt:1-5
Testing and Verification
After compilation, it is highly recommended to run the built-in test suite to ensure the library functions correctly on your specific architecture.
$ make check
Sources: README.md:52-54, CI/clang-check-sanitizer.sh:10
Linking to libfastjson
After installation, the library can be integrated into other C projects using two primary methods.
Method 1: Using pkg-config (Recommended)
If pkgconfig is installed, add the following to your Makefile to automatically resolve headers and library paths:
CFLAGS += $(shell pkg-config --cflags libfastjson)
LDFLAGS += $(shell pkg-config --libs libfastjson)
Sources: README.md:61-68
Method 2: Manual Path Specification
If pkg-config is unavailable, you must manually point your compiler and linker to the installation directory:
LIBFASTJSON_DIR=/path/to/install
CFLAGS += -I$(LIBFASTJSON_DIR)/include/libfastjson
LDFLAGS += -L$(LIBFASTJSON_DIR)/lib -lfastjson
Sources: README.md:70-74
Release and Versioning Workflow
For maintainers, the project follows a strict release checklist involving version updates in several configuration files.
- Version Tracking: Versions are updated in
configure.ac,Doxyfile, andjson_c_version.h. - Shared Library Versioning: The
libjson_la_LDFLAGSinMakefile.ammust be updated according to Libtool versioning rules (usually-version-info x:y+1:z). - Artifact Generation: The process involves creating two tarballs: one containing full documentation and a "nodoc" version.
Sources: RELEASE_CHECKLIST.txt:13-23, RELEASE_CHECKLIST.txt:47-51
The libfastjson build and installation process follows standard Unix conventions using autotools, ensuring compatibility across various Linux and BSD distributions. Proper verification through make check and correct linking via pkg-config are essential steps for reliable deployment.