Skip to main content

Packaging Overview

Applies to
Windows
MacOS
Linux

Packaging a release is accomplished with the pack command in Velopack. Regardless of your operating system, the common required arguments are roughly the same.

Creating your first release​

You first should compile your application with whatever toolchain you would normally use (eg. dotnet publish, msbuild.exe, so forth). Henceforth this will be called {build_dir}.

Required arguments​

  • --packId {id} The unique ID of your application. This should be unique enough to avoid other application authors from colliding with your app.
  • --packVersion {version} The current version you are releasing - in semver2 format (eg. 1.0.0-build.23+metadata).
  • --packDir {build_dir} The folder containing your compiled application.
  • --mainExe {exeName} The main executable to be started after install, and the binary that will handle Velopack Hooks.
tip

Velopack does not support 4 part versions (eg. 1.0.0.0), as it would not be practical to support both formats simultaneously and semver2 offers a lot more flexibility.

A complete example:

dotnet publish -c Release -r win-x64 -o publish
vpk pack --packId MyAppId --packVersion 1.0.0 --packDir publish --mainExe MyApp.exe

There are many optional arguments, the best way to see what features are available for your operating system is to check vpk pack -h. To mention a couple:

  • --packTitle {name} The friendly name for your app, shown to users in dialogs, shortcuts, etc.
  • --outputDir {path} The location Velopack should create the final releases (defaults to .\Releases)
  • --icon {path} The icon used to bundle your app.

Release output​

When building a release has completed, you should have the following assets in your --outputDir:

  • MyAppId-1.0.0-full.nupkg - Full Release: contains your entire update package.
  • MyAppId-1.0.0-delta.nupkg - Delta Release: only if there was a previous release to build a delta from. These are optional to build/deploy, but speeds up the updating process for sers because they only need to download what's changed between versions instead of the full package.
  • MyAppId-Portable.zip - Portable Release: Can deploy this optionally to allow users to run and update your app without installing.
  • MyAppId-Setup.exe - Installer: Used by most users to install the app to the local filesystem.
  • releases.{channel}.json - Releases Index: a list of every available release. Used by UpdateManager to locate the latest applicable release.
  • RELEASES - Legacy Releases File: only used for clients migrating to Velopack from Squirrel.
  • assets.{channel}.json - Build Assets: A list of assets created in the most recent build. Used by Velopack deployment commands.

You do not need to deploy all of these files to allow users to update, so you should review the deployment guide for more information on which files to distribute.

tip

There is no setup/installer package for Linux. The program is distributed as a self-updating .AppImage. The reason is that .AppImage will run on pretty much every modern distro with no extra dependencies needed. Just download the .AppImage, run chmod +x, and click it to start. It is possible to install an .AppImage, but this is left up to the user to install something like appimaged or AppImageLauncher.

Code signing​

While this is not required for local builds / testing, you should always code-sign your application before distributing your application to users.

tip

If you do not code-sign, your application may fail to run. [Read more]

Customising the installer​

On platforms which ship installers, you can customise the behavior. [Read more]

  • If your application is operating-system or CPU architecture specific you should consider adding an --rid. [Read more]
  • If you plan on distributing release channels for different architectures or features, consider adding a --channel [Read more]
  • If your app requires additional frameworks (eg. vcredist) consider --framework [Read more]