dmg

Provides support for building Apple Disk Images. More...

Since: Qbs 1.9

List of all members, including inherited members

Properties

backgroundColor : string
badgeVolumeIcon : bool
compressionLevel : int
defaultLicenseLocale : string
dmgSuffix : string
format : string
hdiutilPath : string
iconPositions : list
iconSize : int
iconX : int
iconY : int
licenseAgreeButtonText : string
licenseDisagreeButtonText : string
licenseInstructionText : string
licenseLanguageName : string
licenseLocale : string
licensePrintButtonText : string
licenseSaveButtonText : string
sourceBase : string
textutilPath : string
volumeName : string
windowHeight : int
windowWidth : int
windowX : int
windowY : int

Detailed Description

The dmg module contains properties and rules for building Apple Disk Images, which are typically used to distribute applications and installers on macOS.

This module is only available on Apple platforms.

Qbs enables you to build macOS disk images with custom backgrounds and icon layouts. Most applications on macOS are installed via a .dmg file, which is usually customized by using a custom image background and icon layout. Unfortunately, it is challenging to construct such DMG files correctly, because the layout relies on several undocumented proprietary file formats, some of which date back to the Mac OS Classic days, and which are even nested within one another.

Most of the existing tools to create DMG files do so by using AppleScript to manipulate the Finder graphically to generate the appropriate icon layout, which is both unstable and incompatible with headless build servers, because the necessary OS services to launch graphical applications may not be running at all. Many projects create the primary .DS_Store file manually, and commit the result to their source repository. This binary blob is difficult to inspect and edit, and might not be backwards compatible with older versions of the OS, depending on how it was generated.

Qbs takes a different approach. It generates the necessary files programmatically, in an entirely reproducible manner. There are no external dependencies that need to be separately installed nor do any binary blobs need to be committed to your source repository.

Appearance Properties

Appearance properties are used to control the contents of the .DS_Store file and its embedded Alias and Bookmark records, that will be generated by Qbs in order to control the appearance of the disk image when mounted in Finder.

License Properties

License properties are used to control the content and appearance of the license prompt displayed when a user attempts to mount the resulting disk image via Finder.

Relevant File Tags

The file tags determine how the tagged files are handled.

Tag	Auto-tagged File Names	Since	Description
`"dmg.input"`	n/a	1.9	Tagged files are copied into the disk image. The sourceBase property controls the destination directory and hierarchy of copied files within the disk image.
`"dmg.license.input"`	`.txt`, `.rtf`, `.html`, `.doc`, `.docx`, `.odt`, `.xml`, `.webarchive`	1.9	Tagged files are converted into rich text and used for the license prompt when mounting the DMG.
`"icns"`	`*.icns`	1.3	The tagged file is added as the Apple Disk Image volume icon, which will show up in the Finder as an overlay on the file icon.
`"tiff"`	`.tif`, `.tiff`	1.9	The tagged file is used as the background image of the directory as shown in Finder when the DMG file is mounted.

Property Documentation

backgroundColor : string

The background color of the disk image as seen when mounted in Finder.

For the full list of supported color names and formats, see the dmgbuild - Settings documentation.

For more information about how to use an image for the background instead, see "tiff".

Default: Undefined

badgeVolumeIcon : bool

Whether to render the user-supplied icon ("icns") on top of the default volume icon instead of using it directly. This generally gives the disk image icon a better and more consistent appearance.

Default: false

compressionLevel : int

The zlib, bzip2, or lzfse compression level for UDZO, UDBZ, or ULFO disk images.

Default: 9 in release mode, otherwise undefined.

defaultLicenseLocale : string

The locale of the default license to display when there is no license whose locale matches the system locale.

Default: "en_US"

dmgSuffix : string

The file extension for disk images.

This should not normally need to be changed.

Default: ".dmg"

format : string

The format to create the disk image in.

Allowed values include but are not limited to "UDZO", "UDBZ", and "ULFO".

Default: "UDBZ"

hdiutilPath : string

The path to the hdiutil binary used to perform disk image related operations.

This should not normally need to be changed.

Default: "/usr/bin/hdiutil"

iconPositions : list

A list of objects containing the path, x, and y properties, which correspond to disk image-relative file paths and visual coordinates of file icons in the disk image as seen when it is mounted in Finder.

For example:

 dmg.iconPositions: [
     {"path": "Applications", "x": 128, "y": 128},
     {"path": "Foo Bar.app", "x": 256, "y": 128}
 ]

This property is useful for specifying the positions of files where you do not have direct control over the corresponding Qbs artifact, or there is no corresponding Qbs artifact (for example, "Foo Bar.app" is a directory, which has no equivalent artifact in the build graph).

For files to which you are directly applying the dmg.input file tag, you should use the iconX and iconY properties instead.

Default: Undefined

iconSize : int

The width and height of the file icons as seen when the disk image is mounted in Finder.

Default: 128

iconX : int

The x position of the file icon in the Finder window that displayed the disk image contents when it is mounted.

This property is only useful with artifacts tagged dmg.input. It cannot be used at the product level to affect all files.

If you do not have access to the artifact corresponding to the file whose position you want to set, use the iconPositions property instead.

Default: windowWidth / 2

iconY : int

The y position of the file icon in the Finder window that displayed the disk image contents when it is mounted.

This property is only useful with artifacts tagged dmg.input. It cannot be used at the product level to affect all files.

If you do not have access to the artifact corresponding to the file whose position you want to set, use the iconPositions property instead.

Default: windowHeight / 2

licenseAgreeButtonText : string

The text shown on the Agree button associated with the license file, localized to the value of licenseLanguageName.