DOCSEARCHbyAlgolia
Submit Docs

Squirrel.Windows Documentation

repository·develop·Indexed 27 days ago

https://github.com/squirrel/squirrel.windows

A toolset and library for managing the installation and background updating of Windows desktop applications. Squirrel.Windows provides a seamless, wizard-free experience and is language-agnostic, supporting both C# and native C++ applications. It leverages NuGet packages for distribution and includes tools for packaging (releasify), distributing via platforms like GitHub, IIS, or Amazon S3, and managing the update lifecycle through the UpdateManager API.

Tokens
12.8K
Snippets
26
Records
85
Agent score
90%

What's inside Squirrel.Windows

  1. Overview of Squirrel.Windows

    develop
    Squirrel is a set of tools and a library designed to manage the complete lifecycle of Desktop Windows applications, including installation and updating. It is language-agnostic; while it supports C#, it can also manage native C++ applications. Squirrel leverages NuGet packages to create installation and update packages, making the packaging process familiar to many developers.

  2. How the UpdateManager performs application updates

    develop

    The UpdateManager (configured during integration) handles background updates automatically each time the application is executed.

    The update workflow is as follows:

    1. Check: The UpdateManager checks the RELEASES file at the specified distribution location for any new versions.
    2. Download & Prepare: If an update is found, the necessary update packages are downloaded and the new version of the application is prepared.
    3. Cleanup: App shortcuts are updated to point to the new version, and old version files are cleaned up.

    User Experience:

    • The first time the user runs the app after an update is available, the app runs the old version normally.
    • The update happens in the background.
    • The next time the user executes the application, they are running the newly installed version.

  3. Understand the Squirrel installation process and file structure

    develop

    When Setup.exe is executed, it performs the following steps:

    1. Creates a directory for the application under %LocalAppData%\MyApp.
    2. Extracts and prepares the application files into a versioned directory named app-x.x.x (e.g., app-1.0.0).
    3. Launches the main application executable (e.g., app-1.0.0\MyApp.exe) once the setup is complete.

    The final installation resides in the %LocalAppData%\MyApp directory.

  4. Understand the Setup.exe bootstrapper

    develop

    The Setup.exe is a C++ bootstrapper application generated during the Squirrel --releasify process. It serves as the entry point for installing your application on a user's local system.

    Key characteristics:

    • It bundles the Update.exe application and the latest version of your application package into a single executable.
    • It automatically ensures that .NET 4.5 is installed on the user's machine.
    • It uses the WriteZipToSetup.exe tool to inject necessary files into the single executable.

  5. Overview of the Squirrel.Windows integration workflow

    develop

    To use Squirrel.Windows for distributing and updating a Windows application, you must follow these five primary steps:

    1. Integrating: Incorporate the Squirrel UpdateManager into your application code.
    2. Packaging: Package your application files and prepare them for release.
    3. Distributing: Provide the necessary install and update files to your users.
    4. Installing: Manage the initial installation process of your application.
    5. Updating: Manage the process of updating an existing installation.

  6. Generate a Delta Package

    develop

    To create a Delta package from a full NuGet package, you must replace existing binary files (DLLs/EXEs) with bsdiff patches to reduce package size. Follow these steps:

    1. Extract the previous NuGet package.
    2. Extract the current NuGet package.
    3. For every EXE/DLL in the current package, replace it with a bsdiff file. For example, lib\net40\MyCoolApp.exe should become lib\net40\MyCoolApp.exe.diff.
    4. For each replaced file, create a .shasum file (e.g., lib\net40\MyCoolApp.exe.shasum) containing the SHA1 hash of the expected resulting file and its file size. This file follows the same format as the 'Releases' file used in the 'Latest' Pointer section.
    5. Include any new DLLs from the current package verbatim.
    6. Zip the resulting directory back into a package.

  7. Integrate Squirrel packaging into Visual Studio build process

    develop

    You can automate the creation of NuGet packages and Squirrel release files by adding an AfterBuild target to your .csproj file. This target extracts the assembly version, runs nuget pack to create a .nupkg file, and then runs squirrel --releasify to generate the final release assets.

    Ensure that nuget.exe is available in your environment (e.g., by installing the NuGet.CommandLine package) and that squirrel.exe is in your system PATH.

    <Target Name="AfterBuild" Condition=" '$(Configuration)' == 'Release'">
  <GetAssemblyIdentity AssemblyFiles="$(TargetPath)">
    <Output TaskParameter="Assemblies" ItemName="myAssemblyInfo"/>
  </GetAssemblyIdentity>
  <Exec Command="nuget pack MyApp.nuspec -Version %(myAssemblyInfo.Version) -Properties Configuration=Release -OutputDirectory $(OutDir) -BasePath $(OutDir)" />
  <Exec Command="squirrel --releasify $(OutDir)MyApp.$([System.Version]::Parse(%(myAssemblyInfo.Version)).ToString(3)).nupkg" />
</Target>

  8. Understand the Squirrel Update Process

    develop

    The UpdateManager automatically performs the following steps every time your application is executed:

    1. Check for Updates: Downloads the RELEASES file from the distribution location and compares it to the local RELEASES file.
    2. Download & Verify Update Packages: Determines whether to download delta packages or the latest full package based on which requires less total downloading. Packages are verified against their SHA1 hash specified in the RELEASES file.
    3. Build Full Package from Deltas: If delta packages were used, a new full package is constructed from the existing full package and the downloaded delta.
    4. Install New Version: Extracts the new version into a new %LocalAppData%\MyApp directory named after the version (e.g., app-1.0.1).
    5. Update Shortcuts: Updates desktop and Windows Start Menu shortcuts to point to the new version using the --processStart command line parameter passed to Update.exe.
    6. Previous Version Clean-up: On the subsequent startup of the application, Squirrel deletes all versions except for the current version and the immediately preceding version (e.g., if updated to app-1.0.5, app-1.0.4 is kept, but app-1.0.3 and older are removed).

  9. Distribute Squirrel updates via GitHub Releases

    develop

    To distribute your RELEASES file and NuGet update packages using GitHub, follow these steps for every release:

    1. Commit Latest Code: Ensure you have at least one additional commit since the last release tag. GitHub will not mark a new release as Latest if the tag points to the same commit as a previous release.
    2. Create a New Release: Create a new GitHub release matching your current version (e.g., 1.0.0).
    3. Upload Release Files: Upload all necessary files from your Releases folder as assets for that specific release. This includes:
      • The RELEASES file
      • Full packages (e.g., MyApp.1.0.0-full.nupkg)
      • Delta packages (e.g., MyApp.1.0.1-delta.nupkg)
    4. Set Pre-release (optional): Mark the release as a pre-release if desired.
    5. Publish the Release.

    Important: You must upload all packages as assets for the release. The GitHubUpdateManager does not look back at previous GitHub releases for older version packages. If you only upload the latest packages, Squirrel will be forced to download the latest full package for every update instead of using efficient delta updates.

  11. Distribute MyApp using Squirrel releases

    develop

    Once your application is packaged, the Releases directory contains the necessary files for distribution:

    • New User Installation: Provide the Setup.exe file to new users to install the current version of your application.
    • Updates: The update process requires the RELEASES file along with the versioned full and delta packages to perform updates.

  12. Add Squirrel packaging to TeamCity

    develop

    To automate the creation of release packages within a TeamCity build pipeline, you can use the squirrel executable to run the --releasify command. This process converts a .nupkg file (generated from a .nuspec file) into the final release format.

    1. Ensure your solution includes Squirrel via NuGet so that squirrel.exe is available in the packages directory.
    2. Add a NuGet Pack process to create the .nupkg file.
    3. Add a command line build step using the following command structure:
    %system.teamcity.build.workingdir%\packages\squirrel.windows.1.4.0\tools\squirrel --releasify [BUILD_SERVER_NUPKG_PATH]\%system.build.number%.nupkg -r [OUTPUT_PATH]

    Note: You must update the paths to match your specific project structure and the exact version of the squirrel.windows NuGet package you are using.