Skip to content

verygoodgraphics/vgg_contrib

Repository files navigation

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