Installing vgl

This page covers every way to get vgl into your own project: the vcpkg port and the Conan 2 recipe kept in the repository, the GitHub release archives planned for version 1, a cmake --install from a source build, and building the source tree as part of your project with add_subdirectory or FetchContent. It then describes what you get: the CMake package and its targets, their dependencies, the pkg-config modules, and what to do about DLLs on Windows. For the build itself and every CMake option, see Building vgl.

vgl 1.0 is released as GitHub release archives, a vcpkg port and a Conan recipe. Until the port is in the vcpkg registry and the recipe in ConanCenter, use them from the repository, as described below.

Which form to choose

Form	Where	What it contains
vcpkg overlay port	`packaging/vcpkg/ports/vgl`	Features `defaults`, `gl` and `d3d11` (Windows) by default, plus `http` and `ogre`
Conan 2 recipe	`packaging/conan`	Options `with_defaults`, `with_gl` and `with_d3d11` (Windows) on by default, plus `with_http`. No Ogre backend, since ConanCenter has no Ogre 14
Release archives	GitHub releases, built by `.github/workflows/release.yml`	Windows x64, Linux x64 and macOS (universal), each shared and static: the core, the defaults module without the HTTP reader, the OpenGL backend, and the Direct3D 11 backend on Windows
`cmake --install`	Your own build	Whatever you configured
Source tree in your build	`add_subdirectory` or `FetchContent`	Whatever you configure, built with your project

All the installed forms come from the same install rules (cmake/vgl_install.cmake) and are checked by the same consumer project, tests/install. The details of each form are in packaging/README.md.

The baker, vgl-bake, is not part of any package. It is a tool for preparing data, built from source with VGL_BUILD_BAKER (Baker).

vcpkg

Until the port is in the vcpkg registry, use it from a clone of vgl as an overlay port. The port takes Zstandard, stb and (for http) curl from their own vcpkg ports, so nothing is downloaded during vgl's build.

Classic mode:

vcpkg install vgl --overlay-ports=<vgl>/packaging/vcpkg/ports
vcpkg install "vgl[http]" --overlay-ports=<vgl>/packaging/vcpkg/ports

Manifest mode: list vgl in your project's vcpkg.json, and point vcpkg-configuration.json at the overlay:

{
  "dependencies": [
    { "name": "vgl", "features": ["http"] }
  ]
}

{
  "overlay-ports": ["<vgl>/packaging/vcpkg/ports"]
}

Then configure your project with vcpkg's toolchain file:

cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg>/scripts/buildsystems/vcpkg.cmake

Feature	Default	Adds
`defaults`	yes	`vgl::defaults`: thread pool, file reader, disk cache
`gl`	yes	`vgl::gl`, the OpenGL 3.3 / OpenGL ES 3.0 backend
`d3d11`	yes, on Windows (not UWP)	`vgl::d3d11`, the Direct3D 11 backend
`http`	no	The HTTP reader in the defaults module, on vcpkg's curl (turns on `defaults`)
`ogre`	no	`vgl::ogre`, the Ogre 14 backend, a static library, on vcpkg's `ogre` port

Notes:

Static or shared follows the triplet: x64-windows builds DLLs, x64-windows-static, x64-linux and arm64-osx build static libraries.
To build the ogre feature, vcpkg's ogre port must provide Ogre 14: vgl looks for find_package(OGRE 14 CONFIG) and, inside vcpkg, never downloads Ogre itself. vcpkg's ogre port is at 14.5.2 at the time of writing; the ogre feature has not been tested yet.
To test the port against a working tree instead of a release, set VGL_PORT_SOURCE_DIR (see packaging/README.md). Until a tag exists, the port's vcpkg_from_github has no hash for a release archive, so this is the way to install it today:
```
export VGL_PORT_SOURCE_DIR=<vgl> VCPKG_KEEP_ENV_VARS=VGL_PORT_SOURCE_DIR
vcpkg install "vgl[http]" --no-binarycaching --overlay-ports=<vgl>/packaging/vcpkg/ports
```

Conan

The recipe builds the working tree it sits in: it reads the version from CMakeLists.txt and exports the sources from the repository root. It needs Conan 2 and C++20. Create the package in your local cache:

conan create <vgl>/packaging/conan -s compiler.cppstd=20
conan create <vgl>/packaging/conan -s compiler.cppstd=20 -o "vgl/*:with_http=True"
conan create <vgl>/packaging/conan -s compiler.cppstd=20 -o "vgl/*:shared=True"

conan create also runs the consumer project (tests/install) as its test package. Then require it from your project, for example with a conanfile.txt:

[requires]
vgl/1.0.0

[generators]
CMakeDeps
CMakeToolchain

[layout]
cmake_layout

conan install . --build=missing -s compiler.cppstd=20
cmake --preset conan-release
cmake --build --preset conan-release

Option	Default	Meaning
`shared`	`False`	Shared libraries; the package then defines `VGL_SHARED` for consumers
`fPIC`	`True`	Position-independent code (not on Windows)
`with_defaults`	`True`	`vgl::defaults`
`with_http`	`False`	The HTTP reader, on ConanCenter's `libcurl`. Needs `with_defaults`
`with_gl`	`True`	`vgl::gl`
`with_d3d11`	`True`	`vgl::d3d11` (Windows only; the option does not exist elsewhere)

The Conan package describes itself through package_info rather than vgl's own CMake files: the CMake file name is vgl and the targets have the same names (vgl::vgl, vgl::defaults, vgl::gl, vgl::d3d11), so find_package(vgl) works the same. vgl's own .pc files are not in the package; use Conan's PkgConfigDeps generator, which writes vgl, vgl-defaults and vgl-gl modules from the same description. There is no vgl::ogre in the Conan package.

Release archives

Each tag v<version> builds archives with release.yml into a GitHub release, with SHA256SUMS; the first is vgl 1.0.0. The archives are:

Archive	Built with
`vgl-<version>-windows-x64-shared.zip`, `vgl-<version>-windows-x64-static.zip`	`windows-msvc-shared`, `windows-msvc-static`
`vgl-<version>-linux-x64-shared.tar.gz`, `vgl-<version>-linux-x64-static.tar.gz`	`linux-gcc-shared`, `linux-gcc-static`
`vgl-<version>-macos-shared.tar.gz`, `vgl-<version>-macos-static.tar.gz`	`macos-clang-shared`, `macos-clang-static`, universal (arm64 and x86_64), deployment target 11.0

Each is an install prefix built in Release with Zstandard compiled in and without the HTTP reader (which would need libcurl), so it depends on nothing but the system. To use one, point CMAKE_PREFIX_PATH at the extracted folder (or PKG_CONFIG_PATH at its lib/pkgconfig).

A static library from MSVC links only into Release builds, since MSVC does not mix the Debug and Release runtimes. For Debug builds on Windows, use the shared archive, vcpkg or Conan.

Installing from a source build

Any configured build tree installs with cmake --install. VGL_INSTALL is on by default when vgl is the top-level project.

cmake --preset linux-gcc-shared
cmake --build --preset linux-gcc-shared-release
cmake --install build/linux-gcc-shared --config Release --prefix /opt/vgl

On Windows:

cmake --preset windows-msvc-shared
cmake --build --preset windows-msvc-shared-release
cmake --install build/windows-msvc-shared --config Release --prefix C:\vgl

Without --prefix, a preset build installs to install/<preset> in the source tree. For a self-contained install, configure with -DVGL_ZSTD_PROVIDER=BUNDLED (and leave VGL_DEFAULTS_HTTP off, or make sure the consumer has libcurl), as the release archives do.

The install tree:

Path	Contents
`include/vgl/`	The core's C headers and C++ wrapper, the generated `version.h`, and the headers of each backend built (`gl.h`, `gl.hpp`, `d3d11.h`, `d3d11.hpp`, `ogre.hpp`)
`lib/` (or `lib64/`, per `GNUInstallDirs`)	`vgl`, `vgl-defaults`, `vgl-gl`, `vgl-d3d11`, `vgl-ogre` libraries (import libraries on Windows)
`bin/`	DLLs on Windows, and `vgl-bake` if the baker was built
`lib/cmake/vgl/`	`vgl-config.cmake`, `vgl-config-version.cmake`, `vgl-targets*.cmake`
`lib/pkgconfig/`	`vgl.pc`, and `vgl-defaults.pc` and `vgl-gl.pc` when those are built
`share/doc/vgl/`	`LICENSE`, `LICENSE.stb`, `LICENSE.zstd` when Zstandard was compiled in, and `LICENSE.curl` when a downloaded curl is linked into a shared defaults module

Using the CMake package

cmake_minimum_required(VERSION 3.24)
project(my_app LANGUAGES C CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(vgl 0.1 REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE vgl::vgl vgl::defaults vgl::gl)

Configure with -DCMAKE_PREFIX_PATH=<install prefix>, or a package manager's toolchain.

The package version is compatible within a major version (SameMajorVersion): find_package(vgl 1.0) accepts any 1.x from 1.0 on, and rejects 2.0. (Before 1.0 it was SameMinorVersion.)

Targets

Target	Library	Present when	Links	Notes
`vgl::vgl`	`vgl`	Always	Zstandard, if vgl was built against an installed one and is static	The core: the C API (`vgl/vgl.h`) and the header-only C++ wrapper (`vgl/vgl.hpp`). Carries `VGL_SHARED` when shared
`vgl::defaults`	`vgl-defaults`	`VGL_BUILD_DEFAULTS`	`vgl::vgl`; `Threads::Threads` and (with the HTTP reader) `CURL::libcurl` when static	Thread pool, file reader, disk cache, HTTP reader (Defaults module)
`vgl::gl`	`vgl-gl`	`VGL_BACKEND_GL`	`vgl::vgl`	No OpenGL library: the host passes a function loader (OpenGL backend)
`vgl::d3d11`	`vgl-d3d11`	`VGL_BACKEND_D3D11` (Windows)	`vgl::vgl`, `d3d11`	Shaders precompiled into the library (Direct3D 11 backend)
`vgl::ogre`	`vgl-ogre`	`VGL_BACKEND_OGRE`, built against an installed Ogre 14	`vgl::vgl`, Ogre's `OgreMain`	Always static (Ogre backend)

The package's vgl-config.cmake finds what the installed targets need, with find_dependency:

zstd (CONFIG), for a static vgl linked against an installed Zstandard;
Threads, for a static vgl::defaults;
CURL, for a static vgl::defaults with the HTTP reader;
OGRE 14 (CONFIG), when vgl::ogre is installed.

A shared vgl carries its dependencies inside its binaries, so its consumers need none of these. vgl::ogre is installed only when vgl was built against an installed Ogre: a downloaded Ogre lives in vgl's build tree and is not installed, so the package could not name it.

Check which optional targets you got with if(TARGET vgl::gl), as the consumer project does.

Windows DLLs

With a shared vgl on Windows, vgl.dll and the DLLs of the other targets are in the install's bin/, and your executable needs them next to it (or on PATH). CMake can copy them after each build:

get_target_property(vgl_type vgl::vgl TYPE)
if(WIN32 AND vgl_type STREQUAL "SHARED_LIBRARY")
    add_custom_command(TARGET my_app POST_BUILD
        COMMAND "${CMAKE_COMMAND}" -E copy_if_different
                $<TARGET_RUNTIME_DLLS:my_app> $<TARGET_FILE_DIR:my_app>
        COMMAND_EXPAND_LISTS)
endif()

This is exactly what tests/install does. With vcpkg's toolchain, vcpkg copies the DLLs itself (VCPKG_APPLOCAL_DEPS). A downloaded curl is linked statically into vgl-defaults.dll, so there is no curl DLL to copy for a source build.

The consumer project as a reference

tests/install/CMakeLists.txt is a complete consumer: it finds the package, builds tests/api_c.c (C99) and tests/api_cpp.cpp (C++20) against it, checks that the expected targets exist, copies DLLs on Windows and runs both as tests. You can run it against any install to check it:

cmake -S <vgl>/tests/install -B build-consumer -DCMAKE_PREFIX_PATH=/opt/vgl
cmake --build build-consumer --config Release
ctest --test-dir build-consumer -C Release --output-on-failure

VGL_EXPECTED_TARGETS lists the targets it requires besides vgl::vgl. The default is vgl::defaults;vgl::gl, plus vgl::d3d11 on Windows; pass your own list for a package built with fewer (an empty one for the core only).

Using pkg-config

Except on Windows, which has no pkg-config convention, the install has pkg-config modules for C projects and other build systems:

Module	Library	Requires
`vgl`	`-lvgl`	`Requires.private: libzstd` when built against an installed Zstandard; `Libs.private: -lstdc++ -lm` with GCC or Clang on Linux (`-lm` on Android)
`vgl-defaults`	`-lvgl-defaults`	`vgl`; `Requires.private: libcurl` with the HTTP reader; `Libs.private: -pthread` on Linux
`vgl-gl`	`-lvgl-gl`	`vgl`

There are no modules for vgl::d3d11 and vgl::ogre. The prefix is computed from the .pc file's location, so an install can be moved. A shared build adds -DVGL_SHARED to the Cflags.

export PKG_CONFIG_PATH=/opt/vgl/lib/pkgconfig
pkg-config --validate vgl

# Shared vgl:
cc main.c $(pkg-config --cflags --libs vgl-defaults vgl-gl) -o my_app

# Static vgl: --static adds the C++ runtime and the private dependencies.
cc main.c $(pkg-config --static --cflags --libs vgl-defaults vgl-gl) -o my_app

CI checks the installed vgl.pc this way, building tests/api_c.c with pkg-config --static --cflags --libs vgl.

Using the source tree directly

vgl's CMake project can be part of yours. When vgl is not the top-level project, its tests, samples and install rules default to off, so only the libraries are built, and the same vgl:: targets are available as aliases. The defaults module and the OpenGL backend (and Direct3D 11 on Windows) are on by default; set options before adding vgl to change that.

With a copy or submodule of vgl in your tree:

set(VGL_DEFAULTS_HTTP ON)  # optional: options take normal variables set before vgl is added
add_subdirectory(third_party/vgl)

target_link_libraries(my_app PRIVATE vgl::vgl vgl::defaults vgl::gl)

With FetchContent:

include(FetchContent)
FetchContent_Declare(vgl
    GIT_REPOSITORY https://github.com/3dgep/vgl.git
    GIT_TAG        main          # pin a commit until releases are tagged
    GIT_SUBMODULES "")           # vgl's only submodule is its wiki, which the build does not need
FetchContent_MakeAvailable(vgl)

target_link_libraries(my_app PRIVATE vgl::vgl vgl::defaults vgl::gl)

Notes:

vgl needs CMake 3.24 or later and enables the C and C++ languages itself.
vgl follows your project's BUILD_SHARED_LIBS. A top-level vgl build gathers its binaries in bin/, but an embedded one does not, so with shared libraries on Windows copy the DLLs as shown in Windows DLLs.
vgl's own dependencies are found or downloaded as in a standalone build (Building vgl). Set VGL_FETCH_DEPENDENCIES to OFF if your build must not download anything.
The vgl target names and internal helper targets (vgl_objects, vgl_zstd, vgl_stb_objects and so on) are global in your build; avoid defining targets of your own with a vgl_ prefix.

Navigation Menu

Repository navigation

Installing vgl

Installing vgl

Which form to choose

vcpkg

Conan

Release archives

Installing from a source build

Using the CMake package

Targets

Windows DLLs

The consumer project as a reference

Using pkg-config

Using the source tree directly

See also

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally