This page provides information on how to consume the Wisdom library in your project. It covers how to link the library, include headers, use CMake flags, and use the provided features.

CMake Usage

Finding the Library

Either you have downloaded the library as a package or you have built it from source, you can link it to your project using CMake.

The recommended way to link the library from releases or installation is to use the find_package command. This will automatically find the library and its dependencies.

The targets file is installed to the lib/cmake/Wisdom directory. You can add this directory to your CMake project using the CMAKE_PREFIX_PATH variable.

Linking the Library

Once you have found the library, you can link it to your project using the target_link_libraries command. The available targets are:

Core Library Targets

Target	Library	Headers	Module	Description
Main Library	`wis::wisdom`	`wis::wisdom-headers`	`wis::wisdom-module`	Main library target
Debug Extension	`wis::wisdom-debug`	`wis::wisdom-debug-headers`	`wis::wisdom-debug-module`	Debug extension with logging
Extended Allocation	`wis::wisdom-extended-allocation`	`wis::wisdom-extended-allocation-headers`	`wis::wisdom-extended-allocation-module`	Extended memory allocation features
Descriptor Buffer	`wis::wisdom-descriptor-buffer`	`wis::wisdom-descriptor-buffer-headers`	`wis::wisdom-descriptor-buffer-module`	Descriptor buffer extension
Raytracing	`wis::wisdom-raytracing`	`wis::wisdom-raytracing-headers`	`wis::wisdom-raytracing-module`	Raytracing support

Platform-Specific Targets

Target	Library	Headers	Module	Description
Platform (auto)	`wis::wisdom-platform`	`wis::wisdom-platform-headers`	`wis::wisdom-platform-module`	Auto-detected platform support
Windows	`wis::wisdom-windows`	`wis::wisdom-windows-headers`	`wis::wisdom-windows-module`	Windows-specific implementation + interop
X11	`wis::wisdom-x11`	`wis::wisdom-x11-headers`	`wis::wisdom-x11-module`	X11 windowing system support
Wayland	`wis::wisdom-wayland`	`wis::wisdom-wayland-headers`	`wis::wisdom-wayland-module`	Wayland compositor support
Linux	`wis::wisdom-linux`	`wis::wisdom-linux-headers`	`wis::wisdom-linux-module`	Linux platform interop support

Note: The C++ modules targets are experimental and not recommended for production use yet. To enable C++ modules in CMake, you need to set the WISDOM_EXPERIMENTAL_CPP_MODULES CMake flag to ON.

CMake Flags

The library provides several CMake flags that can be used to customize the build process.

WISDOM_LOG_LEVEL=debug/warn set the log level for the library, values are debug,trace,info,warn,error,critical log calls under current level are not compiled
WISDOM_USE_SYSTEM_DXC=OFF use system DXC compiler instead of the one provided with the library (default uses the one provided)
WISDOM_FORCE_VULKAN=OFF if set ON forces base types to be Vulkan, useful for debugging Vulkan extensions
WISDOM_BUILD_EXAMPLES=ON enable/disable example compilation
WISDOM_BUILD_TESTS=ON enable/disable test compilation
WISDOM_USE_FMT=ON/OFF use fmt instead of std::format (ON for Linux build for GCC<13 and Clang<16)
WISDOM_BUILD_DOCS=ON/OFF build documentation with Doxygen, default is dependent on wether you are building the library as a top project (ON) or as a part/dep for other (OFF)
WISDOM_BUILD_BINARIES=ON/OFF build static lib. If turned off, the header only version will be the main target.
WISDOM_EXPERIMENTAL_CPP_MODULES=ON/OFF enable C++20 modules support.

Most important flag is WISDOM_FORCE_VULKAN. There is the same #define in the library code. This flag allows you to force the library to use Vulkan types instead of DirectX 12 types. The library picks the best available API for the platform, but you can force it to use Vulkan types if you want to use the library with Vulkan. This is useful for debugging Vulkan extensions or if you want to use the library with Vulkan to further extend it.

NuGet Package

The nuget package is available at https://www.nuget.org/packages/Wisdom/. Its usage is a little different from the CMake usage. There is no need to link libraries manually, as the package will automatically link the library to your project. There is a property page that allows you to configure the library. Options are the same as CMake flags, but with a different naming convention.

Addendum

I would like to add more consumption examples, like conan or vcpkg, but I don't have enough experience with them. I would appreciate any contributions to improve that part.

Examples provides usage examples for the library.