This repo holds third-party libraries used in VGG projects.
All libraries should adhere to the following three rules:
- Inclusion Rule: Source-code only, no binaries, no submodules, no fetching scripts. Just code.
- If the library is header-only, then a pre-built single-header file is prefered.
- Otherwise the whole library directory is included.
- Depedency Rule: Dependencies of a library should be flattened out as other libraries in this repo.
- Patching Rule: The original code lies in the
upstream
directory, with modifications if neccessary. The modifications to the original code are kept in thepatches
directory.
Name | License | Upstream | Patched | Category | Inclusion Type |
---|---|---|---|---|---|
argparse | MIT | 557948 | No | common | Single file |
boost | Boost | 1.80.0 | No | common | Directory (partial) |
rxcpp | Apache-2.0 | 4.1.1 | No | common | Directory (partial) |
json | MIT | 3.11.2 | No | json | Single file |
valijson | BSD | feature-vgg | No | json | Single file |
picosha2 | MIT | 7bfa26 | No | hashing | Single file |
sdefl/sinfl | MIT/Public Domain | 71382a | Yes | compression | Single file(s) |
zlib | ZLIB | 1.3.1 | Yes | compression | Directory |
zstd | BSD/GPLv2 | 1.5.2 | No | compression | Directory |
zip | UNLICENSE | 0.2.6 | No | compression | Directory |
libpng | PNG Reference Library License | 1.6.38 | No | image | Directory |
libjpeg-turbo | Mixed | 2.1.4 | Yes | image | Directory |
libwebp | BSD | 1.2.4 | No | image | Directory |
nanobind | BSD-3-Clause | 1.6.2 | No | binding | Directory |
glm | Mixed | 1.0.1 | No | algorithm | Directory |
yoga | MIT | efd27ef | Yes | algorithm | Directory |
rapidfuzz-cpp | MIT | 2.0.0 | No | algorithm | Directory |
bezier | MIT | 0.2.1 | NO | algorithm | Single file |
If you encounter compiling issues for boost, please refer to boost's README.
You could download its latest code copy here, or clone it using git
git clone https://github.com/verygoodgraphics/vgg_contrib.git
Put vgg_contrib
in your project where you can access it.
Pick a library and write cmake commands to use it. Please check out the full list in the usage summary section below.
#
# example 1: zlib
#
if(NOT VGG_CONTRIB_ZLIB_INCLUDE OR VGG_CONTRIB_ZLIB_INCLUDE STREQUAL "")
add_subdirectory(path_to_your/vgg_contrib/zlib)
endif()
target_include_directories(your_target PRIVATE ${VGG_CONTRIB_ZLIB_INCLUDE} ${VGG_CONTRIB_ZLIB_CONF_INCLUDE})
target_link_libraries(your_target zlib)
#
# example 2: json
#
if (NOT VGG_CONTRIB_JSON_INCLUDE OR VGG_CONTRIB_JSON_INCLUDE STREQUAL "")
add_subdirectory(path_to_your/vgg_contrib/zlib)
endif()
target_include_directories(your_target PRIVATE ${VGG_CONTRIB_JSON_INCLUDE})
#
# example 3: nanobind
#
if (NOT VGG_CONTRIB_NANOBIND_INCLUDE OR VGG_CONTRIB_NANOBIND_INCLUDE STREQUAL "")
add_subdirectory(path_to_your/vgg_contrib/nanobind)
endif()
nanobind_add_module(your_target ${YOUR_TARGET_SRCS}) # use nanobind's macro to add target
target_include_directories(your_target PRIVATE ${VGG_CONTRIB_NANOBIND_INCLUDE}) # this is totally optional
If you put vgg_contrib
outside of your current CMakeLists.txt directory, you should give explicitly the binary directory like this
add_subdirectory(path_to_your/vgg_contrib/zlib ${CMAKE_BINARY_DIR}/vgg_contrib/zlib)
Name | Include Path | Link Target |
---|---|---|
argparse | VGG_CONTRIB_ARGPARSE_INCLUDE |
N/A |
boost | VGG_CONTRIB_BOOST_INCLUDE |
static libs, see boost's README |
rxcpp | VGG_CONTRIB_RXCPP_INCLUDE |
N/A |
json | VGG_CONTRIB_JSON_INCLUDE |
N/A |
valijson | VGG_CONTRIB_VALIJSON_INCLUDE |
N/A |
picosha2 | VGG_CONTRIB_PICOSHA2_INCLUDE |
N/A |
sdefl/sinfl | VGG_CONTRIB_SDEFL_INCLUDE |
N/A |
zlib | VGG_CONTRIB_ZLIB_INCLUDE VGG_CONTRIB_ZLIB_CONF_INCLUDE |
shared: zlib , static: zlibstatic |
zstd | VGG_CONTRIB_ZSTD_INCLUDE |
shared: libzstd_shared , static: libzstd_static |
zip | VGG_CONTRIB_ZIP_INCLUDE |
static: zip |
libpng | VGG_CONTRIB_LIBPNG_INCLUDE VGG_CONTRIB_LIBPNG_CONF_INCLUDE |
shared: png , static: png_static |
libjpeg-turbo | VGG_CONTRIB_LIBJPG_INCLUDE VGG_CONTRIB_LIBJPG_CONF_INCLUDE |
shared: jpeg , static: jpeg-static |
libwebp | VGG_CONTRIB_LIBWEBP_INCLUDE VGG_CONTRIB_LIBWEBP_CONF_INCLUDE |
static: webp |
nanobind | VGG_CONTRIB_NANOBIND_INCLUDE |
N/A (implicitly added by nanobind_add_module ) |
glm | VGG_CONTRIB_GLM_INCLUDE |
N/A |
yoga | VGG_CONTRIB_YOGA_INCLUDE |
static: yogacore |
rapidfuzz-cpp | VGG_CONTRIB_RAPIDFUZZCPP_INCLUDE |
N/A |
bezier | VGG_CONTRIB_BEZIER_INCLUDE |
N/A |
In order to add another library, please keep the following directory structure
vgg_contrib/
└── new_library/
├── CMakeLists.txt
├── patches/
└── upstream/
where upstream
is for original library root, and pathces
is for custom modifications for upstream. A CMakeLists.txt
sample is as follows
cmake_minimum_required(VERSION 3.7)
project(vgg_contrib_new_library)
add_subdirectory(upstream) # only if this library has CMakeLists.txt, otherwise you have to write your own
set(VGG_CONTRIB_NEW_LIBRARY_INCLUDE ${CMAKE_CURRENT_SOURCE_DIR}/upstream/ CACHE PATH "" FORCE) # setup include path properly
mark_as_advanced(VGG_CONTRIB_NEW_LIBRARY_INCLUDE)
And don't forget to update README.md
in the root directory.
When adding third-party source code in upstream folder, it is highly possible that some files are not added to the git version control because of rules in .gitignore
in its directories. To list all files that is not added, use the command to find out
git clean -fdnx
and decide whether or not to forcibly add those missing files using git add -f
. Look out!
Sometimes it is neccessary to patch the library source code to meet our needs, and it is a good practice to keep track of the changes in patch files. For example, if the upstream got updated, we could just re-patch the code effortlessly.
In this project, we assume all the code in upstream
directory is already patched so that we could use it at ease.
Take the sdefl
library for example. Say we have made changes to upstream/sinfl.h
in place, and the original code have been copied as the original
folder. We could use the following command to make a new patch
diff -ru original/ upstream/ > patches/00-patch.applied
If we update the sinfl.h
to the latest upstream version, un-patched, we could use the following command to re-patch this file
cd upstream/
patch -p1 < ../patches/00-patch.applied
If we need to use the original sinfl.h
, we use the following command to turn it back
cd upstream/
patch -R -p1 < ../patches/00-patch.applied