|0.17.0||Nov 17, 2023|
|0.15.0||Nov 9, 2023|
|0.13.0||Dec 21, 2022|
|0.11.0||Oct 2, 2022|
|0.2.0||Mar 28, 2022|
#36 in macOS and iOS APIs
4,756 downloads per month
Used in 13 crates (via apple-codesign)
This crate implements an interface to Apple's flat package installer package
file format. This is the XAR-based installer package (
.pkg) format used since
The interface is in pure Rust and doesn't require the use of Apple specific
tools or hardware to run. The functionality in this crate could be used to
reimplement Apple installer tools like
Apple flat packages.
Apple flat packages - often existing as
.pkg files - are an installer
file format used by macOS.
Flat packages are Apple-flavored XAR archives. XAR is a tar-like
file format consisting of file records/metadata and raw file data.
apple-xar crate for more on this file format.
Flat packages come in 2 flavors: component packages and product
packages. Component packages contain a single component. Product
installers can contain multiple components as well as additional
metadata describing the installer. End-user
.pkg files are typically
product packages. Using Apple tooling, component packages are built
pkgbuild and product packages using
A component defines an installable unit. Components are comprised of a set of well-known files:
A bill of materials describing the contents of the component.
An XML file describing the component. See [PackageInfo] for the Rust
struct defining this file format.
A cpio archive containing files comprising the component. See the
cpio-archive for more on this file format.
A cpio archive containing scripts files that run as part of component
A product flat package consists of 1 or more components and additional metadata.
A product flat package is identified by the presence of a
XML file in the root of the archive. See [Distribution] for the Rust type
defining this file format. See also
Apple's XML documentation.
Components within a product flat package exist in sub-directories which often
have the name
In addition, a product flat package may also have additional resource files
Cryptographic message syntax (CMS) / RFC 5652 signatures can be embedded in the XAR archive's table of contents, which is a data structure at the beginning of the XAR defining the content within.
The cryptographic signature is over the checksum content digest, which is also captured in the XAR table of contents. This checksum effectively captures the content of all files within the XAR.
Nested Archive Formats
Flat packages contain multiple data structures that effectively enumerate lists of files. There are many layers to the onion and there is duplication of functionality to express file manifests.
- XAR archives contain a table of contents enumerating files within the XAR.
- Each component has
Scriptsfiles, which are cpio archives. These cpio archives are file manifests containing file metadata and content.
- Each component may have a
Bom, which is a binary data structure defining file metadata as well as other attributes.
There are also multiple layers that involve compression:
- The XAR table of contents is likely compressed with zlib.
- Individual files within XAR archives can be individually compressed with a compression format denoted by a MIME type.
- cpio archive files may also be compressed.
- Installed files in components may also be compressed (but this file content is treated as opaque by the flat package format).