dmg
Provides support for building Apple Disk Images. More...
| Since: | Qbs 1.9 |
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.
This property is only useful with artifacts tagged dmg.license.input. It cannot be used at the product level to affect all files.
Default: "Agree"
licenseDisagreeButtonText : string |
The text shown on the Disagree button associated with the license file, localized to the value of licenseLanguageName.
This property is only useful with artifacts tagged dmg.license.input. It cannot be used at the product level to affect all files.
Default: "Disagree"
licenseInstructionText : string |
An instruction text associated with the license file that will be shown on the license dialog, localized to the value of licenseLanguageName.
This property is only useful with artifacts tagged dmg.license.input. It cannot be used at the product level to affect all files.
Default: "If you agree with the terms of this license, press \"Agree\" to install the software. If you do not agree, press \"Disagree\"."
licenseLanguageName : string |
The name of the language associated with the license file, localized to that language.
This property is only useful with artifacts tagged dmg.license.input. It cannot be used at the product level to affect all files.
Default: "English"
licenseLocale : string |
The locale of the license file.
Defaults to a value guessed 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. It cannot be used at the product level to affect all files.
Default: Determined automatically.
licensePrintButtonText : string |
The text shown on the Print button associated with the license file, localized to the value of licenseLanguageName.
This property is only useful with artifacts tagged dmg.license.input. It cannot be used at the product level to affect all files.
Default: "Print"
licenseSaveButtonText : string |
The text shown on the Save button associated with the license file, localized to the value of licenseLanguageName.
This property is only useful with artifacts tagged dmg.license.input. It cannot be used at the product level to affect all files.
Default: "Save"
sourceBase : string |
The base directory of the files that are going to be embedded in the DMG ("dmg.input"). The source base directory is omitted from the target directory path of the DMG directory.
Default: The directory of the current file to be embedded, relative to the product's source directory.
textutilPath : string |
The path to the textutil binary used to convert license agreement files to rich text format.
This should not normally need to be changed.
Default: "/usr/bin/textutil"
volumeName : string |
The name of the disk image that is displayed in Finder when the DMG is mounted.
Default: product.targetName
windowHeight : int |
The height of the Finder window that displays the disk image contents when it is mounted.
Note: The window height includes the height of the standard macOS title bar (22 points).
Default: 480
windowWidth : int |
The width of the Finder window that displays the disk image contents when it is mounted.
Default: 640
windowX : int |
The x position of the Finder window that displays the disk image contents when it is mounted.
Default: 100
windowY : int |
The y position of the Finder window that displays the disk image contents when it is mounted.
Default: 100