Skip to main content

Build Velopack SDK

Applies to
Windows
MacOS
Linux

The Velopack SDK is responsible for compiling releases and installers.

It is made up of:

  • Rust binaries which are re-distributed with installed apps,
  • .NET NuGet package (Velopack),
  • .NET command line tool (vpk).

In order to test the project, you need to build the Rust binaries before compiling dotnet.

tip

For local development you only need to build the binaries for your current OS — you do not need to build all platforms to run the tests. A full cross-platform production build (combining binaries from every OS) is handled by CI and is described in the Release / Build section below.

Prerequisites​

  • .NET 10 SDK — the solution multi-targets net8.0, net9.0 and net10.0, so the highest SDK (10) is required to build everything. CI installs the 8.0.x, 9.0.x and 10.0.x SDKs side-by-side.
  • Rust / Cargo — minimum supported Rust version is 1.75 (edition 2021).
  • dotnet tool update -g nbgv
  • dotnet tool install -g dotnet-coverage (only needed for collecting code coverage)

Debug / Test​

On Windows, you need to build the Rust binaries using the windows feature before running tests (a couple of binaries require it). On OSX or Linux, you should run cargo build without the feature flag instead.

On Windows:

git clone https://github.com/velopack/velopack.git
cd velopack
cargo build -p velopack_bins --features windows
dotnet build
dotnet test --no-build

On OSX / Linux:

git clone https://github.com/velopack/velopack.git
cd velopack
cargo build -p velopack_bins
dotnet build
dotnet test --no-build
tip

The test runner is configured via global.json to use Microsoft.Testing.Platform. dotnet test --no-build still works; you can also target a single project, for example dotnet test --project test/Velopack.Tests/Velopack.Tests.csproj --no-build.

Release / Build​

Creating a full production release is complex because Velopack must include native binaries for Windows, Linux, and macOS. You need to build the Rust binaries separately on each platform, then combine them on the final build machine using /p:PackRustAssets=true.

For local development, you typically only need binaries for your current OS. The simplest approach is:

On Windows:

git clone https://github.com/velopack/velopack.git
cd velopack
cargo build --release -p velopack_bins --features windows
dotnet build -c Release

On OSX:

git clone https://github.com/velopack/velopack.git
cd velopack
cargo build --release -p velopack_bins
dotnet build -c Release

On Linux:

git clone https://github.com/velopack/velopack.git
cd velopack
cargo build --release -p velopack_bins
dotnet build -c Release
tip

For a complete working example of building a release using local Velopack code, see the dev-scripts in the Avalonia sample.

note

A full cross-platform production build (combining binaries from all operating systems into one package) requires building Rust on each platform first, then collecting all the artifacts into target/release and running dotnet build -c Release /p:PackRustAssets=true /p:ContinuousIntegrationBuild=true. This workflow is handled by CI and is not practical to replicate locally. See the CI workflows for details.

Preparing Linux​

If you are on Linux (tested on Ubuntu), there are additional package pre-requisites.

If you are building the native Rust libraries/binaries, the following development packages are required:

sudo apt-get install -y libgtk-3-dev libx11-dev libxext-dev libxft-dev libxinerama-dev libxcursor-dev libxrender-dev libxfixes-dev libpango1.0-dev libgl1-mesa-dev libglu1-mesa-dev libpipewire-0.3-dev libclang-dev libgbm-dev libegl-dev libwayland-dev

Installing dotnet and setting up the paths are a pain, I recommend using the dotnet-install.sh script.

./dotnet-install.sh -c 10.0

And then adding the following to the bottom of your .bashrc or .profile:

export DOTNET_ROOT="$HOME/.dotnet"
export DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1
export PATH="$PATH:$HOME/.dotnet"
export PATH="$PATH:$HOME/.dotnet/tools"

Next, install the missing dotnet tools:

dotnet tool update -g nbgv
dotnet tool install -g dotnet-coverage

You need to verify that nbgv is working on the command line (eg. nbgv -h) before continuing. If it's not working, check that your tools installed to ~/.dotnet/tools. If you did not use the dotnet-install.sh script, dotnet could be at a different location (eg. /usr/share/dotnet) and the paths above will need to be updated.

Once dotnet is configured, you can Install Rust, typically done with the rustup script available here

To verify that Rust is installed and working correctly, you should compile the Rust binaries:

cargo build --release -p velopack_bins