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
    \qmltype dmg
    \inqmlmodule QbsModules
    \since Qbs 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.

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

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

    \section2 Relevant File Tags
    \target filetags-dmg

    The file tags determine how the tagged files are handled.

    \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 Tagged files are copied into the disk image. The
            \l{dmg::}{sourceBase} property controls 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 Tagged files are 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 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.
    \row
        \li \c{"tiff"}
        \li \c{*.tif}, \c{*.tiff}
        \li 1.9
        \li The tagged file is used as the background image of the directory as
            shown in Finder when the DMG file is mounted.
    \endtable
*/

/*!
    \qmlproperty string dmg::volumeName

    The name of the disk image that is displayed in Finder when the DMG is
    mounted.

    \defaultvalue \l{Product::targetName}{product.targetName}
*/

/*!
    \qmlproperty bool dmg::badgeVolumeIcon

    Whether to render the user-supplied icon (\l{filetags-dmg}{"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.

    \defaultvalue \c{false}
*/

/*!
    \qmlproperty string dmg::format

    The format to create the disk image in.

    Allowed values include but are not limited to \c{"UDZO"}, \c{"UDBZ"}, and
    \c{"ULFO"}.

    \defaultvalue \c{"UDBZ"}
*/

/*!
    \qmlproperty int dmg::compressionLevel

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

    \defaultvalue \c 9 in release mode, otherwise \c undefined.
*/

/*!
    \qmlproperty string dmg::sourceBase

    The base directory of the files that are going to be embedded in the DMG
    (\l{filetags-dmg}{"dmg.input"}). The source base directory
    is omitted from the target directory path of the DMG directory.

    \defaultvalue The directory of the current file to be embedded, relative to
    the product's source directory.
*/

/*!
    \qmlproperty string dmg::backgroundColor

    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
    \l{dmgbuild - Settings} documentation.

    For more information about how to use an image for the background instead,
    see \l{filetags-dmg}{"tiff"}.

    \nodefaultvalue
*/

/*!
    \qmlproperty int dmg::iconSize

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

    \defaultvalue \c{128}
*/

/*!
    \qmlproperty int dmg::windowX

    The x position of the Finder window that displays the disk image contents
    when it is mounted.

    \defaultvalue \c{100}
*/

/*!
    \qmlproperty int dmg::windowY

    The y position of the Finder window that displays the disk image contents
    when it is mounted.

    \defaultvalue \c{100}
*/

/*!
    \qmlproperty int dmg::windowWidth

    The width of the Finder window that displays the disk image contents
    when it is mounted.

    \defaultvalue \c{640}
*/

/*!
    \qmlproperty int dmg::windowHeight

    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).

    \defaultvalue \c{480}
*/

/*!
    \qmlproperty list dmg::iconPositions

    A list of objects containing the \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 \l{filetags-dmg}{dmg.input}
    file tag, you should use the \l{dmg::}{iconX} and \l{dmg::}{iconY}
    properties instead.

    \nodefaultvalue
*/

/*!
    \qmlproperty int dmg::iconX

    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 \l{filetags-dmg}
    {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 \l{dmg::}{iconPositions} property instead.

    \defaultvalue \c{windowWidth / 2}
*/

/*!
    \qmlproperty int dmg::iconY

    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 \l{filetags-dmg}
    {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 \l{dmg::}{iconPositions} property instead.

    \defaultvalue \c{windowHeight / 2}
*/

/*!
    \qmlproperty string dmg::defaultLicenseLocale

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

    \defaultvalue \c{"en_US"}
*/

/*!
    \qmlproperty string dmg::licenseLocale

    The locale of the license file.

    Defaults to a value guessed from the file path, specifically the base name
    of any \c .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 \l{filetags-dmg}
    {dmg.license.input}. It cannot be used at the product level to affect all
    files.

    \defaultvalue Determined automatically.
*/

/*!
    \qmlproperty string dmg::licenseLanguageName

    The name of the language associated with the license file, localized to that
    language.

    This property is only useful with artifacts tagged \l{filetags-dmg}
    {dmg.license.input}. It cannot be used at the product level to affect all
    files.

    \defaultvalue \c{"English"}
*/

/*!
    \qmlproperty string dmg::licenseAgreeButtonText

    The text shown on the \e Agree button associated with the license file,
    localized to the value of \l{dmg::}{licenseLanguageName}.

    This property is only useful with artifacts tagged \l{filetags-dmg}
    {dmg.license.input}. It cannot be used at the product level to affect all
    files.

    \defaultvalue \c{"Agree"}
*/

/*!
    \qmlproperty string dmg::licenseDisagreeButtonText

    The text shown on the \c Disagree button associated with the license file,
    localized to the value of \l{dmg::}{licenseLanguageName}.

    This property is only useful with artifacts tagged \l{filetags-dmg}
    {dmg.license.input}. It cannot be used at the product level to affect all
    files.

    \defaultvalue \c{"Disagree"}
*/

/*!
    \qmlproperty string dmg::licensePrintButtonText

    The text shown on the \c Print button associated with the license file,
    localized to the value of \l{dmg::}{licenseLanguageName}.

    This property is only useful with artifacts tagged \l{filetags-dmg}
    {dmg.license.input}. It cannot be used at the product level to affect all
    files.

    \defaultvalue \c{"Print"}
*/

/*!
    \qmlproperty string dmg::licenseSaveButtonText

    The text shown on the \e Save button associated with the license file,
    localized to the value of \l{dmg::}{licenseLanguageName}.

    This property is only useful with artifacts tagged \l{filetags-dmg}
    {dmg.license.input}. It cannot be used at the product level to affect all
    files.

    \defaultvalue \c{"Save"}
*/

/*!
    \qmlproperty string dmg::licenseInstructionText

    An instruction text associated with the license file that will be shown on
    the license dialog, localized to the value of
    \l{dmg::}{licenseLanguageName}.

    This property is only useful with artifacts tagged \l{filetags-dmg}
    {dmg.license.input}. It cannot be used at the product level to affect all
    files.

    \defaultvalue \c{"If you agree with the terms of this license, press
    \"Agree\" to install the software. If you do not agree, press
    \"Disagree\"."}
*/

/*!
    \qmlproperty string dmg::dmgSuffix

    The file extension for disk images.

    This should not normally need to be changed.

    \defaultvalue \c{".dmg"}
*/

/*!
    \qmlproperty string dmg::hdiutilPath

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

    This should not normally need to be changed.

    \defaultvalue \c{"/usr/bin/hdiutil"}
*/

/*!
    \qmlproperty string dmg::textutilPath

    The path to the \c textutil binary used to convert license agreement files
    to rich text format.

    This should not normally need to be changed.

    \defaultvalue \c{"/usr/bin/textutil"}
*/