SparkleProject/sparkle-project.github.io
1
0
Fork 0
mirror of https://github.com/sparkle-project/sparkle-project.github.io.git synced 2025-11-01 15:35:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs update 2x (#66)

Browse Source 
* Update Sparkle 2.x paths, migration notes, code signing XPC Services

* Rename 1.x and 2.x to 1 and 2 where appropriate

* Update app cast example to use edSignature and remove Test App zip

* Update copyright to include initial release year
This commit is contained in:
Mayur Pawashe
2021-03-08 21:06:07 -08:00
committed by GitHub
parent fb49b0eb1e
commit 35dd50cf3a
9 changed files with 30 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_layouts/default.html
+1 -1
View File
@@ -84,7 +84,7 @@
<div class="row">
<div class="col-md-12">
<footer>
<p>©&#8202;{{ site.time | date: '%Y' }} Sparkle Project. All Rights Reserved.</p>
<p>© 2006 - &#8202;{{ site.time | date: '%Y' }} Sparkle Project. All Rights Reserved.</p>
<p>This website is <a rel="alternate" href="//github.com/{{ site.github_username }}/sparkle-project.github.io/blob/master/{{page.path}}">open source</a>.</p>
</footer>
</div>
documentation/bundles/index.md
+5 -5
View File
@@ -4,7 +4,7 @@ id: documentation
title: Bundles
---
### Sparkle 1.x
### Sparkle 1
#### Bundles
@@ -36,14 +36,14 @@ The subclass only needs to implement the following two methods:
return [self initForBundle:[NSBundle bundleForClass:[self class]]];
}
### Sparkle 2.x (Beta)
### Sparkle 2 (Beta)
#### Bundles
The story with updating bundles between Sparkle 1.x and 2.x is a bit different.
The story with updating bundles between Sparkle 1 and 2 is a bit different.
First, Sparkle 2.x supports updating any Sparkle-based bundle, which is not just limited to your own application or process. The updater distinguishes the `hostBundle` from the `applicationBundle`. The `hostBundle` is the bundle that Sparkle updates and the `applicationBundle` is the bundle that is re-launched (if applicable). See [Sparkle 2.x's APIs](/documentation/customization#sparkle-2x-apis-beta) for more information on instantiating your own updater.
First, Sparkle 2 supports updating any Sparkle-based bundle, which is not just limited to your own application or process. The updater distinguishes the `hostBundle` from the `applicationBundle`. The `hostBundle` is the bundle that Sparkle updates and the `applicationBundle` is the bundle that is re-launched (if applicable). See [Sparkle 2's APIs](/documentation/customization#sparkle-2x-apis-beta) for more information on instantiating your own updater.
Second, Sparkle 2.x doesn't keep track of shared updater instances and doesn't try to prohibit multiple updater instances from existing -- either inside the same process or multiple updaters updating the same bundle from different processes. In fact, it is even possible for one updater to start an update (say a silent deferred one), and for a second updater (say sparkle-cli) to resume that same update for the same bundle.
Second, Sparkle 2 doesn't keep track of shared updater instances and doesn't try to prohibit multiple updater instances from existing -- either inside the same process or multiple updaters updating the same bundle from different processes. In fact, it is even possible for one updater to start an update (say a silent deferred one), and for a second updater (say sparkle-cli) to resume that same update for the same bundle.
If you want to update a plug-in, injecting Sparkle.framework or sharing a version of Sparkle with the host process is not advisable. Instead, look into calling out to an out-of-process tool that can update the plug-in like [sparkle-cli](/documentation/sparkle-cli) can.
documentation/customization/index.md
+4 -4
View File
@@ -13,7 +13,7 @@ Here are the main routes by which you can bend Sparkle's behavior to your will:
| Key | Type | Value |
| --- | ---- | ----- | ------- |
| `SUFeedURL` | String | The URL of your appcast, e.g. `https://example.com/appcast.xml`. It's recommended to always set it in Info.plist, even if you change it later programmatically. |
| `SUEnableAutomaticChecks` | Boolean | Setting to `YES` (recommended) enables checking for updates (but not installation) by default, without asking your users for permission first. <br>By default, if it's not set to any value, users will be prompted for permission before the first update check. <br>Setting to `NO` disables update checks, but can be overridden by a call to `SUUpdater`'s (or `SPUUpdater`'s in 2.x) `setAutomaticallyChecksForUpdates:` |
| `SUEnableAutomaticChecks` | Boolean | Setting to `YES` (recommended) enables checking for updates (but not installation) by default, without asking your users for permission first. <br>By default, if it's not set to any value, users will be prompted for permission before the first update check. <br>Setting to `NO` disables update checks, but can be overridden by a call to `SUUpdater`'s (or `SPUUpdater`'s in 'Sparkle 2) `setAutomaticallyChecksForUpdates:` |
| `SUPublicEDKey` | String | The base64-encoded public EdDSA key. Use Sparkle's `generate_keys` tool to get it. |
| `SUEnableSystemProfiling` | Boolean | Default: `NO`. Enables anonymous system profiling. See [System Profiling](/documentation/system-profiling) for more. |
| `SUScheduledCheckInterval` | Number | The number of seconds between updates. The default is `86400` (1 day). Setting to 0 disables updates. <br /><br />**Note:** this has a minimum bound of 1 hour in order to keep you from accidentally overloading your servers. |
@@ -23,7 +23,7 @@ Here are the main routes by which you can bend Sparkle's behavior to your will:
| `SUBundleName` | String | Optional alternative bundle display name. For example, if your bundle name already has a version number appended to it, setting this may help smooth out certain messages, e.g. "MyApp 3 4.0 is now available" vs "MyApp 4.0 is now available". |
| `SUDefaultsDomain` | String | Optional alternative `NSUserDefaults` domain name if you don't want to use the standard user defaults, for example when accessing preferences from an App Group suite. |
### Sparkle 1.x APIs
### Sparkle 1 APIs
#### Calls to SUUpdater
@@ -141,7 +141,7 @@ If these methods aren't enough to do what you need, you're going to have to dig
---
### Sparkle 2.x APIs (Beta)
### Sparkle 2 APIs (Beta)
#### Calls to SPUUpdater
@@ -180,7 +180,7 @@ A few methods of interest if you are instantiating `SPUUpdater` programmatically
// Checks for updates and display progress while doing so. This is meant for users initiating an update check.
- (void)checkForUpdates;
The `SPUUserDriver` protocol is the API in Sparkle for controlling the user interface and interaction. If you are using `SPUStandardUpdaterController` in a nib, you can retrieve the user driver via its `userDriver` property. If you are interested in creating your own user interface, please see the header documentation in [`SPUUserDriver.h`](https://github.com/sparkle-project/Sparkle/blob/2.x/Sparkle/SPUUserDriver.h). Note few of the user-facing delegate methods in Sparkle 1.x's `SUUpdaterDelegate` were moved to `SPUStandardUserDriverDelegate`.
The `SPUUserDriver` protocol is the API in Sparkle for controlling the user interface and interaction. If you are using `SPUStandardUpdaterController` in a nib, you can retrieve the user driver via its `userDriver` property. If you are interested in creating your own user interface, please see the header documentation in [`SPUUserDriver.h`](https://github.com/sparkle-project/Sparkle/blob/2.x/Sparkle/SPUUserDriver.h). Note few of the user-facing delegate methods in Sparkle 1's `SUUpdaterDelegate` were moved to `SPUStandardUserDriverDelegate`.
Properties of interest if you are instantiating the standard user driver `SPUStandardUserDriver` yourself:
documentation/index.md
+4 -4
View File
@@ -7,7 +7,7 @@ title: Documentation
If your app already has an older version of Sparkle or you wish to migrate to Sparkle 2.0 beta, see [upgrading from previous versions](/documentation/upgrading/).
Note sandboxed applications are only supported in Sparkle 2.0 which is currently in beta.
Note sandboxed applications are only supported in Sparkle 2 (beta).
### 1. Add the Sparkle framework to your project
@@ -31,7 +31,7 @@ If you don't have CocoaPods, then add Sparkle manually:
* In <samp>Build Settings</samp> tab set "<samp>Runpath Search Paths</samp>" to `@loader_path/../Frameworks` (for non-Xcode projects add the flags `-Wl,-rpath,@loader_path/../Frameworks`). This is not a necessary step in recent versions of Xcode.
* If you have your own process for copying/packaging your app make sure it preserves symlinks!
CocoaPods and pre-built binaries for Sparkle 2.x aren't currently available. To build [2.x](https://github.com/sparkle-project/Sparkle/tree/2.x), clone Sparkle's repository with all its submodules, `git checkout 2.x` branch, run `make release`, and check out the binaries in the resulting `Sparkle-2.0.0.tar.xz` archive. Sandboxed applications using Sparkle 2.x require [additional setup](/documentation/sandboxing).
CocoaPods and official binaries for Sparkle 2 aren't currently available. A nightly distribution can be downloaded from our [GitHub Actions page](https://github.com/sparkle-project/Sparkle/actions?query=event%3Apush+is%3Asuccess+branch%3A2.x) by selecting a recent workflow commit and downloading the `Sparkle-distribution*.tar.xz` artifact. Alternatively, you may checkout the [2.x](https://github.com/sparkle-project/Sparkle/tree/2.x) branch, clone Sparkle's repository with all its submodules, run `make release`, and extract the binaries in the resulting `Sparkle-2.0.0.tar.xz` (or `.bz2`) archive. Sandboxed applications using Sparkle 2 require [additional setup](/documentation/sandboxing).
### 2. Set up a Sparkle updater object
@@ -45,7 +45,7 @@ These instructions are for regular .app bundles. If you want to update a non-app
* Type `SUUpdater` in the <samp>Class</samp> box of the <samp>Custom Class</samp> section in the inspector.
* If you'd like, make a "<samp>Check for Updates...</samp>" menu item in the application menu; set its target to the `SUUpdater` instance and its action to `checkForUpdates:`.
If you are using Sparkle 2.x, `SUUpdater` is a deprecated stub. While it is still functional for transitional purposes, new applications will want to use `SPUStandardUpdaterController` in the above steps instead.
If you are using Sparkle 2, `SUUpdater` is a deprecated stub. While it is still functional for transitional purposes, new applications will want to use `SPUStandardUpdaterController` in the above steps instead.
### 3. Segue for security concerns
@@ -59,7 +59,7 @@ Since Sparkle is downloading executable code to your users' systems, you must be
* Updates using [Installer package](/documentation/package-updates/) (`.pkg`) *must* be signed with EdDSA.
* [Binary Delta updates](/documentation/delta-updates/) *must* be signed with EdDSA.
* [Updates of preference panes and plugins](/documentation/bundles/) *must* be signed with EdDSA.
* EdDSA signatures are optional for updates using regular app bundles that are signed with Apple code signing (Apple's Developer ID program), but we still recommended EdDSA signatures as a backup. In Sparkle 2.x, not supplying EdDSA signatures will emit a deprecation warning.
* EdDSA signatures are optional for updates using regular app bundles that are signed with Apple code signing (Apple's Developer ID program), but we still recommended EdDSA signatures as a backup. In Sparkle 2, not supplying EdDSA signatures will emit a deprecation warning.
#### EdDSA (ed25519) signatures
documentation/preferences-ui/index.md
+2 -2
View File
@@ -5,7 +5,7 @@ title: Adding a Preferences UI
---
## Adding a Preferences UI
### Sparkle 1.x
### Sparkle 1
#### Add the updater to your preferences
@@ -45,7 +45,7 @@ Then just bind the controls to the File's Owner, and start the Model Key Path wi
---
### Sparkle 2.x (Beta)
### Sparkle 2 (Beta)
#### Add the updater to your preferences
documentation/sandboxing/index.md
+3 -3
View File
@@ -30,9 +30,9 @@ The last downloader XPC Service is optional. Use it only if your sandboxed appli
### Code Signing
**Note**: Skip this code signing step if you use Xcode's Archive Organizer to [Distribute your App](/documentation#4-distributing-your-app), which is the recommended way of distributing applications. It will manage re-signing these services in your application with the appropriate entitlements automatically.
**Note**: By default, Sparkle builds XPC Services with an ad-hoc signature and with the Hardened Runtime enabled. In many cases this may be suffice for development. If you use Xcode's Archive Organizer to [Distribute your App](/documentation#4-distributing-your-app), it will manage re-signing these services with a Developer ID certificate and preserve the applied entitlements automatically.
Otherwise, if you use other workflows you will also need to code sign these services by running:
Otherwise if you use alternate methods of distributing your application or you need to use a different certificate for development, you can code sign these services by running:
```
./bin/codesign_embedded_executable "Developer ID Application" XPCServices/*.xpc
@@ -57,5 +57,5 @@ I used "Developer ID Application" for my certificate; you may need to adjust thi
### Testing
Due to the XPC Services being code signed with the Hardened Runtime enabled, Xcode cannot debug the XPC Services and you may see that updating does not work when your application is attached to Xcode's debugger. You can work around this either by editing your project's Scheme and disabling *Debug XPC services used by app* or by testing your application detached from Xcode.
Due to the XPC Services being code signed with the Hardened Runtime enabled by default, Xcode cannot debug the XPC Services and you may see that updating does not work when your application is attached to Xcode's debugger. You can work around this either by editing your project's Scheme and disabling *Debug XPC services used by app* or by testing your application detached from Xcode.
documentation/upgrading/index.md
+10 -10
View File
@@ -10,9 +10,9 @@ We strongly recommend upgrading Sparkle to the [latest production release](//git
**Note**: Sparkle 2.0 is in a pre-release / beta state and not production ready yet.
The `SUUpdater` class has been deprecated and split up in Sparkle 2.x, but it is still functional for transitional purposes.
The `SUUpdater` class has been deprecated and split up in Sparkle 2, but it is still functional for transitional purposes.
Sparkle 2.x includes three new classes / protocols:
Sparkle 2 includes three new classes / protocols:
* **SPUUpdater** - The main API in Sparkle for controlling the update mechanism.
* **SPUUserDriver** - The API in Sparkle for controlling the user interface & interaction (`SPUStandardUserDriver` is the standard one).
* **SPUStandardUpdaterController** - A controller class that instantiates a `SPUUpdater` using `SPUStandardUserDriver` in a nib and allows [binding UI](/documentation/preferences-ui#sparkle-2x-beta) to it.
@@ -21,7 +21,7 @@ If you were previously instantiating a `SUUpdater` in a nib, you will want to ad
If you were previously instantiating a `SUUpdater` in code, you will want to adopt instantiating a `SPUUpdater`.
The deprecated `SUUpdater` in 2.x is now a stub that uses both a `SPUUpdater` and `SPUStandardUserDriver`.
The deprecated `SUUpdater` in 2 is now a stub that uses both a `SPUUpdater` and `SPUStandardUserDriver`.
If you create a `SPUUpdater` instance programatically, you can now create an updater that can update other Sparkle-based bundles and/or an updater that can use your own `SPUUserDriver` / user interface. [sparkle-cli](/documentation/sparkle-cli) makes use of both features as an example.
@@ -31,8 +31,8 @@ If you create a `SPUUpdater` instance programatically, you can now create an upd
If you have scripts that reference Sparkle.framework's helper tools, here are the new paths (note Autoupdate is now a command line tool and the UI bits moved to Updater.app):
```
Sparkle.framework/Versions/A/Resources/Autoupdate
Sparkle.framework/Versions/A/Resources/Updater.app/
Sparkle.framework/Autoupdate (symbolic link to Sparkle.framework/Versions/A/Autoupdate)
Sparkle.framework/Updater.app (symbolic link to Sparkle.framework/Versions/A/Updater.app)
```
Additionally, if you use the `InstallerLauncher` XPC Service, these helpers are in:
@@ -43,15 +43,15 @@ org.sparkle-project.InstallerLauncher.xpc/Contents/MacOS/Updater.app/
(In the case of using the `InstallerLauncher` XPC Service, the helpers in Sparkle.framework are unused and can optionally be removed; note in this case you may need to re-sign Sparkle.framework)
Please see the additional setup on using XPC Services and using Sparkle in [sandboxed applications](/documentation/sandboxing). Note using the XPC Services are only required for sandboxed applications, which Sparkle 1.x didn't support.
Please see the additional setup on using XPC Services and using Sparkle in [sandboxed applications](/documentation/sandboxing). Note using the XPC Services are only required for sandboxed applications, which Sparkle 1 didn't support.
If you use package (pkg) based updates, please see [Package Updates](/documentation/package-updates) for migration notes. In particular, your appcast items may need to include an appropriate installation type to help Sparkle decide if authorization is needed ahead of time.
If you use package (pkg) based updates, please see [Package Updates](/documentation/package-updates) for migration notes. In particular, your appcast items may need to include an appropriate installation type to help Sparkle decide if authorization is needed before starting the installer.
See [Sparkle 2.x's APIs](/documentation/customization#sparkle-2x-apis-beta) for more information.
See [Sparkle 2's APIs](/documentation/customization#sparkle-2x-apis-beta) for more information.
## Upgrading from Sparkle 1.26 and older
## Upgrading from Sparkle 1.25 and older
Support for serving bare, or non-archived, flat packages (`*.pkg` or `*.mpkg`) has been added, but you should still use archived packages until majority of your users update. Please see [Package Updates](/documentation/package-updates) for migration details.
Support for serving bare, or non-archived, flat packages (`*.pkg` or `*.mpkg`) has been added in Sparkle 1.26, but you should still use archived packages until majority of your users update. Please see [Package Updates](/documentation/package-updates) for migration details.
## Upgrading from Sparkle 1.20 and older
files/Sparkle Test App.zip
BIN
View File
Binary file not shown.
files/sparkletestcast.xml
+1 -1
View File
@@ -18,7 +18,7 @@
]]>
</description>
<pubDate>Sat, 26 Jul 2014 15:20:11 +0000</pubDate>
<enclosure url="https://sparkle-project.org/files/Sparkle%20Test%20App.zip" sparkle:version="2.0" length="107758" type="application/octet-stream" sparkle:dsaSignature="MCwCFCdoW13VBGJWIfIklKxQVyetgxE7AhQTVuY9uQT0KOV1UEk21epBsGZMPg==" />
<enclosure url="https://sparkle-project.org/files/Sparkle%20Test%20App.zip" sparkle:version="2.0" length="107758" type="application/octet-stream" sparkle:edSignature="7cLALFUHSwvEJWSkV8aMreoBe4fhRa4FncC5NoThKxwThL6FDR7hTiPJh1fo2uagnPogisnQsgFgq6mGkt2RBw==" />
</item>
</channel>
</rss>