ML SDK VGF Library

The VGF Library is a library that encodes and decodes VGF files. The VGF format covers the entire model use cases. These use cases can be a combination of SPIR-V™ module binary data, their constants, and compute shaders. The library provides a suite of APIs and tools for working with VGF files. The library includes the following:

• C++ encoder API
• C++ decoder API
• C decoder API
• VGF dumping tool: vgf_dump
• VGF updating tool: vgf_updater

The encoder provides a simple, high-level API for building up VGF files. It is designed for easy integration into offline tooling.

The decoder is designed to be lightweight and to be included in high-performing programs, for example game engines. Therefore, the decoder does not allocate any dynamic memory on its own. To maintain full control, you must allocate the memory required and provide it to this library. To minimize copies and peak memory requirements, the format also supports mmap read operations on the contents.

VGF Library also provides a dumping tool which is called vgf_dump. vgf_dump prints the content of a VGF file into human-readable JSON format. You can also use vgf_dump to generate scenario file templates. You can use the scenario file templates with the Scenario Runner tool.

The VGF Updater rewrites an existing VGF file to the latest VGF format version supported by the VGF library. The new version of the VGF file is written to the provided output path.

To see the contents of a VGF file in a visual format, you can use the VGF Adapter for Model Explorer, which lets you view the inputs, outputs, constants and SPIR-V™ graphs.

Cloning the repository

To clone the ML SDK VGF Library as a stand-alone repository, you can use regular git clone commands. However, for better management of dependencies and to ensure everything is placed in the appropriate directories, we recommend using the git-repo tool to clone the repository as part of the ML SDK for Vulkan® suite. Repo tool.

For a minimal build and to initialize only the ML SDK VGF Library and its dependencies, run:

repo init -u https://github.com/arm/ai-ml-sdk-manifest -g vgf-lib

Alternatively, to initialize the repo structure for the entire ML SDK for Vulkan®, including the VGF Library, run:

repo init -u https://github.com/arm/ai-ml-sdk-manifest -g all

After the repo is initialized, fetch the contents with:

repo sync --no-clone-bundle

Cloning on Windows®

To ensure nested submodules do not exceed the maximum long path length, you must enable long paths on Windows®, and you must clone close to the root directory or use a symlink. Make sure to use Git for Windows.

Using PowerShell:

Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1
git config --global core.longpaths true
git --version # Ensure you are using Git for Windows, for example 2.50.1.windows.1
git clone <git-repo-tool-url>
python <path-to-git-repo>\git-repo\repo init -u <manifest-url> -g all
python <path-to-git-repo>\git-repo\repo sync --no-clone-bundle

Using Git Bash:

cmd.exe "/c reg.exe add \"HKLM\System\CurrentControlSet\Control\FileSystem"" /v LongPathsEnabled /t REG_DWORD /d 1 /f"
git config --global core.longpaths true
git --version # Ensure you are using the Git for Windows, for example 2.50.1.windows.1
git clone <git-repo-tool-url>
python <path-to-git-repo>/git-repo/repo init -u <manifest-url> -g all
python <path-to-git-repo>/git-repo/repo sync --no-clone-bundle

After the sync command completes successfully, you can find the ML SDK VGF Library in <repo_root>/sw/vgf-lib/. You can also find all the dependencies required by the ML SDK VGF Library in <repo_root>/dependencies/.

Building VGF Library from source

The build system must have:

• C/C++ 17 compiler: GCC, or optionally Clang on Linux and MSVC on Windows®.
• CMake 3.25 or later.
• Ninja 1.8.2 or later.
• Python 3.10 or later and uv 0.9.26. Test and tooling dependencies are declared in pyproject.toml and locked in uv.lock.

The following dependencies are also needed:

• Argument Parser for Modern C++.
• JSON for Modern C++.
• pybind11.
• GoogleTest. Optional, for testing.

For the preferred dependency versions see the manifest file.

Building with the script

To make the build configuration options easily discoverable, we provide a python build script. When you run the script from a git-repo manifest checkout, the script uses default paths and does not require any additional arguments. If you do not use the script, you must specify paths to the dependencies.

To build on the current platform, for example on Linux or Windows®, run the following command:

python3 $SDK_PATH/sw/vgf-lib/scripts/build.py -j $(nproc)

To cross compile for AArch64 architecture, add the following option:

python3 $SDK_PATH/sw/vgf-lib/scripts/build.py -j $(nproc) --target-platform aarch64

To enable and run tests, use the --test option. To lint the tests, use the --lint option. To enable tests and documentation building python dependencies must be installed:

uv sync --locked --no-install-project --no-default-groups --group test --group tooling

Run build commands with uv run --no-sync python scripts/build.py to use the locked environment. To build documentation, pass --doc; Doxygen must also be installed on your machine.

You can install the build artifacts for this project into a specified location. To install the build artifacts, pass the --install option with the required path.

To create an archive containing the build artifacts, pass the --package-type option with an archive type such as zip or tgz. Use --package-dir to choose where the archive is written; by default, packages are written to the build directory.

For more command line options, see the help output:

python3 $SDK_PATH/sw/vgf-lib/scripts/build.py --help

Code coverage

Sync the locked test and tooling dependencies, then run the C++ and Python unit tests on Linux with GCC coverage instrumentation:

uv sync --locked --no-install-project --no-default-groups --group test --group tooling
uv run --no-sync python scripts/build.py --coverage --build-dir build-coverage

The command writes a detailed HTML report to build-coverage/coverage/index.html and a machine-readable JSON summary to build-coverage/coverage/summary.json. Coverage is collected for the native library and Python binding sources, including native code exercised through pytest. Python source-line coverage is not collected.

PyPI

The ML SDK VGF Library is available on PyPI as the ai-ml-sdk-vgf-library package.

Install:

pip install ai-ml-sdk-vgf-library

Install from source with pip

From the repository root, install the package with:

pip install .

This command compiles the project’s C/C++ library and Python extension, then installs the resulting Python package. Ensure the prerequisites listed in Building VGF Library from source are installed and the repository dependencies have been initialized.

License

The ML SDK VGF Library is distributed under the software licenses in LICENSES directory.

Trademark notice

Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

Khronos® and Vulkan® are registered trademarks, and SPIR-V™ is a trademark of The Khronos Group Inc..