yyjson 0.5.0
A high performance C JSON library.
Build And Test

Table of Contents

  • Import Manually
  • Use CMake to build library
  • Use CMake as a dependency
  • Use CMake to generate project
  • Testing With CMake and CTest
  • Compile-time Options

Import Manually

yyjson aims to provide a cross-platform JSON library, so it was written in ANSI C (actually C99, but compatible with strict C89). You can copy yyjson.h and yyjson.c to your project and start using it without any configuration.

If you get a compile error, please report a bug.

Use CMake to build library

Clone the repository and create build directory:

git clone https://github.com/ibireme/yyjson.git
mkdir build
cd build

Build static library:

cmake ..
cmake --build .

Build shared library:

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

Supported CMake options:

  • -DYYJSON_BUILD_TESTS=ON Build all tests.
  • -DYYJSON_BUILD_FUZZER=ON Build fuzzer with LibFuzzing.
  • -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_SANITIZE=ON Enable sanitizer for tests.
  • -DYYJSON_ENABLE_FASTMATH=ON Enable fast-math for tests.
  • -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_FAST_FP_CONV=ON Disable fast floating-pointer conversion.
  • -DYYJSON_DISABLE_NON_STANDARD=ON Disable non-standard JSON support at compile-time.

See compile-time options for details.

Use CMake as a dependency

You may add the yyjson subdirectory to your CMakeFile.txt, and link it to your target:

add_subdirectory(vendor/yyjson)
target_link_libraries(your_target yyjson)

You may also add some build options for yyjson library:

set(YYJSON_DISABLE_NON_STANDARD ON CACHE INTERNAL "")
add_subdirectory(vendor/yyjson)
target_link_libraries(your_target yyjson)

Use CMake to generate project

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

# 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
# Other 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

Testing With CMake and CTest

Build and run all tests.

cmake .. -DYYJSON_BUILD_TESTS=ON
cmake --build .
ctest --output-on-failure

Build and run tests with valgrind memory checker, you must have valgrind installed.

cmake .. -DYYJSON_BUILD_TESTS=ON -DYYJSON_ENABLE_VALGRIND=ON
cmake --build .
ctest --output-on-failure

Build and run tests with sanitizer, compiler should be gcc or clang.

cmake .. -DYYJSON_BUILD_TESTS=ON -DYYJSON_ENABLE_SANITIZE=ON
cmake --build .
ctest --output-on-failure

Build and run code coverage, compiler should be gcc.

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/yyjson.dir/src -o cov.info
genhtml cov.info -o ./cov_report

Build and run fuzz test with LibFuzzer, compiler should be LLVM Clang, Apple Clang or gcc is not supported.

cmake .. -DYYJSON_BUILD_FUZZER=ON -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake --build .
./fuzzer -dict=fuzzer.dict ./corpus

Compile-time Options

yyjson supports some compile-time options, you can define these macros as 1 to disable some features at compile-time.

YYJSON_DISABLE_READER
Define it as 1 to disable the JSON reader.
This will disable these functions at compile-time:

yyjson_api yyjson_doc * yyjson_read_file(const char *path, yyjson_read_flag flg, const yyjson_alc *alc, yyjson_read_err *err)
yyjson_api yyjson_doc * yyjson_read_opts(char *dat, size_t len, yyjson_read_flag flg, const yyjson_alc *alc, yyjson_read_err *err)
yyjson_api_inline yyjson_doc * yyjson_read(const char *dat, size_t len, yyjson_read_flag flg)
Definition: yyjson.h:738

This will reduce the binary size by about 60%.

YYJSON_DISABLE_WRITER
Define as 1 to disable JSON writer if you don't need to serialize JSON.

This will disable these functions at compile-time:

yyjson_api_inline char * yyjson_val_write(const yyjson_val *val, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1114
yyjson_api bool yyjson_write_file(const char *path, const yyjson_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)
yyjson_api char * yyjson_write_opts(const yyjson_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, size_t *len, yyjson_write_err *err)
yyjson_api_inline char * yyjson_mut_val_write(const yyjson_mut_val *val, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1192
yyjson_api bool yyjson_val_write_file(const char *path, const yyjson_val *val, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)
yyjson_api char * yyjson_val_write_opts(const yyjson_val *val, yyjson_write_flag flg, const yyjson_alc *alc, size_t *len, yyjson_write_err *err)
yyjson_api char * yyjson_mut_write_opts(const yyjson_mut_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, size_t *len, yyjson_write_err *err)
yyjson_api_inline char * yyjson_mut_write(const yyjson_mut_doc *doc, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1033
yyjson_api char * yyjson_mut_val_write_opts(const yyjson_mut_val *val, yyjson_write_flag flg, const yyjson_alc *alc, size_t *len, yyjson_write_err *err)
yyjson_api_inline char * yyjson_write(const yyjson_doc *doc, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:953
yyjson_api bool yyjson_mut_write_file(const char *path, const yyjson_mut_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)
yyjson_api bool yyjson_mut_val_write_file(const char *path, const yyjson_mut_val *val, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)

This will reduce the binary size by about 30%.

YYJSON_DISABLE_FAST_FP_CONV
Define as 1 to disable the fast floating-point number conversion in yyjson, and use libc's strtod/snprintf instead.

This will reduce binary size by about 30%, but significantly slow down floating-point reading and writing speed.

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

  • Reading and writing inf/nan literal, such as 'NaN', '-Infinity'.
  • Single line and multiple line comments.
  • Single trailing comma at the end of an object or array.
  • Invalid unicode in string value.

This will also invalidate these run-time options:

  • YYJSON_READ_ALLOW_INF_AND_NAN
  • YYJSON_READ_ALLOW_COMMENTS
  • YYJSON_READ_ALLOW_TRAILING_COMMAS
  • YYJSON_READ_ALLOW_INVALID_UNICODE
  • YYJSON_WRITE_ALLOW_INF_AND_NAN
  • YYJSON_WRITE_ALLOW_INVALID_UNICODE

This will reduce binary size by about 10%, and increase performance slightly.

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

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