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.

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)

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