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"}, \c{"release"} and \c{"profiling"}.
    A debug build usually contains additional debug symbols that are needed for
    debugging the application and has optimizations turned off. A profiling
    build usually contains debug symbols and has optimizations turned on. This
    is useful for profiling tools or when you need to retain debug symbols
    in a release build. A release build is a build without debug information and
    with optimizations enabled.

    \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} if \l{qbs::buildVariant}{qbs.buildVariant} is \c{"debug"} or
    \c{"profiling"}. Otherwise \c{false}.
*/

/*!
    \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 or profiling 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"} if \l{qbs::buildVariant}{qbs.buildVariant} is \c{"debug"}.
    Otherwise \c{"fast"}.
*/

/*!
    \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{"unix"}
        \li \c{["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"]}
    \row
        \li \c{undefined}
        \li \c{[]}
    \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"}.

    \section2 Supported Processor Architectures

    This table describes the possible values of the \l{qbs::}{architecture} property:
    \table
    \header
        \li Architecture
        \li Description
    \row
        \li \c{"78k"}
        \li 16- and 8-bit accumulator-based register-bank CISC architecture
            microcontroller family manufactured by Renesas Electronics
    \row
        \li \c{"arm"}
        \li 32-bit RISC architecture for computer processors
            developed by Acorn RISC Machine
            \note There are a lot of sub-variants of the ARM architecture.
                  Some specialized \QBS modules differentiate between them,
                  making use of values such as \c "armv7a". Please consult the
                  respective module-specific documentation for information
                  on what kind of value to use.
    \row
        \li \c{"arm64"}
        \li 64-bit RISC architecture for computer processors
            developed by Acorn RISC Machine
    \row
        \li \c{"avr"}
        \li 8-bit modified Harvard RISC architecture microcontroller
            family manufactured by Microchip Technology
    \row
        \li \c{"avr32"}
        \li 32-bit RISC architecture microcontroller family developed by Atmel
    \row
        \li \c{"ia64"}
        \li 64-bit ISA architecture of the Itanium family processors
            developed by Intel
    \row
        \li \c{"m32c"}
        \li 32- and 16-bit CISC microcontrollers featuring high ROM code
            efficiency manufactured by Renesas Electronics
    \row
        \li \c{"m32r"}
        \li 32-bit RISC microcontrollers for general industrial and
            car-mounted systems, digital AV equipment, digital imaging
            equipment manufactured by Renesas Electronics
    \row
        \li \c{"m68k"}
        \li 16- and 32-bit CISC microprocessor, developed by Motorola
            Semiconductor Products Sector, and further improved as ColdFire
            architecture developed by NXP
    \row
        \li \c{"mcs51"}
        \li 8-bit Harvard architecture microcontroller family developed by Intel
    \row
        \li \c{"mips"}
        \li 32-bit RISC microprocessor without interlocked pipelined stages
            architecture developed by MIPS Computer Systems
    \row
        \li \c{"mips64"}
        \li 64-bit RISC microprocessor without interlocked pipelined stages
            architecture developed by MIPS Computer Systems
    \row
        \li \c{"msp430"}
        \li 16-bit mixed-signal microcontroller family manufactured
            by Texas Instruments
    \row
        \li \c{"ppc"}
        \li 32-bit RISC architecture processor family developed by
            Apple–IBM–Motorola alliance
    \row
        \li \c{"ppc64"}
        \li 64-bit RISC architecture processor family developed by
            Apple–IBM–Motorola alliance
    \row
        \li \c{"rh850"}
        \li 32-bit automotive microcontroller family manufactured
            by Renesas Electronics
    \row
        \li \c{"riscv"}
        \li Open and free standard instruction set architecture based on established
            RISC principles
    \row
        \li \c{"rl78"}
        \li 16- and 8-bit accumulator-based register-bank CISC architecture
            with 3-stage instruction pipelining microcontroller family manufactured
            by Renesas Electronics
    \row
        \li \c{"rx"}
        \li High performance 32-bit CISC microcontroller family manufactured
            by Renesas Electronics
    \row
        \li \c{"s390x"}
        \li 64- and 32-bit System/390 processor architecture developed by IBM
    \row
        \li \c{"sh"}
        \li 32-bit RISC architecture processor family developed by Hitachi and
            currently manufactured by Renesas Electronics
    \row
        \li \c{"sparc"}
        \li 32-bit RISC architecture processor family developed by
            Sun Microsystems and Fujitsu
    \row
        \li \c{"sparc64"}
        \li 64-bit RISC architecture processor family developed by
            Sun Microsystems and Fujitsu
    \row
        \li \c{"stm8"}
        \li 8-bit microcontroller family manufactured by STMicroelectronics
    \row
        \li \c{"v850"}
        \li 32-bit RISC microcontroller family manufactured by Renesas Electronics
    \row
        \li \c{"x86"}
        \li 32-bit ISA architecture processor family developed by Intel
    \row
        \li \c{"x86_64"}
        \li 64-bit ISA architecture processor family developed by AMD
    \endtable
    \row
        \li \c{"xtensa"}
        \li 32-bit architecture with a compact 16- and 24-bit instruction set
            developed by Tensilica
    \endtable

    \nodefaultvalue
*/

/*!
    \qmlproperty stringList qbs::toolchain

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

    This property is deduced from the \l{qbs::}{toolchainType} property and is typically
    used to test for a particular toolchain or toolchain family in conditionals:

    \code
        Properties {
            // flags for GCC
            condition: qbs.toolchain.contains("gcc")
            cpp.commonCompilerFlags: ...
        }
        Properties {
            // flags for MSVC
            condition: qbs.toolchain.contains("msvc")
            cpp.commonCompilerFlags: ...
        }
    \endcode

    Unlike \l{qbs::}{toolchainType}, which contains a single value, \c qbs.toolchain
    is a string list which also contains the toolchain family. This allows to make
    conditions and checks simpler. For example, instead of:

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

    use:

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

    since XCode, GCC and Clang belong to the \c "gcc" family.

    \section2 Relation between toolchainType and toolchain

    This table describes the possible values and matching between the \l{qbs::}{toolchainType}
    and the \c toolchain properties:
    \table
    \header
        \li Toolchain Type
        \li Toolchain
    \row
        \li \c{"clang"}
        \li \c{["clang", "llvm", "gcc"]}
    \row
        \li \c{"clang-cl"}
        \li \c{["clang-cl", "msvc"]}
    \row
        \li \c{"gcc"}
        \li \c{["gcc"]}
    \row
        \li \c{"iar"}
        \li \c{["iar"]}
    \row
        \li \c{"keil"}
        \li \c{["keil"]}
    \row
        \li \c{"llvm"}
        \li \c{["llvm", "gcc"]}
    \row
        \li \c{"mingw"}
        \li \c{["mingw", "gcc"]}
    \row
        \li \c{"msvc"}
        \li \c{["msvc"]}
    \row
        \li \c{"sdcc"}
        \li \c{["sdcc"]}
    \row
        \li \c{"xcode"}
        \li \c{["xcode", "clang", "llvm", "gcc"]}
    \endtable

    \nodefaultvalue
*/

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

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

    For example, to build a project using the \c "clang" toolchain, simply do
    \code
    qbs build qbs.toolchainType:clang
    \endcode

    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.

    Typical values include: \c{"gcc"}, \c{"clang"}, \c{"clang-cl"}, \c{"mingw"},
    \c{"msvc"}, and \c{"xcode"}. Also see \l{Relation between toolchainType and toolchain}.

    By default, \c qbs.toolchainType is automatically detected based on the
    \l{qbs::}{targetOS} property:
    \table
    \header
        \li Target OS
        \li Toolchain
    \row
        \li \c{"darwin"}
        \li \c{"xcode"}
    \row
        \li \c{"freebsd"}
        \li \c{"clang"}
    \row
        \li \c{"haiku"}
        \li \c{"gcc"}
    \row
        \li \c{"qnx"}
        \li \c{"qcc"}
    \row
        \li \c{"unix"}
        \li \c{"gcc"}
    \row
        \li \c{"vxworks"}
        \li \c{"gcc"}
    \row
        \li \c{"windows"}
        \li \c{"msvc"}
    \endtable

    \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 string qbs::hostArchitecture
    \since Qbs 1.16

    Contains the host OS architecture.

    \defaultvalue Determined automatically.
*/

/*!
    \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

    Contains the host OS platform.

    \sa {qbs::hostArchitecture}{hostArchitecture}

    \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 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]}
*/