/**************************************************************************** ** ** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** 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 Digia. For licensing terms and ** conditions see http://www.qt.io/licensing. 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, Digia gives you certain additional ** rights. These rights are described in the Digia Qt 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 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 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 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 supportedStaticLibrarySuffixes \table \row \li \b{Type:} \li \c{stringList} \row \li \b{Default:} \li \c{undefined} \endtable List of file suffixes this toolchain's linker accepts as input. For example, for MinGW this list should be \c{[".a", ".lib"]}. \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 infoPlistFile \table \row \li \b{Type:} \li \c{path} \row \li \b{Default:} \li \c{undefined} \endtable Path to the Info.plist file used by the bundle. The contents of this file will be aggregated with the values in \c{infoPlist}. If \c{infoPlistFile} and \c{infoPlist} contain the same key, the latter will take precedence, but may also be overridden during postprocessing (see \c{processInfoPlist}). If undefined, will not be taken into account. \section2 infoPlist \table \row \li \b{Type:} \li \c{object} \row \li \b{Default:} \li \c{undefined} \endtable Dictionary of key-value pairs to add to the bundle's Info.plist. The contents of this property will be aggregated with the values from \c{infoPlistFile}. If \c{infoPlist} and \c{infoPlistFile} contain the same key, the former will take precedence, but may also be overridden during postprocessing (see \c{processInfoPlist}). If undefined, will not be taken into account. \section2 processInfoPlist \table \row \li \b{Type:} \li \c{bool} \row \li \b{Default:} \li \c{true} \endtable Whether to perform post-processing on the aggregated Info.plist contents. If this property is \c{true}, various post-processing operations will be applied to the bundle's property list dictionary after it has been aggregated from the contents of the file specified by the \c{infoPlistFile} property and the \c{infoPlist} property. First, values from a list of defaults will be added to the dictionary if they were not already present. Then, values from the AdditionalInfo key of the platform SDK's Info.plist file will be added to the dictionary if they were not already present, as well as some other miscellaneous keys, such as BuildMachineOSBuild and UIDeviceFamily (on iOS). Finally, variable expansions will be performed such that substrings of the form $(VAR) or ${VAR} will be replaced with their corresponding environment variables. \section2 embedInfoPlist \table \row \li \b{Type:} \li \c{bool} \row \li \b{Default:} \li \c{true} if the product is a command line tool, otherwise \c{false}. \endtable Whether to create a __TEXT section in the product's executable containing the processed Info.plist. Only applies to command line applications. \section2 infoPlistFormat \table \row \li \b{Type:} \li \c{string} \row \li \b{Allowed Values:} \li \c{"xml1"}, \c{"binary1"}, \c{"json"}, \c{"same-as-input"} \row \li \b{Default:} \li \c{"binary1"} for iOS; \c{"same-as-input"} or \c{"xml1"} for OS X depending on whether \c{infoPlistFile} is specified; undefined for all other operating systems. \endtable The file format to write the product's resulting Info.plist in. \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= 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= 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 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. */