path: root/doc/reference/modules/qbs-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 list-of-modules.html
    \qmltype qbs
    \inqmlmodule QbsModules
    \since Qbs 1.0

    \brief Comprises general properties.

    The \c qbs module is implicitly loaded in every product. It contains properties of the current
    build environment, independent of the used programming languages and toolchains.

    \section2 Installation Properties

    Typically, you use \l{Group} items to specify the target directories for
    installing files. To install a group of files, set the \l{qbs::install}
    {qbs.install} property of the Group to \c true. The value of
    \l{qbs::installDir}{qbs.installDir} specifies the path to the directory
    where the files will be installed. You can specify a base directory for all
    installation directories as the value of \l{qbs::installPrefix}
    {qbs.installPrefix}.

    For example, the following properties specify where a set of QML files and
    an application executable are installed on Windows and Linux:

    \badcode
    Application {
        name: "myapp"
        Group {
            name: "Runtime resources"
            files: "*.qml"
            qbs.install: true
            qbs.installDir: condition: qbs.targetOS.contains("unix")
                ? "share/myapp" : "resources"
        }
        Group {
            name: "The App itself"
            fileTagsFilter: "application"
            qbs.install: true
            qbs.installDir: "bin"
        }
        qbs.installPrefix: condition: qbs.targetOS.contains("unix")
            ? "usr/local" : "MyApp"
    }
    \endcode

    On Windows, the QML files will ultimately get installed in
    \c{MyApp\resources} and the application executable in \c MyApp\bin,
    for instance under \c{C:\Program Files}. On Linux, the QML files will be
    installed in \c /usr/local/share/myapp and the executable in
    \c /usr/local/bin.

    By default, \l{qbs::installRoot}{qbs.installRoot} creates the
    \c install-root directory in the build directory for packaging the binaries
    before installation. It is a temporary directory that is usually not
    available when the application is run, and it should therefore not be set in
    the project files. You can override the default value from the command line,
    as described in \l{Installing Files}.

    \section2 Multiplexing Properties

    The following properties are specific to \l{Multiplexing}
    {product multiplexing}:

    \list
        \li \l{qbs::}{architectures}
        \li \l{qbs::}{buildVariants}
        \li \l{qbs::}{profiles}
    \endlist
*/

/*!
    \qmlproperty string qbs::configurationName
    \since Qbs 1.6
    \readonly

    The name of the current build configuration.

    The build configuration is set via the command line parameter \c
    config. For more information, see \l{build}{build}.

    \defaultvalue \c{"default"}
*/

/*!
    \qmlproperty string qbs::buildVariant

    The name of the build variant for the current build.

    Possible values are \c{"debug"} and \c{"release"}. A debug build usually
    contains additional debug symbols that are needed for debugging the
    application but that can be left out from the release version. Debug builds
    are used for testing and release builds for creating the final installation
    file.

    \defaultvalue \c{"release"} if
    \l{qbs::configurationName}{qbs.configurationName} is \c{"release"}. Otherwise
    \c{"debug"}
*/

/*!
    \qmlproperty bool qbs::debugInformation

    Whether to generate debug information.

    \defaultvalue \c{true} for debug builds, \c{false} otherwise.
*/

/*!
    \qmlproperty bool qbs::enableDebugCode

    Whether to enable debug functionality in the product. Not to be confused
    with generation of debug symbols or the code optimization level.

    The property changes the following things when enabled:
    \list
         \li Passes a flag to the Windows linker to link against a debug
             Windows CRT (common runtime) library
             (for example /MTd instead of /MT)
    \endlist

    The property changes the following things when disabled:
    \list
         \li Passes the \c{NDEBUG} define to the compiler
    \endlist

    Typically, this property is enabled for debug builds and disabled for
    release builds.

    \defaultvalue \c{true} for debug builds, \c{false} otherwise.
*/

/*!
    \qmlproperty string qbs::optimization

    The general type of optimization that should be performed by all toolchains.

    Allowed values are:

    \list
        \li \c{"fast"}
        \li \c{"none"}
        \li \c{"small"}
    \endlist

    \defaultvalue \c{"none"} for debug builds, \c{"fast"} for release builds.
*/

/*!
    \qmlproperty string qbs::targetPlatform
    \since 1.11

    The OS you want to build the project for.

    This property is typically set in a profile or for a particular product
    where the target OS is always known (such as an Apple Watch app written in
    native code).

    For example, a profile used for building for the iOS Simulator platform will have this
    property set to the \c ios-simulator value:
    \code
        profiles.xcode-iphonesimulator.qbs.targetPlatform: "ios-simulator"
    \endcode

    You should generally treat this property as \e{write-only} and avoid using
    it to test for the current target OS. Instead, use the \l{qbs::}{targetOS}
    property for conditionals.

    \section2 Relation between targetPlatform and targetOS

    This table describes the possible values and matching between the \c targetPlatform
    and the \l{qbs::}{targetOS} properties:
    \table
    \header
        \li Target Platform
        \li Target OS
    \row
        \li \c{"aix"}
        \li \c{["aix", "unix"]}
    \row
        \li \c{"android"}
        \li \c{["android", "linux", "unix"]}
    \row
        \li \c{"freebsd"}
        \li \c{["freebsd", "bsd", "unix"]}
    \row
        \li \c{"haiku"}
        \li \c{["haiku"]}
    \row
        \li \c{"hpux"}
        \li \c{["hpux", "unix"]}
    \row
        \li \c{"hurd"}
        \li \c{["hurd", "unix"]}
    \row
        \li \c{"integrity"}
        \li \c{["integrity", "unix"]}
    \row
        \li \c{"ios"}
        \li \c{["ios", "darwin", "bsd", "unix"]}
    \row
        \li \c{"ios-simulator"}
        \li \c{["ios-simulator", "ios", "darwin", "bsd", "unix"]}
    \row
        \li \c{"linux"}
        \li \c{["linux", "unix"]}
    \row
        \li \c{"lynx"}
        \li \c{["lynx"]}
    \row
        \li \c{"macos"}
        \li \c{["macos", "darwin", "bsd", "unix"]}
    \row
        \li \c{"netbsd"}
        \li \c{["netbsd", "bsd", "unix"]}
    \row
        \li \c{"openbsd"}
        \li \c{["openbsd", "bsd", "unix"]}
    \row
        \li \c{"qnx"}
        \li \c{["qnx", "unix"]}
    \row
        \li \c{"solaris"}
        \li \c{["solaris", "unix"]}
    \row
        \li \c{"tvos"}
        \li \c{["tvos", "darwin", "bsd", "unix"]}
    \row
        \li \c{"tvos-simulator"}
        \li \c{["tvos-simulator", "tvos", "darwin", "bsd", "unix"]}
    \row
        \li \c{"vxworks"}
        \li \c{["vxworks"]}
    \row
        \li \c{"watchos"}
        \li \c{["watchos", "darwin", "bsd", "unix"]}
    \row
        \li \c{"watchos-simulator"}
        \li \c{["watchos-simulator", "watchos", "darwin", "bsd", "unix"]}
    \row
        \li \c{"windows"}
        \li \c{["windows"]}
    \endtable

    \sa {Target Platforms}

    \nodefaultvalue
*/

/*!
    \qmlproperty string qbs::architecture

    The target platform's processor architecture.

    \c{undefined} indicates that the target platform is architecture-independent
    (for example the CLR or JVM).

    This property is typically set in a profile.

    Commonly used values are: \c{"x86"}, \c{"x86_64"}, and \c{"arm"}.

    \nodefaultvalue
*/

/*!
    \qmlproperty string qbs::toolchainType
    \since Qbs 1.11

    The toolchain that is going to be used for this build.

    You should generally treat this property as \e{write-only} and avoid using
    it to test for the current toolchain. Instead, use the \l{qbs::}{toolchain}
    property for conditionals.

    For example, instead of:

    \code
    (qbs.toolchainType === "xcode" || qbs.toolchainType === "clang" || qbs.toolchainType === "gcc")
    \endcode

    use:

    \code
    qbs.toolchain.contains("gcc")
    \endcode

    However, there are some cases when using \c toolchainType would be
    acceptable, such as when the resulting condition would be simpler while
    still being correct:

    \code
    (qbs.toolchainType === "gcc")
    \endcode

    versus:

    \code
    (qbs.toolchain.contains("gcc") && !qbs.toolchain.contains("clang"))
    \endcode

    Typical values include: \c{"gcc"}, \c{"clang"}, \c{"mingw"}, \c{"msvc"}, and
    \c{"xcode"}.

    \defaultvalue Determined automatically.
*/

/*!
    \qmlproperty string qbs::sysroot

    The \c sysroot of the target platform.

    This property is typically set in a profile for cross-compiling.

    \nodefaultvalue
*/

/*!
    \qmlproperty string qbs::pathListSeparator

    The platform-specific separator for a path list that is used in environment
    variables or other contexts.

    \defaultvalue \c{";"} on Windows, \c{":"} on Unix.
*/

/*!
    \qmlproperty string qbs::nullDevice
    \since Qbs 1.4.2

    The platform-specific file path corresponding to the null device.

    \defaultvalue \c{"NUL"} on Windows, \c{"/dev/null"} on Unix.
*/

/*!
    \qmlproperty path qbs::shellPath
    \since Qbs 1.5

    The platform-specific file path corresponding to the command line
    interpreter.

    On Windows, this is the path to \c{cmd.exe}, which is held in the
    \c{COMSPEC} environment variable (typically,
    \c{C:/Windows/System32/cmd.exe}),
    On Unix-like platforms, this is \c{/bin/sh}.

    \defaultvalue \c{"%COMSPEC%"} on Windows, \c{"/bin/sh"} on Unix
*/

/*!
    \qmlproperty stringList qbs::hostOS

    This property is set by \QBS internally and specifies the OS \QBS is running
    on.

    The possible values for this property are the values of \l{qbs::}{targetOS},
    even though some of them may not be supported.

    \nodefaultvalue
*/

/*!
    \qmlproperty string qbs::hostOSVersion
    \readonly
    \since Qbs 1.2

    The host operating system version. Currently, only defined for Windows and
    Apple platforms.

    Consists of two or three numbers separated by dots. For example, \c "10.9"
    or \c "6.3.9600".

    \nodefaultvalue
*/

/*!
    \qmlproperty string qbs::hostOSBuildVersion
    \readonly
    \since Qbs 1.2

    The host operating system's build version. Currently, only defined for
    Windows and Apple platforms.

    On Windows, this is the 4 or 5 digit Windows build number and is equivalent
    to \l{qbs::}{versionPatch}. On Apple platforms, this is a standard build
    number in the Apple versioning scheme. For example, \c "13C64".

    \nodefaultvalue
*/

/*!
    \qmlproperty int qbs::hostOSVersionMajor
    \readonly
    \since Qbs 1.2

    The host operating system major version.

    \defaultvalue \c{hostOSVersionParts[0]}
*/

/*!
    \qmlproperty int qbs::hostOSVersionMinor
    \since Qbs 1.2

    The host operating system minor version.

    \defaultvalue \c{hostOSVersionParts[1]}
*/

/*!
    \qmlproperty list qbs::hostOSVersionParts
    \readonly
    \since Qbs 1.2

    The host operating system version as a list.

    For example, Windows 8.1 (version 6.3.9600) would correspond to a value of
    \c[6, 3, 9600].

    \defaultvalue \c []
*/

/*!
    \qmlproperty int qbs::hostOSVersionPatch
    \readonly
    \since Qbs 1.2

    The host operating system patch level.

    \defaultvalue \c{hostOSVersionParts[2]}
*/

/*!
    \qmlproperty string qbs::hostPlatform
    \since Qbs 1.11

    Do not use this property.

    \defaultvalue Determined automatically.
*/

/*!
    \qmlproperty stringList qbs::targetOS
    \readonly

    Contains the list of string values describing the OS and OS family that is
    used to build a project.

    This property is calculated based on the \l{qbs::}{targetPlatform} property and is typically
    used to test for a particular OS or OS family in conditionals:
    \code
        Group {
            // Includes all Unix-like platforms, such as: Linux, BSD, Apple platforms and others.
            condition: qbs.targetOS.contains("unix")
            files: ...
        }
        Group {
            // Includes all Apple platforms, such as macOS, iOS, and iOS Simulator.
            condition: qbs.targetOS.contains("darwin")
            files: ...
        }
        Group {
            // Includes only macOS
            condition: qbs.targetOS.contains("macos")
            files: ...
        }
    \endcode
    Avoid using \l{qbs::}{targetPlatform} for this purpose. For example, instead of:

    \code
    qbs.targetPlatform === "macos" || qbs.targetPlatform === "ios" || qbs.targetPlatform === "tvos" || qbs.targetPlatform === "watchos"
    \endcode

    use

    \code
    qbs.targetOS.contains("darwin")

    \endcode

    However, in some cases using \l{qbs::}{targetPlatform} would be acceptable, such as
    when the resulting condition would be simpler while still being correct:

    \code
    qbs.targetPlatform === "linux"
    \endcode

    versus
    \code
    qbs.targetOS.contains("linux") && !qbs.targetOS.contains("android")
    \endcode

    For the complete list of possible values, see
    \l{Relation between targetPlatform and targetOS}.

    \nodefaultvalue
*/

/*!
    \qmlproperty stringList qbs::toolchain

    The attributes of the toolchain that is going to be used for this build.

    Typical values include \c{"llvm"}, in addition to the possible values of
    \l{qbs::}{toolchainType}.

    \nodefaultvalue
*/

/*!
    \qmlproperty string qbs::version
    \readonly
    \since Qbs 1.4.1

    The version number of \QBS as a string. For example, \c "1.4.1".
*/

/*!
    \qmlproperty int qbs::versionMajor
    \readonly
    \since Qbs 1.4.1

    The major version number of \QBS.
*/

/*!
    \qmlproperty int qbs::versionMinor
    \readonly
    \since Qbs 1.4.1

    The minor version number of \QBS.
*/

/*!
    \qmlproperty int qbs::versionPatch
    \readonly
    \since Qbs 1.4.1

    The patch version number of \QBS.
*/

/*!
    \qmlproperty bool qbs::install

    Whether to install a certain set of files.

    This property is typically set in a \l{Group} item to mark a number of files
    as installable.

    \note Artifacts for which this property is enabled automatically receive the
    file tag \c "installable". This is useful for writing packaging-related
    rules.

    \defaultvalue \c{false}
*/

/*!
    \qmlproperty string qbs::installSourceBase
    \since Qbs 1.4

    The base directory of the local files that are going to be installed. The
    source base directory is omitted from the target directory path specified in
    \l{qbs::}{installDir}.

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

/*!
    \qmlproperty string qbs::installDir

    The installation directory for the files of a \l{Product}{product} or a
    \l{Group}.

    The value of this property is a path that is relative to \l{qbs::}
    {installPrefix}.

    \nodefaultvalue
*/

/*!
    \qmlproperty string qbs::installPrefix
    \since Qbs 1.1

    The global installation prefix. It is implicitly prepended to all values of
    \l{qbs::}{installDir}.

    The value of this property itself is relative to the \l{qbs::}{installRoot}
    in the context of installation.

    \defaultvalue \c "/usr/local" on Unix, \c "" otherwise
*/

/*!
    \qmlproperty string qbs::installRoot
    \since Qbs 1.4

    The global installation root. It is implicitly prepended to all values
    of \l{qbs::}{installPrefix} in the context of installation.

    \note This property is fundamentally different from \l{qbs::}{installDir}
    and \l{qbs::}{installPrefix} in that it must not be visible to the code
    being built. In fact, the install root is often just a temporary location
    used to package the binaries, which should therefore not assume they will be
    in that location at run-time. For the same reason, this property
    is usually not set from within project files.

    \defaultvalue \c{<build dir>/install-root}
*/

/*!
    \qmlproperty stringList qbs::architectures
    \since Qbs 1.9

    The architectures the product will be built for.

    \nodefaultvalue
*/

/*!
    \qmlproperty stringList qbs::buildVariants
    \since Qbs 1.9

    The build variants the product will be built for.

    \nodefaultvalue
*/

/*!
    \qmlproperty stringList qbs::profiles
    \since Qbs 1.9

    The profiles for which the product should be built.

    For each profile listed here, one instance of the product will be built
    according to the properties set in the respective profile.

    \defaultvalue \l{Project::profile}{[project.profile]}
*/