actool - compiles, prints, updates, and verifies asset
catalogs.
actool [options] document
actool verifies, updates, and prints the contents of an
asset catalog, generating its output in standard plist format. The tool
follows a "read", "modify", "write",
"print" order of operations.
- --output-format
format
- By default, actool provides output in the form of an XML property list.
Specifying binary1 will instruct actool to output a binary property
list. Similarly, xml1 specifies an XML property list, and
human-readable-text specifies human readable text.
- --compile
path
- Compiles document and writes the output to the specified directory
path. The name of the CAR file will be Assets.car. The compile
option instructs actool to convert an asset catalog to files optimized for
runtime. Additionally, --warnings, --errors, and
--output-format are three other options that are commonly combined
with --compile.
- --warnings
- Include document warning messages in actool's plist output. Warnings will
appear under the key com.apple.actool.document.warnings, with
messages listed under the subkey message and warning types
under the subkey type.
- --errors
- Include document error messages in actool's plist output. Errors will
appear under the key com.apple.actool.document.errors, with messages
listed under the subkey message and error types under the
subkey type.
- --notices
- Include document notice messages in actool's plist output. Notices will
appear under the key com.apple.actool.document.notices, with
messages listed under the subkey message and error types
under the subkey type.
- --output-partial-info-plist
path
- Emit a plist to path that contains keys and values to include in an
application's info plist. path is the full path to the info plist,
and should have the path extension .plist specified. The plist is
populated with information gathered while compiling the CAR file, and
currently contains information about the app icon and launch images used
by the project. During builds, the information produced here will be
merged into the target bundle's Info.plist.
- --app-icon
name
- Can be combined with --compile to select a primary app icon. The
app icon will either be copied into the output directory specified by
--compile, or into the generated CAR file, depending on the value
of --minimum-deployment-target. Deploying to macOS 10.13 or iOS
11.0 and later will cause the app icon to be included in the generated CAR
file. A partially defined image is still generated into the output path,
but this behavior may go away in the future. This flag also causes actool
to declare the app icon in the partial info plist component specified by
--output-partial-info-plist.
- --include-all-app-icons
- When compiling, causes all app icon assets from all named catalogs to be
included in the compiled CAR file. The value for --app-icon will be
the primary app icon, and the additional icon names will be added to the
partial info plist.
- --alternate-app-icon
name
- Specifies an additional app icon set name to include in the compiled CAR
file and listed in the partial info plist. Can be specified multiple
times. This is an alternative to --include-all-app-icons providing
more detailed control.
- --launch-image
name
- Can be combined with --compile to select a launch image to compile
to the output directory, for most platforms. On tvOS, the launch image is
compiled into the resulting CAR file. This flag also causes actool to
declare the launch image in the partial info plist component specified by
--output-partial-info-plist.
- --accent-color
name
- Selects a named color to use as the target's primary accent or tint color.
A warning is generated if the referenced color is missing. When the color
is present and has a non-empty value, the NSAccentColorName key is added
to the partial info plist file specified by
--output-partial-info-plist.
- --widget-background-color
name
- Selects a named color to use for the background color, if the target is a
widget. A warning is generated if the referenced color is missing. When
the color is present and has a non-empty value, the color name is added to
the partial info plist file specified by
--output-partial-info-plist.
- --skip-app-store-deployment
- Whether to perform App Store-specific behaviors such as validations. For
example, building for an iOS or watchOS app will warn if a 1024 App Store
icon is not present, but only when compiling for App Store deployment. You
might want to pass --skip-app-store-deployment for targets that are
not intended to be submitted to the App Store.
- --include-partial-info-plist-localizations
yes|no
- When enabled, includes the localization information of the selected assets
in the generated partial Info.plist file under the
CFBundleLocalizations key. This will allow the assets to be used at
runtime in the absence of a corresponding lproj directory in the bundle.
The default value is YES.
- --platform
platform-name
- Specifies the target platform to compile for. This option influences
warnings, validation, and which images are included in the built product.
- --minimum-deployment-target
version
- Specifies the minimum deployment target to compile for. This option
influences warnings, validation, and which images are included in the
built product.
- --standalone-icon-behavior
default|all|none
- Controls whether loose PNG or ICNS files are created for the app icon, in
addition to including the content in the Assets.car file. By default, a
small subset of sizes are included as loose files, allowing external
management tools to display a representative icon without reading the CAR
file. This can be set to all or none to include more or
fewer icon sizes as loose files.
- --target-device
device-name
- Specifies the target device to compile for, and may be passed multiple
times. This option influences warnings, validation, and which images are
included in the built product.
- --compress-pngs
- PNGs copied into iOS targets will be processed using pngcrush to
optimize reading the images on iOS devices. This has no effect for images
that wind up in the compiled CAR file, as it only affects PNG images
copied in to the output bundle.
- --filter-for-device-model
device
- Causes actool to filter the files put into the CAR file by device. This
simulates how the App Store will thin the developer's application. For
example, if you pass iPhone9,1, actool will only include images
appropriate to iPhone 7. This is useful for testing to make sure thinned
applications will work properly. During build time, this is driven by the
TARGET_DEVICE_MODEL build setting, and is selected by choosing the
active run destination in the scheme pop-up. When the argument is not
present, no thinning will occur.
- --filter-for-device-os-version
os_version
- Causes actool to filter the files put into the CAR file by OS version.
This simulates how the App Store will thin the developer's application
based on the final target OS of the app. For example, if you pass
/fI11.0/fR, actool will only include images appropriate to iOS 11.0, but
not previous versions. This is useful for testing to make sure thinned
applications will work properly.
- --include-sticker-content
- Include sticker pack content from the input asset catalogs.
- --stickers-icon-role
role
- Pass app-host or extension to select the appropriate icon
sizes for the target when using a Messages-style app icon.
- --sticker-pack-identifier-prefix
prefix
- Sets the default prefix used to identify your sticker path. This should be
a valid domain type identifier. For example: com.mycompany.
- --sticker-pack-strings-file
strings_file
- Specifies a string file that maps the stickers names to localized
translations.
- --product-type
product-type
- Deprecated; use the --include-sticker-content and --stickers-icon-role
options instead.
Sets the type of the product that's being built. In Xcode, all
targets have a product type, and certain product types will cause
slightly different behaviors in actool. These behaviors are currently
centered around how stickers generate their content, as sticker packs
have special requirements for where and how content should be formatter.
actool currently recognizes two special product types:
com.apple.product-type.app-extension.messages-sticker-pack and
com.apple.product-type.app-extension.messages.
- --enable-on-demand-resources
- Tells actool to process on-demand resources. This may result in multiple
CAR files being produced. Without this option, actool ignores ODR tags
found in the asset catalog.
- --asset-pack-output-specifications
filename
- Tells actool where to write the information about ODR resources found in
the asset catalog. The emitted file will be a plist.
- --version
- Print the version of actool. The version information is output under the
key com.apple.actool.version with the subkeys bundle-version
and short-bundle-version.