updated readme

scriptingosx · scriptingosx · commit 67270d69b835 · 2026-02-15T17:15:43.000+01:00
diff --git a/README.md b/README.md
@@ -1,14 +1,40 @@
 # `quickpkg` - Build packages quickly
 
-This tool will quickly and easily build a package from an installed application, a disk image file or zip archive with an enclosed application bundle. It will also extract the application name and version and use it to name the resulting `pkg` file. 
+This tool will quickly and easily build a package from an installed application, a disk image file, or zip/xip archive with an enclosed application bundle. It will also extract the application name, version, identifier, and minimum OS version and use them for the resulting `pkg` file.
 
 The tool will look for applications on the first level of the disk image or archive. If it finds no or more than one application it will error.
 
 The name of the resulting package will be of the form `{name}-{version}.pkg`. Spaces will be removed from the name. The package will be written to the current working directory.
 
-## Dependencies
+## Implementations
 
-Apple will remove the Python 2.7 binary at `/usr/local/python` from macOS in macOS Monterey 12.3. This script is built and tested with [the MacAdmins "Managed Python."](https://github.com/macadmins/python) It should (probably) work with other Python 3 distributions, as well, but has not been tested on any.
+Two implementations are available:
+
+- [**Swift** (v2.0)](https://github.com/scriptingosx/quickpkg/releases/latest) - Primary implementation requiring macOS 15+
+- [**Python** (v1.0)](https://github.com/scriptingosx/quickpkg/releases/tag/v1.0) - _Legacy_ implementation using [MacAdmins Managed Python](https://github.com/macadmins/python)
+
+The Swift version includes additional features like distribution packages, automatic minimum OS version detection, and compression options.
+
+## Installation
+
+### Swift Version (Recommended)
+
+Build from source:
+
+```bash
+git clone https://github.com/scriptingosx/quickpkg.git
+cd quickpkg
+swift build -c release
+sudo cp .build/release/quickpkg /usr/local/bin/
+```
+
+### Python Version
+
+Requires [MacAdmins Managed Python](https://github.com/macadmins/python) or another Python 3 distribution.
+
+```bash
+sudo cp quickpkg /usr/local/bin/
+```
 
 ## Examples
 
@@ -21,7 +47,7 @@ quickpkg /Applications/Numbers.app
 Build package from a disk image:
 
 ```
-quickpkg ~/Downloads/Firefox\ 43.0.4.dmg
+quickpkg ~/Downloads/Firefox.dmg
 ```
 
 Build package from a zip archive:
@@ -30,27 +56,71 @@ Build package from a zip archive:
 quickpkg ~/Downloads/Things.zip
 ```
 
+Build package from an xip archive:
+
+```
+quickpkg ~/Downloads/Xcode.xip
+```
+
+Build a signed distribution package:
+
+```
+quickpkg /Applications/MyApp.app --sign "Developer ID Installer: Your Name"
+```
+
+Build a component package (instead of distribution):
+
+```
+quickpkg /Applications/MyApp.app --component
+```
+
 ## Options
 
-### `--scripts scripts_folder`:
+### Installation Scripts
+
+#### `--scripts <folder>`
+
+Pass a folder with scripts that are passed to `pkgbuild`'s `--scripts` option. If there is a `preinstall` and/or `postinstall` script they will be run at the respective times and can call other scripts in this folder.
+
+#### `--postinstall <script>` (or `--post`)
+
+Use the script file given as a postinstall script. If given together with the `--scripts` option will attempt to merge the two and error if a `postinstall` script is already present.
+
+#### `--preinstall <script>` (or `--pre`)
+
+Use the script file given as a preinstall script. If given together with the `--scripts` option will attempt to merge the two and error if a `preinstall` script is already present.
+
+### Package Options
+
+#### `--install-location <path>`
+
+Set the install location for the application. Default is `/Applications`.
+
+#### `--ownership <recommended|preserve|preserve-other>`
 
-Pass a folder with scripts that are passed to `pkgbuild`'s `--scripts` option. If the there is a `preinstall` and/or `postinstall` script they will be run at the respective and can call other scripts in this folder.
+This parameter will be passed to `pkgbuild`. See `man pkgbuild` for details.
 
-### `--postinstall postinstall_script`
+#### `--compression <latest|legacy>` (v2.0)
 
-Use the script file given as a postinstall script. If given together with the `-scripts` option will attempt to merge the two and error if a `postinstall` script is already present.
+Set the compression type for the package. Default is `latest`.
 
-### `--preinstall preinstall_script`
+#### `--component` / `--distribution` (v2.0)
 
-Use the script file given as a preinstall script. If given together with the `-scripts` option will attempt to merge the two and error if a `preinstall` script is already present.
+Choose the package type. Default is `--distribution` which wraps the component package using `productbuild`. Use `--component` for a simple component package.
 
-### `--ownership {recommended,preserve,preserve-other}`
+#### `--[no-]relocatable`
 
-This parameter will be passed into `pkgbuild`. Default is `recommended`. See `man pkgbuild` for details.
+Controls whether the resulting pkg file is relocatable, i.e. if the installer process will search for the bundle by bundle-identifier if it was moved to another location. By default packages are created **non-relocatable**.
 
-### `--output pkgpath`
+#### `--[no-]clean`
 
-Will write the resulting package to `pkgpath` instead of the current working directory. If `pkgpath` is a directory, then the default package name (`{name}-{version}.pkg`) is used. You can also give the complete path, including a name. You can use the placeholders `{name}`, `{version}` and `{identifier}` in the name.
+Controls whether temporary files are cleaned up after building. Default is `--clean`.
+
+### Output Options
+
+#### `--output <path>` (or `-o`)
+
+Write the resulting package to `<path>` instead of the current working directory. If `<path>` is a directory, then the default package name (`{name}-{version}.pkg`) is used. You can also give the complete path, including a name. You can use the placeholders `{name}`, `{version}` and `{identifier}` in the name.
 
 Examples:
 
@@ -64,37 +134,49 @@ Will create `Numbers-X.Y.Z.pkg` in `~/Packages`.
 quickpkg /Applications/Numbers.app --output Numbers_latest.pkg
 ```
 
-will create `Numbers_latest.pkg` in the current working directory.
+Will create `Numbers_latest.pkg` in the current working directory.
 
 ```
 quickpkg /Applications/Numbers.app --output ~/Packages/{identifier}_{version}.pkg
 ```
 
-will create `com.apple.Numbers_X.Y.Z.pkg` in `~/Packages`.
+Will create `com.apple.Numbers_X.Y.Z.pkg` in `~/Packages`.
+
+### Signing Options
+
+#### `--sign <identity>`
+
+Sign the resulting package with the specified identity. Usually a "Developer ID Installer" certificate from your Apple Developer account.
 
-### `--[no-]relocatable`
+#### `--keychain <path>`
 
-Controls wether the resulting pkg file is relocatable, i.e. if the installer process will search for the bundle by bundle-identifier if it was moved to another location. By default  packages will be created NON-relocatable.
+Specify a keychain to search for the signing identity.
 
-## `--sign`, `--keychain` and `--cert`
+#### `--cert <path>`
 
-You can add these options to sign the resulting package. These three options are passed through to the `pkgbuild` command. Read the `pkgbuild` man page for details.
+Specify an intermediate certificate to embed in the package.
 
-Usually you can find the proper signing identity (from the Apple Developer account) with the command
+You can find available signing identities with:
 
 ```
-$ security find-identity -p basic -v
+security find-identity -p basic -v
 ```
 
-and then you add the proper identity with the `--sign` option.
+Example:
 
 ```
-$ quickpkg ~/Downloads/Firefox\ 53.0.3.dmg --sign "3rd Party Mac Developer Installer: Your Name Here"
+quickpkg ~/Downloads/Firefox.dmg --sign "Developer ID Installer: Your Name"
 ```
 
+### Verbosity
+
+#### `-v`, `-vv`, `-vvv`
+
+Increase verbosity. Use `-v` for basic info, `-vv` for more detail, `-vvv` for full command output including all shell commands.
+
 ## Background
 
-OS X has had the `pkgbuild` tool since Xcode 3.2 on Snow Leopard. With pkgbuild you can directly build a installer package from an application in the `/Applications` folder:
+macOS has had the `pkgbuild` tool since Xcode 3.2 on Snow Leopard. With pkgbuild you can directly build an installer package from an application in the `/Applications` folder:
 
 ```
 pkgbuild --component /Applications/Numbers.app Numbers.pkg
@@ -110,22 +192,17 @@ pkgbuild --component /Volumes/Firefox/Firefox.app \
 
 This tool even does the work of determining a bundle's identifier and version and sets the identifier and version of the pkg to the same values.
 
-However, while `pkgbuild` does automatically name the package, it does not include the version, which is important when you tracking many versions of the same application. It also doesn't automatically look into a `dmg` file or `zip` archive. 
+However, while `pkgbuild` does automatically name the package, it does not include the version, which is important when tracking many versions of the same application. It also doesn't automatically look into a `dmg` file or `zip` archive.
 
 ## `quickpkg` vs `autopkg`
 
 This tool is not meant to replace [`autopkg`](https://github.com/autopkg/autopkg). `autopkg` will automate the download, the re-packaging (if necessary) and the upload to and configuration of your client management system. It can also handle much more complex setups than `quickpkg`. `autopkg` is far superior and should be your tool of choice.
 
-However, there are situations where `autopkg` does not work well. The most common reason is if the download cannot be automated because the download page is behind a paywall. Or maybe you are just experimenting with a test server and do not want to change your production `autopkg` setup. Also `autopkg` requires a recipe for a given piece of software. If no recipe exists, `quickpkg` may be a simple alternative. (Though if `quickpkg` works, creating an `autopkg` recipe should not be hard.) 
-
-## `quickpkg` vs `munkipkg`
-
-`quickpkg` is meant for 'quick' packaging. No configuration, no options. Download the application from the AppStore or the dmg or zip from the web and go. (I started working on it because I could never remember the exact options needed for `pkgbuild`.) [`munkipkg`](https://github.com/munki/munki-pkg/) is a tool that makes it easier to access the complex options of `pkgbuild` and `packagebuild`, but it still supports complex projects. 
+However, there are situations where `autopkg` does not work well. The most common reason is if the download cannot be automated because the download page is behind a paywall. Or maybe you are just experimenting with a test server and do not want to change your production `autopkg` setup. Also `autopkg` requires a recipe for a given piece of software. If no recipe exists, `quickpkg` may be a simple alternative. (Though if `quickpkg` works, creating an `autopkg` recipe should not be hard.)
 
-If you prefer a UI rather than a command line tool, then use [Stéphane Sudre's Packages](http://s.sudre.free.fr/Software/Packages/about.html).
 
 ## Warning
 
-All `quickpkg` does is identify an application bundle and package it in a way that the package will install that application bundle into the `/Applications` folder. If the application needs other files (libraries, frameworks, configuration files, license files, preferences etc.) to run and work they are your responsibility.
+All `quickpkg` does is identify an application bundle and package it in a way that the package will install that application bundle into the `/Applications` folder (or another location specified with `--install-location`). If the application needs other files (libraries, frameworks, configuration files, license files, preferences etc.) to run and work they are your responsibility.
 
-Also be sure to understand what you are running `quickpkg` against. If you run `quickpkg` on the disk image you get from DropBox or for the Adobe Flash Player, you will get a pkg that installs the DropBox or Flash Player installer in the `/Applications` folder. Probably not what you wanted.
+Also be sure to understand what you are running `quickpkg` against. For example, when you run `quickpkg` on the disk image you get from DropBox, you will get a pkg that installs the DropBox installer in the `/Applications` folder. Probably not what you wanted.
