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

PropertyTypeSinceDefaultDescription
volumeNamestring1.9product.targetNameThe name of the disk image which displayed in Finder when the DMG is mounted.
badgeVolumeIconbool1.9falseWhether 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.
formatstring1.9"UDBZ"The format to create the disk image in. Allowed values include but are not limited to "UDZO", "UDBZ" and "ULFO".
compressionLevelint1.99 in release mode, otherwise undefinedSets the zlib, bzip2, or lzfse compression level for UDZO, UDBZ, or ULFO disk images.
sourceBasestring1.9undefinedSpecifies 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.

PropertyTypeSinceDefaultDescription
backgroundColorstring1.9undefinedSpecifies 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.
iconSizeint1.9128Specifies the width and height of the file icons as seen when the disk image is mounted in Finder.
windowXint1.9100Specifies the X position of the Finder window that displays the disk image contents when it is mounted.
windowYint1.9100Specifies the Y position of the Finder window that displays the disk image contents when it is mounted.
windowWidthint1.9640Specifies the width of the Finder window that displays the disk image contents when it is mounted.
windowHeightint1.9480Specifies 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).
iconPositionslist1.9undefined 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.

iconXint1.9windowWidth / 2X 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.
iconYint1.9windowHeight / 2Y 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.

PropertyTypeSinceDefaultDescription
defaultLicenseLocalestring1.9"en_US"Locale of the default license to display when there is no license whose locale matches the system locale.
licenseLocalestring1.9determined automaticallyLocale 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.
licenseLanguageNamestring1.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.
licenseAgreeButtonTextstring1.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.
licenseDisagreeButtonTextstring1.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.
licensePrintButtonTextstring1.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.
licenseSaveButtonTextstring1.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.
licenseInstructionTextstring1.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

PropertyTypeSinceDefaultDescription
dmgSuffixstring1.9".dmg"File extension for disk images. This should not normally need to be changed.
hdiutilPathstring1.9"/usr/bin/hdiutil"Path to the hdiutil binary used to perform disk image related operations. This should not normally need to be changed.
textutilPathstring1.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

TagAuto-tagged File NamesSinceDescription
"dmg.input"n/a1.9If 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, *.webarchive1.9If 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"*.icns1.3If 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, *.tiff1.9If 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.