path: root/doc/reference/modules/dmg-module.qdoc

/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qbs.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \contentspage index.html
    \page dmg-module.html
    \ingroup list-of-modules

    \title Module dmg
    \since 1.9
    \brief Provides support for building Apple Disk Images

    The \c 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 \c .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 \c .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.

    \section1 General Properties

    \table
    \header
        \li Property
        \li Type
        \li Since
        \li Default
        \li Description
    \row
        \li volumeName
        \li \c{string}
        \li 1.9
        \li \c{product.targetName}
        \li The name of the disk image which displayed in Finder when the DMG is mounted.
    \row
        \li badgeVolumeIcon
        \li \c{bool}
        \li 1.9
        \li \c{false}
        \li Whether to render the user-supplied icon (see the \c{"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.
    \row
        \li format
        \li \c{string}
        \li 1.9
        \li \c{"UDBZ"}
        \li The format to create the disk image in.
            Allowed values include but are not limited to \c{"UDZO"}, \c{"UDBZ"} and \c{"ULFO"}.
    \row
        \li compressionLevel
        \li \c{int}
        \li 1.9
        \li 9 in release mode, otherwise undefined
        \li Sets the zlib, bzip2, or lzfse compression level for UDZO, UDBZ, or ULFO disk images.
    \row
        \li sourceBase
        \li \c{string}
        \li 1.9
        \li \c{undefined}
        \li Specifies the base directory of the files that are going to be embedded in the DMG
            (see the \c{"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.
    \endtable

    \section1 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.

    \table
    \header
        \li Property
        \li Type
        \li Since
        \li Default
        \li Description
    \row
        \li backgroundColor
        \li \c{string}
        \li 1.9
        \li \c{undefined}
        \li Specifies the background color of the disk image as seen when mounted in Finder.
            Refer to the \l{https://dmgbuild.readthedocs.io/en/latest/settings.html#background}
            {dmgbuild documentation}
            for the full list of supported color names and formats.
            To use an image for the background instead,
            refer to the \c{"tiff"} file tag documentation.
    \row
        \li iconSize
        \li \c{int}
        \li 1.9
        \li \c{128}
        \li Specifies the width and height of the file icons as seen when the disk image is mounted
            in Finder.
    \row
        \li windowX
        \li \c{int}
        \li 1.9
        \li \c{100}
        \li Specifies the X position of the Finder window that displays the disk image contents
            when it is mounted.
    \row
        \li windowY
        \li \c{int}
        \li 1.9
        \li \c{100}
        \li Specifies the Y position of the Finder window that displays the disk image contents
            when it is mounted.
    \row
        \li windowWidth
        \li \c{int}
        \li 1.9
        \li \c{640}
        \li Specifies the width of the Finder window that displays the disk image contents
            when it is mounted.
    \row
        \li windowHeight
        \li \c{int}
        \li 1.9
        \li \c{480}
        \li 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).
    \row
        \li iconPositions
        \li \c{list}
        \li 1.9
        \li \c{undefined}
            List of objects containing \c{path}, \c{x}, and \c{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:
            \code
            dmg.iconPositions: [
                {"path": "Applications", "x": 128, "y": 128},
                {"path": "Foo Bar.app", "x": 256, "y": 128}
            ]
            \endcode
            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 \c{dmg.input} file
            tag, you should use the \c{dmg.iconX} and \c{dmg.iconY} properties instead.
    \row
        \li iconX
        \li \c{int}
        \li 1.9
        \li \c{windowWidth / 2}
        \li 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 \c{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 \c{dmg.iconPositions} property instead.
    \row
        \li iconY
        \li \c{int}
        \li 1.9
        \li \c{windowHeight / 2}
        \li 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 \c{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 \c{dmg.iconPositions} property instead.
    \endtable

    \section1 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.

    \table
    \header
        \li Property
        \li Type
        \li Since
        \li Default
        \li Description
    \row
        \li defaultLicenseLocale
        \li \c{string}
        \li 1.9
        \li \c{"en_US"}
        \li Locale of the default license to display when there is no license whose locale matches
            the system locale.
    \row
        \li licenseLocale
        \li \c{string}
        \li 1.9
        \li determined automatically
        \li 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 \c{dmg.license.input} and
            cannot be used at the product level to affect all files.
    \row
        \li licenseLanguageName
        \li \c{string}
        \li 1.9
        \li \c{"English"}
        \li Name of the language associated with the license file, localized for that language.
            This property is only useful with artifacts tagged \c{dmg.license.input} and
            cannot be used at the product level to affect all files.
    \row
        \li licenseAgreeButtonText
        \li \c{string}
        \li 1.9
        \li \c{"Agree"}
        \li Text shown on the "Agree" button associated with the license file,
            localized for that language.
            This property is only useful with artifacts tagged \c{dmg.license.input} and
            cannot be used at the product level to affect all files.
    \row
        \li licenseDisagreeButtonText
        \li \c{string}
        \li 1.9
        \li \c{"Disagree"}
        \li Text shown on the "Disagree" button associated with the license file,
            localized for that language.
            This property is only useful with artifacts tagged \c{dmg.license.input} and
            cannot be used at the product level to affect all files.
    \row
        \li licensePrintButtonText
        \li \c{string}
        \li 1.9
        \li \c{"Print"}
        \li Text shown on the "Print" button associated with the license file,
            localized for that language.
            This property is only useful with artifacts tagged \c{dmg.license.input} and
            cannot be used at the product level to affect all files.
    \row
        \li licenseSaveButtonText
        \li \c{string}
        \li 1.9
        \li \c{"Save"}
        \li Text shown on the "Save" button associated with the license file,
            localized for that language.
            This property is only useful with artifacts tagged \c{dmg.license.input} and
            cannot be used at the product level to affect all files.
    \row
        \li licenseInstructionText
        \li \c{string}
        \li 1.9
        \li \c{"If you agree with the terms of this license, press \"Agree\" to install the software.  If you do not agree, press \"Disagree\"."}
        \li 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 \c{dmg.license.input} and
            cannot be used at the product level to affect all files.
    \endtable

    \section1 Advanced Properties

    \table
    \header
        \li Property
        \li Type
        \li Since
        \li Default
        \li Description
    \row
        \li dmgSuffix
        \li \c{string}
        \li 1.9
        \li \c{".dmg"}
        \li File extension for disk images.
            This should not normally need to be changed.
    \row
        \li hdiutilPath
        \li \c{string}
        \li 1.9
        \li \c{"/usr/bin/hdiutil"}
        \li Path to the hdiutil binary used to perform disk image related operations.
            This should not normally need to be changed.
    \row
        \li textutilPath
        \li \c{string}
        \li 1.9
        \li \c{"/usr/bin/textutil"}
        \li Path to the textutil binary used to convert license agreement files to rich text format.
            This should not normally need to be changed.
    \endtable

    \section1 Relevant File Tags

    \table
    \header
        \li Tag
        \li Auto-tagged File Names
        \li Since
        \li Description
    \row
        \li \c{"dmg.input"}
        \li n/a
        \li 1.9
        \li If the product contains files with this tag, they will be copied into the disk image.
            See the \c{sourceBase} property to learn how to control the destination directory and
            hierarchy of copied files within the disk image.
    \row
        \li \c{"dmg.license.input"}
        \li \c{*.txt}, \c{*.rtf}, \c{*.html}, \c{*.doc}, \c{*.docx}, \c{*.odt}, \c{*.xml},
            \c{*.webarchive}
        \li 1.9
        \li 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.
    \row
        \li \c{"icns"}
        \li \c{*.icns}
        \li 1.3
        \li 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.
    \row
        \li \c{"tiff"}
        \li \c{*.tif}, \c{*.tiff}
        \li 1.9
        \li 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.
    \endtable
*/