VGG Contrib

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 the patches directory.

Library List

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.

How to use

1. Get vgg_contrib

You could download its latest code copy here, or clone it using git

git clone https://github.com/verygoodgraphics/vgg_contrib.git

2. Put it in the right place

Put vgg_contrib in your project where you can access it.

3. Choose any library you'd like to use

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)

A. Library usage summary

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

How to contribute

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.

Contribution Tip 1: Make sure to add all files

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!

Contribution Tip 2: About patching

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.

How to make a patch

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

How to apply a patch

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

How to revert a patch

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