Configuration

The path specified should not include -<target-triple><.exe> suffix, it will be auto-added when by the packager when reading these paths, so the actual binary name should have the target platform’s target triple appended, as well as .exe for Windows.

For example, if you’re packaging an external binary called sqlite3, the packager expects a binary named sqlite3-x86_64-unknown-linux-gnu on linux, and sqlite3-x86_64-pc-windows-gnu.exe on windows.

If you are building a universal binary for MacOS, the packager expects your external binary to also be universal, and named after the target triple, e.g. sqlite3-universal-apple-darwin. See <https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary>

fileAssociations

FileAssociation[] | null

The file associations

formats

PackageFormat[] | null

The packaging formats to create, if not present, [PackageFormat::platform_default] is used.

homepage

string | null

The package’s homepage.

icons

string[] | null

The app’s icon list. Supports glob patterns.

identifier

string | null pattern of ^[a-zA-Z0-9-\.]*$

The application identifier in reverse domain name notation (e.g. com.packager.example). This string must be unique across applications since it is used in some system configurations. This string must contain only alphanumeric characters (A–Z, a–z, and 0–9), hyphens (-), and periods (.).

licenseFile

string | null

A path to the license file.

linux

LinuxConfig | null

Linux-specific configuration

logLevel

LogLevel | null

The logging level.

longDescription

string | null

The app’s long description.

macos

MacOsConfig | null

MacOS-specific configuration.

name

string | null

The app name, this is just an identifier that could be used to filter which app to package using --packages cli arg when there is multiple apps in the workspace or in the same config.

This field resembles, the name field in Cargo.toml or package.json

If unset, the CLI will try to auto-detect it from Cargo.toml or package.json otherwise, it will keep it unset.

nsis

NsisConfig | null

Nsis configuration.

outDir

string

The directory where the generated packages will be placed.

If [Config::binaries_dir] is not set, this is also where the [Config::binaries] exist.

pacman

PacmanConfig | null

Pacman configuration.

productName

string

The package’s product name, for example “My Awesome App”.

publisher

string | null

The app’s publisher. Defaults to the second element in Config::identifier string. Currently maps to the Manufacturer property of the Windows Installer.

resources

Resource[] | null

The app’s resources to package. This a list of either a glob pattern, path to a file, path to a directory or an object of src and target paths. In the case of using an object, the src could be either a glob pattern, path to a file, path to a directory, and the target is a path inside the final resources folder in the installed package.

Format-specific:

[PackageFormat::Nsis] / [PackageFormat::Wix]: The resources are placed next to the executable in the root of the packager. - [PackageFormat::Deb]: The resources are placed in usr/lib of the package.

targetTriple

string | null

The target triple we are packaging for.

Defaults to the current OS target triple.

version

string

The package’s version.

windows

WindowsConfig | null

Windows-specific configuration.

wix

WixConfig | null

WiX configuration.

Definitions

AppCategory

The possible app categories. Corresponds to LSApplicationCategoryType on macOS and the GNOME desktop categories on Debian.

AppImageConfig

The Linux AppImage configuration.

Object Properties:

bins
excludedLibs
files
libs
linuxdeployPlugins

bins

string[] | null

List of binary paths to include in the final AppImage. For example, if you want xdg-open, you’d specify /usr/bin/xdg-open

excludedLibs

string[] | null

List of globs of libraries to exclude from the final AppImage. For example, to exclude libnss3.so, you’d specify libnss3*

files

| null

List of custom files to add to the appimage package. Maps a dir/file to a dir/file inside the appimage package.

Allows additional properties: string

libs

string[] | null

List of libs that exist in /usr/lib* to be include in the final AppImage. The libs will be searched for, using the command find -L /usr/lib* -name <libname>

linuxdeployPlugins

| null

A map of linuxdeploy plugin name and its URL to be downloaded and executed while packaing the appimage. For example, if you want to use the gtk plugin, you’d specify gtk as the key and its url as the value.

Allows additional properties: string

Binary

A binary to package within the final package.

Object Properties:

main
path (required)

main

boolean

Whether this is the main binary or not

path

string

Path to the binary (without .exe on Windows). If it’s relative, it will be resolved from [Config::out_dir].

BundleTypeRole

One of the following:

"editor" CFBundleTypeRole.Editor. Files can be read and edited.
"viewer" CFBundleTypeRole.Viewer. Files can be read.
"shell" CFBundleTypeRole.Shell
"qLGenerator" CFBundleTypeRole.QLGenerator
"none" CFBundleTypeRole.None

macOS-only*. Corresponds to CFBundleTypeRole

DebianConfig

The Linux Debian configuration.

Object Properties:

depends
desktopTemplate
files
priority
section

depends

Dependencies | null

The list of Debian dependencies.

desktopTemplate

string | null

Path to a custom desktop file Handlebars template.

Available variables: categories, comment (optional), exec, icon and name.

Default file contents: text [Desktop Entry] Categories={{categories}} {{#if comment}} Comment={{comment}} {{/if}} Exec={{exec}} {{exec_arg}} Icon={{icon}} Name={{name}} Terminal=false Type=Application {{#if mime_type}} MimeType={{mime_type}} {{/if}}

The {{exec_arg}} will be set to: * “%F”, if at least one [Config::file_associations] was specified but no deep link protocols were given. * The “%F” arg means that your application can be invoked with multiple file paths. * “%U”, if at least one [Config::deep_link_protocols] was specified. * The “%U” arg means that your application can be invoked with multiple URLs. * If both [Config::file_associations] and [Config::deep_link_protocols] were specified, the “%U” arg will be used, causing the file paths to be passed to your app as file:// URLs. * An empty string "" (nothing) if neither are given. * This means that your application will never be invoked with any URLs or file paths.

To specify a custom exec_arg, just use plaintext directly instead of {{exec_arg}}: text Exec={{exec}} %u

See more here: <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#exec-variables>.

files

| null

List of custom files to add to the deb package. Maps a dir/file to a dir/file inside the debian package.

Allows additional properties: string

priority

string | null

Change the priority of the Debian Package. By default, it is set to optional. Recognized Priorities as of now are : required, important, standard, optional, extra

section

string | null

Define the section in Debian Control file. See : <https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections>

DeepLinkProtocol

Deep link protocol

Object Properties:

name
role
schemes (required)

name

string | null

The protocol name. macOS-only and maps to CFBundleTypeName. Defaults to <bundle-id>.<schemes[0]>

role

BundleTypeRole

The app’s role for these schemes. macOS-only and maps to CFBundleTypeRole.

Default: "editor"

schemes

string[]

URL schemes to associate with this app without ://. For example my-app

Dependencies

Any of the following:

string[] The list of dependencies provided directly as a vector of Strings.
string A path to the file containing the list of dependences, formatted as one per line: text libc6 libxcursor1 libdbus-1-3 libasyncns0 ...

A list of dependencies specified as either a list of Strings or as a path to a file that lists the dependencies, one per line.

DmgConfig

The Apple Disk Image (.dmg) configuration.

Object Properties:

appFolderPosition
appPosition
background
windowPosition
windowSize

appFolderPosition

Position | null

Position of application folder on window.

appPosition

Position | null

Position of application file on window.

background

string | null

Image to use as the background in dmg file. Accepted formats: png/jpg/gif.

windowPosition

Position | null

Position of volume window on screen.

windowSize

Size | null

Size of volume window.

FileAssociation

A file association configuration.

Object Properties:

description
extensions (required)
mimeType
name
role

description

string | null

The association description. Windows-only. It is displayed on the Type column on Windows Explorer.

extensions

string[]

File extensions to associate with this app. e.g. ‘png’

mimeType

string | null

The mime-type e.g. ‘image/png’ or ‘text/plain’. Linux-only.

name

string | null

The name. Maps to CFBundleTypeName on macOS. Defaults to the first item in ext

role

BundleTypeRole

The app’s role with respect to the type. Maps to CFBundleTypeRole on macOS. Defaults to [BundleTypeRole::Editor]

Default: "editor"

HookCommand

Any of the following:

string Run the given script with the default options.
Run the given script with custom options. Object Properties: - dir - script (required) ##### dir string | null The working directory. ##### script string The script to execute.

Describes a shell command to be executed when a CLI hook is triggered.

LinuxConfig

Linux configuration

Object Properties:

generateDesktopEntry

generateDesktopEntry

boolean

Flag to indicate if desktop entry should be generated.

Default: true

LogLevel

One of the following:

"error" The “error” level. Designates very serious errors.
"warn" The “warn” level. Designates hazardous situations.
"info" The “info” level. Designates useful information.
"debug" The “debug” level. Designates lower priority information.
"trace" The “trace” level. Designates very low priority, often extremely verbose, information.

An enum representing the available verbosity levels of the logger.

MacOsConfig

The macOS configuration.

Object Properties:

backgroundApp
embeddedApps
embeddedProvisionprofilePath
entitlements
exceptionDomain
frameworks
infoPlistPath
minimumSystemVersion
providerShortName
signingIdentity

backgroundApp

boolean

Whether this is a background application. If true, the app will not appear in the Dock.

Sets the LSUIElement flag in the macOS plist file.

embeddedApps

string[] | null

Apps that need to be packaged within the app.

embeddedProvisionprofilePath

string | null

Path to the embedded.provisionprofile file for the package.

entitlements

string | null

Path to the entitlements.plist file.

exceptionDomain

string | null

The exception domain to use on the macOS .app package.

This allows communication to the outside world e.g. a web server you’re shipping.

frameworks

string[] | null

MacOS frameworks that need to be packaged with the app.

Each string can either be the name of a framework (without the .framework extension, e.g. "SDL2"), in which case we will search for that framework in the standard install locations (~/Library/Frameworks/, /Library/Frameworks/, and /Network/Library/Frameworks/), or a path to a specific framework bundle (e.g. ./data/frameworks/SDL2.framework). Note that this setting just makes cargo-packager copy the specified frameworks into the OS X app bundle (under Foobar.app/Contents/Frameworks/); you are still responsible for:

arranging for the compiled binary to link against those frameworks (e.g. by emitting lines like cargo:rustc-link-lib=framework=SDL2 from your build.rs script)
embedding the correct rpath in your binary (e.g. by running install_name_tool -add_rpath "@executable_path/../Frameworks" path/to/binary after compiling)

infoPlistPath

string | null

Path to the Info.plist file for the package.

minimumSystemVersion

string | null

A version string indicating the minimum MacOS version that the packaged app supports (e.g. "10.11"). If you are using this config field, you may also want have your build.rs script emit cargo:rustc-env=MACOSX_DEPLOYMENT_TARGET=10.11.

providerShortName

string | null

Provider short name for notarization.

signingIdentity

string | null

Code signing identity.

This is typically of the form: "Developer ID Application: TEAM_NAME (TEAM_ID)".

NsisCompression

One of the following:

"zlib" ZLIB uses the deflate algorithm, it is a quick and simple method. With the default compression level it uses about 300 KB of memory.
"bzip2" BZIP2 usually gives better compression ratios than ZLIB, but it is a bit slower and uses more memory. With the default compression level it uses about 4 MB of memory.
"lzma" LZMA (default) is a new compression method that gives very good compression ratios. The decompression speed is high (10-20 MB/s on a 2 GHz CPU), the compression speed is lower. The memory size that will be used for decompression is the dictionary size plus a few KBs, the default is 8 MB.
"off" Disable compression.

Compression algorithms used in the NSIS installer.

See <https://nsis.sourceforge.io/Reference/SetCompressor>

NsisConfig

The NSIS format configuration.

Object Properties:

appdataPaths
compression
customLanguageFiles
displayLanguageSelector
headerImage
installerIcon
installMode
languages
preinstallSection
sidebarImage
template

appdataPaths

string[] | null

List of paths where your app stores data. This options tells the uninstaller to provide the user with an option (disabled by default) whether they want to rmeove your app data or keep it.

The path should use a constant from <https://nsis.sourceforge.io/Docs/Chapter4.html#varconstant> in addition to $IDENTIFIER, $PUBLISHER and $PRODUCTNAME, for example, if you store your app data in C:\\Users\\<user>\\AppData\\Local\\<your-company-name>\\<your-product-name> you’d need to specify toml [package.metadata.packager.nsis] appdata-paths = ["$LOCALAPPDATA/$PUBLISHER/$PRODUCTNAME"]

compression

NsisCompression | null

Set the compression algorithm used to compress files in the installer.

See <https://nsis.sourceforge.io/Reference/SetCompressor>

customLanguageFiles

| null

An key-value pair where the key is the language and the value is the path to a custom .nsi file that holds the translated text for cargo-packager’s custom messages.

See <https://github.com/crabnebula-dev/cargo-packager/blob/main/crates/packager/src/nsis/languages/English.nsh> for an example .nsi file.

Note: the key must be a valid NSIS language and it must be added to [NsisConfig]languages array,

Allows additional properties: string

displayLanguageSelector

boolean

Whether to display a language selector dialog before the installer and uninstaller windows are rendered or not. By default the OS language is selected, with a fallback to the first language in the languages array.

headerImage

string | null

The path to a bitmap file to display on the header of installers pages.

The recommended dimensions are 150px x 57px.

installerIcon

string | null

The path to an icon file used as the installer icon.

installMode

NSISInstallerMode

Whether the installation will be for all users or just the current user.

Default: "currentUser"

languages

string[] | null

A list of installer languages. By default the OS language is used. If the OS language is not in the list of languages, the first language will be used. To allow the user to select the language, set display_language_selector to true.

See <https://github.com/kichik/nsis/tree/9465c08046f00ccb6eda985abbdbf52c275c6c4d/Contrib/Language%20files> for the complete list of languages.

preinstallSection

string | null

Logic of an NSIS section that will be ran before the install section.

See the available libraries, dlls and global variables here <https://github.com/crabnebula-dev/cargo-packager/blob/main/crates/packager/src/package/nsis/installer.nsi>

Example ```toml [package.metadata.packager.nsis] preinstall-section = """ ; Setup custom messages LangString webview2AbortError ${LANG_ENGLISH} “Failed to install WebView2! The app can’t run without it. Try restarting the installer.” LangString webview2DownloadError ${LANG_ARABIC} “خطأ: فشل تنزيل WebView2 - $0”

Section PreInstall ; <section logic here> SectionEnd

Section AnotherPreInstall ; <section logic here> SectionEnd """ ```

sidebarImage

string | null

The path to a bitmap file for the Welcome page and the Finish page.

The recommended dimensions are 164px x 314px.

template

string | null

A custom .nsi template to use.

See the default template here <https://github.com/crabnebula-dev/cargo-packager/blob/main/crates/packager/src/package/nsis/installer.nsi>

NSISInstallerMode

One of the following:

"currentUser" Default mode for the installer. Install the app by default in a directory that doesn’t require Administrator access. Installer metadata will be saved under the HKCU registry path.
"perMachine" Install the app by default in the Program Files folder directory requires Administrator access for the installation. Installer metadata will be saved under the HKLM registry path.
"both" Combines both modes and allows the user to choose at install time whether to install for the current user or per machine. Note that this mode will require Administrator access even if the user wants to install it for the current user only. Installer metadata will be saved under the HKLM or HKCU registry path based on the user’s choice.

Install Modes for the NSIS installer.

PackageFormat

One of the following:

"all" All available package formats for the current platform. See [PackageFormat::platform_all]
"default" The default list of package formats for the current platform. See [PackageFormat::platform_default]
"app" The macOS application bundle (.app).
"dmg" The macOS DMG package (.dmg).
"wix" The Microsoft Software Installer (.msi) through WiX Toolset.
"nsis" The NSIS installer (.exe).
"deb" The Linux Debian package (.deb).
"appimage" The Linux AppImage package (.AppImage).
"pacman" The Linux Pacman package (.tar.gz and PKGBUILD)

Types of supported packages by cargo-packager.

PacmanConfig

The Linux pacman configuration.

Object Properties:

conflicts
depends
files
provides
replaces
source

conflicts

string[] | null

Packages that conflict or cause problems with the app. All these packages and packages providing this item will need to be removed

See : <https://wiki.archlinux.org/title/PKGBUILD#conflicts>

depends

Dependencies | null

List of softwares that must be installed for the app to build and run.

See : <https://wiki.archlinux.org/title/PKGBUILD#depends>

files

| null

List of custom files to add to the pacman package. Maps a dir/file to a dir/file inside the pacman package.

Allows additional properties: string

provides

string[] | null

Additional packages that are provided by this app.

See : <https://wiki.archlinux.org/title/PKGBUILD#provides>

replaces

string[] | null

Only use if this app replaces some obsolete packages. For example, if you rename any package.

See : <https://wiki.archlinux.org/title/PKGBUILD#replaces>

source

string[] | null

Source of the package to be stored at PKGBUILD. PKGBUILD is a bash script, so version can be referred as ${pkgver}

Position

Position coordinates struct.

Object Properties:

x (required)
y (required)

x

integer formatted as uint32

X coordinate.

y

integer formatted as uint32

Y coordinate.

Resource

Any of the following:

string Supports glob patterns
An object descriping the src file or directory and its target location in the final package. Object Properties: - src (required) - target (required) ##### src string The src file or directory, supports glob patterns. ##### target string A relative path from the root of the final package. If src is a glob, this will always be treated as a directory where all globbed files will be placed under.

A path to a resource (with optional glob pattern) or an object of src and target paths.

Size

Size struct.

Object Properties:

height (required)
width (required)

height

integer formatted as uint32

Height.

width

integer formatted as uint32

Width.

WindowsConfig

The Windows configuration.

Object Properties:

allowDowngrades
certificateThumbprint
digestAlgorithm
signCommand
timestampUrl
tsp

allowDowngrades

boolean

Whether to validate a second app installation, blocking the user from installing an older version if set to false.

For instance, if 1.2.1 is installed, the user won’t be able to install app version 1.2.0 or 1.1.5.

The default value of this flag is true.

Default: true

certificateThumbprint

string | null

The SHA1 hash of the signing certificate.

digestAlgorithm

string | null

The file digest algorithm to use for creating file signatures. Required for code signing. SHA-256 is recommended.

signCommand

string | null

Specify a custom command to sign the binaries. This command needs to have a %1 in it which is just a placeholder for the binary path, which we will detect and replace before calling the command.

By Default we use signtool.exe which can be found only on Windows so if you are on another platform and want to cross-compile and sign you will need to use another tool like osslsigncode.

timestampUrl

string | null

Server to use during timestamping.

tsp

boolean

Whether to use Time-Stamp Protocol (TSP, a.k.a. RFC 3161) for the timestamp server. Your code signing provider may use a TSP timestamp server, like e.g. SSL.com does. If so, enable TSP by setting to true.

WixConfig

The wix format configuration

Object Properties:

bannerPath
componentGroupRefs
componentRefs
customActionRefs
dialogImagePath
featureGroupRefs
featureRefs
fipsCompliant
fragmentPaths
fragments
languages
mergeModules
mergeRefs
template

bannerPath

string | null

Path to a bitmap file to use as the installation user interface banner. This bitmap will appear at the top of all but the first page of the installer.

The required dimensions are 493px × 58px.

componentGroupRefs

string[] | null

The ComponentGroup element ids you want to reference from the fragments.

componentRefs

string[] | null

The Component element ids you want to reference from the fragments.

customActionRefs

string[] | null

The CustomAction element ids you want to reference from the fragments.

dialogImagePath

string | null

Path to a bitmap file to use on the installation user interface dialogs. It is used on the welcome and completion dialogs. The required dimensions are 493px × 312px.

featureGroupRefs

string[] | null

The FeatureGroup element ids you want to reference from the fragments.

featureRefs

string[] | null

The Feature element ids you want to reference from the fragments.

fipsCompliant

boolean

Enables FIPS compliant algorithms.

fragmentPaths

string[] | null

A list of paths to .wxs files with WiX fragments to use.

fragments

string[] | null

List of WiX fragments as strings. This is similar to config.wix.fragments_paths but is a string so you can define it inline in your config.

text <?xml version="1.0" encoding="utf-8"?> <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi"> <Fragment> <CustomAction Id="OpenNotepad" Directory="INSTALLDIR" Execute="immediate" ExeCommand="cmd.exe /c notepad.exe" Return="check" /> <InstallExecuteSequence> <Custom Action="OpenNotepad" After="InstallInitialize" /> </InstallExecuteSequence> </Fragment> </Wix>

string Built-in wix language identifier.
Custom wix language. Object Properties: - identifier (required) - path ##### identifier string Idenitifier of this language, for example en-US ##### path string | null The path to a locale (.wxl) file. See <https://wixtoolset.org/documentation/manual/v3/howtos/ui_and_localization/build_a_localized_version.html>.

A wix language.