diff --git a/docs/index.md b/docs/index.md index 5e210c04..726f3876 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,35 +2,4 @@ _layout: landing --- -# Velopack Documentation -🚧🚧This documentation is still under construction.🚧🚧 - -## FAQ - - **My application was detected as a virus?**
- Velopack can't help with this, but you can [code-sign](signing.md) your app and check [other suggestions here](https://github.com/clowd/Clowd.Squirrel/issues/28#issuecomment-1016241760). - - **What happened to SquirrelAwareApp? / Shortcuts**
- 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?**
- Yes, this is fully supported. Before installing updates, Velopack will prompt the user to install any missing updates. - -## Using Velopack -- [Migrating to Velopack](migrating.md) -- [Logging & Debugging](debugging.md) -- [Command Line Reference](cli.md) -- Packaging Releases - - Overview - - Release Channels - - Installer Overview & Customisation - - [Code Signing](signing.md) - - [Boostrapping frameworks (.NET, .Net Framework, VCRedist, etc)](bootstrapping.md) - - Specify app RID / supported OS versions / supported architecture -- Distributing Releases - - Overview - - CI / CD Tips & Examples - - Deploying to GitHub Releases - - Deploying to Amazon S3 Storage (or compatible, eg. B2, Linode) -- Updating - - Overview - - Rolling back to a previous release - - [Windows Shortcuts](shortcuts.md) - - Customising updates (AfterInstall, BeforeUninstall, BeforeUpdate, AfterUpdate hooks) +# WIP diff --git a/docs/pages/compiling.md b/docs/pages/compiling.md index 4cd4c613..90e6f3e5 100644 --- a/docs/pages/compiling.md +++ b/docs/pages/compiling.md @@ -1,9 +1,6 @@ -| [docs](.) / compiling.md | -|:---| - -# Compiling Velopack *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 diff --git a/docs/pages/distributing/overview.md b/docs/pages/distributing/overview.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/pages/distributing/toc.yml b/docs/pages/distributing/toc.yml new file mode 100644 index 00000000..4e54b9da --- /dev/null +++ b/docs/pages/distributing/toc.yml @@ -0,0 +1,2 @@ +- name: Overview + href: overview.md \ No newline at end of file diff --git a/docs/pages/getting-started/samples.md b/docs/pages/getting-started/samples.md deleted file mode 100644 index fe96c8d7..00000000 --- a/docs/pages/getting-started/samples.md +++ /dev/null @@ -1,5 +0,0 @@ -# Velopack Examples - -- [**AvaloniaCrossPlat**](AvaloniaCrossPlat) - uses Avalonia to provide a desktop UI, installer, and updates for Mac, Linux, and Windows. - -- [**VeloWpfSample**](VeloWpfSample) - demonstrates how to use Velopack effectively with WPF. \ No newline at end of file diff --git a/docs/pages/getting-started/toc.yml b/docs/pages/getting-started/toc.yml index becfa7e8..e64467d6 100644 --- a/docs/pages/getting-started/toc.yml +++ b/docs/pages/getting-started/toc.yml @@ -1,4 +1,2 @@ - name: C# / .NET - href: csharp.md -- name: Sample Apps - href: samples.md \ No newline at end of file + href: csharp.md \ No newline at end of file diff --git a/docs/pages/migrating.md b/docs/pages/migrating.md index e9e6969c..c427d784 100644 --- a/docs/pages/migrating.md +++ b/docs/pages/migrating.md @@ -1,8 +1,6 @@ -| [docs](.) / migrating.md | -|:---| +*Applies to: Windows* # Migrating to Velopack -*Applies to: Windows* ## Squirrel.Windows and Clowd.Squirrel If you are using one of these packages in your application, migrating will be mostly automated. Here are the general steps needed: @@ -14,7 +12,7 @@ If you are using one of these packages in your application, migrating will be mo 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]](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: +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) { diff --git a/docs/pages/packaging/bootstrapping.md b/docs/pages/packaging/bootstrapping.md index cbdffa4d..37b999c1 100644 --- a/docs/pages/packaging/bootstrapping.md +++ b/docs/pages/packaging/bootstrapping.md @@ -1,9 +1,6 @@ -| [docs](.) / bootstrapping.md | -|:---| - -# Bootstrapping *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: diff --git a/docs/pages/channels.md b/docs/pages/packaging/channels.md similarity index 99% rename from docs/pages/channels.md rename to docs/pages/packaging/channels.md index 503789b6..bf0debc0 100644 --- a/docs/pages/channels.md +++ b/docs/pages/packaging/channels.md @@ -1,9 +1,6 @@ -| [docs](.) / channels.md | -|:---| - -# Release Channels *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. diff --git a/docs/pages/packaging/index.md b/docs/pages/packaging/index.md deleted file mode 100644 index 67b076e0..00000000 --- a/docs/pages/packaging/index.md +++ /dev/null @@ -1 +0,0 @@ -Hello! test \ No newline at end of file diff --git a/docs/pages/packaging/installer.md b/docs/pages/packaging/installer.md new file mode 100644 index 00000000..972d9b33 --- /dev/null +++ b/docs/pages/packaging/installer.md @@ -0,0 +1,2 @@ +*Applies to: Windows, MacOS* +# Customising Installers diff --git a/docs/pages/packaging/overview.md b/docs/pages/packaging/overview.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/pages/packaging/rid.md b/docs/pages/packaging/rid.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/pages/packaging/signing.md b/docs/pages/packaging/signing.md index 5ed2faa3..0876473e 100644 --- a/docs/pages/packaging/signing.md +++ b/docs/pages/packaging/signing.md @@ -1,9 +1,6 @@ -| [docs](.) / signing.md | -|:---| - -# Code Signing *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. @@ -47,7 +44,7 @@ Codesigning and Notarization is required before your application can be run by u ### 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. ![apple certificate list](artwork/apple_certificate_list.png) +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. ![apple certificate list](~/artwork/apple_certificate_list.png) 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 diff --git a/docs/pages/packaging/toc.yml b/docs/pages/packaging/toc.yml index d6906b04..408a2f0b 100644 --- a/docs/pages/packaging/toc.yml +++ b/docs/pages/packaging/toc.yml @@ -1,4 +1,12 @@ +- name: Overview + href: overview.md +- name: Release Channels + href: channels.md - name: Code Signing href: signing.md +- name: Customising Installers + href: installer.md - name: Boostrapping frameworks (.NET, .Net Framework, VCRedist, etc) - href: bootstrapping.md \ No newline at end of file + href: bootstrapping.md +- name: RID / Minimum Supported OS + href: rid.md \ No newline at end of file diff --git a/docs/pages/toc.yml b/docs/pages/toc.yml index 0382ef07..bf4e4bc8 100644 --- a/docs/pages/toc.yml +++ b/docs/pages/toc.yml @@ -1,35 +1,31 @@ +- name: Welcome + href: welcome.md + - name: Getting Started href: getting-started/toc.yml -- name: Migrating to Velopack - href: migrating.md -- name: Logging / Debugging - href: debugging.md -- name: Command Line Reference - href: cli.md + +- name: Sample Apps + items: + - name: Avalonia / Cross Platform + href: https://github.com/velopack/velopack/tree/master/examples/AvaloniaCrossPlat + - name: WPF Windows + href: https://github.com/velopack/velopack/tree/master/examples/VeloWpfSample + - name: Packaging Releases href: packaging/toc.yml - homepage: packaging/index.md +- name: Distributing Releases + href: distributing/toc.yml +- name: Updating + href: updating/toc.yml + +- name: Troubleshooting + href: troubleshooting/toc.yml + +- name: Migrating to Velopack + href: migrating.md + +- name: Contributing + href: compiling.md -# ## Using Velopack -# - [Migrating to Velopack](migrating.md) -# - [Logging & Debugging](debugging.md) -# - [Command Line Reference](cli.md) -# - Packaging Releases -# - Overview -# - Release Channels -# - Installer Overview & Customisation -# - [Code Signing](signing.md) -# - [Boostrapping frameworks (.NET, .Net Framework, VCRedist, etc)](bootstrapping.md) -# - Specify app RID / supported OS versions / supported architecture -# - Distributing Releases -# - Overview -# - CI / CD Tips & Examples -# - Deploying to GitHub Releases -# - Deploying to Amazon S3 Storage (or compatible, eg. B2, Linode) -# - Updating -# - Overview -# - Rolling back to a previous release -# - [Windows Shortcuts](shortcuts.md) -# - Customising updates (AfterInstall, BeforeUninstall, BeforeUpdate, AfterUpdate hooks) diff --git a/docs/pages/cli.md b/docs/pages/troubleshooting/cli.md similarity index 99% rename from docs/pages/cli.md rename to docs/pages/troubleshooting/cli.md index d4c5464d..facb8a4d 100644 --- a/docs/pages/cli.md +++ b/docs/pages/troubleshooting/cli.md @@ -1,8 +1,6 @@ -| [docs](.) / cli.md | -|:---| +*Applies to: Windows, MacOS, Linux* # Velopack Command Line Reference -*Applies to: Windows, MacOS, Linux* ## vpk ```txt diff --git a/docs/pages/debugging.md b/docs/pages/troubleshooting/debugging.md similarity index 92% rename from docs/pages/debugging.md rename to docs/pages/troubleshooting/debugging.md index f575bfca..18ae51bd 100644 --- a/docs/pages/debugging.md +++ b/docs/pages/troubleshooting/debugging.md @@ -1,8 +1,6 @@ -| [docs](.) / debugging.md | -|:---| +*Applies to: Windows, MacOS, Linux* # Debugging Velopack -*Applies to: Windows, MacOS, Linux* ## 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. @@ -36,7 +34,7 @@ Running Update.exe will log most output to it's base directory as `Velopack.log` 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. +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. diff --git a/docs/pages/troubleshooting/toc.yml b/docs/pages/troubleshooting/toc.yml new file mode 100644 index 00000000..9544eacf --- /dev/null +++ b/docs/pages/troubleshooting/toc.yml @@ -0,0 +1,4 @@ +- name: Command Line Reference + href: cli.md +- name: Debugging / Logging + href: debugging.md \ No newline at end of file diff --git a/docs/pages/updating/overview.md b/docs/pages/updating/overview.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/pages/shortcuts.md b/docs/pages/updating/shortcuts.md similarity index 96% rename from docs/pages/shortcuts.md rename to docs/pages/updating/shortcuts.md index d229c0a9..2777a05f 100644 --- a/docs/pages/shortcuts.md +++ b/docs/pages/updating/shortcuts.md @@ -1,9 +1,6 @@ -| [docs](.) / shortcuts.md | -|:---| - -# Windows Shortcuts *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"`. diff --git a/docs/pages/updating/toc.yml b/docs/pages/updating/toc.yml new file mode 100644 index 00000000..6cd13c93 --- /dev/null +++ b/docs/pages/updating/toc.yml @@ -0,0 +1,4 @@ +- name: Overview + href: overview.md +- name: Windows Shortcuts + href: shortcuts.md \ No newline at end of file diff --git a/docs/pages/welcome.md b/docs/pages/welcome.md new file mode 100644 index 00000000..e519f50c --- /dev/null +++ b/docs/pages/welcome.md @@ -0,0 +1,11 @@ +# Velopack Documentation +🚧🚧This documentation is still under construction.🚧🚧 + +## FAQ + - **My application was detected as a virus?**
+ 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**
+ 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?**
+ Yes, this is fully supported. Before installing updates, Velopack will prompt the user to install any missing updates. +