diff options
author | Leena Miettinen <riitta-leena.miettinen@qt.io> | 2017-10-05 11:15:00 +0200 |
---|---|---|
committer | Leena Miettinen <riitta-leena.miettinen@qt.io> | 2017-10-05 10:34:58 +0000 |
commit | d4ae9eac017bf3ddb9f1619d4fa574544a7a7829 (patch) | |
tree | 8c240b31c14d7cac41c6ce70d34e42f83cc98ebf /doc/appendix/qbs-porting.qdoc | |
parent | b195b8ea48d29b2fa76717821812ebdada820450 (diff) |
Doc: Describe porting qmake projects to Qbs
Task-number: QBS-407
Change-Id: Ia2f59288e2f9aca0d9fed800ee52c4082cf18d07
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>
Diffstat (limited to 'doc/appendix/qbs-porting.qdoc')
-rw-r--r-- | doc/appendix/qbs-porting.qdoc | 511 |
1 files changed, 511 insertions, 0 deletions
diff --git a/doc/appendix/qbs-porting.qdoc b/doc/appendix/qbs-porting.qdoc new file mode 100644 index 000000000..9b0b316a9 --- /dev/null +++ b/doc/appendix/qbs-porting.qdoc @@ -0,0 +1,511 @@ +/**************************************************************************** +** +** 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 + \previouspage building-qbs.html + \page porting-to-qbs.html + \nextpage attributions.html + + \title Appendix B: Migrating from Other Build Systems + + You can use the \c {qbs create-project} command to automatically generate + \QBS project files from an arbitrary directory structure. This is a useful + starting point when migrating from other build tools, such as qmake or + CMake. + + To use the tool, switch to the project directory and run the + \c {qbs create-project} command, which is located in the \c bin directory of + the \QBS installation directory (or the Qt Creator installation directory). + + After generating the initial .qbs file, add the missing configuration + variables and functions to it, as described in the following sections. + + \section1 Migrating from qmake + + The following sections describe the \QBS equivalents of qmake variable + values. + + \section2 CONFIG + + Specify project configuration and compiler options. + + \section3 console + + Set the \l{Product Item}{consoleApplication} property to \c true for the + \l{Application Item}{Application}, \l{CppApplication Item}{CppApplication}, + or \l{QtApplication Item}{QtApplication} item. For example: + + \code + Application { + name: "helloworld" + files: "main.cpp" + Depends { name: "cpp" } + consoleApplication: true + } + \endcode + + \section3 ordered + + This qmake variable has no direct equivalent in \QBS. Instead, the build + order is determined by implicit and explicit dependencies between products. + To add an explicit dependency, add a \l{Depends Item}{Depends item} to a + \l{Product Item}{product}: + + \code + CppApplication { + name: "myapp" + Depends { name: "mylib" } + } + \endcode + + The \c myapp product depends on and links to the \c mylib product, and is + therefore built after it. + + \section3 qt + + In qmake, the Qt dependency is implicit, whereas in \QBS it is not. + If \c {CONFIG -= qt}, add a \l{Depends Item}{Depends item} to specify that + the \l{Product Item}{product} depends on the \l{Module cpp}{cpp module}: + + \code + Product { + Depends { name: "cpp" } + } + \endcode + + \section2 DEFINES + + Set the \l{Module cpp}{cpp.defines} property for the \l{Product Item}{product}. + + \note To reference \c cpp.defines, you must specify a dependency on the + \l{Module cpp}{cpp} module. + + \code + Product { + Depends { name: "cpp" } + cpp.defines: ["SUPPORT_MY_FEATURES"] + } + \endcode + + \section2 DESTDIR + + We recommend that you use the \l{Installing Files}{installation mechanism} + to specify the location of the target file: + + \code + Application { + Group { + name: "Runtime resources" + files: "*.qml" + qbs.install: true + qbs.installDir: "share/myproject" + } + Group { + name: "The App itself" + fileTagsFilter: "application" + qbs.install: true + qbs.installDir: "bin" + } + } + \endcode + + If that is not possible, you can use the \c destinationDirectory property: + + \code + DynamicLibrary { + name: "mydll" + destinationDirectory: "libDir" + } + \endcode + + \section2 HEADERS, SOURCES, FORMS, RESOURCES + + Include header, source, form, and resource files as values of the \c files + property of the \l{Product Item}{product}: + + \code + QtApplication { + name: "myapp" + files: ["myapp.h", "myapp.cpp", "myapp.ui", "myapp.qrc"] + } + \endcode + + \QBS uses \l{FileTagger Item}{file taggers} to figure out what kind of file + it is dealing with. + + \section2 ICON + + There is no direct equivalent in \QBS. If you add a \l{Depends Item} + {dependency} to the \l{Module ib}{ib module} and add the \c .xcassets + directory as a value of the \c files property of the \l{Product Item} + {product}, \QBS takes care of setting the application icon automatically + when building for Apple platforms: + + \code + Application { + name: "myapp" + files [".xcassets"] + Depends { name: "ib" } + } + \endcode + + Alternatively, you can set the icon name as the value of the + \l{Module bundle}{bundle.infoPlist} parameter, specify a dependency to the + \c ib module, and add the application \c .icns file as a value of the + \c files property: + + \code + Application { + name: "myapp" + files ["myapp.icns"] + Depends { name: "ib" } + bundle.infoPlist: ({"CFBundleIconFile": "myapp"}) + \endcode + + \section2 INCLUDEPATH + + Add the paths to the include files as values of the \l{Module cpp} + {cpp.includePaths} property: + + \code + CppApplication { + cpp.includePaths: ["..", "some/other/dir"] + } + \endcode + + \section2 LIBS + + For libraries that are part of the project, use \l{Depends Item} + {Depends items}. + + To pull in external libraries, use the \l{Module cpp}{cpp.libraryPaths} + property for the Unix \c -L (library path) flags and the + \c cpp.dynamicLibraries and \c cpp.staticLibraries properties for the + \c -l (library) flags. + + For example, \c {LIBS += -L/usr/local/lib -lm} would become: + + \code + CppApplication { + cpp.libraryPaths: ["/usr/local/lib"] + cpp.dynamicLibraries: ["m"] + } + \endcode + + \section2 OUT_PWD + + Use the \c product.buildDirectory property of the \l{Product Item}{product} + to refer to the base output directory of the generated artifacts. + + \section2 PWD + + Corresponds to the the file-scope variable \c path. + + \section2 _PRO_FILE_ + + Corresponds to the file-scope variable \c filePath when used in a + \l{Project Item}{project} or \l{Product Item}{product}. + + \section2 _PRO_FILE_PWD_ + + Corresponds to the \c sourceDirectory property of a + \l{Project Item}{project} or \l{Product Item}{product}. + + \section2 QMAKE_ASSET_CATALOGS + + Add a \l{Depends Item}{dependency} to the \l{Module ib}{ib module} and add + the \c .xcassets directory as a value of the \c files property of the + \l{Product Item}{product}: + + \code + Application { + name: "myapp" + files [".xcassets"] + Depends { name: "ib" } + } + \endcode + + \section2 QMAKE_BUNDLE_DATA + + For the time being, you can manually place files in the appropriate location + using the \l{Installing Files}{installation mechanism}. Better solutions are + under development. + + \section2 QMAKE_BUNDLE_EXTENSION + + Set the \c bundle.extension property for the \l{Module bundle}{bundle}. + + \note Unlike qmake, \QBS automatically prepends a period (.) to the property + value. + + \section2 QMAKE_{C,CXX,OBJECTIVE}_CFLAGS{_DEBUG,_RELEASE} + + Use the \c cpp.commonCompilerFlags property of the the \l{Module cpp}{cpp} + module or the properties corresponding to each compiler flags variable: + + \table + \header + \li qmake Variable + \li cpp Module Property + \row + \li \c QMAKE_CFLAGS_DEBUG + + \c QMAKE_CFLAGS_RELEASE + \li \c cpp.cCompilerFlags + \row + \li \c QMAKE_CXXFLAGS_DEBUG + + \c QMAKE_CXXFLAGS_RELEASE + \li \c cpp.cxxCompilerFlags + \row + \li \c QMAKE_OBJECTIVE_CFLAGS + \li \c cpp.objcCompilerFlags + + \c cpp.objcxxCompilerFlags + \endtable + + Use \l{Properties Item}{Properties items} or simple conditionals as values + of the \l{Module qbs}{qbs.buildVariant} property to simulate the \c _DEBUG + and\c _RELEASE variants of the qmake variables. + + \section2 QMAKE_FRAMEWORK_BUNDLE_NAME + + Set the \c bundle.bundleName property (which is derived from + \c product.target) combined with \c bundle.extension for the + \l{Module bundle}{bundle}. + + \section2 QMAKE_FRAMEWORK_VERSION + + Set the \c bundle.frameworkVersion property for the \l{Module bundle} + {bundle}. + + \section2 QMAKE_INFO_PLIST + + Include the \c info.plist file as a value of the \c files property of the + \l{Product Item}{product} and specify a dependency to the \l{Module bundle} + {bundle} module: + + \code + Application { + name: "myapp" + files ["info.plist"] + Depends { name: "bundle" } + } + \endcode + + \QBS will automatically add any necessary properties to your \c Info.plist + file. Typically, it determines the appropriate values from the other + properties in the project, and therefore you do not need to use the + \c {Info.plist.in > Info.plist} configuration mechanism. Further, you almost + never need to embed placeholders into the source \c Info.plist file. Set the + \c bundle.processInfoPlist property to \c false to disable this behavior: + + \code + \\ ... + bundle.processInfoPlist: false + \endcode + + In addition to, or instead of, using an actual \c Info.plist file, you can + add \c Info.plist properties using the \c bundle.infoPlist property. For + example: + + \code + \\ ... + bundle.infoPlist: ({ + "NSHumanReadableCopyright": "Copyright (c) 2017 Bob Inc", + "Some other key", "Some other value, & XML special characters are no problem! >;) 非凡!" + }) + \endcode + + \section2 QMAKE_LFLAGS + + Set the \l{Module cpp}{cpp.linkerFlags} property for the \l{Product Item} + {product}. + + \section2 QMAKE_{MACOSX,IOS,TVOS,WATCHOS}_DEPLOYMENT_TARGET + + For each qmake deployment target variable, use the corresponding property of + the \l{Module cpp}{cpp} module: + + \table + \header + \li qmake Variable + \li cpp Module Property + \row + \li \c QMAKE_MACOSX_DEPLOYMENT_TARGET + \li \c cpp.minimumMacosVersion + \row + \li \c QMAKE_IOS_DEPLOYMENT_TARGET + \li \c cpp.minimumIosVersion + \row + \li \c QMAKE_TVOS_DEPLOYMENT_TARGET + \li \c cpp.minimumTvosVersion + \row + \li \c QMAKE_WATCHOS_DEPLOYMENT_TARGET + \li \c cpp.minimumWatchosVersion + \endtable + + \section2 QMAKE_RPATHDIR + + Set the \l{Module cpp}{cpp.rpaths} property for the \l{Product Item} + {product}. + + \section2 QMAKE_SONAME_PREFIX + + Use the \l{Module cpp}{cpp.sonamePrefix} property for the \l{Product Item} + {product}. + + \section2 QML_IMPORT_PATH + + Used only for Qt Creator QML syntax highlighting. Inside a \l{Product Item} + {Product}, \l{Application Item}{Application}, \l{CppApplication Item} + {CppApplication}, or \l{QtApplication Item}{QtApplication}, create a + \c qmlImportPaths property: + + \code + Product { + name: "myProduct" + property stringList qmlImportPaths: [sourceDirectory + "/path/to/qml/"] + } + \endcode + + \section2 QT + + Add a \l{Depends Item}{Depends item} to the \l{Product Item}{product} that + specifies the dependencies to \l{Qt Modules}{Qt modules}. For example: + + \code + QtApplication { + Depends { name: "Qt.widgets" } + } + \endcode + + You could also use the following form that is equivalent to the previous + one: + + \code + QtApplication { + Depends { name: "Qt"; submodules: "widgets" } + } + \endcode + + \section2 QTPLUGIN + + Building static applications often requires linking to static QPA plugins, + such as \c qminimal. You can use the following syntax to enable \QBS to + link to the required plugins: + + \code + QtApplication { + name: "myapp" + Depends { name: "Qt"; submodules: ["core", "gui", "widgets"] } + Depends { name: "Qt.qminimal"; condition: Qt.core.staticBuild } + } + \endcode + + \section2 RC_FILE + + Add Windows resource files to the value of the \c files property for the + \l{Product Item}{product}. + + \section2 TARGET + + Use the \c targetName property to specify the base file name of target + artifacts of the \l{Product Item}{product}. + + \section2 TEMPLATE + + \section3 app + + Use \l{Application Item}{Application} or \l{CppApplication Item} + {CppApplication} as the \l{Product Item}{product}: + + \code + CppApplication { + name: "helloworld" + files: "main.cpp" + } + \endcode + + This is roughly equivalent to: + + \code + Product { + name: "helloworld" + type: "application" + files: "main.cpp" + Depends { name: "cpp" } + } + \endcode + + \section3 lib + + Use either \l{DynamicLibrary Item}{DynamicLibrary} or \l{StaticLibrary Item} + {StaticLibrary} as the \l{Product Item}{product}, depending on whether the + value of \c CONFIG in the .pro file is \c shared or \c static. For example, + if the value is \c shared: + + \code + DynamicLibrary { + name: "mydll" + files: ["mySourceFile.cpp"] + Depends { name: "cpp" } + } + \endcode + + \section3 subdirs + + In a \l{Project Item}{Project item}, specify subdirectories as values of the + \c references property: + + \code + Project { + references: [ + "app/app.qbs", + "lib/lib.qbs" + ] + } + \endcode + + \section2 message(), warning(), error(), log() + + You can use the JavaScript console printing functions (\c console.info, + \c console.warn, \c console.error, and \c console.log) to print info, + warning, error, and log messages to the console. + + \code + Product { + name: { + console.info("--> now evaluating the product name"); + return "theName"; + } + Depends { name: "cpp" } + cpp.includePath: { throw "An error occurred." } + } + \endcode +*/ |