From 2f6079572d92457b62d716b84a41857297084e1c Mon Sep 17 00:00:00 2001 From: Caelan Sayler Date: Fri, 15 Dec 2023 14:17:49 +0000 Subject: [PATCH] fix repo line endings --- docs/contributing/vs-solution-overview.md | 58 +++++------ docs/getting-started/3-distributing.md | 2 +- docs/getting-started/4-installing.md | 8 +- docs/goals.md | 4 +- docs/using/application-signing.md | 82 ++++++++-------- docs/using/delta-packages.md | 2 +- docs/using/loading-gif.md | 2 +- docs/using/machine-wide-installs.md | 72 +++++++------- docs/using/squirrel-command-line.md | 2 +- docs/using/update-manager.md | 114 +++++++++++----------- 10 files changed, 173 insertions(+), 173 deletions(-) diff --git a/docs/contributing/vs-solution-overview.md b/docs/contributing/vs-solution-overview.md index b5ff0d160..2f4a8dae8 100644 --- a/docs/contributing/vs-solution-overview.md +++ b/docs/contributing/vs-solution-overview.md @@ -1,29 +1,29 @@ -| [docs](..) / [contributing](.) / vs-solution-overview.md -|:---| - -# Visual Studio Solution Overview - -An overview of the various projects in the Squirrel.Windows Visual Studio solution and how they relate to different aspects of the update process. - - -| Project / Assembly Name | Libraries (NuGet) | Libraries (NuGet) | Releases Directory (releasify output) | MyApp (install location) | -|--------------------------------|---------|-----|------------------|-------------| -| **Core** NuGet.Squirrel.dll | NuGet.Squirrel.dll | | | | -| **Squirrel** Squirrel.dll | Squirrel.dll | | | | -| **SyncRelease** SyncRelease.exe | | SyncRelease.exe | | | -| **Update** Update.exe | | Squirrel.exe | | Update.exe | -| **Setup** Setup.exe | | Setup.exe | Setup.exe (+MyApp.Latest.nupkg) | | -| **WriteZipToSetup** WriteZipToSetup.exe | | WriteZipToSetup.exe | | | - -* **Project / Assembly Name**: Solution project name (from Squirrel.sln) and output assembly name. -* **Libraries (NuGet)**: Program libraries installed added as references in your MyApp solution when adding the Squirrel.Windows NuGet package to your project. -* **Libraries (NuGet)**: Executable tools included in the Squirrel.Windows NuGet package used to prepare deployments via the Package Manager Console (e.g., Squirrel.exe). -* **Releases Directory (releasify output)**: Directory where the Squirrel --releasify process outputs the packages and Setup application for your project (e.g., MyAppSourceCode/Releases). -* **MyApp (install location)**: MyApp install directory (e.g., %LOCALAPPDATA%\MyApp) where the application is actually installed and updated via Squirrel.Windows. - -**Note**: Note that the Squirrel.exe application found in the tools directory of the Squirrel.Windows NuGet package is actually a renamed version of the Update.exe application (see Squirrel.Windows\src\Squirrel.nuspec) - ---- -| Return: [Table of Contents](../readme.md) | -|----| - +| [docs](..) / [contributing](.) / vs-solution-overview.md +|:---| + +# Visual Studio Solution Overview + +An overview of the various projects in the Squirrel.Windows Visual Studio solution and how they relate to different aspects of the update process. + + +| Project / Assembly Name | Libraries (NuGet) | Libraries (NuGet) | Releases Directory (releasify output) | MyApp (install location) | +|--------------------------------|---------|-----|------------------|-------------| +| **Core** NuGet.Squirrel.dll | NuGet.Squirrel.dll | | | | +| **Squirrel** Squirrel.dll | Squirrel.dll | | | | +| **SyncRelease** SyncRelease.exe | | SyncRelease.exe | | | +| **Update** Update.exe | | Squirrel.exe | | Update.exe | +| **Setup** Setup.exe | | Setup.exe | Setup.exe (+MyApp.Latest.nupkg) | | +| **WriteZipToSetup** WriteZipToSetup.exe | | WriteZipToSetup.exe | | | + +* **Project / Assembly Name**: Solution project name (from Squirrel.sln) and output assembly name. +* **Libraries (NuGet)**: Program libraries installed added as references in your MyApp solution when adding the Squirrel.Windows NuGet package to your project. +* **Libraries (NuGet)**: Executable tools included in the Squirrel.Windows NuGet package used to prepare deployments via the Package Manager Console (e.g., Squirrel.exe). +* **Releases Directory (releasify output)**: Directory where the Squirrel --releasify process outputs the packages and Setup application for your project (e.g., MyAppSourceCode/Releases). +* **MyApp (install location)**: MyApp install directory (e.g., %LOCALAPPDATA%\MyApp) where the application is actually installed and updated via Squirrel.Windows. + +**Note**: Note that the Squirrel.exe application found in the tools directory of the Squirrel.Windows NuGet package is actually a renamed version of the Update.exe application (see Squirrel.Windows\src\Squirrel.nuspec) + +--- +| Return: [Table of Contents](../readme.md) | +|----| + diff --git a/docs/getting-started/3-distributing.md b/docs/getting-started/3-distributing.md index 78ca990f7..a53d329e1 100644 --- a/docs/getting-started/3-distributing.md +++ b/docs/getting-started/3-distributing.md @@ -1,7 +1,7 @@ | [docs](..) / [getting-started](.) / 3-distributing.md | |:---| -# Step 3. Distributing +# Step 3. Distributing After packaging MyApp for distribution, the various files in the `Releases` directory are used to distribute MyApp to users. diff --git a/docs/getting-started/4-installing.md b/docs/getting-started/4-installing.md index 8f212655c..45911557d 100644 --- a/docs/getting-started/4-installing.md +++ b/docs/getting-started/4-installing.md @@ -1,8 +1,8 @@ | [docs](..) / [getting-started](.) / 4-installing.md | |:---| -# Step 4. Installing - -The process to install MyApp is as simple as executing the `Setup.exe` application. `Setup.exe` is generated by the `Squirrel --releasify` process and is located in the `Releases` directory. +# Step 4. Installing + +The process to install MyApp is as simple as executing the `Setup.exe` application. `Setup.exe` is generated by the `Squirrel --releasify` process and is located in the `Releases` directory. ## Setup.exe @@ -22,7 +22,7 @@ An installation for MyApp will look like the following after the initial install #### `%LocalAppData%\MyApp` Directory -![](images/1.3-local-app-data-dir.png) +![](images/1.3-local-app-data-dir.png) --- diff --git a/docs/goals.md b/docs/goals.md index 1eae720f2..24168bb86 100644 --- a/docs/goals.md +++ b/docs/goals.md @@ -1,8 +1,8 @@ | [docs](.) / goals.md | |:---| -# What Do We Want? - +# What Do We Want? + Deployment and Updates for Desktop applications are a real drag. ClickOnce almost works, but has some glaring bugs that don't seem like they'll ever be fixed. So let's own our own future and build a new one. 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 diff --git a/docs/using/application-signing.md b/docs/using/application-signing.md index adf288796..695e8eaa9 100644 --- a/docs/using/application-signing.md +++ b/docs/using/application-signing.md @@ -1,41 +1,41 @@ -| [docs](..) / [using](.) / application-signing.md -|:---| - - -# Application Signing - -Signing your installer with a valid code signing certificate is one of the most important things that you need to do for production apps. Both IE SmartScreen as well as virus scanning software will give a significant amount of "points" to apps that are signed correctly, preventing your users from getting scary dialogs. - -Acquire a code-signing certificate - it's recommended to get a Windows Error Reporting-compatible certificate, see this [MSDN article](https://msdn.microsoft.com/library/windows/hardware/hh801887.aspx) for more information, then pass the -n parameter, which are the parameters you would pass to `signtool.exe sign` to sign the app. - -Squirrel makes signing easy, as it signs all of your application's executables *as well* as the final generated Setup.exe. - -An example invocation including both of these features would be something like: - -~~~powershell -PM> Squirrel --releasify MyApp.1.0.0.nupkg -n "/a /f CodeCert.pfx /p MySecretCertPassword /fd sha256 /tr http://timestamp.digicert.com /td sha256" -~~~ - -If you are using the [Visual Studio Build Packaging](visual-studio-packaging.md) process be careful how you escape your quotation marks in the `XML` of your `.csproj` file for the -n, --signWithParams argument. The wrapping quotation marks must be defined in `XML` safe ampersand escape strings or `"`. Within this command you will likely need quotation marks around your certificate password. Since this is already within a quoted string you will need to double quote the password: `/p ""PASSWORD""`. - -~~~xml - - - - - - - - -~~~ - - - -## See Also -* [Squirrel Command Line](squirrel-command-line.md) - command line options for `Squirrel --releasify` -* [Visual Studio Build Packaging](visual-studio-packaging.md) - integrating Squirrel packaging into your build process - - ---- -| Return: [Table of Contents](../readme.md) | -|----| +| [docs](..) / [using](.) / application-signing.md +|:---| + + +# Application Signing + +Signing your installer with a valid code signing certificate is one of the most important things that you need to do for production apps. Both IE SmartScreen as well as virus scanning software will give a significant amount of "points" to apps that are signed correctly, preventing your users from getting scary dialogs. + +Acquire a code-signing certificate - it's recommended to get a Windows Error Reporting-compatible certificate, see this [MSDN article](https://msdn.microsoft.com/library/windows/hardware/hh801887.aspx) for more information, then pass the -n parameter, which are the parameters you would pass to `signtool.exe sign` to sign the app. + +Squirrel makes signing easy, as it signs all of your application's executables *as well* as the final generated Setup.exe. + +An example invocation including both of these features would be something like: + +~~~powershell +PM> Squirrel --releasify MyApp.1.0.0.nupkg -n "/a /f CodeCert.pfx /p MySecretCertPassword /fd sha256 /tr http://timestamp.digicert.com /td sha256" +~~~ + +If you are using the [Visual Studio Build Packaging](visual-studio-packaging.md) process be careful how you escape your quotation marks in the `XML` of your `.csproj` file for the -n, --signWithParams argument. The wrapping quotation marks must be defined in `XML` safe ampersand escape strings or `"`. Within this command you will likely need quotation marks around your certificate password. Since this is already within a quoted string you will need to double quote the password: `/p ""PASSWORD""`. + +~~~xml + + + + + + + + +~~~ + + + +## See Also +* [Squirrel Command Line](squirrel-command-line.md) - command line options for `Squirrel --releasify` +* [Visual Studio Build Packaging](visual-studio-packaging.md) - integrating Squirrel packaging into your build process + + +--- +| Return: [Table of Contents](../readme.md) | +|----| diff --git a/docs/using/delta-packages.md b/docs/using/delta-packages.md index 5bb288946..ef84462d9 100644 --- a/docs/using/delta-packages.md +++ b/docs/using/delta-packages.md @@ -2,7 +2,7 @@ |:---| -# Delta Packages +# Delta Packages Now, once we've got a full package, we need to generate a Delta package. To do this, we'll replace all the DLL/EXEs in the NuGet packages with bsdiff files. [bspatch/bsdiff](http://code.logos.com/blog/2010/12/binary_patching_with_bsdiff.html) is a mostly efficient algorithm for calculating diffs between binary files (especially Native binaries, but it works well for .NET ones too), and a way to apply them. diff --git a/docs/using/loading-gif.md b/docs/using/loading-gif.md index 2f0effafe..b45d8ca2e 100644 --- a/docs/using/loading-gif.md +++ b/docs/using/loading-gif.md @@ -1,7 +1,7 @@ | [docs](..) / [using](.) / loading-gif.md |:---| -# Loading GIF +# Loading GIF Squirrel installers don't have any UI - the goal of a Squirrel installer is to install so blindingly fast that double-clicking on Setup.exe *feels* like double-clicking on an app shortcut. Make your installer **fast**. diff --git a/docs/using/machine-wide-installs.md b/docs/using/machine-wide-installs.md index e1e43f8d3..bb166d343 100644 --- a/docs/using/machine-wide-installs.md +++ b/docs/using/machine-wide-installs.md @@ -1,36 +1,36 @@ -| [docs](..) / [using](.) / machine-wide-installs.md -|:---| - - -# Machine-wide Installs - -Squirrel's Releasify command generates an MSI file suitable for installation via Group Policy. This MSI isn't a general-purpose installer, this means that once you run the MSI, users from now on will get the app installed, on next Login. - -So, most normal users should continue to run the Setup.exe's generated by Releasify, but if you want to have an IT Admin Friendly version, you can hand off the MSI - -## Common pitfalls - -### Missing data in `.nuspec` - -Most users of Squirrel won't have to do anything new to enable this behavior, though certain NuGet package IDs / names might cause problems with MSI. - -**Source:** See [issue #466](https://github.com/Squirrel/Squirrel.Windows/issues/466) for more details. - -### Nothing happens on login - -In cases where the end user has previously installed your application, the installer that runs on login will not re-install your application on every login. This can easily be the case if you as a developer is testing out both the EXE and the MSI. - -Squirrel leaves behind an almost-empty `%LocalAppData%\MyApp` folder after an uninstall. Deleting this folder (the entire folder, not just the contents) will allow the installer that runs on login to install successfully. - -**Source:**: See [issue #555](https://github.com/Squirrel/Squirrel.Windows/issues/555#issuecomment-253265130) for details. - -## Disabling MSI Generation -Generating MSIs can be disabled via the --no-msi flag as shown below: - -~~~powershell -PM> Squirrel --releasify MyApp.1.0.0.nupkg --no-msi -~~~ - ---- -| Return: [Table of Contents](../readme.md) | -|----| +| [docs](..) / [using](.) / machine-wide-installs.md +|:---| + + +# Machine-wide Installs + +Squirrel's Releasify command generates an MSI file suitable for installation via Group Policy. This MSI isn't a general-purpose installer, this means that once you run the MSI, users from now on will get the app installed, on next Login. + +So, most normal users should continue to run the Setup.exe's generated by Releasify, but if you want to have an IT Admin Friendly version, you can hand off the MSI + +## Common pitfalls + +### Missing data in `.nuspec` + +Most users of Squirrel won't have to do anything new to enable this behavior, though certain NuGet package IDs / names might cause problems with MSI. + +**Source:** See [issue #466](https://github.com/Squirrel/Squirrel.Windows/issues/466) for more details. + +### Nothing happens on login + +In cases where the end user has previously installed your application, the installer that runs on login will not re-install your application on every login. This can easily be the case if you as a developer is testing out both the EXE and the MSI. + +Squirrel leaves behind an almost-empty `%LocalAppData%\MyApp` folder after an uninstall. Deleting this folder (the entire folder, not just the contents) will allow the installer that runs on login to install successfully. + +**Source:**: See [issue #555](https://github.com/Squirrel/Squirrel.Windows/issues/555#issuecomment-253265130) for details. + +## Disabling MSI Generation +Generating MSIs can be disabled via the --no-msi flag as shown below: + +~~~powershell +PM> Squirrel --releasify MyApp.1.0.0.nupkg --no-msi +~~~ + +--- +| Return: [Table of Contents](../readme.md) | +|----| diff --git a/docs/using/squirrel-command-line.md b/docs/using/squirrel-command-line.md index 8b28ac589..e88534546 100644 --- a/docs/using/squirrel-command-line.md +++ b/docs/using/squirrel-command-line.md @@ -1,7 +1,7 @@ | [docs](..) / [using](.) / squirrel-command-line.md |:---| -# Squirrel Command Line +# Squirrel Command Line Here is a simplified help output specifically around creating releases: diff --git a/docs/using/update-manager.md b/docs/using/update-manager.md index bcfc977d5..db240a5bf 100644 --- a/docs/using/update-manager.md +++ b/docs/using/update-manager.md @@ -1,57 +1,57 @@ -| [docs](..) / [using](.) / update-manager.md -|:---| - -# Update Manager Reference - -## Basic Updating - -The "Easy Mode" method that does everything all in one go. - -* `UpdateApp` - downloads and updates the app to the latest version. - -## Advanced Updating - -The following methods are provided to allow you to have more control of the update process (i.e., to interact with app updates and apply them if desired). - -* `CheckForUpdate` - checks on the server if there are updates available. Returns an `UpdateInfo` object that contains information about any pending updates. - -* `DownloadReleases` - downloads release files (the `nupkg` file deltas) from the server to the local machine - -* `ApplyReleases` - installs the downloaded packages, and returns the new `app-[version]` directory path. - -### UpdateInfo - -The `UpdateInfo` class contains information about available and installed releases. - -~~~cs -public class UpdateInfo -{ - public ReleaseEntry CurrentlyInstalledVersion; - public ReleaseEntry FutureReleaseEntry; - public List ReleasesToApply; -} -~~~ - -### ReleaseEntry - -The `ReleaseEntry` class contains the specifics of each release. - -~~~cs -public interface ReleaseEntry -{ - public string SHA1; - public string Filename; - public long Filesize; - public bool IsDelta; -} -~~~ - - -## See Also -* [Update Process](update-process.md) - overview of the steps in the update process. -* [GitHub Update Manager](github.md) - process of using `GitHubUpdateManager`. - ---- -| Return: [Table of Contents](../readme.md) | -|----| - +| [docs](..) / [using](.) / update-manager.md +|:---| + +# Update Manager Reference + +## Basic Updating + +The "Easy Mode" method that does everything all in one go. + +* `UpdateApp` - downloads and updates the app to the latest version. + +## Advanced Updating + +The following methods are provided to allow you to have more control of the update process (i.e., to interact with app updates and apply them if desired). + +* `CheckForUpdate` - checks on the server if there are updates available. Returns an `UpdateInfo` object that contains information about any pending updates. + +* `DownloadReleases` - downloads release files (the `nupkg` file deltas) from the server to the local machine + +* `ApplyReleases` - installs the downloaded packages, and returns the new `app-[version]` directory path. + +### UpdateInfo + +The `UpdateInfo` class contains information about available and installed releases. + +~~~cs +public class UpdateInfo +{ + public ReleaseEntry CurrentlyInstalledVersion; + public ReleaseEntry FutureReleaseEntry; + public List ReleasesToApply; +} +~~~ + +### ReleaseEntry + +The `ReleaseEntry` class contains the specifics of each release. + +~~~cs +public interface ReleaseEntry +{ + public string SHA1; + public string Filename; + public long Filesize; + public bool IsDelta; +} +~~~ + + +## See Also +* [Update Process](update-process.md) - overview of the steps in the update process. +* [GitHub Update Manager](github.md) - process of using `GitHubUpdateManager`. + +--- +| Return: [Table of Contents](../readme.md) | +|----| +