View on GitHub

VulkanSceneGraphPrototype

Prototype of the VulkanSceneGraph/VkSceneGraph

Build and Install instructions index


Prerequisites

The above dependency versions are known to work so they’ve been set as the current minimum, it may be possible to build against older versions. If you find success with older versions let us know and we can update the version info.


Quick build instructions for Unix from the command line

Command line instructions for default build of static library (.a/.lib) in source:

git clone https://github.com/vsg-dev/VulkanSceneGraphPrototype.git
cd VulkanSceneGraphPrototype
cmake .
make -j 8
make install

Command line instructions for building shared library (.so/.lib + .dll) in out of source:

git clone https://github.com/vsg-dev/VulkanSceneGraphPrototype.git
mkdir vsg-shared-build
cd vsg-shared-build
cmake ../VulkanSceneGraphPrototype -DBUILD_SHARED_LIBS=ON
make -j 8
make install

Quick build instructions for Windows using Visual Studio 2017

Command line instructions for default build of static library (.lib) in source:

git clone https://github.com/vsg-dev/VulkanSceneGraphPrototype.git
cd VulkanSceneGraphPrototype
cmake . -G "Visual Studio 15 2017 Win64"

After running cmake open the generated VSG.sln file and build the All target. Once built you can run the install target. If you are using the default cmake install path (in Program Files folder), ensure you have started Visual Studio as administrator otherwise the install will fail.

More detailed Windows platform instructions can be found below.


Quick build instructions for Android

Requires Android NDK 18 and CMake 3.13 (lower CMake versions may work but have not been tested).

cmake ./ \
-DCMAKE_BUILD_TYPE="Debug" \
-DCMAKE_SYSTEM_NAME="Android" \
-DCMAKE_SYSTEM_VERSION=24 \
-DCMAKE_ANDROID_STL_TYPE="c++_static" \
-DCMAKE_ANDROID_ARCH_ABI=armeabi-v7a \
-DCMAKE_ANDROID_NDK=/location/of/Android/sdk/ndk-bundle \
-DCMAKE_INSTALL_PREFIX=/usr/local/android

make -j 8
make install

More detailed Android platform instructions can be found below.


Quick build instructions for macOS using Xcode 9

Command line instructions for default build of static library (.lib) in source:

git clone https://github.com/vsg-dev/VulkanSceneGraphPrototype.git
cd VulkanSceneGraphPrototype
cmake . -G "Xcode"

After running cmake open the generated VSG.xcodeproj file and build the All target. Once built you can run the install target. Please note that for release builds you currently need to use the Archive option in xcode. This will rebuild every time so you can just select the install target and run Archive which will also build the All target.


Available build targets

Once you have generated the build system using cmake as above, you can list the available make options using:

make help

This lists the options:

... all (the default if no target is provided)
... clean
... depend
... install/strip
... install/local
... rebuild_cache
... clobber
... install
... docs
... uninstall
... build_all_h
... list_install_components
... cppcheck
... clang-format
... edit_cache
... vsg

Most of these are standard options which you can look up in CMake and make documentation, the following are ones we’ve added so require explanation:

# remove all files not part of the git repository - including all temporary CMake and build files.
make clobber

# run cppcheck on headers & source to generate a static analysis
make cppcheck

# run clang-format on headers & source to format to style specified by .clang-format specification
make clang-format

# generate the include/vsg/all.h from all the files that match include/vsg/*/*.h
make build_all_h

Using the VSG within your own projects

The project is currently a prototype that is undergoing continuous development so it isn’t recommend to use as base for long term software development. At this point it’s available for developers who want to test the bleeding edge and provide feedback on it’s fitness for purpose. Following instructions assume your project uses CMake, which at this early stage in the project is the recommended route when using the VSG.

To assist with setting up software to work with the VSG when you install the library a CMake package configuration file will be installed in the lib/cmake/vsg directory. Within your CMake CMakeLists.txt script to find the VSG related dependencies you’ll need to add:

find_package(vsg)

To select C++17 compilation you’ll need:

set_property(TARGET mytargetname PROPERTY CXX_STANDARD 17)

To link your lib/application to required dependencies you’ll need:

target_link_libraries(mytargetname vsg::vsg)

This will tell CMake to set up all the appropriate include paths, libs and any definitions (such as the VSG_SHARED_LIBRARY #define that is required under Windows with shared library builds to select the correct declspec().)

For example, a bare minimum CMakeLists.txt file to compile a single file application would be:

cmake_minimum_required(VERSION 3.7)
find_package(vsg REQUIRED)
add_executable(myapp "myapp.cpp")
set_property(TARGET myapp PROPERTY CXX_STANDARD 17)
target_link_libraries(myapp vsg::vsg)

Detailed instructions for setting up your environment and building for Microsoft Windows

VSG currently has two main dependancies, the Vulkan SDK itself and for now GLFW for window creation. LunarG provides a convient installer for the Vulkan SDK and runtime on Windows.

Vulkan Downloads

From there download and install the Vulkan SDK (1.1 or later) and the Vulkan runtime. Once installed we need to let CMake know where to find the Vulkan SDK. Both VSG and GLFW use the VULKAN_SDK environment variable to find the Vulkan SDK so go ahead and add it.

VULKAN_SDK = C:\VulkanSDK\1.1.85.0

So now we have the Vulkan SDK installed and findable by CMake so we can go ahead and build VSG. Below are simple instructions for downloading the VSG source code, generating a Visual Studio project using CMake and finally building and installing VSG onto your system.

git clone https://github.com/vsg-dev/VulkanSceneGraphPrototype.git
cd VulkanSceneGraphPrototype
cmake . -G "Visual Studio 15 2017 Win64"

After running CMake open the generated VSG.sln file and build the All target. Once built you can run the install target. If you are using the default CMake install path (in Program Files folder), ensure you have started Visual Studio as administrator otherwise the install will fail.

It’s recommended at this point that you add the VSG install path to you CMAKE_PREFIX_PATH, this will allow other CMake projects, like the vsgExamples project to find your VSG installation. CMAKE_PREFIX_PATH can be set as an environment variable on you system.

CMAKE_PREFIX_PATH = C:\Program Files\VSG

Detailed instructions for setting up your environment and building for Android

This guide is to build VSG for Android, these steps have been completed on macOS but should be almost identical on Linux and similar on Windows. Inorder to build VSG for Android you’ll need the following installed on your machine.

Android NDK 18
CMake 3.13

The easiest way to get the Android NDK installed is via Android Studio. Follow the link below to download and install it for your OS.

Android Studio

If you got to the ‘SDK Manager’ ensure you have at least Android API level 24 installed, then go to the ‘SDK Tools’ tab and check the ‘NDK’ option. Once done click apply and Android Studio should download and install these components for you.

If you already have Android Studio and or the NDK installed. Still go to the ‘SDK Manager’ and see if you need to update your NDK to version 18.

Take note of the ‘Android SDK Location’ as you’ll need it when running CMake to generate our Android make files.

So now we have the Android NDK installed lets go ahead and fetch the VSG source then use CMake to generate the make files.

git clone https://github.com/vsg-dev/VulkanSceneGraphPrototype.git
cd VulkanSceneGraphPrototype
cmake ./ \
-DCMAKE_BUILD_TYPE="Debug" \
-DCMAKE_SYSTEM_NAME="Android" \
-DCMAKE_SYSTEM_VERSION=24 \
-DCMAKE_ANDROID_STL_TYPE="c++_static" \
-DCMAKE_ANDROID_ARCH_ABI=armeabi-v7a \
-DCMAKE_ANDROID_NDK=/location/of/Android/sdk/ndk-bundle \
-DCMAKE_INSTALL_PREFIX=/usr/local/android

Make sure you change the -DCMAKE_ANDROID_NDK path to the path of your NDK, typically this is the ‘Android SDK Location’/ndk-bundle. Also note the -DCMAKE_INSTALL_PREFIX. This is where the VSG library and header will be installed. It’s useful to change this from the default to seperate your Android version from your native OS version. Depending where you put it you may need to manually create the top level folder first depending on permissions.

Now we’ve generated the make files we can simply run

make -j 8
make install

That’s it, you’ve built VSG for Android and installed the required headers and library files onto your machine ready to use with you project or the Android vsgExamples.