mirror of
https://github.com/velopack/velopack.git
synced 2025-10-25 15:19:22 +00:00
Update README.md
This commit is contained in:
Caelan Sayler
GitHub
109
README.md
109
README.md
@@ -1,22 +1,18 @@
|
||||
| README.md |
|
||||
|:---|
|
||||
|
||||
# Contributors Needed
|
||||
[](https://www.nuget.org/packages/Clowd.Squirrel/)
|
||||
|
||||
We are looking for help with maintaining this important project - please read the discussion in [#1470](https://github.com/Squirrel/Squirrel.Windows/issues/1470) for more information.
|
||||
# Clowd.Squirrel
|
||||
|
||||
Squirrel is both a set of tools and a library, to completely manage both installation and updating your Desktop Windows application.
|
||||
|
||||
This project is a fork of the library [Squirrel.Windows](https://github.com/Squirrel/Squirrel.Windows), which has been largely discontinued by the author. The main focus here has been to update to more modern tooling, such as upgrading the main libraries to `netstandard2.0`.
|
||||
|
||||
This library will help you build a `Setup.exe`, integrated (or standalone `Update.exe`) application updater, and release updates to your users very quickly and easily. The `Setup.exe` and `Update.exe` produced by this library are completely dependency free, and can even help you bootstrap/install a runtime of your choice (such as dotnet 5, .net 4.8 or others).
|
||||
|
||||
---
|
||||
|
||||
# Squirrel: It's like ClickOnce but Works™
|
||||
|
||||
|
||||
|
||||
[](https://dev.azure.com/squirrel-installers/Squirrel.Windows/_build/latest?definitionId=1&branchName=master)
|
||||
|
||||
Squirrel is both a set of tools and a library, to completely manage both installation and updating your Desktop Windows application, written in either C# or any other language (i.e., Squirrel can manage native C++ applications).
|
||||
|
||||
Squirrel uses NuGet packages to create installation and update packages, which means that you probably already know most of what you need to create an installer.
|
||||
|
||||
## What Do We Want?
|
||||
|
||||
Windows apps should be as fast and as easy to install and update as apps like Google Chrome. From an app developer's side, it should be really straightforward to create an installer for my app, and publish updates to it, without having to jump through insane hoops.
|
||||
@@ -27,27 +23,96 @@ Windows apps should be as fast and as easy to install and update as apps like Go
|
||||
* **Installing** is Wizard-Free™, with no UAC dialogs, does not require reboot, and is .NET Framework friendly.
|
||||
* **Updating** is in the background, doesn't interrupt the user, and does not require a reboot.
|
||||
|
||||
Refer to our full list of goals for [integrating, packaging, distributing, installing, and updating](docs/goals.md).
|
||||
---
|
||||
|
||||
## Documentation
|
||||
## Quick Start For .NET Apps
|
||||
|
||||
See the documentation [Table of Contents](docs/readme.md) for an overview of the available documentation for Squirrel.Windows. It includes a [Getting Started Guide](docs/getting-started/0-overview.md) as well as additional topics related to using Squirrel in your applications.
|
||||
1. Install the [Clowd.Squirrel Nuget Package](https://www.nuget.org/packages/Clowd.Squirrel/)
|
||||
|
||||
2. Add SquirrelAwareVersion attribute somewhere in your project. (It can be placed in any cs file, but usually it goes into `AssemblyInfo.cs` if your project has one)
|
||||
|
||||
```cs
|
||||
[assembly: AssemblyMetadata("SquirrelAwareVersion", "1")]
|
||||
```
|
||||
3. Handle Squirrel events somewhere very early in your application startup (such as the beginning of `main()` or `Application.OnStartup()` for WPF).
|
||||
|
||||
```cs
|
||||
SquirrelAwareApp.HandleEvents(
|
||||
onInitialInstall: OnInstall,
|
||||
onAppUpdate: OnUpdate,
|
||||
onAppUninstall: OnUninstall,
|
||||
onFirstRun: OnFirstRun);
|
||||
```
|
||||
|
||||
When installed, uninstalled or updated, your app will be run to give you a chance to add or remove application shortcuts.
|
||||
|
||||
```cs
|
||||
private static void OnInstall(Version obj)
|
||||
{
|
||||
using var mgr = new UpdateManager("https://the.place/you-host/updates");
|
||||
mgr.CreateUninstallerRegistryEntry();
|
||||
mgr.CreateShortcutForThisExe(ShortcutLocation.StartMenu | ShortcutLocation.Desktop);
|
||||
}
|
||||
```
|
||||
|
||||
4. Publish your app and build a Nuget package with your publish output in the "lib/net45" target folder. (yes, even if your app does not have anything to do with net45)
|
||||
You can use `NuGet.exe pack` for this, or any other Nuget creation tool (eg. OctoPack). <br/>
|
||||
[More information here](docs/using/visual-studio-packaging.md#example-nuspec-file-for-myapp) <br/>
|
||||
*Note: The package version must comply to strict SemVer syntax. (eg. `1.0.0`, `1.0.1-pre`)*
|
||||
|
||||
5. Create a Squirrel release using the `Squirrel.com --releasify` command line tool.
|
||||
It is shipped with the [Clowd.Squirrel](https://www.nuget.org/packages/Clowd.Squirrel/) nuget package.
|
||||
The path of the Squirrel tools is available via the MSBuild property `$(SquirrelToolsPath)` if you are integrating this into your build pipeline.
|
||||
If not, the tools can usually be found at:
|
||||
- `%username%\.nuget\packages\Clowd.Squirrel\tools`, or;
|
||||
- `..\packages\Clowd.Squirrel\tools`
|
||||
|
||||
Once you have located the tools folder, create a release. Example below with some useful options, but explore `Squirrel.com -h` for a complete list. You should use the same `releaseDir` each time, so delta updates can be generated.
|
||||
```cmd
|
||||
Squirrel.com --releasify MyApp.1.0.0 --selfContained --releaseDir=".\releases" --setupIcon=myIcon.ico
|
||||
```
|
||||
|
||||
6. Distribute your entire `releaseDir` folder online. This folder can be hosted on any static web/file server, [Amazon S3](docs/using/amazon-s3.md), BackBlaze B2, or even via [GitHub Releases](docs/using/github.md).
|
||||
|
||||
7. Update your app periodically with UpdateManager.
|
||||
```cs
|
||||
using var mgr = new UpdateManager("https://the.place/you-host/updates");
|
||||
var newVersion = await mgr.UpdateApp();
|
||||
|
||||
// optionally restart the app automatically, or ask the user if/when they want to restart
|
||||
if (newVersion != null) {
|
||||
UpdateManager.RestartApp();
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start For Native / Other Apps
|
||||
|
||||
This quick start guide is coming soon. Refer to below for complete docs which contains native app instructions.
|
||||
|
||||
---
|
||||
|
||||
## More Documentation
|
||||
|
||||
See the documentation [Table of Contents](docs/readme.md) for an overview of the available documentation.
|
||||
|
||||
---
|
||||
|
||||
## Building Squirrel
|
||||
For the impatient:
|
||||
|
||||
```sh
|
||||
git clone --recursive https://github.com/squirrel/squirrel.windows
|
||||
cd squirrel.windows
|
||||
.\.NuGet\NuGet.exe restore
|
||||
msbuild /p:Configuration=Release
|
||||
```cmd
|
||||
git clone https://github.com/clowd/Clowd.Squirrel
|
||||
cd clowd/Clowd.Squirrel
|
||||
build.cmd
|
||||
```
|
||||
See [Contributing](docs/contributing/contributing.md) for additional information on building and contributing to Squirrel.
|
||||
|
||||
See [Contributing](docs/contributing/contributing.md) for additional information on building and contributing to Squirrel.
|
||||
|
||||
## License and Usage
|
||||
|
||||
See [COPYING](COPYING) for details on copyright and usage of the Squirrel.Windows software.
|
||||
See [COPYING](COPYING) for details on copyright and usage.
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user