Doc: Describe porting qmake projects to Qbs

Task-number: QBS-407
Change-Id: Ia2f59288e2f9aca0d9fed800ee52c4082cf18d07
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>

2 files changed, 517 insertions, 5 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
+*/
diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc
index 38abffda4..9c6717b0c 100644
--- a/doc/qbs.qdoc
+++ b/doc/qbs.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of Qbs.
@@ -82,7 +82,8 @@
            \endlist
 
        \li  \l{Appendix A: Building Qbs}
-       \li  \l{Appendix B: Code Attributions}
+       \li  \l{Appendix B: Migrating from Other Build Systems}
+       \li  \l{Appendix C: Code Attributions}
     \endlist
 */
 
@@ -335,7 +336,7 @@
     \contentspage index.html
     \previouspage reference.html
     \page building-qbs.html
-    \nextpage attributions.html
+    \nextpage porting-to-qbs.html
 
     \title Appendix A: Building Qbs
 
@@ -1414,10 +1415,10 @@
 
 /*!
     \contentspage index.html
-    \previouspage building-qbs.html
+    \previouspage porting-to-qbs.html
     \page attributions.html
 
-    \title Appendix B: Code Attributions
+    \title Appendix C: Code Attributions
 
     \QBS contains third-party code, which we gratefully acknowledge:
     \generatelist{groupsbymodule attributions-qbs}