Qbs Manual | List of Modules | Module dmg

Qbs 1.10.1

# Module dmg

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.

## General Properties

Property | Type | Since | Default | Description
--- | --- | --- | --- | ---
volumeName | `string` | 1.9 | `product.targetName` | The name of the disk image which displayed in Finder when the DMG is mounted.
badgeVolumeIcon | `bool` | 1.9 | `false` | Whether to render the user-supplied icon (see the `"icns"` file tag documentation) 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.
format | `string` | 1.9 | `"UDBZ"` | The format to create the disk image in. Allowed values include but are not limited to `"UDZO"`, `"UDBZ"` and `"ULFO"`.
compressionLevel | `int` | 1.9 | 9 in release mode, otherwise undefined | Sets the zlib, bzip2, or lzfse compression level for UDZO, UDBZ, or ULFO disk images.
sourceBase | `string` | 1.9 | `undefined` | Specifies the base directory of the files that are going to be embedded in the DMG (see the `"dmg.input"` file tag documentation). The source base directory is omitted from the target directory path of the DMG directory. The default value of this property is the directory of the current file to be embedded, relative to the product's source directory.

## Appearance Properties

Properties in this section 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.

Property | Type | Since | Default | Description
--- | --- | --- | --- | ---
backgroundColor | `string` | 1.9 | `undefined` | Specifies the background color of the disk image as seen when mounted in Finder. Refer to the dmgbuild documentation for the full list of supported color names and formats. To use an image for the background instead, refer to the `"tiff"` file tag documentation.
iconSize | `int` | 1.9 | `128` | Specifies the width and height of the file icons as seen when the disk image is mounted in Finder.
windowX | `int` | 1.9 | `100` | Specifies the X position of the Finder window that displays the disk image contents when it is mounted.
windowY | `int` | 1.9 | `100` | Specifies the Y position of the Finder window that displays the disk image contents when it is mounted.
windowWidth | `int` | 1.9 | `640` | Specifies the width of the Finder window that displays the disk image contents when it is mounted.
windowHeight | `int` | 1.9 | `480` | Specifies the height of the Finder window that displays the disk image contents when it is mounted. Note that the window height includes the height of the standard macOS title bar (22 points).
iconPositions | `list` | 1.9 | `undefined` List of objects containing `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 `dmg.iconX` and `dmg.iconY` properties instead.
iconX | `int` | 1.9 | `windowWidth / 2` | 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` and 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 `dmg.iconPositions` property instead.
iconY | `int` | 1.9 | `windowHeight / 2` | 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` and 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 `dmg.iconPositions` property instead.

## License Properties

Properties in this section 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.

Property | Type | Since | Default | Description
--- | --- | --- | --- | ---
defaultLicenseLocale | `string` | 1.9 | `"en_US"` | Locale of the default license to display when there is no license whose locale matches the system locale.
licenseLocale | `string` | 1.9 | determined automatically | Locale of the license file. Defaults to a value guess from the file path, specifically the base name of any .lproj directory found in the file's path. If the locale could not be determined from the file path and this property is not set, an error will be emitted. This property is only useful with artifacts tagged `dmg.license.input` and cannot be used at the product level to affect all files.
licenseLanguageName | `string` | 1.9 | `"English"` | Name of the language associated with the license file, localized for that language. This property is only useful with artifacts tagged `dmg.license.input` and cannot be used at the product level to affect all files.
licenseAgreeButtonText | `string` | 1.9 | `"Agree"` | Text shown on the "Agree" button associated with the license file, localized for that language. This property is only useful with artifacts tagged `dmg.license.input` and cannot be used at the product level to affect all files.
licenseDisagreeButtonText | `string` | 1.9 | `"Disagree"` | Text shown on the "Disagree" button associated with the license file, localized for that language. This property is only useful with artifacts tagged `dmg.license.input` and cannot be used at the product level to affect all files.
licensePrintButtonText | `string` | 1.9 | `"Print"` | Text shown on the "Print" button associated with the license file, localized for that language. This property is only useful with artifacts tagged `dmg.license.input` and cannot be used at the product level to affect all files.
licenseSaveButtonText | `string` | 1.9 | `"Save"` | Text shown on the "Save" button associated with the license file, localized for that language. This property is only useful with artifacts tagged `dmg.license.input` and cannot be used at the product level to affect all files.
licenseInstructionText | `string` | 1.9 | `"If you agree with the terms of this license, press \"Agree\" to install the software. If you do not agree, press \"Disagree\"."` | Instruction text associated with the license file that will be shown on the license dialog, localized for that language. This property is only useful with artifacts tagged `dmg.license.input` and cannot be used at the product level to affect all files.

## Advanced Properties

Property | Type | Since | Default | Description
--- | --- | --- | --- | ---
dmgSuffix | `string` | 1.9 | `".dmg"` | File extension for disk images. This should not normally need to be changed.
hdiutilPath | `string` | 1.9 | `"/usr/bin/hdiutil"` | Path to the hdiutil binary used to perform disk image related operations. This should not normally need to be changed.
textutilPath | `string` | 1.9 | `"/usr/bin/textutil"` | Path to the textutil binary used to convert license agreement files to rich text format. This should not normally need to be changed.

## Relevant File Tags

Tag | Auto-tagged File Names | Since | Description
--- | --- | --- | ---
`"dmg.input"` | n/a | 1.9 | If the product contains files with this tag, they will be copied into the disk image. See the `sourceBase` property to learn how to control 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 | If the product contains files with this tag, they will be converted into rich text and used for the license prompt when mounting the DMG.
`"icns"` | `*.icns` | 1.3 | If the product contains a file with this tag, it will be 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 | If the product contains a file with this tag, it will be used as the background image of the directory as shown in Finder when the DMG file is mounted.