/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing
**
** This file is part of the Qt Build Suite.
**
** 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 http://www.qt.io/terms-conditions. For further information
** use the contact form at http://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 or version 3 as published by the Free
** Software Foundation and appearing in the file LICENSE.LGPLv21 and
** LICENSE.LGPLv3 included in the packaging of this file.  Please review the
** following information to ensure the GNU Lesser General Public License
** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, The Qt Company gives you certain additional
** rights.  These rights are described in The Qt Company LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
****************************************************************************/

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

    \title Module cpp
    \brief Provides C/C++ support.

    The \c cpp module contains the properties and rules for toolchains of the C/C++ family.
    On OS X this includes support for Objective-C/C++.

    \section1 General Properties

    \section2 allowUnresolvedSymbols

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{false}
    \endtable

    Switch this on if you want the linking step to succeed even if the resulting binary contains
    unresolved symbols. Normally this makes little sense, but in special cases it is possible that
    the respective symbols will be available at load time even if they are not present during
    linking.

    \section2 architecture

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{qbs.architecture}
    \endtable

    Target architecture. See \c{qbs.architecture}.

    \section2 debugInformation

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{qbs.debugInformation}
    \endtable

    Generate debug information. See \c{qbs.debugInformation}.

    \section2 separateDebugInformation

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{false} for gcc/clang, \c{true} for MSVC
    \endtable

    Whether to store debug information in an external file or bundle instead of within the binary.

    \section2 defines

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of preprocessor macros that gets passed to the compiler.
    To set macro values use the following syntax:
    \code
    cpp.defines: ["USE_COLORS=1", 'COLOR_STR="blanched almond"']
    \endcode

    \section2 platformDefines

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of preprocessor macros that are used for all projects that are built for the current
    target platform. User project files usually do not set this property.

    \section2 compilerDefines

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of preprocessor macros that are used for all projects that are using the current toolchain.
    User project files usually do not set this property.

    \section2 includePaths

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of include paths. Relative paths are considered to be relative to the .qbs product file
    they are used in.

    \section2 systemIncludePaths

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of include paths that are passed as system include paths to the compiler.
    For header files in those paths warnings will be ignored.
    Relative paths are considered to be relative to the .qbs product file they are used in.

    \section2 libraryPaths

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of library search paths. Relative paths are considered to be relative to the .qbs product
    file they are used in.

    \section2 dynamicLibraries

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of dynamic libraries to be linked. If the library is part of your project, consider
    using a Depends item instead.

    \section2 staticLibraries

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of static libraries to be linked. If the library is part of your project, consider
    using a Depends item instead.

    \section2 prefixHeaders

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of files to automatically include at the beginning of each source file in the product.

    \section2 precompiledHeader

    \table
    \row    \li \b{Type:}            \li \c{path}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Name of the header file to be precompiled.

    If you want to use the same precompiled header for all languages (C, C++,
    Objective-C and Objective-C++), set this property and ensure that the header
    contains appropriate ifdefs.

    Otherwise, use the \c{cPrecompiledHeader}, \c{cppPrecompiledHeader},
    \c{objcPrecompiledHeader} and \c{objcppPrecompiledHeader} to specify
    precompiled headers per-language.

    \section2 cPrecompiledHeader

    \table
    \row    \li \b{Type:}            \li \c{path}
    \row    \li \b{Default:}         \li \c{precompiledHeader}
    \endtable

    Name of the C header file to be precompiled.

    \section2 cxxPrecompiledHeader

    \table
    \row    \li \b{Type:}            \li \c{path}
    \row    \li \b{Default:}         \li \c{precompiledHeader}
    \endtable

    Name of the C++ header file to be precompiled.

    \section2 objcPrecompiledHeader

    \table
    \row    \li \b{Type:}            \li \c{path}
    \row    \li \b{Default:}         \li \c{precompiledHeader}
    \endtable

    Name of the Objective-C header file to be precompiled.

    \section2 objcxxPrecompiledHeader

    \table
    \row    \li \b{Type:}            \li \c{path}
    \row    \li \b{Default:}         \li \c{precompiledHeader}
    \endtable

    Name of the Objective-C++ header file to be precompiled.

    \section2 precompiledHeaderDir

    \table
    \row    \li \b{Type:}            \li \c{path}
    \row    \li \b{Default:}         \li \c{product.buildDirectory}
    \endtable

    The directory that will contain the precompiled header files.
    Usually you won't need to set this.

    \section2 optimization

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{qbs.optimization}
    \endtable

    Optimization level. See \c{qbs.optimization}.

    \section2 treatWarningsAsErrors

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{false}
    \endtable

    Warnings will be handled as errors and cause the build to fail.

    \section2 warningLevel

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Allowed Values:}  \li \c{"none"}, \c{"all"}
    \row    \li \b{Default:}         \li \c{"all"}
    \endtable

    Specifies the warning level for the compiler.

    \section2 commonCompilerFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Flags that are added to all compilation commands independently of the language.

    \section2 compilerVersionMajor

    \table
    \row    \li \b{Type:}            \li \c{int}
    \row    \li \b{Default:}         \li undefined
    \endtable

    The major version of the compiler.

    \section2 compilerVersionMinor

    \table
    \row    \li \b{Type:}            \li \c{int}
    \row    \li \b{Default:}         \li undefined
    \endtable

    The minor version of the compiler.

    \section2 compilerVersionPatch

    \table
    \row    \li \b{Type:}            \li \c{int}
    \row    \li \b{Default:}         \li undefined
    \endtable

    The patch level component of the compiler version.

    \section2 cppFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the C preprocessor.

    \section2 cFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the C compiler.

    \section2 cxxFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the C++ compiler.

    \section2 cLanguageVersion

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li undefined
    \row    \li \b{Allowed Values:}  \li \c{"c89"}, \c{"c99"}, \c{"c11"}
    \endtable

    The version of the C standard with which the code must comply. If this property is set,
    corresponding compiler and/or linker flags will be added, depending on the toolchain.
    If the value is left undefined, the compiler default will be used.

    \section2 cxxLanguageVersion

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li undefined
    \row    \li \b{Allowed Values:}  \li \c{"c++98"}, \c{"c++11"}, \c{"c++14"}
    \endtable

    The version of the C++ standard with which the code must comply. If this property is set,
    corresponding compiler and/or linker flags will be added, depending on the toolchain.
    If the value is left undefined, the compiler default will be used.

    \section2 cxxStandardLibrary

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li undefined
    \row    \li \b{Possible Values:} \li \c{"libstdc++"}, \c{"libc++"}
    \endtable

    The C++ standard library to link to. If this property is set, corresponding compiler and/or
    linker flags will be added, assuming the value is valid for the current toolchain.
    If the value is left undefined, the compiler default will be used.

    \section2 objcFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the Objective-C compiler.

    \section2 objcxxFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the Objective-C++ compiler.

    \section2 linkerFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the linker.

    \section2 linkerScripts

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of linker script files.

    \section2 compilerName

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li determined by qbs-setup-toolchains
    \endtable

    Name of the main compiler binary. This is set in the build profile.

    \section2 compilerPath

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li determined by qbs-setup-toolchains
    \endtable

    Full path of the main compiler binary. This is set in the build profile.
    If the toolchain provides different compilers for different languages, then
    \c{compilerPathByLanguage} is used.

    \section2 compilerPathByLanguage

    \table
    \row    \li \b{Type:}            \li \c{string} to \c{string} map
    \row    \li \b{Default:}         \li determined by qbs-setup-toolchains
    \endtable

    Maps file tags to full paths of compiler binaries. This is set in the build profile.

    \section2 compilerWrapper

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Wrapper binary and its arguments for wrapping compiler calls.
    This is useful for compiler wrappers like ccache and alike.

    \section2 linkerName

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li determined by qbs-setup-toolchains
    \endtable

    Name of the linker binary. This is set in the build profile.

    \section2 linkerPath

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li determined by qbs-setup-toolchains
    \endtable

    Full path of the linker binary. This is set in the build profile.

    \section2 entryPoint

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Name of the entry point of an executable or dynamic library. If this property is undefined, the
    toolchain's default is used.

    \section2 runtimeLibrary

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{"dynamic"} for MSVC, \c{undefined} for others
    \endtable

    Type of the used runtime library. Accepted values are \c{"static"} and \c{"dynamic"}.
    If this property is set to \c{undefined}, then the default runtime library of the toolchain
    is used.
    \note For MSVC the default value is \c{"dynamic"}.
    \note At the moment this property is only functional for MSVC.


    \section1 Properties Specific to iOS and OS X

    \section2 frameworkPaths

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of framework search paths. Relative paths are considered to be relative to the .qbs product
    file they are used in.

    \section2 systemFrameworkPaths

    \table
    \row    \li \b{Type:}            \li \c{pathList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of framework search paths. Relative paths are considered to be relative to the .qbs product
    file they are used in. Header files in frameworks in those paths will not cause warnings.

    \section2 frameworks

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of frameworks to be linked.
    If the framework is part of your project, consider using a Depends item instead.

    \section2 weakFrameworks

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of frameworks to be weakly linked.
    If the framework is part of your project, consider using a Depends item instead.

    \section2 installNamePrefix

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    The prefix for the internal install name (LC_ID_DYLIB) of a dynamic library on Darwin
    (OS X and iOS). Typically this should be set to \c{"@rpath"} on modern platforms that
    support it, which includes OS X 10.5 and above, and all versions of iOS.

    \section2 automaticReferenceCounting

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Whether to enable Automatic Reference Counting (ARC) for Objective-C and Objective-C++ source
    code. If \c{undefined}, uses the compiler default (probably \c{false}).

    \section2 requireAppExtensionSafeApi

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Whether to enforce the use of only app-extension-safe APIs on OS X and iOS. This is necessary
    for building Application Extensions in OS X Yosemite and iOS 8 and above. If \c{undefined}, uses
    the compiler and linker defaults (probably \c{false}).


    \section1 Properties Specific to iOS

    \section2 minimumIosVersion

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li undefined, but may be set by generated profiles
    \endtable

    A version number in the format [major].[minor] indicating the earliest version of OS X that the
    product should run on. Passes -miphoneos-version-min=<version> to the compiler.
    If undefined, compiler defaults will be used.


    \section1 Properties Specific to OS X

    \section2 minimumOsxVersion

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li undefined, but may be set by generated profiles
    \endtable

    A version number in the format [major].[minor] indicating the earliest version of OS X that the
    product should run on. Passes -mmacosx-version-min=<version> to the compiler.
    If undefined, compiler defaults will be used.


    \section1 Properties Specific to Unix Platforms

    \section2 archiverName

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{"ar"}
    \endtable

    Name of the archiver binary. This is set in the build profile.

    \section2 archiverPath

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li determined by qbs-setup-toolchains
    \endtable

    Full path of the archiver binary. This is set in the build profile.

    \section2 exportedSymbolsCheckMode

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li "ignore-undefined"
    \endtable

    Controls how \QBS determines whether an updated dynamic library causes relinking of
    dependents. The default value is \c "ignore-undefined", which means that undefined symbols being
    added or removed do not cause any relinking. If that should happen, for example because
    dependent products are linked with an option such as \c "--no-undefined", then this property
    can be set to \c "strict".

    \section2 nmName

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{"nm"}
    \endtable

    Name of the nm binary. This is set in the build profile.

    \section2 nmPath

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li determined by qbs-setup-toolchains
    \endtable

    Full path of the nm binary. This is set in the build profile.

    \section2 objcopyName

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{"objcopy"}
    \endtable

    Name of the objcopy binary. This is set in the build profile.

    \section2 objcopyPath

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li determined by qbs-setup-toolchains
    \endtable

    Full path of the objcopy binary. This is set in the build profile.

    \section2 stripName

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li \c{"strip"}
    \endtable

    Name of the strip binary. This is set in the build profile.

    \section2 stripPath

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li determined by qbs-setup-toolchains
    \endtable

    Full path of the strip binary. This is set in the build profile.

    \section2 dsymutilPath

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li determined by qbs-setup-toolchains
    \endtable

    Full path of the dsymutil binary. This is set in the build profile.

    \section2 dsymutilFlags

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li undefined
    \endtable

    Additional flags for the dsymutil tool.

    \section2 positionIndependentCode

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    Generate position independent code.
    If this property is \c{undefined}, then position independent code is generated for libraries,
    but not for applications.

    \section2 rpaths

    \table
    \row    \li \b{Type:}            \li \c{stringList}
    \row    \li \b{Default:}         \li \c{undefined}
    \endtable

    List of rpaths that are passed to the linker.

    \section2 useRPaths

    \table
    \row    \li \b{Type:}            \li \c{bool}
    \row    \li \b{Default:}         \li \c{true}
    \endtable

    Set this property to \c{false} to prevent the linker from writing rpaths to the binary.

    \section2 visibility

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Allowed Values:}  \li \c{"default"}, \c{"hidden"}, \c{"hiddenInlines"},
                                         \c{"minimal"}
    \row    \li \b{Default:}         \li \c{"default"}
    \endtable

    Visibility level for exported symbols.
    The \c{"minimal"} value combines \c{"hidden"} and \c{"hiddenInlines"}.


    \section1 Properties Specific to Windows

    \section2 windowsApiCharacterSet

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Allowed Values:}  \li \c{"unicode"}, \c{"mbcs"}, \c{undefined}
    \row    \li \b{Default:}         \li \c{"unicode"}
    \endtable

    Specifies the character set used in the Win32 API. "unicode" will define the
    preprocessor symbols UNICODE and _UNICODE, "mbcs" will define _MBCS, and
    setting the value to undefined will use the default character set.

    \section2 minimumWindowsVersion

    \table
    \row    \li \b{Type:}            \li \c{string}
    \row    \li \b{Default:}         \li undefined, but may be set by generated profiles
    \endtable

    A version number in the format [major].[minor] indicating the earliest version of Windows that
    the product should run on. Defines WINVER, _WIN32_WINNT, and _WIN32_WINDOWS, and applies a
    version number to the linker flags /SUBSYSTEM and /OSVERSION for MSVC or
    -Wl,--major-subsystem-version, -Wl,--minor-subsystem-version, -Wl,--major-os-version and
    -Wl,--minor-os-version for MinGW.
    If undefined, compiler defaults will be used.
*/
