lib/yyjson-0.12.0/doc/doxygen/html/building-and-testing.html
| yyjson 0.12.0
A high performance C JSON library. |
Loading...
Searching...
No Matches
Building and testing
There are several ways to integrate this library into your project: source code, package manager, and CMake.
This library aims to provide a cross-platform JSON library, so it is 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.
The library has been tested with gcc, clang, msvc, tcc compilers and x86, arm, ppc, riscv, s390x architectures in Github CI. Please report a bug if you encounter any compilation issues.
The library has all features enabled by default, but you can trim out some of them by adding compile-time options. For example, you can disable the JSON writer to reduce the binary size when you don't need serialization, or disable comments support to improve parsing performance. See Compile-time Options for details.
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.
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.
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 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_FORCE_32_BIT=ON Force 32-bit for tests (gcc/clang/icc).-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_UTILS=ON Disable JSON Pointer, JSON Patch and JSON Merge Patch.-DYYJSON_DISABLE_FAST_FP_CONV=ON Disable builtin fast floating-pointer 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.You can download and unzip yyjson to your project directory and link it in your CMakeLists.txt file:
set(YYJSON_DISABLE_NON_STANDARD ON CACHE INTERNAL "")
yyjson subdirectoryadd_subdirectory(vendor/yyjson)
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)
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()
target_link_libraries(your_target PRIVATE yyjson)
If you want to build or debug yyjson with another compiler or IDE, try these commands:
cmake -E make_directory build; cd build
cmake .. -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake .. -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc
cmake .. -DCMAKE_C_COMPILER=/usr/local/gcc-8.2/bin/gcc -DCMAKE_CXX_COMPILER=/usr/local/gcc-8.2/bin/g++
cmake .. -G "Visual Studio 16 2019" -A x64
cmake .. -G "Visual Studio 16 2019" -A Win32
cmake .. -G "Visual Studio 15 2017 Win64"
cmake .. -G Xcode
cmake .. -G Xcode -DCMAKE_SYSTEM_NAME=iOS
cmake .. -G Xcode -DYYJSON_BUILD_TESTS=ON
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/
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 (compiler should be gcc or clang):
cmake -E make_directory build; cd build
cmake .. -DYYJSON_BUILD_TESTS=ON -DYYJSON_ENABLE_SANITIZE=ON
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
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 ...
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.
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.
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.
Define as 1 to disable JSON Pointer, JSON Patch and JSON Merge Patch supports.
This disables functions with ptr or patch in their name.
It is recommended when these functions are not required.
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.
Define as 1 to disable non-standard JSON features support at compile-time:
This reduces binary size by about 10%, and slightly improves performance.
It is recommended when not dealing with non-standard JSON.
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:
yyjson_mut_val, the string's end may be accessed out of bounds, potentially causing a segmentation fault.Define as 1 to export symbols when building the library as a Windows DLL.
Define as 1 to import symbols when using the library as a Windows DLL.