mirror of
https://github.com/logos-co/velopack.git
synced 2026-09-02 06:31:10 +00:00
rename 'pages' to 'docs'
This commit is contained in:
Caelan Sayler
@@ -0,0 +1,51 @@
|
||||
*Applies to: Windows, MacOS, Linux*
|
||||
|
||||
# Compiling Velopack
|
||||
Velopack is made up of some Rust binaries which are re-distributed with installed apps, a .NET NuGet package, and a .NET command line tool. In order to test the project, you need to build the Rust binaries before compiling dotnet.
|
||||
|
||||
### Prerequisites
|
||||
- [.NET 6 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0)
|
||||
- [.NET 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
|
||||
- [Rust / Cargo](https://www.rust-lang.org/tools/install)
|
||||
- `dotnet tool install -g dotnet-coverage`
|
||||
- `dotnet tool install -g nbgv`
|
||||
|
||||
### Debug / Test
|
||||
On windows, you need to build the Rust binaries using the `windows` feature before running tests. On OSX, you should run `cargo build` instead.
|
||||
|
||||
```shell
|
||||
git clone https://github.com/velopack/velopack.git
|
||||
cd velopack/src/Rust
|
||||
cargo build --features windows
|
||||
cd ../../
|
||||
dotnet build
|
||||
dotnet test --no-build
|
||||
```
|
||||
|
||||
### Release / Build
|
||||
This is slightly complicated, because you will need to compile Rust on x64 OSX and x64 Windows before creating the final packages.
|
||||
|
||||
On OSX:
|
||||
```shell
|
||||
git clone https://github.com/velopack/velopack.git
|
||||
cd velopack/src/Rust
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
On Windows:
|
||||
```shell
|
||||
git clone https://github.com/velopack/velopack.git
|
||||
cd velopack/src/Rust
|
||||
cargo build --release --features windows
|
||||
copy {path_to_osx_update} target/release/updatemac
|
||||
dotnet build -c Release /p:PackRustAssets=true
|
||||
```
|
||||
|
||||
### Compiling on Linux
|
||||
If you are on Linux (tested on Ubuntu), there are additional package pre-requisites:
|
||||
```sh
|
||||
sudo apt install libssl-dev pkg-config
|
||||
```
|
||||
You need to verify that `nbgv` is working on the command line, you may be missing a `DOTNET_ROOT` variable in your bash profile, which might need to point at `/usr/share/dotnet` or `$HOME/.dotnet`.
|
||||
|
||||
If you are missing localisation packages, you can search for them or add `export DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1` to your bash profile.
|
||||
@@ -0,0 +1,2 @@
|
||||
- name: Overview
|
||||
href: overview.md
|
||||
@@ -0,0 +1,46 @@
|
||||
*Applies to: Windows, MacOS, Linux*
|
||||
|
||||
# Getting Started: C# / .NET
|
||||
|
||||
1. Install the command line tool `vpk`:
|
||||
```cmd
|
||||
dotnet tool update -g vpk
|
||||
```
|
||||
2. Install the [Velopack NuGet Package](https://www.nuget.org/packages/velopack) in your main project:
|
||||
```cmd
|
||||
dotnet add package Velopack
|
||||
```
|
||||
3. Configure your Velopack app at the beginning of `Program.Main`:
|
||||
```cs
|
||||
static void Main(string[] args)
|
||||
{
|
||||
VelopackApp.Build().Run();
|
||||
// ... your other startup code below
|
||||
}
|
||||
```
|
||||
4. Add automatic updating to your app:
|
||||
```cs
|
||||
private static async Task UpdateMyApp()
|
||||
{
|
||||
var mgr = new UpdateManager("https://the.place/you-host/updates");
|
||||
|
||||
// check for new version
|
||||
var newVersion = await mgr.CheckForUpdatesAsync();
|
||||
if (newVersion == null)
|
||||
return; // no update available
|
||||
|
||||
// download new version
|
||||
await mgr.DownloadUpdatesAsync(newVersion);
|
||||
|
||||
// install new version and restart app
|
||||
mgr.ApplyUpdatesAndRestart();
|
||||
}
|
||||
```
|
||||
5. Publish dotnet and build your first Velopack release! 🎉
|
||||
```cmd
|
||||
dotnet publish -c Release --self-contained -r win-x64 -o .\publish
|
||||
vpk pack -u YourAppId -v 1.0.0 -p .\publish -e yourMainApp.exe
|
||||
```
|
||||
6. Upload the files created by Velopack to `https://the.place/you-host/updates`
|
||||
|
||||
If you're not sure how these instructions fit into your app, check the example apps for common scenarios such as WPF or Avalonia.
|
||||
@@ -0,0 +1,2 @@
|
||||
- name: C# .NET
|
||||
href: csharp.md
|
||||
@@ -0,0 +1,67 @@
|
||||
*Applies to: Windows*
|
||||
|
||||
# Migrating to Velopack
|
||||
|
||||
## From Squirrel
|
||||
If you are using one of these packages in your application, migrating will be mostly automated. Here are the general steps needed:
|
||||
|
||||
1. Replace the `Squirrel.Windows` or `Clowd.Squirrel` nuget package with the latest [`Velopack NuGet Package`](https://www.nuget.org/packages/velopack).
|
||||
|
||||
0. Install the `vpk` command line tool, as this is what you'll use to build Velopack releases.
|
||||
```cmd
|
||||
dotnet tool install -g vpk
|
||||
```
|
||||
|
||||
0. You will need to replace `SquirrelAwareApp` at the beginning of your app to `VelopackApp.Build().Run()`. Shortcuts [[Read more]](updating/shortcuts.md) and registry entries are managed automatically for you in Velopack, so if you are currently doing this in `SquirrelAwareApp` hooks they should be removed. For example, if your hooks were this before:
|
||||
```cs
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
SquirrelAwareApp.HandleEvents(
|
||||
onInitialInstall: OnAppInstall,
|
||||
onAppUninstall: OnAppUninstall,
|
||||
onEveryRun: OnAppRun);
|
||||
}
|
||||
|
||||
private static void OnAppInstall(SemanticVersion version, IAppTools tools)
|
||||
{
|
||||
tools.CreateShortcutForThisExe(ShortcutLocation.StartMenu | ShortcutLocation.Desktop);
|
||||
}
|
||||
|
||||
private static void OnAppUninstall(SemanticVersion version, IAppTools tools)
|
||||
{
|
||||
tools.RemoveShortcutForThisExe(ShortcutLocation.StartMenu | ShortcutLocation.Desktop);
|
||||
}
|
||||
|
||||
private static void OnAppRun(SemanticVersion version, IAppTools tools, bool firstRun)
|
||||
{
|
||||
if (firstRun) MessageBox.Show("Thanks for installing my application!");
|
||||
}
|
||||
```
|
||||
Then you would migrate to the following code, removing the shortcut hooks:
|
||||
```cs
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
VelopackApp.Build()
|
||||
.WithFirstRun(v => MessageBox.Show("Thanks for installing my application!"))
|
||||
.Run();
|
||||
}
|
||||
```
|
||||
|
||||
0. The concept of `SquirrelAwareApp` no longer exists, so if you've added any attributes, assembly manifest entries, or other files to indicate that your binary is now aware, you can remove that. Every Velopack package has exactly one "VelopackApp" binary, which must implement the above interface at the top of `Main`. By default, Velopack will search for a binary in `{packDir}\{packId}.exe`. If your exe is named differently, you should provide the name with the `--mainExe yourApp.exe` argument.
|
||||
|
||||
0. The "RELEASES" file is no longer a format that Velopack uses, but it will produce one when building packages on windows with the default channel (eg. no channel argument provided). Instead, Velopack will produce `releases.{channel}.json` files, which should be treated in the same way. If you are wishing for a legacy windows app to migrate to Velopack, you should upload both the `RELEASES` file and the `releases.win.json` file which is produced by Velopack to your update feed.
|
||||
|
||||
0. In general, the command line supports all of the same features, but argument names or commands may have changed. Velopack no longer supports taking a `.nupkg` which was created by dotnet or nuget.exe. You should publish your app, and use `vpk pack` instead. A very simple example might look like this
|
||||
```cmd
|
||||
dotnet publish --self-contined -r win-x64 -o publish
|
||||
vpk pack -u YourAppId -v 1.0.0 -p publish -e yourMainBinary.exe
|
||||
```
|
||||
|
||||
Please review the vpk command line help for more details:
|
||||
```cmd
|
||||
vpk -h
|
||||
```
|
||||
|
||||
|
||||
## From ClickOnce
|
||||
There is no guide or advice for migrating ClickOnce applications yet. If you would like to contribute one, please open an issue or PR!
|
||||
@@ -0,0 +1,76 @@
|
||||
*Applies to: Windows*
|
||||
|
||||
# Bootstrapping
|
||||
While installing Velopack applications on Windows, it is possible to install other commonly required runtime dependencies using the `--framework` / `-f` argument.
|
||||
|
||||
It is possibly to specify more than one requirement, using a comma delimited list. For example:
|
||||
```cmd
|
||||
vpk pack ... --framework net6.0-x64-desktop,vcredist142-x64
|
||||
```
|
||||
|
||||
These dependencies will be downloaded and installed before your application will be installed.
|
||||
|
||||
> [!CAUTION]
|
||||
> If you are building a dotnet application with `--self-contained`, you should **NOT** provide a `--framework` argument specifying that your app requires dotnet installed, because your application already has the runtime bundled in. If you are publishing your application with `--no-self-contained`, then you should provide the `--framework` argument.
|
||||
|
||||
## Adding dependencies during updates
|
||||
|
||||
Velopack will check that all required dependencies are installed before applying new updates. This means if a new version of your app adds a new dependency, the user will be prompted to install it before your new version is applied.
|
||||
|
||||
## List of supported frameworks
|
||||
Any of the following can be passed via the `--framework` argument.
|
||||
|
||||
### Edge WebView2
|
||||
- `webview2`
|
||||
|
||||
### vcredist
|
||||
- `vcredist100-x86` (VC++ 10.0 / VS 2010)
|
||||
- `vcredist100-x64` (VC++ 10.0 / VS 2010)
|
||||
- `vcredist110-x86` (VC++ 11.0 / VS 2012)
|
||||
- `vcredist110-x64` (VC++ 11.0 / VS 2012)
|
||||
- `vcredist120-x86` (VC++ 12.0 / VS 2013)
|
||||
- `vcredist120-x64` (VC++ 12.0 / VS 2013)
|
||||
- `vcredist140-x86` (VC++ 14.0 / VS 2015)
|
||||
- `vcredist140-x64` (VC++ 14.0 / VS 2015)
|
||||
- `vcredist141-x86` (VC++ 14.1 / VS 2017)
|
||||
- `vcredist141-x64` (VC++ 14.1 / VS 2017)
|
||||
- `vcredist142-x86` (VC++ 14.2 / VS 2019)
|
||||
- `vcredist142-x64` (VC++ 14.2 / VS 2019)
|
||||
- `vcredist143-x86` (VC++ 14.3 / VS 2022)
|
||||
- `vcredist143-x64` (VC++ 14.3 / VS 2022)
|
||||
- `vcredist143-arm64` (VC++ 14.3 / VS 2022)
|
||||
|
||||
### .Net Framework
|
||||
- `net45`
|
||||
- `net451`
|
||||
- `net452`
|
||||
- `net46`
|
||||
- `net461`
|
||||
- `net462`
|
||||
- `net47`
|
||||
- `net471`
|
||||
- `net472`
|
||||
- `net48`
|
||||
- `net481`
|
||||
|
||||
### dotnet
|
||||
Every version of dotnet is supported >= 5.0. The framework argument should be supplied in the format `$"net{major.minor}-{arch}-{type}"`.
|
||||
|
||||
The valid `{arch}` values are
|
||||
- x86
|
||||
- x64
|
||||
- arm64
|
||||
|
||||
The valid `{type}` values are
|
||||
- runtime
|
||||
- aspnetcore
|
||||
- desktop
|
||||
|
||||
Here are some examples:
|
||||
- .NET 6.0 Desktop Runtime (x64) `--framework net6.0-x64-desktop`
|
||||
- .NET 8.0 Runtime (arm64) `--framework net8.0-arm64-runtime`
|
||||
- .NET 5.0 AspNetCore (x86) `--framework net5.0-x86-aspnetcore`
|
||||
|
||||
By default, Velopack will accept any installed release, but always install the latest. That is to say, if your dependency is specified as `net6.0-x64-desktop` and version `6.0.2` is installed, it will be accepted. If it's not installed, Velopack will download the latest available version (at the time of writing, that's `6.0.26`).
|
||||
|
||||
If you need a specific version of dotnet, (eg. `6.0.11`) - you can specify a third version part in your dependency string: `--framework net6.0.11-x64-desktop`. In this case, if the installed version is `< 6.0.11`, then it will be upgraded to the latest available.
|
||||
@@ -0,0 +1,36 @@
|
||||
*Applies to: Windows, MacOS, Linux*
|
||||
|
||||
# Release Channels
|
||||
Channels is a fundemental part of how Velopack understands and builds releases. Every release must belong to a channel. If you do not specify a channel when building a release (via the `--channel`) argument, the default channel will be the name of the target Operating System (eg. `win`, `osx`, or `linux`).
|
||||
|
||||
When building releases, Velopack will create a `releases.{channel}.json` file, that should be uploaded with your other assets (eg. `.nupkg`). This is how `UpdateManager` knows what releases are available.
|
||||
|
||||
In general, you should not provide a channel to the `UpdateManager` constructor (leave it null). In this case, it will only search for update packages in the same channel that the current release was built for. For example, if you provided the `--channel stable` argument to `vpk`, and installed your app, then `UpdateManager` will automatically be searching for the file `releases.stable.json` when checking for updates.
|
||||
|
||||
❗For legacy purposes, Velopack will also generate a `RELEASES` file (for the `win` channel), or a `RELEASES-{channel}` file (for any other channel). By deploying these files as well as the `releases.{channel}.json` will allow legacy apps to upgrade to Velopack. If you do not have any users on legacy versions of your software, you can ignore these files.
|
||||
|
||||
## Switching channels in installed apps
|
||||
It is often desirable to allow users to switch channels easily. For example, if your users downloaded an installer for a "stable" version of your app, they will only receive updates for the "stable" channel. Later on, they decide they wish to switch to the "beta" channel to try some experimental features in your app.
|
||||
|
||||
This can be done by supplying a non-null channel argument to the UpdateManager constructor. So you would instantiate as `new UpdateManager("https://the.place/you-store/updates", "beta")` and then perform an update process as usual.
|
||||
|
||||
## Deploying cross-platform apps
|
||||
|
||||
It's important when deploying cross platform (or cross-architecture) apps that every unique os/rid has it's own channel. It wouldn't be good if your Windows app tried to install an OSX package etc!
|
||||
|
||||
The default channels are, `win`, `osx`, or `linux`, so if you are only distributing one release per platform, you do not need to specify a channel argument, everything should work automatically. If you are distributing feature channels (eg. 'stable', 'beta') or need to distribute multiple versions of your app per os (eg. `win-x64`, `win-arm64`) then you will need to define a channel strategy that does not collide.
|
||||
|
||||
For example, if I was distributing an app on windows and osx which needed to support x64, and arm64, and also needed to support "stable" and "beta", then I would need the following 8 channels:
|
||||
- win-x64-stable
|
||||
- win-x64-beta
|
||||
- win-arm64-stable
|
||||
- win-arm64-beta
|
||||
- osx-x64-stable
|
||||
- osx-x64-beta
|
||||
- osx-arm64-stable
|
||||
- osx-arm64-beta
|
||||
|
||||
## Renaming a channel
|
||||
You can't rename a channel per-say, but you can supercede it (ie. force all your users to switch to the new channel). Imagine you have been publishing an app that only supports x64 windows to the channel `stable` until now, but you now would like to release an arm64 version of your app. So you want to migrate all the users on `stable` to `win-x64`, while also creating a new channel named `win-arm64`.
|
||||
|
||||
You should publish your next update (say v2.0.0) using `--channel win-x64`, which will create a new `releases.win-x64.json` file. You can now copy this file and rename it to `releases.stable.json` and deploy both files along with your v2.0.0 `.nupkg` to your update server. Any users on the "stable" channel will find the `releases.stable.json` file and update to your v2.0.0 win-x64 release, and once done will search for future updates at `releases.win-x64.json`. You only need to do this once, you will not need to update the `releases.stable.json` file again, however you may not want to delete it so users who have not opened your app in some time can still find the new updates.
|
||||
@@ -0,0 +1,48 @@
|
||||
*Applies to: Windows, MacOS*
|
||||
|
||||
# Installer Overview
|
||||
Velopack takes a relatively light-touch when it comes to installers, so there is not a lot of customisation available like you would find in other installation frameworks. This is the tradeoff Velopack makes to ensure that the developer/user experience is as fast and easy as possible.
|
||||
|
||||
In both operating systems, if [code signing is configured](signing.md) the installer will also be signed. (This is _required_ on MacOS)
|
||||
|
||||
## Windows Overview
|
||||
The Windows installer is currently a "one-click" installer, meaning when the `Setup.exe` binary is run, Velopack will not show any questions / wizards to the user, it will simply attempt to install the app as fast as possible and then launch it.
|
||||
|
||||
The setup will install a shortcut to `StartMenuRoot` and `Desktop` by default. [[Read more]](../updating/shortcuts.md)
|
||||
|
||||
The key options which will customize the installer are as follows:
|
||||
- `--packTitle {app name}` customizes shortcut names, the Apps & Features name, and the portable entry exe name.
|
||||
- `--icon {path}` sets the .ico on Update.exe and Setup.exe (and also the icon of any dialogs shown)
|
||||
- `--splashImage {path}` sets the (possibly animated) splash image to be shown while installing.
|
||||
|
||||
The splash image can be a `jpeg`, `png`, or `gif`. In the latter case, it will be animated.
|
||||
|
||||
You can also [bootstrap required frameworks](bootstrapping.md) before installing your app.
|
||||
|
||||
The Windows installer will extract the application to `%LocalAppData%\{packId}`, and the directory structure will look like:
|
||||
|
||||
```
|
||||
{packId}
|
||||
├── current
|
||||
│ ├── YourFile.dll
|
||||
│ ├── sq.version
|
||||
│ └── YourApp.exe
|
||||
└── Update.exe
|
||||
```
|
||||
|
||||
The `current` directory will be fully replaced [while doing updates](../updating/overview.md). The other two files added by Velopack (`Update.exe` and `sq.version`) are crucial and are required files for Velopack to be able to properly update your application.
|
||||
|
||||
## MacOS Overview
|
||||
The MacOS installer will be a standard `.pkg` - which is just a bundle where the UI is provided by the operating system, allowing the user to pick the install location. The app will be launched automatically after the install (mirroring the behavior on Windows) because of a `postinstall` script added by Velopack.
|
||||
|
||||
The key options which will customize the installer are as follows:
|
||||
- `--packTitle {app name}` customizes the name of the `.app` bundle and the app name shown in the `.pkg`
|
||||
- `--pkgWelcome {path}` adds a Welcome page
|
||||
- `--pkgReadme {path}` adds a Readme page
|
||||
- `--pkgLicense {path}` adds a License Acceptance page
|
||||
- `--pkgConclusion {path}` adds a Conclusion page
|
||||
- `--noPkg` disable generating a `.pkg` installer entirely
|
||||
|
||||
The pkgPage arguments can be a `.rtf` or a `.html` file.
|
||||
|
||||
The `.app` package can be extracted to `/Applications` or `~/Applications`, this is selected by the user while installing.
|
||||
@@ -0,0 +1,58 @@
|
||||
*Applies to: Windows, MacOS, Linux*
|
||||
# Packaging Overview
|
||||
|
||||
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](https://semver.org/) (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](../updating/overview.md).
|
||||
- `--icon {path}` The icon used to bundle your app. Only required on MacOS and Linux.
|
||||
|
||||
> [!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:
|
||||
```cmd
|
||||
dotnet publish -c Release -r win-x64 -o publish
|
||||
vpk pack --packId MyAppId -packVersion 1.0.0 --packDir publish --mainExe MyApp.exe
|
||||
```
|
||||
|
||||
### Optional recommended arguments
|
||||
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`)
|
||||
|
||||
### 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](../migrating.md) from Squirrel.
|
||||
- `assets.{channel}.json` - Build Assets: A list of assets created in the most recent build. Used by [Velopack deployment commands](../distributing/overview.md).
|
||||
|
||||
You do not need to deploy all of these files to allow users to update, so you should review the [deployment guide](../distributing/overview.md) 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](https://github.com/probonopd/go-appimage/blob/master/src/appimaged/README.md) or [AppImageLauncher](https://github.com/TheAssassin/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.
|
||||
|
||||
> [!WARNING]
|
||||
> If you do not code-sign, your application may fail to run. [[Read more]](signing.md)
|
||||
|
||||
## Customising the installer
|
||||
On platforms which ship installers, you can customise the behavior. [[Read more]](installer.md)
|
||||
|
||||
## Other recommended arguments
|
||||
- If your application is operating-system or CPU architecture specific you should consider adding an `--rid`. [[Read more]](rid.md)
|
||||
- If you plan on distributing release channels for different architectures or features, consider adding a `--channel` [[Read more]](channels.md)
|
||||
- If your app requires additional frameworks (eg. vcredist) consider `--framework` [[Read more]](bootstrapping.md)
|
||||
@@ -0,0 +1,22 @@
|
||||
*Applies to: Windows, MacOS, Linux*
|
||||
|
||||
# RID (Runtime Identifier)
|
||||
Similar to how you provide a RID to dotnet to designate your target operating system and architecture, you can do the same for Velopack to tell it what your application supports.
|
||||
|
||||
An RID is composed of three parts (`{os}{version?}-{arch}`)
|
||||
- os: operating system (`win`, `osx`, or `linux`)
|
||||
- version: optionally, specify minimum supported version (eg. `win7`, `win8.1`, `win10.0.18362`)
|
||||
- arch: optionaly, specify supported CPU architecture (eg.`win-x86`, `win-x64`, `win-arm64`)
|
||||
|
||||
If you were to provide the RID `--rid win10-arm64`, any users trying to install your app on Windows 7, 8, or 8.1 will receive a message saying their operating system is not supported. Similarly, if a Windows 11 user with an x64 cpu were trying to install - it would also fail with a helpful message.
|
||||
|
||||
If trying to target Windows 11, they did not increment the major build number from 10 to 11. Anything >= build 22000 is classified as Windows 11. For example:
|
||||
- `win11 == win10.0.22000`
|
||||
- `win11.0.22621 == win10.0.22621`
|
||||
|
||||
On MacOS, the RID (min version and arch) is just stored as metadata in the `.pkg` which will be handled natively by the operating system.
|
||||
|
||||
#### Also read
|
||||
- [Windows 10 version history](https://en.wikipedia.org/wiki/Windows_10_version_history)
|
||||
- [Windows 11 version history](https://en.wikipedia.org/wiki/Windows_11_version_history)
|
||||
- [.NET RID Catalog](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog)
|
||||
@@ -0,0 +1,147 @@
|
||||
*Applies to: Windows, MacOS*
|
||||
|
||||
# Code Signing
|
||||
Code signing is an essential part of application distribution. On Windows, applications without code signatures are likely to be flagged as viruses. On OSX, codesigning and Notarization is required before your application can be run by users.
|
||||
|
||||
On both platforms, signing needs to be performed by Velopack itself, this is because the Velopack binaries (such as Update and Setup) need to be signed at different points in the package build process.
|
||||
|
||||
## Signing on Windows
|
||||
|
||||
### Acquiring a code signing certificate
|
||||
First, you need to acquire a code-signing certificate from a reputable brand. To name a few: Digicert, Sectigo, Comodo. It may be possible to purchase a certificate through an official reseller for cheaper than buying directly from the issuer. If you are looking for an open source development certificate, at the time of writing Certum does an [Open Source Cloud Signing](https://certum.store/data-safety/code-signing-certificates.html?as_dane_w_certyfikacie=5720) certificate for $58.
|
||||
|
||||
**Disclaimer: This is by no means a recommendation or advice for any particular code-signing certificate issuer, but instead is general guidance for the process one might follow to purchase a certificate.**
|
||||
|
||||
### Signing via `signtool.exe`
|
||||
Usually signing is accomplished via `signtool.exe`. If you already use this tool to sign your application, you can just pass your sign parameters straight to Velopack (minus the 'sign' command).
|
||||
|
||||
For example, if your signing command before was:
|
||||
```cmd
|
||||
signtool.exe sign /td sha256 /fd sha256 /f yourCert.pfx /tr http://timestamp.comodoca.com
|
||||
```
|
||||
|
||||
Then now with `--signParams` it would be:
|
||||
```cmd
|
||||
vpk pack ... --signParams "/td sha256 /fd sha256 /f yourCert.pfx /tr http://timestamp.comodoca.com"
|
||||
```
|
||||
|
||||
If you are new to using `signtool.exe`, you can check the [command line reference here](https://learn.microsoft.com/en-us/dotnet/framework/tools/signtool-exe). I recommend getting signing working on a single binary first, using `signtool.exe`, before trying to get things working with the Velopack CLI.
|
||||
|
||||
❗**Take care when providing parameters: If any have a space in a signing argument, you must wrap it with quotes and escape with a backslash.**
|
||||
|
||||
By default, Velopack will sign 10 files per call to `signtool.exe`, to speed up signing and reduce the number of times you need to interact with the console if you are using some kind of interactive signing method. This can be disabled with the `--signParallel 1` argument.
|
||||
|
||||
### Custom signing commands and tools
|
||||
If you have more advanced signing requirements, such as a custom signing tool (eg. `AzureSignTool.exe`), then you can provide a command template instead, where `{{file}}` is the binary that Velopack will substitute and sign:
|
||||
|
||||
```cmd
|
||||
vpk pack ... --signTemplate "AzureSignTool.exe sign ... {{file}}"
|
||||
```
|
||||
|
||||
## Signing & Notarizing on OSX
|
||||
Codesigning and Notarization is required before your application can be run by users, therefore it is a required step before deploying your application.
|
||||
|
||||
### Creating code signing certificates
|
||||
1. First, you will need to create an account at https://developer.apple.com, pay the annual developer fee, and accept any license agreements.
|
||||
0. Navigate to your certificates: https://developer.apple.com/account/resources/certificates
|
||||
0. Click the (+) icon to create new certificates. You need to create both a `Developer ID Installer` and a `Developer ID Application` certificate for distribution of Velopack apps outside the Mac App Store. 
|
||||
0. Open both certificates by clicking on them, press Download, and then double click the ".cer" file to install it to your local keychain.
|
||||
|
||||
### Setting up a NotaryTool profile
|
||||
1. Create an app-specific password: https://support.apple.com/en-us/102654. You will only be shown this password once, so save or write it down somewhere.
|
||||
0. Find your apple team ID: https://developer.apple.com/account#MembershipDetailsCard
|
||||
0. Store your Apple account credentials to a new NotaryTool profile:
|
||||
```sh
|
||||
xcrun notarytool store-credentials \
|
||||
--apple-id "yourapple@account.com" \
|
||||
--team-id "your-located-team-id" \
|
||||
--password "your-generated-app-specific-password" \
|
||||
"your-local-profile-name-here"
|
||||
```
|
||||
|
||||
### Putting it all together
|
||||
Now that you have your NotaryTool profile and code signing certificates installed, you can add the following parameters to your `pack` command:
|
||||
|
||||
```sh
|
||||
vpk pack \
|
||||
...
|
||||
--signAppIdentity "Developer ID Application: Your Name" \
|
||||
--signInstallIdentity "Developer ID Installer: Your Name" \
|
||||
--notaryProfile "your-local-profile-name-here" \
|
||||
```
|
||||
|
||||
When these parameters are specified and valid, Velopack will automatically code sign and notarize your application and installer packages.
|
||||
|
||||
### Automate signing in CI/CD (Github Actions)
|
||||
It is also posible to store your certificates and notary credentials as Action Secrets and sign your code during CI builds.
|
||||
|
||||
1. Launch Keychain Access and open the "My Certificates" pane.
|
||||
0. Select both certificates, right click and select "Export". Save as a p12 file and make note of the password. You can use the same password for both certificates.
|
||||
0. Copy the contents of the certificate to clipboard as base64, example:
|
||||
```sh
|
||||
base64 -i CERT.p12 | pbcopy
|
||||
```
|
||||
0. Create 7 [Github Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) for your Actions workflows
|
||||
- `BUILD_CERTIFICATE_BASE64` (b64 of your app cert)
|
||||
- `INSTALLER_CERTIFICATE_BASE64` (b64 of your installer cert)
|
||||
- `P12_PASSWORD` (password for the certificates)
|
||||
- `APPLE_ID` (your apple username)
|
||||
- `APPLE_PASSWORD` (your app-specific password from earlier)
|
||||
- `APPLE_TEAM` (your team id from earlier)
|
||||
- `KEYCHAIN_PASSWORD` (can be any random string, will be used to create a new keychain)
|
||||
|
||||
0. Add a step to your workflow which installs the certificates and keychain profile. Here is an example:
|
||||
```yml
|
||||
name: App build & sign
|
||||
on: push
|
||||
jobs:
|
||||
build_with_signing:
|
||||
runs-on: macos-latest
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Install Apple certificates and notary profile
|
||||
env:
|
||||
BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
|
||||
INSTALLER_CERTIFICATE_BASE64: ${{ secrets.INSTALLER_CERTIFICATE_BASE64 }}
|
||||
P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
|
||||
APPLE_ID: ${{ secrets.APPLE_ID }}
|
||||
APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
|
||||
APPLE_TEAM: ${{ secrets.APPLE_TEAM }}
|
||||
KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
|
||||
run: |
|
||||
# create variables for file paths
|
||||
CERT_BUILD_PATH=$RUNNER_TEMP/build_certificate.p12
|
||||
CERT_INSTALLER_PATH=$RUNNER_TEMP/installer_certificate.p12
|
||||
KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
|
||||
|
||||
# import certificates from secrets
|
||||
echo -n "$BUILD_CERTIFICATE_BASE64" | base64 --decode -o $CERT_BUILD_PATH
|
||||
echo -n "$INSTALLER_CERTIFICATE_BASE64" | base64 --decode -o $CERT_INSTALLER_PATH
|
||||
|
||||
# create temporary keychain
|
||||
security create-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
|
||||
security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
|
||||
security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
|
||||
|
||||
# import certificates to keychain
|
||||
security import $CERT_BUILD_PATH -P "$P12_PASSWORD" -A -t cert -f pkcs12 -k $KEYCHAIN_PATH
|
||||
security import $CERT_INSTALLER_PATH -P "$P12_PASSWORD" -A -t cert -f pkcs12 -k $KEYCHAIN_PATH
|
||||
security list-keychain -d user -s $KEYCHAIN_PATH
|
||||
|
||||
# create notarytool profile
|
||||
xcrun notarytool store-credentials --apple-id "$APPLE_ID" --team-id "$APPLE_TEAM" --password "$APPLE_PASSWORD" velopack-profile
|
||||
|
||||
- name: Build app
|
||||
...
|
||||
|
||||
- name: Create Velopack Release
|
||||
run: |
|
||||
dotnet tool install -g vpk
|
||||
vpk ... --signAppIdentity "Developer ID Application: Your Name" --signInstallIdentity "Developer ID Installer: Your Name" --notaryProfile "velopack-profile"
|
||||
|
||||
- name: Clean up keychain
|
||||
if: ${{ always() }}
|
||||
run: security delete-keychain $RUNNER_TEMP/app-signing.keychain-db
|
||||
```
|
||||
@@ -0,0 +1,12 @@
|
||||
- name: Overview
|
||||
href: overview.md
|
||||
- name: Release Channels
|
||||
href: channels.md
|
||||
- name: Code Signing
|
||||
href: signing.md
|
||||
- name: Installer Overview
|
||||
href: installer.md
|
||||
- name: Boostrapping (.NET, .Net Framework, VCRedist, etc)
|
||||
href: bootstrapping.md
|
||||
- name: RID / Min Supported OS
|
||||
href: rid.md
|
||||
@@ -0,0 +1,35 @@
|
||||
- name: Welcome
|
||||
href: welcome.md
|
||||
|
||||
- name: Getting Started
|
||||
href: getting-started/toc.yml
|
||||
homepage: getting-started/csharp.md
|
||||
|
||||
- name: Sample Apps
|
||||
items:
|
||||
- name: C# Avalonia / Cross Platform
|
||||
href: https://github.com/velopack/velopack/tree/master/examples/AvaloniaCrossPlat
|
||||
- name: C# WPF / .Net Framework
|
||||
href: https://github.com/velopack/velopack/tree/master/examples/VeloWpfSample
|
||||
|
||||
- name: Packaging Releases
|
||||
href: packaging/toc.yml
|
||||
homepage: packaging/overview.md
|
||||
|
||||
- name: Distributing Releases
|
||||
href: distributing/toc.yml
|
||||
homepage: distributing/overview.md
|
||||
|
||||
- name: Updating
|
||||
href: updating/toc.yml
|
||||
homepage: updating/overview.md
|
||||
|
||||
- name: Troubleshooting
|
||||
href: troubleshooting/toc.yml
|
||||
homepage: troubleshooting/debugging.md
|
||||
|
||||
- name: Migrating to Velopack
|
||||
href: migrating.md
|
||||
|
||||
- name: Contributing
|
||||
href: compiling.md
|
||||
@@ -0,0 +1,87 @@
|
||||
*Applies to: Windows, MacOS, Linux*
|
||||
|
||||
# Velopack Command Line Reference
|
||||
|
||||
## vpk
|
||||
```txt
|
||||
Description:
|
||||
Velopack CLI 0.0.61-g2e7ffeb (prerelease) for creating and distributing releases.
|
||||
|
||||
Usage:
|
||||
vpk [command] [options]
|
||||
|
||||
Options:
|
||||
-?, -h, --help Show help and usage information
|
||||
--version Show version information
|
||||
--verbose Print diagnostic messages.
|
||||
|
||||
Commands:
|
||||
pack Creates a release from a folder containing application files.
|
||||
download Download's the latest release from a remote update source.
|
||||
upload Upload local package(s) to a remote update source.
|
||||
delta Utilities for creating or applying delta packages.
|
||||
```
|
||||
|
||||
## Update.exe & UpdateMac
|
||||
```txt
|
||||
Velopack Updater (0.0.66) manages packages and installs updates.
|
||||
https://github.com/velopack/velopack
|
||||
|
||||
Usage: update [OPTIONS]
|
||||
update apply [OPTIONS] [-- [EXE_ARGS]...]
|
||||
update patch [OPTIONS] --old <FILE> --patch <FILE> --output <FILE>
|
||||
update start [OPTIONS] [EXE_NAME] [-- [EXE_ARGS]...]
|
||||
update uninstall [OPTIONS]
|
||||
|
||||
Options:
|
||||
--verbose Print debug messages to console / log
|
||||
-s, --silent Don't show any prompts / dialogs
|
||||
-l, --log <PATH> Override the default log file location
|
||||
-h, --help Print help
|
||||
-V, --version Print version
|
||||
|
||||
update apply:
|
||||
Applies a staged / prepared update, installing prerequisite runtimes if necessary
|
||||
-r, --restart Restart the application after the update
|
||||
-w, --wait Wait for the parent process to terminate before applying the update
|
||||
-p, --package <FILE> Update package to apply
|
||||
--noelevate If the application does not have sufficient privileges, do not elevate to admin
|
||||
-h, --help Print help
|
||||
[EXE_ARGS]... Arguments to pass to the started executable. Must be preceeded by '--'.
|
||||
|
||||
update patch:
|
||||
Applies a Zstd patch file
|
||||
--old <FILE> Base / old file to apply the patch to
|
||||
--patch <FILE> The Zstd patch to apply to the old file
|
||||
--output <FILE> The file to create with the patch applied
|
||||
-h, --help Print help
|
||||
|
||||
update start:
|
||||
Starts the currently installed version of the application
|
||||
-w, --wait Wait for the parent process to terminate before starting the application
|
||||
-h, --help Print help
|
||||
[EXE_ARGS]... Arguments to pass to the started executable. Must be preceeded by '--'.
|
||||
[EXE_NAME] The optional name of the binary to execute
|
||||
|
||||
update uninstall:
|
||||
Remove all app shortcuts, files, and registry entries.
|
||||
-h, --help Print help
|
||||
```
|
||||
|
||||
|
||||
## Setup.exe
|
||||
|
||||
```txt
|
||||
Velopack Setup (0.0.66) installs applications.
|
||||
https://github.com/velopack/velopack
|
||||
|
||||
Usage: setup [OPTIONS]
|
||||
|
||||
Options:
|
||||
-s, --silent Hides all dialogs and answers 'yes' to all prompts
|
||||
-v, --verbose Print debug messages to console
|
||||
-l, --log <FILE> Enable file logging and set location
|
||||
-t, --installto <DIR> Installation directory to install the application
|
||||
-d, --debug <FILE> Debug mode, install from a nupkg file
|
||||
-h, --help Print help
|
||||
```
|
||||
@@ -0,0 +1,41 @@
|
||||
*Applies to: Windows, MacOS, Linux*
|
||||
|
||||
# Debugging Velopack
|
||||
|
||||
## Logging
|
||||
All parts of Velopack have logging built in to help troubleshoot issues, and you should provide these logs when opening a GitHub issue about a potential bug.
|
||||
|
||||
### UpdateManager / In your application
|
||||
You should provide an instance of `Microsoft.Extensions.Logging.ILogger` to `VelopackApp.Run(ILogger)` and to `UpdateManager` to record potential issues. If you are not using Microsoft Hosting or Logging already, it is very simple to implement this interface yourself and log to a file, or integrate with another logging framework.
|
||||
|
||||
For example:
|
||||
```cs
|
||||
using Microsoft.Extensions.Logging;
|
||||
|
||||
// ...
|
||||
|
||||
class ConsoleLogger : ILogger
|
||||
{
|
||||
public IDisposable BeginScope<TState>(TState state) where TState : notnull => null;
|
||||
public bool IsEnabled(LogLevel logLevel) => true;
|
||||
public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception exception, Func<TState, Exception, string> formatter)
|
||||
=> Console.WriteLine(formatter(state, exception));
|
||||
}
|
||||
|
||||
// ...
|
||||
|
||||
new UpdateManager("https://path.to/your-updates", logger: new ConsoleLogger());
|
||||
```
|
||||
|
||||
### Windows
|
||||
Running Update.exe will log most output to it's base directory as `Velopack.log`. Setup.exe will not log to file by default. However, you can override the log location for both binaries with the `--log {path}` parameter. You can also use the `--verbose` flag to capture debug/trace output to log. Unfortunately, on Windows, to avoid showing up as a console window, these binaries are compiled as a WinExe and there will be no console output by default. Please see the [command line reference](cli.md) for a comprehensive list of arguments supported.
|
||||
|
||||
### MacOS / Linux
|
||||
All logs will be sent to `/tmp/velopack.log`.
|
||||
|
||||
## Advanced Debugging
|
||||
The debug builds of Velopack binaries have additional logging/debugging capabilities, and will produce console output. In some instances, it may be useful to [compile Velopack](../compiling.md) for your platform, and replace the release binaries of Setup.exe and Update.exe with debug versions.
|
||||
|
||||
If your issue is with package building, after building the rust binaries in Debug mode, it can also be useful to run the Velopack.Vpk project from Visual Studio with your intended command line arguments rather than running the `vpk` tool directly.
|
||||
|
||||
If doing this has not helped, you may need to debug and step through the rust binaries - for which I recommend the CodeLLDB VSCode extension.
|
||||
@@ -0,0 +1,4 @@
|
||||
- name: Debugging / Logging
|
||||
href: debugging.md
|
||||
- name: Command Line Reference
|
||||
href: cli.md
|
||||
@@ -0,0 +1,19 @@
|
||||
*Applies to: Windows*
|
||||
|
||||
# Windows Shortcuts
|
||||
By default, during installation Velopack will create a shortcut on the Desktop and in the StartMenuRoot. It will automatically delete any shortcuts it finds when uninstalling the application.
|
||||
|
||||
The name of the shortcuts will be determined by the `--packTitle` vpk argument. For example, if you pass `--packTitle "My Fancy App"`, then the shortcuts created will be created as `"My Fancy App.lnk"`.
|
||||
|
||||
If you need to create shortcuts in any extra locations, the `Velopack.Windows.Shortcuts` and `Velopack.Windows.ShellLink` classes are provided. These classes are provided for legacy reasons, and in general the stability of such functions is not guarenteed.
|
||||
|
||||
For example, if you wished to create a shortcut during the install of your app, you might do the following:
|
||||
|
||||
```cs
|
||||
using Velopack;
|
||||
using Velopack.Windows;
|
||||
|
||||
VelopackApp.Build()
|
||||
.WithAfterInstallFastCallback((v) => new Shortcuts().CreateShortcutForThisExe(ShortcutLocation.Desktop))
|
||||
.Run()
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
- name: Overview
|
||||
href: overview.md
|
||||
- name: Windows Shortcuts
|
||||
href: shortcuts.md
|
||||
@@ -0,0 +1,11 @@
|
||||
# Velopack Documentation
|
||||
🚧🚧This documentation is still under construction.🚧🚧
|
||||
|
||||
## FAQ
|
||||
- **My application was detected as a virus?** <br/>
|
||||
Velopack can't help with this, but you can [code-sign](packaging/signing.md) your app and check [other suggestions here](https://github.com/clowd/Clowd.Squirrel/issues/28#issuecomment-1016241760).
|
||||
- **What happened to SquirrelAwareApp? / Shortcuts** <br/>
|
||||
This concept no longer exists in Velopack. You can create hooks on install/update in a similar way using the `VelopackApp` builder. Although note that creating shortcuts or registry entries yourself during hooks is no longer required.
|
||||
- **Can Velopack bootstrap new runtimes during updates?** <br/>
|
||||
Yes, this is fully supported. Before installing updates, Velopack will prompt the user to install any missing updates.
|
||||
|
||||
Reference in New Issue
Block a user