Skip to content
This repository has been archived by the owner on Jul 5, 2024. It is now read-only.

Commit

Permalink
fix repo line endings
Browse files Browse the repository at this point in the history
  • Loading branch information
caesay committed Dec 15, 2023
1 parent 8e21995 commit 2f60795
Show file tree
Hide file tree
Showing 10 changed files with 173 additions and 173 deletions.
58 changes: 29 additions & 29 deletions docs/contributing/vs-solution-overview.md
Original file line number Diff line number Diff line change
@@ -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) |
|----|

2 changes: 1 addition & 1 deletion docs/getting-started/3-distributing.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
8 changes: 4 additions & 4 deletions docs/getting-started/4-installing.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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)


---
Expand Down
4 changes: 2 additions & 2 deletions docs/goals.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
82 changes: 41 additions & 41 deletions docs/using/application-signing.md
Original file line number Diff line number Diff line change
@@ -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
<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)" />
<!-- Notice the use of &quot; rather than " after the \n flag. For the password to contain spaces we need to double-&quot; the string. -->
<Exec Command="squirrel --releasify $(OutDir)MyApp.$([System.Version]::Parse(%(myAssemblyInfo.Version)).ToString(3)).nupkg -n &quot;/a /f .\CertificateInProjectFolder.pfx /p &quot;&quot;CERTIFICATE PASSWORD&quot;&quot; /fd sha256 /tr http://timestamp.digicert.com /td sha256&quot;" />
</Target>
~~~



## 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 `&quot;`. 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 &quot;&quot;PASSWORD&quot;&quot;`.

~~~xml
<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)" />
<!-- Notice the use of &quot; rather than " after the \n flag. For the password to contain spaces we need to double-&quot; the string. -->
<Exec Command="squirrel --releasify $(OutDir)MyApp.$([System.Version]::Parse(%(myAssemblyInfo.Version)).ToString(3)).nupkg -n &quot;/a /f .\CertificateInProjectFolder.pfx /p &quot;&quot;CERTIFICATE PASSWORD&quot;&quot; /fd sha256 /tr http://timestamp.digicert.com /td sha256&quot;" />
</Target>
~~~



## 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) |
|----|
2 changes: 1 addition & 1 deletion docs/using/delta-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/using/loading-gif.md
Original file line number Diff line number Diff line change
@@ -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**.

Expand Down
72 changes: 36 additions & 36 deletions docs/using/machine-wide-installs.md
Original file line number Diff line number Diff line change
@@ -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) |
|----|
2 changes: 1 addition & 1 deletion docs/using/squirrel-command-line.md
Original file line number Diff line number Diff line change
@@ -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:

Expand Down
114 changes: 57 additions & 57 deletions docs/using/update-manager.md
Original file line number Diff line number Diff line change
@@ -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<ReleaseEntry> 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<ReleaseEntry> 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) |
|----|

0 comments on commit 2f60795

Please sign in to comment.