Libx yyjson Documentation

    On this page

    Building and testing

    There are several ways to integrate this library into your project: source code, package manager, and CMake.

    Source code

    This library aims to provide a cross-platform JSON library and targets the ANSI C (C89) standard. It can be compiled with both strict C89 and modern C or C++ compilers. Simply copy yyjson.h and yyjson.c into your project and start using it without any configuration.

    The library is tested in GitHub CI with multiple compilers (gcc, clang, msvc, tcc, watcom) and architectures (x86, arm, ppc, riscv, s390x, wasm). Please report a bug if you encounter any compilation issues.

    All features are enabled by default, but you can disable some of them with compile-time options. For example, you can disable the JSON writer to reduce binary size when serialization is not needed, or disable comment support to improve parsing performance. See Compile-time Options for details.

    Package manager

    You can use some popular package managers like vcpkg, conan, and xmake to download and install yyjson. The yyjson package in these package managers is kept up to date by community contributors. If the version is out of date, please create an issue or pull request on their repository.

    Use vcpkg

    You can build and install yyjson using vcpkg dependency manager:

    git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh  # ./bootstrap-vcpkg.bat for PowerShell
./vcpkg integrate install
./vcpkg install yyjson

    If the version is out of date, please create an issue or pull request on the vcpkg repository.

    CMake

    Use CMake to build the library

    Clone the repository and create build directory:

    git clone https://github.com/ibireme/yyjson.git
cmake -E make_directory build; cd build

    Build static library:

    cmake .. 
cmake --build .

    Build shared library:

    cmake .. -DBUILD_SHARED_LIBS=ON
cmake --build .

    Supported CMake options (default OFF):

    • -DYYJSON_BUILD_TESTS=ON Build all tests.

    • -DYYJSON_BUILD_FUZZER=ON Build fuzzer with LibFuzzer.

    • -DYYJSON_BUILD_MISC=ON Build misc.

    • -DYYJSON_BUILD_DOC=ON Build documentation with doxygen.

    • -DYYJSON_ENABLE_COVERAGE=ON Enable code coverage for tests.

    • -DYYJSON_ENABLE_VALGRIND=ON Enable valgrind memory checker for tests.

    • -DYYJSON_ENABLE_FASTMATH=ON Enable fast-math for tests.

    • -DYYJSON_FORCE_32_BIT=ON Force 32-bit for tests (gcc/clang/icc).

    • -DYYJSON_SANITIZER=<name> Enable sanitizer for tests (address, undefined, or memory).

    • -DYYJSON_DISABLE_READER=ON Disable JSON reader if you don’t need it.

    • -DYYJSON_DISABLE_WRITER=ON Disable JSON writer if you don’t need it.

    • -DYYJSON_DISABLE_INCR_READER=ON Disable incremental reader if you don’t need it.

    • -DYYJSON_DISABLE_FILE=ON Disable file/fp read and write APIs.

    • -DYYJSON_DISABLE_UTILS=ON Disable JSON Pointer, JSON Patch and JSON Merge Patch.

    • -DYYJSON_DISABLE_FAST_FP_CONV=ON Disable built-in fast floating-point number conversion.

    • -DYYJSON_DISABLE_NON_STANDARD=ON Disable non-standard JSON support at compile-time.

    • -DYYJSON_DISABLE_UTF8_VALIDATION=ON Disable UTF-8 validation at compile-time.

    • -DYYJSON_DISABLE_UNALIGNED_MEMORY_ACCESS=ON Disable unaligned memory access support at compile-time.

    • -DYYJSON_FREESTANDING=ON Build without libc (see YYJSON_FREESTANDING below).

    • -DYYJSON_READER_DEPTH_LIMIT=<n> Set a maximum nesting depth for JSON reader (see YYJSON_READER_DEPTH_LIMIT below).

    • -DYYJSON_WRITER_DEPTH_LIMIT=<n> Set a maximum nesting depth for JSON writer (see YYJSON_WRITER_DEPTH_LIMIT below).

    Use CMake as a dependency

    You can download and unzip yyjson to your project directory and link it in your CMakeLists.txt file:

    # Add some options (optional)
set(YYJSON_DISABLE_NON_STANDARD ON CACHE INTERNAL "")

# Add the `yyjson` subdirectory
add_subdirectory(vendor/yyjson)

# Link yyjson to your target
target_link_libraries(your_target PRIVATE yyjson)

    If your CMake version is higher than 3.11, you can use the following code to let CMake automatically download it:

    include(FetchContent)

# Let CMake download yyjson
FetchContent_Declare(
    yyjson
    GIT_REPOSITORY https://github.com/ibireme/yyjson.git
    GIT_TAG master # master, or version number, e.g. 0.6.0
)
FetchContent_GetProperties(yyjson)
if(NOT yyjson_POPULATED)
  FetchContent_Populate(yyjson)
  add_subdirectory(${yyjson_SOURCE_DIR} ${yyjson_BINARY_DIR} EXCLUDE_FROM_ALL)
endif()

# Link yyjson to your target
target_link_libraries(your_target PRIVATE yyjson)

    Use CMake to generate project

    If you want to build or debug yyjson with another compiler or IDE, try these commands:

    cmake -E make_directory build; cd build

# Clang for Linux/Unix:
cmake .. -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++

# Intel ICC for Linux/Unix:
cmake .. -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc

# Another version of GCC:
cmake .. -DCMAKE_C_COMPILER=/usr/local/gcc-8.2/bin/gcc -DCMAKE_CXX_COMPILER=/usr/local/gcc-8.2/bin/g++

# Microsoft Visual Studio for Windows:
cmake .. -G "Visual Studio 16 2019" -A x64
cmake .. -G "Visual Studio 16 2019" -A Win32
cmake .. -G "Visual Studio 15 2017 Win64"

# Xcode for macOS:
cmake .. -G Xcode

# Xcode for iOS:
cmake .. -G Xcode -DCMAKE_SYSTEM_NAME=iOS

# Xcode with XCTest
cmake .. -G Xcode -DYYJSON_BUILD_TESTS=ON

    Use CMake to generate documentation

    This project uses doxygen to generate the documentation. Make sure doxygen is installed on your system before proceeding, it’s best to use the version specified in doc/Doxyfile.in.

    To build the documentation:

    cmake -E make_directory build; cd build
cmake .. -DYYJSON_BUILD_DOC=ON
cmake --build .

    The generated HTML files will be located in build/doxygen/html.

    You can also browse the pre-generated documentation online: https://ibireme.github.io/yyjson/doc/doxygen/html/

    Testing With CMake and CTest

    Build and run all tests:

    cmake -E make_directory build; cd build
cmake .. -DYYJSON_BUILD_TESTS=ON
cmake --build .
ctest --output-on-failure

    Build and run tests with valgrind memory checker, (make sure you have valgrind installed before proceeding):

    cmake -E make_directory build; cd build
cmake .. -DYYJSON_BUILD_TESTS=ON -DYYJSON_ENABLE_VALGRIND=ON
cmake --build .
ctest --output-on-failure

    Build and run tests with sanitizer (address, undefined, or memory) using -DYYJSON_SANITIZER=<name>. For memory, use Clang on Linux x86_64:

    cmake -E make_directory build; cd build
# address / undefined
cmake .. -DYYJSON_BUILD_TESTS=ON -DYYJSON_SANITIZER=address
cmake .. -DYYJSON_BUILD_TESTS=ON -DYYJSON_SANITIZER=undefined

# memory (Linux x86_64 + Clang)
cmake .. -DYYJSON_BUILD_TESTS=ON -DYYJSON_SANITIZER=memory \
  -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++

cmake --build .
ctest --output-on-failure

    Build and run code coverage with gcc:

    cmake -E make_directory build; cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug -DYYJSON_BUILD_TESTS=ON -DYYJSON_ENABLE_COVERAGE=ON
cmake --build . --config Debug
ctest --output-on-failure

lcov -c -d ./CMakeFiles --include "*/yyjson.*" -o cov.info
genhtml cov.info -o ./cov_report

    Build and run code coverage with clang:

    cmake -E make_directory build; cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug -DYYJSON_BUILD_TESTS=ON -DYYJSON_ENABLE_COVERAGE=ON -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake --build . --config Debug

export LLVM_PROFILE_FILE=cov/profile-%p.profraw
ctest --output-on-failure

ctest_files=$(grep -o "test_\w\+" CTestTestfile.cmake | uniq | tr '\n' ' ')
ctest_files=$(echo $ctest_files | sed 's/  $//' | sed "s/ / -object /g")
llvm-profdata merge -sparse cov/profile-*.profraw -o coverage.profdata
llvm-cov show $ctest_files -instr-profile=coverage.profdata -format=html > coverage.html

    Build and run fuzz test with LibFuzzer (compiler should be LLVM Clang, while Apple Clang or gcc are not supported):

    cmake -E make_directory build; cd build
cmake .. -DYYJSON_BUILD_FUZZER=ON -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake --build .
./fuzzer -dict=fuzzer.dict ./corpus

    Compile-time Options

    This library provides some compile-time options that can be defined as 1 to disable specific features during compilation. For example, to disable the JSON writer:

    cmake -E make_directory build; cd build
cmake .. -DYYJSON_DISABLE_WRITER=ON
gcc -DYYJSON_DISABLE_WRITER=1 ...

    YYJSON_DISABLE_READER

    Define as 1 to disable JSON reader at compile-time.
    This disables functions with read in their name.
    Reduces binary size by about 60%.
    It is recommended when JSON parsing is not required.

    YYJSON_DISABLE_WRITER

    Define as 1 to disable JSON writer at compile-time.
    This disables functions with write in their name.
    Reduces binary size by about 30%.
    It is recommended when JSON serialization is not required.

    YYJSON_DISABLE_INCR_READER

    Define as 1 to disable JSON incremental reader at compile-time.
    This disables functions with incr in their name.
    It is recommended when JSON incremental reader is not required.

    YYJSON_DISABLE_FILE

    Define as 1 to disable file and FILE pointer APIs at compile-time.
    stdio.h is not included by yyjson.h when this is set.

    YYJSON_DISABLE_UTILS

    Define as 1 to disable JSON Pointer, JSON Patch and JSON Merge Patch support.
    This disables functions with ptr or patch in their name.
    It is recommended when these functions are not required.

    YYJSON_DISABLE_FAST_FP_CONV

    Define as 1 to disable the fast floating-point number conversion in yyjson.
    Libc’s strtod/snprintf will be used instead.
    This reduces binary size by about 30%, but significantly slows down the floating-point read/write speed.
    It is recommended when processing JSON with few floating-point numbers.

    YYJSON_DISABLE_NON_STANDARD

    Define as 1 to disable non-standard JSON features support at compile-time:

    • YYJSON_READ_ALLOW_INF_AND_NAN
    • YYJSON_READ_ALLOW_COMMENTS
    • YYJSON_READ_ALLOW_TRAILING_COMMAS
    • YYJSON_READ_ALLOW_INVALID_UNICODE
    • YYJSON_READ_ALLOW_BOM
    • YYJSON_READ_ALLOW_EXT_NUMBER
    • YYJSON_READ_ALLOW_EXT_ESCAPE
    • YYJSON_READ_ALLOW_EXT_WHITESPACE
    • YYJSON_READ_ALLOW_SINGLE_QUOTED_STR
    • YYJSON_READ_ALLOW_UNQUOTED_KEY
    • YYJSON_READ_JSON5
    • YYJSON_WRITE_ALLOW_INF_AND_NAN
    • YYJSON_WRITE_ALLOW_INVALID_UNICODE

    This reduces binary size by about 10%, and slightly improves performance.
    It is recommended when not dealing with non-standard JSON.

    YYJSON_DISABLE_UTF8_VALIDATION

    Define as 1 to disable UTF-8 validation at compile-time.

    Use this if all input strings are guaranteed to be valid UTF-8 (e.g. language-level String types are already validated).

    Disabling UTF-8 validation improves performance for non-ASCII strings by about 3% to 7%.

    Note: If this flag is enabled while passing illegal UTF-8 strings, the following errors may occur:

    • Escaped characters may be ignored when parsing JSON strings.
    • Ending quotes may be ignored when parsing JSON strings, causing the string to merge with the next value.
    • When serializing with yyjson_mut_val, the string’s end may be accessed out of bounds, potentially causing a segmentation fault.

    YYJSON_FREESTANDING

    Define as 1 to build yyjson without libc (stdlib.h, string.h, math.h, and stdio.h).

    When string.h is unavailable, yyjson provides built-in inline fallbacks for memcpy, memmove, memset, memcmp, and strlen. On modern GCC and Clang at -O2/-O3, these are typically inlined with little impact on throughput. Alternatively, define YYJSON_FREESTANDING_HEADER to a custom header that supplies your own implementations.

    malloc and free are not available. Pass a yyjson_alc allocator to each API that accepts one, or define a global default at compile time, for example -DYYJSON_CUSTOM_ALC=my_alc.

    File and FILE pointer APIs are also disabled (same effect as YYJSON_DISABLE_FILE). This macro cannot be used together with YYJSON_DISABLE_FAST_FP_CONV.

    Intended for freestanding targets such as WebAssembly without a libc sysroot.

    YYJSON_READER_DEPTH_LIMIT

    Define as a positive integer to set the maximum allowed nesting depth for JSON arrays and objects.

    When the parser encounters a container whose depth exceeds this value, it stops and returns the error code YYJSON_READ_ERROR_DEPTH.

    The default value is 0, which means unlimited depth is supported. The parser does not use stack recursion, so nesting depth is only bounded by available memory.

    YYJSON_WRITER_DEPTH_LIMIT

    Define as a positive integer to set the maximum allowed nesting depth for JSON arrays and objects when writing.

    When a document exceeds this depth, writing stops and returns YYJSON_WRITE_ERROR_DEPTH.

    The default value is 0, which means unlimited depth is supported. The writer does not use stack recursion, so nesting depth is only bounded by available memory.

    YYJSON_EXPORTS

    Define as 1 to export symbols when building the library as a Windows DLL.

    YYJSON_IMPORTS

    Define as 1 to import symbols when using the library as a Windows DLL.