diff options
Diffstat (limited to 'doc')
163 files changed, 5053 insertions, 902 deletions
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 000000000..04ff12470 --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1,30 @@ +set(_DOC_SOURCES + ../README.md + ../CONTRIBUTING.md + classic.css + external-resources.qdoc + fixnavi.pl + howtos.qdoc + qbs.qdoc + qbs-online.qdocconf + config/style/qt5-sidebar.html + ) + +file(GLOB_RECURSE _DOC_APPENDIX_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/appendix/*") +file(GLOB_RECURSE _DOC_REFERENCE_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/reference/*") +file(GLOB_RECURSE _DOC_TEMPLATES_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/templates/*") +file(GLOB_RECURSE _DOC_IMAGES_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/images/*") +file(GLOB_RECURSE _DOC_TARGETS_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/targets/*") + +add_qbs_documentation( + "qbs.qdocconf" + SOURCES + ${_DOC_SOURCES} + ${_DOC_APPENDIX_SOURCES} + ${_DOC_REFERENCE_SOURCES} + ${_DOC_TEMPLATES_SOURCES} + ${_DOC_IMAGES_SOURCES} + ${_DOC_TARGETS_SOURCES} + ) + +add_subdirectory(man) diff --git a/doc/appendix/json-api.qdoc b/doc/appendix/json-api.qdoc index f8840de37..7b093bc4e 100644 --- a/doc/appendix/json-api.qdoc +++ b/doc/appendix/json-api.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \previouspage porting-to-qbs.html \nextpage attributions.html \page json-api.html @@ -95,6 +94,7 @@ \header \li Property \li Type \row \li api-level \li int \row \li api-compat-level \li int + \row \li lsp-socket \li string \endtable The value of \c api-level is increased whenever the API is extended, for instance @@ -109,6 +109,10 @@ The value of \c api-compat-level is always less than or equal to the value of \c api-level. + The value of \c lsp-socket is a path to a local domain socket (on Unix) or + a named pipe (on Windows). It provides a server implementing the + \l{https://microsoft.github.io/language-server-protocol}{Language Server Protocol}. + \section1 Resolving a Project To instruct \QBS to load a project from disk, a request of type @@ -118,13 +122,14 @@ \row \li build-root \li \l FilePath \li yes \row \li configuration-name \li string \li no \row \li data-mode \li \l DataMode \li no + \row \li deprecation-warning-mode \li string \li no \row \li dry-run \li bool \li no \row \li environment \li \l Environment \li no \row \li error-handling-mode \li string \li no - \row \li fallback-provider-enabled \li bool \li no \row \li force-probe-execution \li bool \li no \row \li log-time \li bool \li no \row \li log-level \li \l LogLevel \li no + \row \li max-job-count \li int \li no \row \li module-properties \li list of strings \li no \row \li overridden-properties \li object \li no \row \li project-file-path \li FilePath \li if resolving from scratch @@ -402,17 +407,12 @@ \header \li Property \li Type \li Mandatory \row \li error \li \l ErrorInfo \li no \row \li failed-files \li \l FilePath list \li no - \row \li project-data \li \l TopLevelProjectData \li no \endtable If the \c error property is present, the operation has at least partially failed and \c failed-files will list the files that could not be added or removed. - If the project data has changed as a result of the operation - (which it should unless the operation failed completely), then - the \c project-data property will contain the updated project data. - \section1 The \c get-run-environment Message This request retrieves the full run environment for a specific @@ -634,8 +634,8 @@ \row \li version \li string \endtable - The \c dependencies are the names of products that occur in the (enabled) - \l Depends items of this product. + The elements of the \c dependencies array correspond to the full-display-name + properties of the products that this product has pulled in via \l Depends items. The \c generated-artifacts are files that are created by the \l{Rule}{rules} in this product. @@ -771,7 +771,7 @@ \c items is an array of objects with the following structure: \table \header \li Property \li Type \li Mandatory - \row \li \c message \li string \li yes + \row \li description \li string \li yes \row \li location \li \l Location \li no \endtable diff --git a/doc/appendix/qbs-porting.qdoc b/doc/appendix/qbs-porting.qdoc index ba697d7be..47e5f7678 100644 --- a/doc/appendix/qbs-porting.qdoc +++ b/doc/appendix/qbs-porting.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \previouspage building-qbs.html \page porting-to-qbs.html \nextpage json-api.html diff --git a/doc/codeattributions.qdoc b/doc/codeattributions.qdoc index ee4e4b901..092f7794f 100644 --- a/doc/codeattributions.qdoc +++ b/doc/codeattributions.qdoc @@ -1,6 +1,5 @@ /*! -\contentspage attributions.html \ingroup attributions-libs \ingroup attributions-qbs \page qbs-attribution-ds_store.html attribution @@ -49,7 +48,6 @@ THE SOFTWARE. /*! -\contentspage attributions.html \ingroup attributions-libs \ingroup attributions-qbs \page qbs-attribution-dmgbuild.html attribution @@ -98,7 +96,6 @@ THE SOFTWARE. /*! -\contentspage attributions.html \ingroup attributions-libs \ingroup attributions-qbs \page qbs-attribution-mac_alias.html attribution @@ -147,7 +144,6 @@ THE SOFTWARE. /*! -\contentspage attributions.html \ingroup attributions-libs \ingroup attributions-qbs \page qbs-attribution-biplist.html attribution @@ -184,7 +180,7 @@ modification, are permitted provided that the following conditions are met: notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of biplist nor the names of its contributors may be - used to endorse or promote products derived from this software without + used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" @@ -199,3 +195,94 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. \endcode */ + +/*! + +\ingroup attributions-libs +\ingroup attributions-qbs +\page qbs-attribution-cppscanner.html attribution +\target cppscanner + +\title cppscanner +\brief MIT License + +The cpp scanner module is used to parse C/C++ files and to find includes +in them. + +The sources can be found in src/plugins/scanner/cpp. + +\badcode +Copyright (c) 2008 Roberto Raggi +\endcode + +\l{https://spdx.org/licenses/MIT.html}{MIT License}. + +\badcode +// Copyright (c) 2008 Roberto Raggi <roberto.raggi@gmail.com> +// +// Permission is hereby granted, free of charge, to any person obtaining a copy +// of this software and associated documentation files (the "Software"), to deal +// in the Software without restriction, including without limitation the rights +// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +// copies of the Software, and to permit persons to whom the Software is +// furnished to do so, subject to the following conditions: +// +// The above copyright notice and this permission notice shall be included in +// all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +// THE SOFTWARE. +\endcode +*/ + +/*! + +\ingroup attributions-libs +\ingroup attributions-qbs +\page qbs-attribution-quickjs.html attribution +\target quickjs + +\title QuickJS +\brief MIT License + +The JavaScript engine used to evaluate all JavaScript code in \QBS project files. + +The sources can be found in src/shared/quickjs. + +\badcode +Copyright (c) 2017-2021 Fabrice Bellard +Copyright (c) 2017-2021 Charlie Gordon +\endcode + +\l{https://spdx.org/licenses/MIT.html}{MIT License}. + +\badcode +QuickJS Javascript Engine + +Copyright (c) 2017-2021 Fabrice Bellard +Copyright (c) 2017-2021 Charlie Gordon + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. +\endcode +*/ diff --git a/doc/config/macros.qdocconf b/doc/config/macros.qdocconf index a8abe25e5..31b9b9a8d 100644 --- a/doc/config/macros.qdocconf +++ b/doc/config/macros.qdocconf @@ -4,6 +4,7 @@ macro.qbsversion = $QBS_VERSION macro.defaultvalue = "Default:" macro.nodefaultvalue = "Default: Undefined" macro.appleproperty = "This property is specific to Apple platforms." +macro.androidproperty = "This property is specific to Android platforms." macro.unixproperty = "This property is specific to Unix platforms." macro.windowsproperty = "This property is specific to Windows." macro.baremetalproperty = "This property is specific to bare-metal platforms." @@ -50,6 +51,8 @@ macro.endfloat.HTML = "</div>" macro.clearfloat.HTML = "<br style=\"clear: both\" />" macro.emptyspan.HTML = "<span></span>" +macro.CMAKE = "CMake" + # Embed YouTube content by video ID - Example: \youtube dQw4w9WgXcQ # Also requires a <ID>.jpg thumbnail for offline docs. In .qdocconf, add: # diff --git a/doc/config/qbs-project.qdocconf b/doc/config/qbs-project.qdocconf index bab672e11..bf5051c77 100644 --- a/doc/config/qbs-project.qdocconf +++ b/doc/config/qbs-project.qdocconf @@ -5,6 +5,9 @@ include($QT_INSTALL_DOCS/global/fileextensions.qdocconf) project = "Qbs" description = "Qbs Manual" +#Words to ignore for auto-linking +ignorewords += macOS + headerdirs = sourcedirs = .. imagedirs = ../images ../templates/images diff --git a/doc/doc.pri b/doc/doc.pri deleted file mode 100644 index cd05a9450..000000000 --- a/doc/doc.pri +++ /dev/null @@ -1,18 +0,0 @@ -include(../src/install_prefix.pri) - -include(doc_shared.pri) - -DOC_OUTDIR_POSTFIX = /html -DOC_HTML_INSTALLDIR = $$QBS_INSTALL_PREFIX/share/doc/qbs -DOC_QCH_OUTDIR = $$OUT_PWD/doc -DOC_QCH_INSTALLDIR = $$QBS_INSTALL_PREFIX/share/doc/qbs - -include(doc_targets.pri) - -fixnavi.commands = \ - cd $$shell_path($$PWD) && \ - perl fixnavi.pl -Dqcmanual -Dqtquick \ - qbs.qdoc -QMAKE_EXTRA_TARGETS += fixnavi - -include(man/man.pri) diff --git a/doc/doc.qbs b/doc/doc.qbs index dd8377c6c..0dfc5f474 100644 --- a/doc/doc.qbs +++ b/doc/doc.qbs @@ -1,6 +1,6 @@ -import qbs 1.0 import qbs.File import qbs.FileInfo +import qbs.Probes Project { references: ["man/man.qbs"] @@ -16,13 +16,21 @@ Project { Depends { name: "qbsbuildconfig" } Depends { name: "qbsversion" } + Probes.BinaryProbe { + id: pythonProbe + names: ["python3", "python"] // on Windows, there's no python3 + } + property string pythonPath: pythonProbe.found ? pythonProbe.filePath : undefined + files: [ - "../README", + "../README.md", + "../CONTRIBUTING.md", "classic.css", "external-resources.qdoc", "fixnavi.pl", "howtos.qdoc", "qbs.qdoc", + "tutorial.qdoc", "qbs-online.qdocconf", "config/*.qdocconf", "config/style/qt5-sidebar.html", @@ -58,9 +66,11 @@ Project { outputFileTags: ["qdoc-html", "qbsdoc.dummy"] // TODO: Hack. Rule injection to the rescue? outputArtifacts: [{filePath: "dummy", fileTags: ["qbsdoc.dummy"]}] prepare: { + if (!product.pythonPath) + throw "Python executable was not found"; var scriptPath = explicitlyDependsOn["qbsdoc.fiximports"][0].filePath; var htmlDir = FileInfo.path(FileInfo.path(inputs["qdoc-png"][0].filePath)); - var fixCmd = new Command("python", [scriptPath, htmlDir]); + var fixCmd = new Command(product.pythonPath, [scriptPath, htmlDir]); fixCmd.description = "fixing bogus QML import statements"; return [fixCmd]; } diff --git a/doc/doc_shared.pri b/doc/doc_shared.pri deleted file mode 100644 index 3e4eccf48..000000000 --- a/doc/doc_shared.pri +++ /dev/null @@ -1,14 +0,0 @@ -include(../qbs_version.pri) - -qbsdoc_version.name = QBS_VERSION -qbsdoc_version.value = $$QBS_VERSION -qbsdoc_versiontag.name = QBS_VERSION_TAG -qbsdoc_versiontag.value = $$replace(QBS_VERSION, "[-.]", ) -qbsdoc_qtdocs.name = QT_INSTALL_DOCS -qbsdoc_qtdocs.value = $$[QT_INSTALL_DOCS/src] -QDOC_ENV += qbsdoc_version qbsdoc_versiontag qbsdoc_qtdocs - -build_online_docs: \ - DOC_FILES += $$PWD/qbs-online.qdocconf -else: \ - DOC_FILES += $$PWD/qbs.qdocconf diff --git a/doc/doc_targets.pri b/doc/doc_targets.pri deleted file mode 100644 index 0636be2b5..000000000 --- a/doc/doc_targets.pri +++ /dev/null @@ -1,86 +0,0 @@ -# Creates targets for building documentation -# (adapted from qt_docs.prf) -# -# Usage: Define variables (details below) and include this pri file afterwards. -# -# QDOC_ENV - environment variables to set for the qdoc call (see example below) -# DOC_INDEX_PATHS - list of paths where qdoc should search for index files of dependent -# modules (Qt index path is included by default) -# DOC_FILES - list of qdocconf files -# DOC_OUTDIR_POSTFIX - html is generated in $$OUT_PWD/<qdocconf_name>$$DOC_OUTDIR_POSTFIX -# DOC_HTML_INSTALLDIR - path were to install the directory of html files -# DOC_QCH_OUTDIR - path where to generated the qch files -# DOC_QCH_INSTALLDIR - path where to install the qch files -# DOC_TARGET_PREFIX - prefix for generated target names -# -# Example for QDOC_ENV: -# ver.name = VERSION -# ver.value = 1.0.2 -# foo.name = FOO -# foo.value = foo -# QDOC_ENV = ver foo - -isEmpty(DOC_FILES): error("Set DOC_FILES before including doc_targets.pri") -isEmpty(DOC_HTML_INSTALLDIR): error("Set DOC_HTML_INSTALLDIR before including doc_targets.pri") -isEmpty(DOC_QCH_OUTDIR): error("Set DOC_QCH_OUTDIR before including doc_targets.pri") -isEmpty(DOC_QCH_INSTALLDIR): error("Set DOC_QCH_INSTALLDIR before including doc_targets.pri") - -QT_TOOL_ENV = $$QDOC_ENV -qtPrepareTool(QDOC, qdoc) -QT_TOOL_ENV = - -!build_online_docs: qtPrepareTool(QHELPGENERATOR, qhelpgenerator) - -DOCS_BASE_OUTDIR = $$OUT_PWD/doc -DOC_INDEXES += -indexdir $$shell_quote($$[QT_INSTALL_DOCS]) -for (index_path, DOC_INDEX_PATHS): \ - DOC_INDEXES += -indexdir $$shell_quote($$index_path) - -DTP = $$DOC_TARGET_PREFIX -for (doc_file, DOC_FILES) { - !exists($$doc_file): error("Cannot find documentation specification file $$doc_file") - DOC_TARGET = $$replace(doc_file, ^(.*/)?(.*)\\.qdocconf$, \\2) - DOC_TARGETDIR = $$DOC_TARGET - DOC_OUTPUTDIR = $${DOCS_BASE_OUTDIR}/$${DOC_TARGETDIR}$${DOC_OUTDIR_POSTFIX} - - $${DTP}html_docs_$${DOC_TARGET}.commands = $$QDOC -outputdir $$shell_quote($$DOC_OUTPUTDIR) $$doc_file $$DOC_INDEXES - QMAKE_EXTRA_TARGETS += $${DTP}html_docs_$${DOC_TARGET} - - !isEmpty($${DTP}html_docs.commands): $${DTP}html_docs.commands += && - $${DTP}html_docs.commands += $$eval($${DTP}html_docs_$${DOC_TARGET}.commands) - - $${DTP}inst_html_docs.files += $$DOC_OUTPUTDIR - - !build_online_docs { - $${DTP}qch_docs_$${DOC_TARGET}.commands = $$QHELPGENERATOR $$shell_quote($$DOC_OUTPUTDIR/$${DOC_TARGET}.qhp) -o $$shell_quote($$DOC_QCH_OUTDIR/$${DOC_TARGET}.qch) - $${DTP}qch_docs_$${DOC_TARGET}.depends = $${DTP}html_docs_$${DOC_TARGET} - QMAKE_EXTRA_TARGETS += $${DTP}qch_docs_$${DOC_TARGET} - - !isEmpty($${DTP}qch_docs.commands): $${DTP}qch_docs.commands += && - $${DTP}qch_docs.commands += $$eval($${DTP}qch_docs_$${DOC_TARGET}.commands) - - $${DTP}inst_qch_docs.files += $$DOC_QCH_OUTDIR/$${DOC_TARGET}.qch - } -} - -!build_online_docs { - $${DTP}qch_docs.depends = $${DTP}html_docs - $${DTP}inst_qch_docs.path = $$DOC_QCH_INSTALLDIR - $${DTP}inst_qch_docs.CONFIG += no_check_exist no_default_install no_build - install_$${DTP}docs.depends = install_$${DTP}inst_qch_docs - $${DTP}docs.depends = $${DTP}qch_docs - INSTALLS += $${DTP}inst_qch_docs - QMAKE_EXTRA_TARGETS += $${DTP}qch_docs install_$${DTP}docs -} else { - $${DTP}docs.depends = $${DTP}html_docs -} - -$${DTP}inst_html_docs.path = $$DOC_HTML_INSTALLDIR -$${DTP}inst_html_docs.CONFIG += no_check_exist no_default_install directory -INSTALLS += $${DTP}inst_html_docs -install_$${DTP}docs.depends += install_$${DTP}inst_html_docs - -QMAKE_EXTRA_TARGETS += $${DTP}html_docs $${DTP}docs - -unset(DTP) - diff --git a/doc/external-resources.qdoc b/doc/external-resources.qdoc index 00b7bf975..9d7aa3aeb 100644 --- a/doc/external-resources.qdoc +++ b/doc/external-resources.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2018 The Qt Company Ltd. +** Copyright (C) 2022 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of Qbs. @@ -121,9 +121,8 @@ */ /*! - \externalpage nolink - \title macOS - \internal + \externalpage https://github.com/nanopb/nanopb + \title nanopb */ /*! diff --git a/doc/fix-qmlimports.py b/doc/fix-qmlimports.py index 93fdb437a..bb022d25b 100755 --- a/doc/fix-qmlimports.py +++ b/doc/fix-qmlimports.py @@ -1,4 +1,4 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 ############################################################################# ## ## Copyright (C) 2017 The Qt Company Ltd. @@ -121,7 +121,7 @@ if __name__ == '__main__': if not (fileCount % progStep): print('.', end='') sys.stdout.flush() - with open(html, 'r+') as file_: + with open(html, 'r+', encoding='utf8') as file_: try: soup = BeautifulSoup(file_, 'lxml') actions = [] @@ -145,7 +145,7 @@ if __name__ == '__main__': if 'lxml' in str(e): print('(If using pip, try \"pip install lxml\")', file=sys.stderr) quit(1) - for k, v in modified.iteritems(): + for k, v in modified.items(): print ('\n\t', k, 'in %d files' % v, end='') pb = pre_blocks.get(k, 0) if pb: diff --git a/doc/howtos.qdoc b/doc/howtos.qdoc index b63e2ca96..9a81318ee 100644 --- a/doc/howtos.qdoc +++ b/doc/howtos.qdoc @@ -25,8 +25,7 @@ ** ****************************************************************************/ /*! - \contentspage index.html - \previouspage custom-modules.html + \previouspage tutorial-8.html \nextpage reference.html \page howtos.html @@ -37,7 +36,10 @@ \list \li \l{How do I build a Qt-based project?} \li \l{How do I make my app build against my library?} + \li \l{How do I build release with debug information?} + \li \l{How do I separate and install debugging symbols?} \li \l{How do I use precompiled headers?} + \li \l{How do I make use of rpaths?} \li \l{How do I make sure my generated sources are getting compiled?} \li \l{How do I run my autotests?} \li \l{How do I use ccache?} @@ -45,11 +47,15 @@ \li \l{How do I build against libraries that provide pkg-config files?} \li \l{How do I create application bundles and frameworks on iOS, macOS, tvOS, and watchOS?} \li \l{How do I apply C/C++ preprocessor macros to only a subset of the files in my product?} + \li \l{How do I disable a compiler warning?} \li \l{How do I make the state of my Git repository available to my source files?} \li \l{How do I limit the number of concurrent jobs for the linker only?} \li \l{How do I add QML files to a project?} \li \l{How do I define a reusable Group of files that can be included in other \QBS files?} + \li \l{How do I access properties of a base type?} \li \l{How do I print the value of a property?} + \li \l{How do I debug \QBS scripts?} + \li \l{How do I sign an application for an Apple platform?} \endlist \section1 How do I build a Qt-based project? @@ -94,7 +100,7 @@ ] Export { Depends { name: "cpp" } - cpp.includePaths: [product.sourceDirectory] + cpp.includePaths: [exportingProduct.sourceDirectory] } } } @@ -129,6 +135,89 @@ } \endcode + \section1 How do I build release with debug information? + + You can simply use the \c{"profiling"} \l{qbs::buildVariant}{qbs.buildVariant}: + \code + qbs build qbs.buildVariant:profiling + \endcode + + \section1 How do I separate and install debugging symbols? + + First, you need to set the \l{cpp::debugInformation}{cpp.debugInformation} and + \l{cpp::separateDebugInformation}{cpp.separateDebugInformation} + properties to \c true or use some conditional expression in your product: + \code + CppApplication { + // ... + cpp.debugInformation: qbs.buildVariant !== "release" + cpp.separateDebugInformation: true + } + \endcode + + Now, you can install your \l{Application}{application}, \l{DynamicLibrary}{dynamic library} + or \l{LoadableModule}{loadable module} among with its debugging symbols as follows: + \code + CppApplication { + // ... + install: true + installDir: "bin" + installDebugInformation: true + debugInformationInstallDir: "bin" + } + \endcode + + If you are not using \l{List of Convenience Items}{convenience items}, + you can install debug symbols manually using the \l{Group} item. If the + \l{cpp::separateDebugInformation}{cpp.separateDebugInformation} property is set to \c true, + \QBS will create debugging symbols with the corresponding file tags + \c "debuginfo_app" (for an application), \c "debuginfo_dll" (for a dynamic library), + or \c "debuginfo_loadablemodule" (for a macOS plugin). + + \code + Product { + type: "application" + Depends { name: "cpp" } + cpp.debugInformation: qbs.buildVariant !== "release" + cpp.separateDebugInformation: true + Group { + fileTagsFilter: cpp.separateDebugInformation ? ["debuginfo_app"] : [] + qbs.install: true + qbs.installDir: "bin" + qbs.installSourceBase: buildDirectory + } + } + \endcode + + If you're building a shared library, you need to use the \c "debuginfo_dll" tag instead: + \code + Product { + type: "dynamic_library" + // ... + Group { + fileTagsFilter: cpp.separateDebugInformation ? ["debuginfo_dll"] : [] + qbs.install: true + qbs.installDir: "lib" + qbs.installSourceBase: buildDirectory + } + } + \endcode + + If you're building a macOS plugin, you need to use the \c "debuginfo_loadablemodule" + tag instead: + \code + Product { + type: "loadablemodule" + // ... + Group { + fileTagsFilter: cpp.separateDebugInformation ? ["debuginfo_loadablemodule"] : [] + qbs.install: true + qbs.installDir: "PlugIns" + qbs.installSourceBase: buildDirectory + } + } + \endcode + \section1 How do I use precompiled headers? If you use a \l Group item to add a precompiled header file to a product @@ -152,6 +241,42 @@ } \endcode + \section1 How do I make use of rpaths? + + rpath designates the run-time search path used by the dynamic linker when loading + libraries on UNIX platforms. This concept does not apply to Windows. + + Suppose you have a project with two dynamic library products \c LibraryA and \c LibraryB + and one dependent application product. Also, \c LibraryB depends on \c LibraryA. The + application is installed to the \c bin folder and the libraries are installed to the + \c lib folder next to the \c bin folder. You want the application to be able to find the + dependent libraries relative to its own location. This can be achieved by usage of the + \l{cpp::rpaths}{cpp.rpaths} property. + + First, you need to set \l{cpp::rpaths}{cpp.rpaths} in your libraries so they can + find dependent libraries in the same folder where they are located. This can be + done as follows: + + \snippet ../examples/rpaths/rpaths.qbs 0 + + We are setting \l{cpp::rpaths}{cpp.rpaths} to \l{cpp::rpathOrigin}{cpp.rpathOrigin} which + expands to \c "$ORIGIN" on Linux and to \c "@loader_path" on macOS. + + On macOS you also need to set \l{cpp::sonamePrefix}{cpp.sonamePrefix} to \c "@rpath" to + tell the dynamic linker to use RPATHs when loading this library. + + \c LibraryB looks exactly the same: + + \snippet ../examples/rpaths/rpaths.qbs 1 + + In a real project, it might be a good idea to move common properties to some base item + and inherit it in library items. + + The application item is a bit different. It sets \l{cpp::rpaths}{cpp.rpaths} to the + \c "lib" folder which is located one level up from the \c bin folder: + + \snippet ../examples/rpaths/rpaths.qbs 2 + \section1 How do I make sure my generated sources are getting compiled? The rules in a \QBS project do not care whether its inputs are actual source files @@ -265,19 +390,19 @@ Depends { name: "cpp" } cpp.includePaths: ["/somewhere/include"] Properties { - condition: qbs.targetOS.contains("android") + condition: qbs.targetOS.includes("android") cpp.dynamicLibraries: ["/somewhere/android/" + Android.ndk.abi + "/lib1.so"] } Properties { - condition: qbs.targetOS.contains("macos") + condition: qbs.targetOS.includes("macos") cpp.dynamicLibraries: ["/somewhere/macos/lib1.dylib"] } Properties { - condition: qbs.targetOS.contains("windows") && qbs.architecture === "x86" + condition: qbs.targetOS.includes("windows") && qbs.architecture === "x86" cpp.dynamicLibraries: ["/somewhere/windows_x86/lib1.lib"] } Properties { - condition: qbs.targetOS.contains("windows") && qbs.architecture === "x86_64" + condition: qbs.targetOS.includes("windows") && qbs.architecture === "x86_64" cpp.dynamicLibraries: ["/somewhere/windows_x86_64/lib1.lib"] } } @@ -342,15 +467,17 @@ \section1 How do I build against libraries that provide pkg-config files? - Just add a \l Depends item that matches the name of the pkg-config module, and \QBS - will automatically employ \l{https://www.freedesktop.org/wiki/Software/pkg-config}{pkg-config} + Just add a \l Depends item that matches the name of the pkg-config module, + set the \l Product::qbsModuleProviders property to \c "qbspkgconfig", + and \QBS will employ + \l{https://www.freedesktop.org/wiki/Software/pkg-config}{pkg-config} to find the headers and libraries if no matching \QBS module can be found. For instance, to build against the OpenSSL library, you would write this: \code + qbsModuleProviders: "qbspkgconfig" Depends { name: "openssl" } \endcode - That's it. The pkg-config behavior can be fine-tuned via the \l pkgconfig module, - but normally you will not need to pull it in explicitly. + That's it. The pkg-config behavior can be fine-tuned via the \l qbspkgconfig provider. Internally, this functionality is implemented via \l {Module Providers} @@ -398,6 +525,37 @@ } \endcode + \section1 How do I disable a compiler warning? + + You can use the \l {cpp::commonCompilerFlags}{cpp.commonCompilerFlags} property + to pass flags to the compiler. For example, to disable deprecation warnings: + + \code + CppApplication { + // ... + + readonly property bool isMsvc: qbs.toolchain.includes("msvc") + + cpp.commonCompilerFlags: isMsvc ? "/wd4996" : "-Wno-deprecated-declarations" + } + \endcode + + It is also possible to disable all warnings at once by setting the + \l {cpp::commonCompilerFlags}{cpp.warningLevel} property to \c "none". + Usually this approach is discouraged, but it can be useful in some cases, + such as when compiling third party code: + + \code + Group { + cpp.warningLevel: "none" + + files: [ + "3rdparty.h", + "3rdparty.cpp" + ] + } + \endcode + \section1 How do I make the state of my Git repository available to my source files? Add a dependency to the \l{vcs} module to your product: @@ -474,7 +632,7 @@ \section1 How do I add QML files to a project? The simplest way to add QML files to a project is to add them to a - \l {The Qt Resource System}{resource file}: + \l {https://doc.qt.io/qt/resources.html}{Qt resource file}: \code QtGuiApplication { @@ -567,6 +725,31 @@ } \endcode + \section1 How do I access properties of a base type? + + You can use the \l base property. For example, to append to a list of files + that come from the base type, you can use \c {base.concat()}: + + \code + // TestBase.qbs + + QtGuiApplication { + files: [ + "TestCaseBase.h", + "TestCaseBase.cpp" + ] + } + \endcode + + \code + // tst_stuff.qbs + TestBase { + files: base.concat(["tst_stuff.cpp"]) + } + \endcode + + See \l {Special Property Values} for more details. + \section1 How do I print the value of a property? Use the \l {Console API}{console API}. For example, suppose your project @@ -574,7 +757,7 @@ \c qbs.targetOS has the wrong value: \code - readonly property bool unix: qbs.targetOS.contains("unix") + readonly property bool unix: qbs.targetOS.includes("unix") \endcode To find out the value of \c qbs.targetOS, use \c {console.info()}: @@ -582,7 +765,86 @@ \code readonly property bool unix: { console.info("qbs.targetOS: " + qbs.targetOS) - return qbs.targetOS.contains("unix") + return qbs.targetOS.includes("unix") + } + \endcode + + It is also possible to throw an exception with the text saying what is wrong - this might + be useful if the property contains invalid or unsupported value: + \code + readonly property bool unix: { + if (qbs.targetOS.includes("darwin")) + throw "Apple platforms are not supported"; + return qbs.targetOS.includes("unix") } \endcode + + \section1 How do I debug \QBS scripts? + + To debug the value of a specific property, see the \l{How do I print the value of a property} + section. + + Similar debugging techniques could be used within \l{Rule}{Rules} or \c .js files. + + It is also possible to increase \QBS' logging level using the \c --more-verbose (\c -v) option + of the \c{qbs build} command: + + \code + qbs build -v config:release + \endcode + + \QBS uses the Qt Categorized Logging system which allows to configure logging categories + in \l{https://doc.qt.io/qt-5/qloggingcategory.html#configuring-categories}{multiple ways}. For + example, to enable debug logging for the \c moduleloader category, use the following command: + \code + QT_LOGGING_RULES="qbs.moduleloader.debug=true" qbs resolve + \endcode + + To list all the files in the project directory and show whether they are known to qbs in the + respective configuration, use the \c{qbs status} command: + \code + qbs status config:release + \endcode + + \section1 How do I sign an application for an Apple platform? + + To sign an application for an Apple platform, you need to use the \l{codesign} module. + + \code + Depends { name: "codesign" } + \endcode + + Several properties should be set to do signing as shown below. + + Make sure that bundle and team indentifiers match the one used for signing: + + \code + bundle.identifierPrefix: "com.johndoe" + codesign.teamIdentifier: "John Doe" + \endcode + + It is also possible to use an ID of the team identifier instead of a name: + \code + codesign.teamIdentifier: "1234ABCDEF" + \endcode + + \QBS will then try to find the matching signing identity and provisioning profile based on + \l{codesign::signingType}{codesign.signingType}. + + It is also possible to specify \l{codesign::signingIdentity}{codesign.signingIdentity} + manually: + + \code + codesign.signingIdentity: "Apple Development: johndoe@apple.com (ABCDEF1234)" + \endcode + + It is also possible to use an ID of the signing identity instead of a name: + \code + codesign.signingIdentity: "ABCDEF1234567890ABCDEF1234567890ABCDEF12" + \endcode + + If \QBS cannot find the suitable provisioning profile, you can specify it manually as well: + \code + codesign.provisioningProfile: "abcdef12-1234-5678-1111-abcdef123456" + \endcode */ diff --git a/doc/man/CMakeLists.txt b/doc/man/CMakeLists.txt new file mode 100644 index 000000000..00d003d7f --- /dev/null +++ b/doc/man/CMakeLists.txt @@ -0,0 +1,3 @@ +if (QBS_INSTALL_MAN_PAGE) + install(FILES qbs.1 DESTINATION ${QBS_RESOURCES_INSTALL_DIR}/man/man1 COMPONENT qbs_docs) +endif() diff --git a/doc/man/man.pri b/doc/man/man.pri deleted file mode 100644 index 2e29f9112..000000000 --- a/doc/man/man.pri +++ /dev/null @@ -1,5 +0,0 @@ -qbs_no_man_install: return() - -man.files = $$PWD/qbs.1 -man.path = $${QBS_INSTALL_PREFIX}/share/man/man1 -INSTALLS += man diff --git a/doc/man/man.qbs b/doc/man/man.qbs index 32f8e624e..8b81f62ae 100644 --- a/doc/man/man.qbs +++ b/doc/man/man.qbs @@ -1,4 +1,3 @@ -import qbs import qbs.File import qbs.FileInfo import qbs.ModUtils diff --git a/doc/qbs-hugo.qdocconf b/doc/qbs-hugo.qdocconf new file mode 100644 index 000000000..66ba0548c --- /dev/null +++ b/doc/qbs-hugo.qdocconf @@ -0,0 +1,6 @@ +include(config/qbs-project.qdocconf) + +syntaxhighlighting = true + +HTML.prologue = "<div class=\"content\">" +HTML.footer += "</div>" diff --git a/doc/qbs-online.qdocconf b/doc/qbs-online.qdocconf index fc90ebdd1..e7f05e3b2 100644 --- a/doc/qbs-online.qdocconf +++ b/doc/qbs-online.qdocconf @@ -3,7 +3,7 @@ include(config/qbs-project.qdocconf) HTML.footer = \ " </div>\n" \ " <p class=\"copy-notice\">\n" \ - " <acronym title=\"Copyright\">©</acronym> 2018 The Qt Company Ltd.\n" \ + " <acronym title=\"Copyright\">©</acronym> 2022 The Qt Company Ltd.\n" \ " Documentation contributions included herein are the copyrights of\n" \ " their respective owners. " \ " The documentation provided herein is licensed under the terms of the" \ diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc index 852329f73..83e461f29 100644 --- a/doc/qbs.qdoc +++ b/doc/qbs.qdoc @@ -33,7 +33,6 @@ /*! - \contentspage{index.html}{Qbs} \page index.html \nextpage overview.html @@ -68,8 +67,21 @@ \li \l{Generators} \li \l{Multiplexing} \li \l{Custom Modules and Items} + \li \l{Special Property Values} \li \l{Module Providers} \endlist + \li \l{Tutorial} + \list + \li \l{tutorial-1.html}{Console Application} + \li \l{tutorial-2.html}{Static Library} + \li \l{tutorial-3.html}{Dynamic Library} + \li \l{tutorial-4.html}{Convenience Items} + \li \l{tutorial-5.html}{Autotest} + \li \l{tutorial-6.html}{Project Properties} + \li \l{tutorial-7.html}{Buildconfig Module} + \li \l{tutorial-8.html}{Configurable Library} + \li \l{tutorial-9.html}{Version Header} + \endlist \li \l{How-tos} \li \l{Reference} \list @@ -82,6 +94,7 @@ \li \l{List of Built-in Services} \li \l{Command-Line Interface} \li \l{List of Modules} + \li \l{List of Module Providers} \li \l{Command and JavaScriptCommand} \endlist @@ -94,7 +107,6 @@ /*! - \contentspage index.html \previouspage index.html \page overview.html \nextpage setup.html @@ -301,25 +313,38 @@ \section2 IDE Integration \QBS can be used not only from the command line, but also in combination - with an IDE, such as Qt Creator, Microsoft Visual Studio, or Xcode. - Qt Creator directly supports \QBS projects. Visual Studio and Xcode users - can use \QBS to generate Microsoft Visual Studio and Xcode projects. - For more information, see \l {Generators}. + with an IDE, such as Qt Creator or Visual Studio Code. These IDEs directly + support \QBS projects using the new \QBS \l{session} feature. Thus, these IDEs + can retrieve all the information required to build a single file or project + through a session's JSON protocol \l{Appendix C: The JSON API}{API}. + + In addition, \QBS can generate projects for Visual Studio, IAR EW, and + Keil uVision, but it still is an experimental option. For more information, + see \l {Generators}. \section3 Qt Creator - \l{http://doc.qt.io/qtcreator/index.html}{Qt Creator} uses the same \QBS - library as the \QBS command line tools. Therefore, it can retrieve all the - information required to build a single file or project through a defined - public API. Qt Creator provides accurate information about the build - progress and displays a project tree that reflects the logical structure of - the project, instead of presenting low-level information, such as the file - system structure. Adding or removing source files keeps the existing project - file structure intact. + \l{http://doc.qt.io/qtcreator/index.html}{Qt Creator} provides accurate + information about the build progress and displays a project tree that + reflects the logical structure of the project, instead of presenting low-level + information, such as the file system structure. Adding or removing source + files keeps the existing project file structure intact. For more information about using \QBS to build projects from Qt Creator, see \l{http://doc.qt.io/qtcreator/creator-project-qbs.html}{Setting Up Qbs}. + \section3 Visual Studio Code + + \l{https://code.visualstudio.com/}{Visual Studio Code} provides the + \l{https://marketplace.visualstudio.com/items?itemName=qbs-community.qbs-tools} + {qbs-community} plugin that provides accurate information about the build progress + and displays a project tree that reflects the logical structure of the project. + Also, it can provide low-level information, such as the file system structure. + + For more information about using \QBS to build projects from Visual Studio Code, + see \l{https://github.com/denis-shienkov/vscode-qbs/blob/master/docs/how-to.md} + {How To}. + \section1 Build Process \image qbs-build-process.png @@ -352,12 +377,12 @@ Module { // ... Rule { - inputs {"cpp"] - Artifact [ + inputs: ["cpp"] + Artifact { filePath: input.fileName + ".o" - fileTags: {"obj"] + fileTags: ["obj"] } - prepare: [ + prepare: { // g++ -c main.cpp -o main.o ... } } @@ -409,7 +434,6 @@ /*! - \contentspage index.html \previouspage overview.html \page setup.html \nextpage installing.html @@ -424,7 +448,6 @@ */ /*! - \contentspage index.html \previouspage reference.html \page building-qbs.html \nextpage porting-to-qbs.html @@ -451,7 +474,7 @@ To build \QBS from the source, you need: \list - \li Qt 5.11, or later + \li Qt 5.15, or later \li Windows: MinGW with GCC 4.9 or Microsoft Visual Studio 2015, or later \li Linux: GCC 4.9, or later, or Clang 3.9.0, or later @@ -471,6 +494,50 @@ Regenerating the man page requires the \c help2man tool. + \section1 Building \QBS with СMake + + To build \QBS, enter the following commands: + + \code + mkdir build && cd build + cmake -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ .. + make + \endcode + + Where \c ${QT_DIR} is the directory where Qt is installed. Passing the \c Qt5_DIR option + is not necessary if \c qmake is present in \c PATH. + + Depending on your platform, you might use \c mingw32-make, \c nmake, or + \c jom instead of \c make. + + Alternatively, you can use the + \l{https://cmake.org/cmake/help/latest/generator/Ninja.html}{Ninja} generator: + \code + cmake -GNinja -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ .. + ninja + \endcode + + \section2 CMake Configure Options + + \QBS recognizes the following CMake options (passed to CMake in the form of \c{-DOPTION=value}) + to customize the build: + + \table + \header \li Option \li Notes \li Default value + \row \li WITH_TESTS \li Enable autotests. \li \c ON + \row \li WITH_UNIT_TESTS \li Enable additional autotests. \li \c OFF + \li \c OFF + \row \li INSTALL_PUBLIC_HEADERS \li Whether to install public headers. \li \c ON + \endtable + + \section2 Using ccache with CMake + + To enable using \l{https://ccache.dev}{ccache} when building \QBS, pass the following options + to CMake: + \code + cmake -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache .. + \endcode + \section1 Building \QBS with QMake To build \QBS, enter the following command: @@ -502,9 +569,6 @@ \row \li qbs_no_dev_install \li Exclude header files from installation, that is, perform a non-developer build. \row \li qbs_no_man_install \li Exclude the man page from installation. - \row \li qbs_enable_project_file_updates \li Enable API for updating project files. This - implies a dependency to the Qt GUI module. - \row \li qbs_use_bundled_qtscript \li Use the bundled QtScript library. \endtable In addition, you can set the \c QBS_SYSTEM_SETTINGS_DIR environment variable @@ -576,11 +640,6 @@ \li Enable additional autotests. Enabling this option will export some symbols that would otherwise be private. \row - \li enableProjectFileUpdates - \li \c false - \li Enable API for updating project files. This is required for an IDE and implies a - dependency to the Qt GUI module that would not be needed for the \QBS command-line tool. - \row \li enableRPath \li \c true \li Use this property to disable the use of rpath. This can be used when packaging \QBS @@ -592,15 +651,10 @@ is required to build against the \QBS libraries. \row \li enableBundledQt - \li \c true + \li \c false \li Holds whether the Qt libraries that \QBS depends on will be bundled with \QBS during the \c install step. This option is only implemented on macOS. \row - \li useBundledQtScript - \li \c false - \li Use the bundled QtScript module instead of the one shipped with Qt. In that case, - QtScript should be checked out as a git submodule. - \row \li libDirName \li \c "lib" \li Directory name used by \c libInstallDir and \c importLibInstallDir properties. @@ -694,7 +748,7 @@ A set of Docker images for developing \QBS (which are maintained by the \QBS team) is available \l{https://hub.docker.com/u/qbsbuild/}{on Docker Hub}. - Both Windows Server Core and Debian Linux container types are available. + Both Windows 10 and Debian Linux container types are available. \note The source code for the \QBS development Docker images is located in the \c{docker/} directory of the \QBS source tree, if you wish to build them yourself. @@ -712,45 +766,46 @@ \li Latest stable release of \QBS for building \QBS with \QBS \endlist - Run the following command to download the \QBS development image based on Ubuntu 18.04 \e Bionic: + We are using docker-compose for building and running the Docker images because it simplifies + the Docker command line and ensures that the correct image tag is used. All available images + are listed in the \c docker-compose.yml file in the project root directory. + + Run the following command to download the \QBS development image based on Ubuntu 20.04 + \e Focal: \code - docker pull qbsbuild/qbsdev:bionic + docker-compose pull focal \endcode You can then create a new container with the \QBS source directory mounted from your host machine's file system, by running: \code - docker run -it -v ${PWD}:/qbs -w /qbs qbsbuild/qbsdev:bionic + docker-compose run --rm focal \endcode You will now be in an interactive Linux shell where you can develop and build \QBS. - For convenience, you can also run \c docker-compose from the project root directory: - - \code - docker-compose run --rm bionic - \endcode - - This will download and run the container in one go and mount the project root directory - to \c /qbs in the container. - \section2 Windows Containers To build \QBS for Windows using Windows containers, your host OS must be running Windows 10 Pro - and have Hyper-V enabled. \l{https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers}{Switch your Docker environment to use Windows containers}, then run the - following command to download the Windows 10 \QBS development image: + and have Hyper-V enabled. \l{https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers}{Switch your Docker environment to use Windows containers}. + + We are using docker-compose for building and running the Docker images because it simplifies + the Docker command line and ensures that the correct image tag is used. All available images + are listed in the \c docker-compose.yml file in the project root directory. + + Run the following command to download the \QBS development image based on Windows 10: \code - docker pull qbsbuild/qbsdev:windowsservercore + docker-compose pull windows \endcode You can then create a new container with the \QBS source directory mounted from your host machine's file system, by running: \code - docker run -it -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore + docker-compose run --rm windows \endcode If you want to use Windows containers on a macOS or Linux host, you will have to create a @@ -764,7 +819,7 @@ \code eval $(docker-machine env windows) - docker run -it -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore + docker-compose run --rm windows \endcode \section2 Building Release Packages @@ -772,20 +827,19 @@ Release packages for \QBS for Windows can be built using the following command on Windows: \code - docker run --rm -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\make-release-archives + docker-compose run --rm windows cmd /c scripts\make-release-archives \endcode For building release packages for Windows on macOS or Linux: \code eval $(docker-machine env windows) - docker run --rm -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\\make-release-archives + docker-compose run --rm windows cmd /c scripts\\make-release-archives \endcode */ /*! - \contentspage index.html \previouspage setup.html \page installing.html \nextpage configuring.html @@ -842,7 +896,6 @@ */ /*! - \contentspage index.html \previouspage installing.html \page configuring.html \nextpage qt-versions.html @@ -866,7 +919,7 @@ For example, a profile for building C++ applications contains at least the installation path and the type of the compiler toolchain. A profile for building Qt applications contains the toolchain-specific properties as well - as \l{Qt-specific Module Provider Properties}{the path to the Qt installation}. + as \l{Qt::qmakeFilePaths}{the path to the Qt installation}. This topic describes profiles stored in the \QBS settings. In some cases it might be beneficial to keep profiles explicitly in the project sources. This @@ -936,7 +989,6 @@ */ /*! - \contentspage index.html \previouspage configuring.html \page qt-versions.html \nextpage usage.html @@ -1006,7 +1058,6 @@ */ /*! - \contentspage index.html \previouspage qt-versions.html \page usage.html \nextpage language-introduction.html @@ -1023,14 +1074,13 @@ \li \l{Generators} \li \l{Multiplexing} \li \l{Custom Modules and Items} + \li \l{Special Property Values} \li \l{Module Providers} \endlist */ - /*! - \contentspage index.html \previouspage usage.html \page language-introduction.html \nextpage building-applications.html @@ -1055,9 +1105,6 @@ } \endcode - The import statement gives us access to some built-in types and specifies the - used language version. - \a Application describes the product we want to build. In this case, an application. This is just a shortcut for writing \code @@ -1091,6 +1138,11 @@ ---CrazyProduct.qbs--- Product { property string craziness: "low" + + files: [ + "Crazy.h", + "Crazy.cpp" + ] } ---hellocrazyworld.qbs--- @@ -1099,6 +1151,7 @@ CrazyProduct { craziness: "enormous" name: "hellocrazyworld" + files: base.concat(["main.cpp"]) // ... } \endcode @@ -1124,6 +1177,7 @@ } \endcode + See \l {Special Property Values} for more details about the \l base property. \section1 Modules @@ -1166,27 +1220,17 @@ } \endcode - A module can implicitly depend on other modules. For example, the - \l{Qt.core} module depends on the \l{cpp} module. However, to set the - properties of a module, you must make the dependency explicit. + A module can depend on other modules. For example, the + \l{Qt.core} module depends on the \l{cpp} module. The module dependencies are transitive, + i.e. in a Product, all dependent modules are accessible: \code - // THIS DOES NOT WORK Application { name: "helloworld" files: ["main.cpp"] Depends { name: "Qt.core" } - cpp.optimization: "ludicrousSpeed" - // ERROR! We do not know about "cpp" here, - // though "Qt.core" depends on "cpp". - } - - // THIS WORKS - Application { - name: "helloworld" - files: ["main.cpp"] - Depends { name: "Qt.core" } - Depends { name: "cpp" } + // the "cpp" module is available since + // "Qt.core" depends on "cpp". cpp.optimization: "ludicrousSpeed" } \endcode @@ -1216,7 +1260,7 @@ This is how you do it: \code Group { - condition: qbs.targetOS.contains("windows") + condition: qbs.targetOS.includes("windows") files: [ "harddiskdeleter_win.cpp", "blowupmonitor_win.cpp", @@ -1224,7 +1268,7 @@ ] } Group { - condition: qbs.targetOS.contains("linux") + condition: qbs.targetOS.includes("linux") files: [ "harddiskdeleter_linux.cpp", "blowupmonitor_linux.cpp", @@ -1240,8 +1284,6 @@ \list \li \l{qbs::}{buildVariant} that specifies the name of the build variant for the current build. - \li \l{qbs::}{hostOS} that is set by \QBS internally and specifies the - operating system \QBS is running on. \li \l{qbs::}{targetOS} that specifies the operating system you want to build the project for. \endlist @@ -1437,13 +1479,15 @@ /*! - \contentspage index.html \previouspage language-introduction.html \page building-applications.html \nextpage running-applications.html \title Building Applications + This section assumes that \QBS is present in \c PATH. For the details how to install \QBS, see + the \l{Installing} page. + To build applications from the command line, enter the following commands: \code @@ -1497,7 +1541,6 @@ */ /*! - \contentspage index.html \previouspage running-applications.html \page installing-files.html \nextpage {Target Platforms} @@ -1524,33 +1567,60 @@ \endcode In this example, we want to install a couple of QML files and an executable. - The actual installation is then done like this (using the default profile): + When building, \QBS installs artifacts into the default root folder, namely + \c{<build root>/install-root}. The \l{qbs::installPrefix}{qbs.installPrefix} and + \l{qbs::installDir}{qbs.installDir} properties are appended to the root folder. \code - qbs --clean-install-root qbs.installRoot:/tmp/myProjectRoot + qbs build qbs.installPrefix:/usr \endcode + In this example, the executable will be installed into the \c{<build root>/install-root/usr/bin} + folder and the QML files will be installed into the + \c{<build root>/install-root/usr/share/myproject} folder. - Here, we want the \c installDir properties from the project file to be - interpreted relative to the directory \c{/tmp/myProjectRoot}, and we want - that directory to be removed first. + To skip installation during the build, use the \c --no-install option. + + To override the default location, use the \c --install-root option of the \c{qbs install} + command: + \code + qbs build --no-install qbs.installPrefix:/usr + sudo qbs install --no-build --install-root / + \endcode + In this example, artifacts will be installed directly into the \c /usr folder. Since the + \c{qbs install} command implies \c build, we use the \c --no-build parameter to ensure that + we do not accidentally rebuild the project, thereby changing the artifacts' owner to \c root. - If the \l{qbs::installRoot}{qbs.installRoot} property is not given, a - default is used, namely \c{<build root>/install-root}. + Sometimes, it makes sense to install the application into a temporary root folder, keeping the + same folder structure within that root folder as in the examples above; for instance, + when building a Linux package such as \c deb or \c rmp. To install the application into the + \c /tmp/myProjectRoot folder, use the following command: + + \code + $ qbs install --install-root /tmp/myProjectRoot + \endcode + + In this example, the executable will be installed into the \c{/tmp/myProjectRoot/usr/bin} folder + and QML files will be installed into the \c{/tmp/myProjectRoot/usr/share/myproject} folder. + + To remove all files from the install root prior to installing, use the \c --clean-install-root + parameter: + + \code + qbs install --clean-install-root --install-root /tmp/myProjectRoot + \endcode For more information about how the installation path is constructed, see \l {Installation Properties}. */ /*! - \contentspage index.html \previouspage building-applications.html \page running-applications.html \nextpage installing-files.html \title Running Applications - By default, running an application also builds it and installs it to a - location from where it can be run on the desktop or on a device. + Qbs has the convenience \l{run}{qbs run} command that simplifies running applications. For example, entering the following command runs the Qt Creator application: @@ -1558,11 +1628,19 @@ qbs run --products qtcreator \endcode - This command also builds and installs the product, if necessary. + By default, running an application also builds it and installs it to a + location from where it can be run on the desktop or on a device. Also, this command + \l{Module::setupRunEnvironment}{sets up} the environment so that the application can find + dependent libraries. + + This is not the case when running the binary manually - you'll have to make sure that the + app will find its dependencies and/or is relocatable. You can achieve that by + \l{How do I make use of rpaths?}{configuring rpaths} properly or setting the appropriate + environment variable for the respective host system. + */ /*! - \contentspage index.html \previouspage {Target Platforms} \page shell.html \nextpage generators.html @@ -1582,10 +1660,9 @@ */ /*! - \contentspage index.html \previouspage multiplexing.html \page custom-modules.html - \nextpage module-providers.html + \nextpage special-property-values.html \title Custom Modules and Items @@ -1614,6 +1691,8 @@ To introduce a custom item \c MyItem, create the file \c{search-path/imports/MyItem.qbs}. + \note Item file names must start with a capital letter due to the fact that type names can + only start with a capital letter. Otherwise, the file will be silently ignored. \section1 Making \QBS Aware of Custom Modules and Items @@ -1654,10 +1733,166 @@ */ /*! - \contentspage index.html \previouspage custom-modules.html + \page special-property-values.html + \nextpage module-providers.html + + \title Special Property Values + + Depending on the context, \QBS provides the following special values for use in property + bindings and JavaScript code: + + \list + \li \l base + \li \l exportingProduct + \li \l filePath + \li \l importingProduct + \li \l original + \li \l outer + \li \l path + \li \l product + \li \l project + \endlist + + \section2 \c base + This value is useful when making use of inheritance. It stands for the value of the respective + property in the item one level up in the inheritance chain. For instance: + \code + Product { // defined in MyProduct.qbs + Depends { name: "mymodule" } + mymodule.someProperty: ["value1"] + } + ------ some other file ------ + MyProduct { + mymodule.someProperty: base.concat(["value2"]) // => ["value1", "value2"] + } + \endcode + + \section2 \c exportingProduct + Within an \l Export item, you can use the \c exportingProduct variable to refer to + the product which defines the Export item: + + \code + Product { + Export { + Depends { name: "cpp" } + cpp.includePaths: exportingProduct.sourceDirectory + } + } + \endcode + + \section2 \c filePath + + This value holds the full file path to the \c .qbs file it appears in. This property is + rarely used, but might be useful when debugging: + \code + Product { + property bool dummy: { + console.info("I'm located at " + filePath); + } + } + \endcode + + \section2 \c importingProduct + Within an \l Export item, you can use the \c importingProduct variable to refer to + the product that pulls in the resulting module: + + \code + Product { + Export { + Depends { name: "cpp" } + cpp.includePaths: importingProduct.buildDirectory + } + } + \endcode + Usually, you should use the \l product variable instead for consistency with \l Module items. + + \section2 \c original + On the right-hand side of a module property binding, this refers to the value of the property + in the module itself (possibly overridden from a profile). Use it to set a module property + conditionally: + \code + Module { // This is mymodule + property string aProperty: "z" + } + ---------- + Product { + Depends { name: "mymodule" } + Depends { name: "myothermodule" } + // "y" if myothermodule.anotherProperty is "x", "z" otherwise: + mymodule.aProperty: myothermodule.anotherProperty === "x" ? "y" : original + } + \endcode + + \section2 \c outer + This value is used in nested items, where it refers to the value of the respective property + in the surrounding item. It is only valid in \l{Group} and \l{Properties} items: + \code + Product { + Depends { name: "mymodule" } + mymodule.someProperty: ["value1"] + Group { + name: "special files" + files: ["somefile1", "somefile2"] + mymodule.someProperty: outer.concat(["value"]) // => ["value1", "value2"] + } + } + \endcode + + \section2 \c path + + This value holds the path to the folder where the \c .qbs file is located. Use it to e.g. add + the product's directory to file paths: + \code + Product { + Depends { name: "cpp" } + cpp.includePaths: path + } + \endcode + + \section2 \c product + + This value holds the properties of the product that contains the current item or pulls in the + current module: + \code + Module { + Rule { + Artifact { + fileTags: product.type + filePath: { + var result = input.fileName; + // module properties are available as well + if (product.qbs.buildVariant === "debug") + result = result + "_debug"; + result = result + ".out"; + return result; + } + } + } + } + \endcode + Within the \l Export item, same as \l importingProduct. + + \section2 \c project + This value holds the properties of the project that references the current item or pulls in the + current module: + \code + Project { + property bool enableProduct: true + Product { + name: "theProduct" + condition: project.enableProduct + } + } + \endcode + If the nearest project in the project tree does not have the desired property, \QBS looks it + up in the parent project, potentially all the way up to the top-level project. +*/ + +/*! + \previouspage special-property-values.html \page module-providers.html - \nextpage howtos.html + \nextpage tutorial.html \title Module Providers @@ -1673,7 +1908,12 @@ If \QBS encounters a \l Depends item whose name does not match a known module, it checks whether such a module can be generated. This procedure works as follows: \list 1 - \li All \l{Project::qbsSearchPaths}{search paths} are scanned for a file called + \li If the \l{Product::qbsModuleProviders}{qbsModuleProviders} property is not + \c undefined, for each provider name in the list, all + \l{Project::qbsSearchPaths}{search paths} are scanned for a file called + \c {module-providers/<name>.qbs} or \c {module-providers/<name>/provider.qbs}. + \li If the \l{Product::qbsModuleProviders}{qbsModuleProviders} property is \c undefined, + \l{Project::qbsSearchPaths}{search paths} are scanned for a file called \c {module-providers/<name>/provider.qbs}, where \c <name> is the name of the dependency as specified in the \c Depends item. Multi-component names such as "a.b" are turned into nested directories, and each of them is scanned, starting with the deepest path. @@ -1687,14 +1927,22 @@ a second attempt will be made to locate the dependency using the new paths. The search for a matching module provider ends as soon as one was found, regardless of whether it created any modules or not. - \li If no matching module provider was found in any of the search paths, \QBS will fall back - to a generic module provider, which creates a module that attempts to locate the - dependency via \c pkg-config. - This fallback mechanism can be disabled in the respective - \l{Depends::enableFallback}{Depends} item or globally via the - \l{no-fallback-module-provider}{--no-fallback-module-provider} option. \endlist + \section1 Selecting Module Providers + + As described above, it is possible to select which providers to run using the + \l{Product::qbsModuleProviders}{qbsModuleProviders} property. Providers contribute to the + \l{Product::}{qbsSearchPaths} in the order specified by this property, so modules generated + by providers specified earlier are prioritized. This property can be set on the + Product as well as the \l{Project::qbsModuleProviders}{Project} level: + + \code + $ qbs resolve project.qbsModuleProviders:providerA \ # sets property globally for the Project + projects.SomeProject.qbsModuleProviders:providerB \ # overrides property for the specific Project + products.SomeProduct.qbsModuleProviders:providerC \ # overrides property for the specific Product + \endcode + \section1 Parameterizing Module Providers You can pass information to module providers from the command line, via profiles or @@ -1710,7 +1958,6 @@ */ /*! - \contentspage index.html \previouspage shell.html \page generators.html \nextpage multiplexing.html @@ -1902,7 +2149,6 @@ */ /*! - \contentspage index.html \previouspage generators.html \page multiplexing.html \nextpage custom-modules.html @@ -1966,7 +2212,6 @@ */ /*! - \contentspage index.html \previouspage json-api.html \page attributions.html diff --git a/doc/reference/cli/builtin/cli-build.qdoc b/doc/reference/cli/builtin/cli-build.qdoc index f9312350d..8547a78d2 100644 --- a/doc/reference/cli/builtin/cli-build.qdoc +++ b/doc/reference/cli/builtin/cli-build.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-build.html \ingroup cli @@ -79,8 +78,6 @@ \include cli-options.qdocinc products-specified \include cli-options.qdocinc settings-dir \include cli-options.qdocinc show-progress - \target no-fallback-module-provider - \include cli-options.qdocinc no-fallback-module-provider \include cli-options.qdocinc wait-lock \section1 Parameters diff --git a/doc/reference/cli/builtin/cli-clean.qdoc b/doc/reference/cli/builtin/cli-clean.qdoc index bd6ba1616..901ac2f33 100644 --- a/doc/reference/cli/builtin/cli-clean.qdoc +++ b/doc/reference/cli/builtin/cli-clean.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-clean.html \ingroup cli diff --git a/doc/reference/cli/builtin/cli-dump-nodes-tree.qdoc b/doc/reference/cli/builtin/cli-dump-nodes-tree.qdoc index 2e5485ec2..270927ccd 100644 --- a/doc/reference/cli/builtin/cli-dump-nodes-tree.qdoc +++ b/doc/reference/cli/builtin/cli-dump-nodes-tree.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-dump-nodes-tree.html \ingroup cli diff --git a/doc/reference/cli/builtin/cli-generate.qdoc b/doc/reference/cli/builtin/cli-generate.qdoc index b6dda6f4f..c7c14fc84 100644 --- a/doc/reference/cli/builtin/cli-generate.qdoc +++ b/doc/reference/cli/builtin/cli-generate.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-generate.html \ingroup cli diff --git a/doc/reference/cli/builtin/cli-help.qdoc b/doc/reference/cli/builtin/cli-help.qdoc index c36d03317..da19fda15 100644 --- a/doc/reference/cli/builtin/cli-help.qdoc +++ b/doc/reference/cli/builtin/cli-help.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-help.html \ingroup cli diff --git a/doc/reference/cli/builtin/cli-install.qdoc b/doc/reference/cli/builtin/cli-install.qdoc index b55f05296..92fad06a9 100644 --- a/doc/reference/cli/builtin/cli-install.qdoc +++ b/doc/reference/cli/builtin/cli-install.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-install.html \ingroup cli diff --git a/doc/reference/cli/builtin/cli-list-products.qdoc b/doc/reference/cli/builtin/cli-list-products.qdoc index 92ef043da..583029a73 100644 --- a/doc/reference/cli/builtin/cli-list-products.qdoc +++ b/doc/reference/cli/builtin/cli-list-products.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-list-products.html \ingroup cli diff --git a/doc/reference/cli/builtin/cli-resolve.qdoc b/doc/reference/cli/builtin/cli-resolve.qdoc index b13f3de3d..99f1658ea 100644 --- a/doc/reference/cli/builtin/cli-resolve.qdoc +++ b/doc/reference/cli/builtin/cli-resolve.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-resolve.html \ingroup cli @@ -56,7 +55,7 @@ \include cli-options.qdocinc more-verbose \include cli-options.qdocinc settings-dir \include cli-options.qdocinc show-progress - \include cli-options.qdocinc no-fallback-module-provider + \include cli-options.qdocinc deprecation-warnings \section1 Parameters diff --git a/doc/reference/cli/builtin/cli-run.qdoc b/doc/reference/cli/builtin/cli-run.qdoc index 9f20f868e..a0d3adee9 100644 --- a/doc/reference/cli/builtin/cli-run.qdoc +++ b/doc/reference/cli/builtin/cli-run.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-run.html \ingroup cli diff --git a/doc/reference/cli/builtin/cli-session.qdoc b/doc/reference/cli/builtin/cli-session.qdoc index 62999a82e..853674234 100644 --- a/doc/reference/cli/builtin/cli-session.qdoc +++ b/doc/reference/cli/builtin/cli-session.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-session.html \ingroup cli diff --git a/doc/reference/cli/builtin/cli-shell.qdoc b/doc/reference/cli/builtin/cli-shell.qdoc index 221bef24d..f024fc335 100644 --- a/doc/reference/cli/builtin/cli-shell.qdoc +++ b/doc/reference/cli/builtin/cli-shell.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-shell.html \ingroup cli diff --git a/doc/reference/cli/builtin/cli-status.qdoc b/doc/reference/cli/builtin/cli-status.qdoc index ddc8537f3..16bea5198 100644 --- a/doc/reference/cli/builtin/cli-status.qdoc +++ b/doc/reference/cli/builtin/cli-status.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-status.html \ingroup cli diff --git a/doc/reference/cli/builtin/cli-update-timestamps.qdoc b/doc/reference/cli/builtin/cli-update-timestamps.qdoc index 366f1352b..8d66071b0 100644 --- a/doc/reference/cli/builtin/cli-update-timestamps.qdoc +++ b/doc/reference/cli/builtin/cli-update-timestamps.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-update-timestamps.html \ingroup cli diff --git a/doc/reference/cli/builtin/cli-version.qdoc b/doc/reference/cli/builtin/cli-version.qdoc index 38240eef0..f4dab3cb9 100644 --- a/doc/reference/cli/builtin/cli-version.qdoc +++ b/doc/reference/cli/builtin/cli-version.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-version.html \ingroup cli diff --git a/doc/reference/cli/cli-options.qdocinc b/doc/reference/cli/cli-options.qdocinc index b02ce68ea..ecb8f5c3e 100644 --- a/doc/reference/cli/cli-options.qdocinc +++ b/doc/reference/cli/cli-options.qdocinc @@ -331,6 +331,27 @@ //! [config-ui-system] +//! [deprecation-warnings] + + \section2 \c {--deprecation-warnings <mode>} + + Uses the specified deprecation warning mode, which controls what to do when deprecated + items or properties are encountered in the project. By default, a warning is emitted + if the item or property is scheduled for removal in the next minor version of \QBS. + Warnings can also be switched on or off unconditionally, and it can be specified that + project resolving should abort if deprecated constructs are present. + + Possible values of \c <mode> are: + + \list + \li \c error + \li \c on + \li \c before-removal (default value) + \li \c off + \endlist + +//! [deprecation-warnings] + //! [log-level] \section2 \c {--log-level <level>} @@ -499,6 +520,9 @@ \li \c iar \li \c keil \li \c sdcc + \li \c cosmic + \li \c dmc + \li \c watcom \endlist //! [type] diff --git a/doc/reference/cli/cli.qdoc b/doc/reference/cli/cli.qdoc index c93b51cd0..ccc67373a 100644 --- a/doc/reference/cli/cli.qdoc +++ b/doc/reference/cli/cli.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage reference.html \group cli \title Command-Line Interface diff --git a/doc/reference/cli/tools/cli-config-ui.qdoc b/doc/reference/cli/tools/cli-config-ui.qdoc index d900841d6..ed2287c1e 100644 --- a/doc/reference/cli/tools/cli-config-ui.qdoc +++ b/doc/reference/cli/tools/cli-config-ui.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-config-ui.html \ingroup cli diff --git a/doc/reference/cli/tools/cli-config.qdoc b/doc/reference/cli/tools/cli-config.qdoc index 2b78ff8ef..6758dce61 100644 --- a/doc/reference/cli/tools/cli-config.qdoc +++ b/doc/reference/cli/tools/cli-config.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-config.html \ingroup cli diff --git a/doc/reference/cli/tools/cli-create-project.qdoc b/doc/reference/cli/tools/cli-create-project.qdoc index db3af2284..c78d8fb83 100644 --- a/doc/reference/cli/tools/cli-create-project.qdoc +++ b/doc/reference/cli/tools/cli-create-project.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-create-project.html \ingroup cli diff --git a/doc/reference/cli/tools/cli-setup-android.qdoc b/doc/reference/cli/tools/cli-setup-android.qdoc index 5421de896..357d42706 100644 --- a/doc/reference/cli/tools/cli-setup-android.qdoc +++ b/doc/reference/cli/tools/cli-setup-android.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-setup-android.html \ingroup cli diff --git a/doc/reference/cli/tools/cli-setup-qt.qdoc b/doc/reference/cli/tools/cli-setup-qt.qdoc index 1cf961d0d..c50348144 100644 --- a/doc/reference/cli/tools/cli-setup-qt.qdoc +++ b/doc/reference/cli/tools/cli-setup-qt.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-setup-qt.html \ingroup cli diff --git a/doc/reference/cli/tools/cli-setup-toolchains.qdoc b/doc/reference/cli/tools/cli-setup-toolchains.qdoc index 70cb0c23b..97f9c0235 100644 --- a/doc/reference/cli/tools/cli-setup-toolchains.qdoc +++ b/doc/reference/cli/tools/cli-setup-toolchains.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage cli.html \page cli-setup-toolchains.html \ingroup cli diff --git a/doc/reference/commands.qdoc b/doc/reference/commands.qdoc index d34c20cb7..3f542e1d1 100644 --- a/doc/reference/commands.qdoc +++ b/doc/reference/commands.qdoc @@ -29,7 +29,6 @@ // TODO: "\c" markup is used for all properties in table due to QTBUG-35505. /*! - \contentspage reference.html \page commands.html \title Command and JavaScriptCommand @@ -124,9 +123,11 @@ \li Time limit for the command execution in seconds. If the command does not finish within the timeout, it is cancelled. In case of a \c Command, the process is requested to terminate. If it does not terminate within three seconds, it is killed. A value below - or equal to 0 means no timeout. + or equal to 0 means no timeout. \br + This property was introduced in Qbs 1.15. \endtable + \section2 Command Properties \table diff --git a/doc/reference/items/convenience/appleapplicationdiskimage.qdoc b/doc/reference/items/convenience/appleapplicationdiskimage.qdoc index 69a10c797..d1fa15052 100644 --- a/doc/reference/items/convenience/appleapplicationdiskimage.qdoc +++ b/doc/reference/items/convenience/appleapplicationdiskimage.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \nextpage AppleDiskImage \qmltype AppleApplicationDiskImage \since Qbs 1.9 @@ -78,10 +77,11 @@ The base directory from which artifacts installed into the disk image will be copied. This directory is always considered to be relative to \l{qbs::installRoot} - {qbs.installRoot}. + {qbs.installRoot}/\l{qbs::installPrefix} + {qbs.installPrefix}. For example, if the application Example.app exists at - \c{qbs.installRoot/Applications/Example.app}, and the value of this property - is \c{"/Applications"}, the application will be located at\c{/Example.app} + \c{qbs.installRoot/qbs.installPrefix/Applications/Example.app}, and the value of this property + is \c{"/Applications"}, the application will be located at \c{/Example.app} relative to the disk image root. Therefore, its full path when the disk image is mounted would be something like \c{/Volumes/Example-1.0/Example.app}. diff --git a/doc/reference/items/convenience/applediskimage.qdoc b/doc/reference/items/convenience/applediskimage.qdoc index 78772db52..16fec266b 100644 --- a/doc/reference/items/convenience/applediskimage.qdoc +++ b/doc/reference/items/convenience/applediskimage.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage AppleApplicationDiskImage \nextpage Application \qmltype AppleDiskImage diff --git a/doc/reference/items/convenience/application.qdoc b/doc/reference/items/convenience/application.qdoc index c09d15918..15b05515d 100644 --- a/doc/reference/items/convenience/application.qdoc +++ b/doc/reference/items/convenience/application.qdoc @@ -25,8 +25,7 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html - \previouspage AppleApplicationDiskImage + \previouspage AppleDiskImage \nextpage ApplicationExtension \qmltype Application \inherits Product @@ -41,15 +40,16 @@ The target artifact of this type of product is usually an executable binary tagged \c "application". However, on Android, unless you set \l{Product::}{consoleApplication} to \c true, - the application target will be an APK package tagged \c "android.apk", and a - dependency to the \l{Android.sdk} module is automatically added to the product. + the application target will be an APK or an AAB package tagged \c "android.package" + according to the \l{Android.sdk}{packageType} property. A dependency to the \l{Android.sdk} + module is automatically added to the product. */ /*! \qmlproperty bool Application::install If \c{true}, the executable that is produced when building the application will be installed - to \l installDir. + to \l{Application::installDir}{installDir}. \defaultvalue \c false \since Qbs 1.13 @@ -58,8 +58,8 @@ /*! \qmlproperty string Application::installDir - Where to install the executable that is produced when building the application, if \l install - is enabled. + Where to install the executable that is produced when building the application, if + \l{Application::install}{install} is enabled. The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} when constructing the actual installation directory. @@ -67,3 +67,28 @@ \defaultvalue \c Applications if the app is a \l{bundle::isBundle}{bundle}, \c bin otherwise. \since Qbs 1.13 */ + +/*! + \qmlproperty bool Application::installDebugInformation + + If \c{true}, the debug information will be installed to + \l{Application::debugInformationInstallDir}{debugInformationInstallDir}. + + \defaultvalue \c false + \since Qbs 1.16 + \sa{How do I separate and install debugging symbols?} +*/ + +/*! + \qmlproperty string Application::debugInformationInstallDir + + Where to install the debug information if \l installDebugInformation is enabled. + + The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} + when constructing the actual installation directory. + + \defaultvalue \l installDir. + \since Qbs 1.16 + + \sa{How do I separate and install debugging symbols?} +*/ diff --git a/doc/reference/items/convenience/applicationextension.qdoc b/doc/reference/items/convenience/applicationextension.qdoc index bc65c5449..9ff0101ff 100644 --- a/doc/reference/items/convenience/applicationextension.qdoc +++ b/doc/reference/items/convenience/applicationextension.qdoc @@ -26,7 +26,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage Application \nextpage AutotestRunner \qmltype ApplicationExtension diff --git a/doc/reference/items/convenience/autotestrunner.qdoc b/doc/reference/items/convenience/autotestrunner.qdoc index e8690ffe2..c9fb217ef 100644 --- a/doc/reference/items/convenience/autotestrunner.qdoc +++ b/doc/reference/items/convenience/autotestrunner.qdoc @@ -26,7 +26,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage ApplicationExtension \nextpage CppApplication \qmltype AutotestRunner @@ -69,6 +68,27 @@ \endcode \endlist + + \section2 Setting Properties for individual Tests + \target autotestrunner-autotest-module + + To control the behavior of individual tests, some properties of the \c AutotestRunner + can be overridden by depending on the \l autotest module and setting its properties: + + \code + CppApplication { + name: "tst_mytest" + type: ["application", "autotest"] + + Depends { name: "autotest" } + + autotest.timeout: 60 + + // ... + } + \endcode + + \section2 Relevant Job Pools \target autotestrunner-job-pools @@ -147,3 +167,16 @@ \defaultvalue empty */ + +/*! + \qmlproperty int AutotestRunner::timeout + + Time limit for the execution of the individual tests. If a test does not finish within + the time limit, the test is cancelled and considered failed. A value below or equal to 0 + means no timeout. + A test can override this by setting the \l{autotest::timeout}{timeout} property + of the \l autotest module. + + \defaultvalue -1 + \since Qbs 1.15 +*/ diff --git a/doc/reference/items/convenience/cppapplication.qdoc b/doc/reference/items/convenience/cppapplication.qdoc index 13bd523b7..3518ba1e1 100644 --- a/doc/reference/items/convenience/cppapplication.qdoc +++ b/doc/reference/items/convenience/cppapplication.qdoc @@ -25,18 +25,17 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage AutotestRunner \nextpage DynamicLibrary \qmltype CppApplication - \inherits Product + \inherits Application \inqmlmodule QbsConvenienceItems \ingroup list-of-items \keyword QML.CppApplication \brief C++ application. - A CppApplication is a \l{Product}{product} that has a dependency on the + A CppApplication is an \l{Application}{application} that has a dependency on the \l{cpp} module. It is entirely equivalent to the following: \code diff --git a/doc/reference/items/convenience/dynamiclibrary.qdoc b/doc/reference/items/convenience/dynamiclibrary.qdoc index 488aef3eb..861d0509d 100644 --- a/doc/reference/items/convenience/dynamiclibrary.qdoc +++ b/doc/reference/items/convenience/dynamiclibrary.qdoc @@ -25,11 +25,10 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage CppApplication \nextpage InnoSetup \qmltype DynamicLibrary - \inherits Product + \inherits Library \inqmlmodule QbsConvenienceItems \ingroup list-of-items \keyword QML.DynamicLibrary @@ -37,7 +36,7 @@ \brief Dynamic library. - A DynamicLibrary item is a \l{Product} of the \l{Product::}{type} + A DynamicLibrary item is a \l{Library}{library} of the \l{Product::}{type} \c "dynamiclibrary". For Android targets, the following applies: @@ -47,51 +46,3 @@ \li There is a dependency on the \l{cpp} and \l{Android.ndk} modules. \endlist */ - -/*! - \qmlproperty bool DynamicLibrary::install - - If \c{true}, the library will be installed to \l installDir. - - \defaultvalue \c false - \since Qbs 1.13 -*/ - -/*! - \qmlproperty string DynamicLibrary::installDir - - Where to install the library, if \l install is enabled. On Unix, the symbolic links - are also installed to this location. - - The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} - when constructing the actual installation directory. - - \defaultvalue \c Library/Frameworks if the library is a \l{bundle::isBundle}{bundle}, - otherwise \c bin for Windows and \c lib for Unix-like targets. - \since Qbs 1.13 -*/ - -/*! - \qmlproperty bool DynamicLibrary::installImportLib - - If \c{true}, the import library will be installed to \l importLibInstallDir. - This property is only relevant for Windows targets. - Enable it if you want to create a development package. - - \defaultvalue \c false - \since Qbs 1.13 -*/ - -/*! - \qmlproperty string DynamicLibrary::importLibInstallDir - - Where to install the import library, if \l installImportLib is enabled. - - The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} - when constructing the actual installation directory. - - This property is only relevant for Windows targets. - - \defaultvalue \c lib - \since Qbs 1.13 -*/ diff --git a/doc/reference/items/convenience/innosetup.qdoc b/doc/reference/items/convenience/innosetup.qdoc index f4b52dafd..0f66243e9 100644 --- a/doc/reference/items/convenience/innosetup.qdoc +++ b/doc/reference/items/convenience/innosetup.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage DynamicLibrary \nextpage InstallPackage \qmltype InnoSetup diff --git a/doc/reference/items/convenience/installpackage.qdoc b/doc/reference/items/convenience/installpackage.qdoc index 4f82f71b7..7c5e8ec9b 100644 --- a/doc/reference/items/convenience/installpackage.qdoc +++ b/doc/reference/items/convenience/installpackage.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage InnoSetup \nextpage JavaClassCollection \qmltype InstallPackage diff --git a/doc/reference/items/convenience/javaclasscollection.qdoc b/doc/reference/items/convenience/javaclasscollection.qdoc index fb93eb29e..ae060135c 100644 --- a/doc/reference/items/convenience/javaclasscollection.qdoc +++ b/doc/reference/items/convenience/javaclasscollection.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage InstallPackage \nextpage JavaJarFile \qmltype JavaClassCollection diff --git a/doc/reference/items/convenience/javajarfile.qdoc b/doc/reference/items/convenience/javajarfile.qdoc index 48643d80e..97c775f16 100644 --- a/doc/reference/items/convenience/javajarfile.qdoc +++ b/doc/reference/items/convenience/javajarfile.qdoc @@ -25,9 +25,8 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage JavaClassCollection - \nextpage LoadableModule + \nextpage Library \qmltype JavaJarFile \inherits Product \inqmlmodule QbsConvenienceItems diff --git a/doc/reference/items/convenience/library.qdoc b/doc/reference/items/convenience/library.qdoc new file mode 100644 index 000000000..409af3f19 --- /dev/null +++ b/doc/reference/items/convenience/library.qdoc @@ -0,0 +1,129 @@ +/**************************************************************************** +** +** Copyright (C) 2020 Ivan Komissarov (abbapoh@gmail.com) +** 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$ +** +****************************************************************************/ + +/*! + \previouspage JavaJarFile + \nextpage LoadableModule + \qmltype Library + \since Qbs 1.4 + \inherits Product + \inqmlmodule QbsConvenienceItems + \ingroup list-of-items + \keyword QML.NativeBinary + + \brief Generic library. + + A Library item is a base item for native libraries and can have \l{Product::}{type} set to + one of the following values: \c "dynamiclibrary", \c "staticlibrary", \c "loadablemodule". + + The default \l{Product::}{type} value is \c "dynamiclibrary" except for iOS prior to + version 8, in which case the default value is \c "staticlibrary". + + This item can automatically install the library target (and library symlinks on Unix) and + separated debug information. + + For Android targets, the following applies: + \list + \li The \l{Product::type}{Product.type} property value contains + \c "android.nativelibrary" in addition to \c "dynamiclibrary". + \li There is a dependency on the \l{cpp} and \l{Android.ndk} modules. + \endlist +*/ + +/*! + \qmlproperty bool Library::install + + If \c{true}, the library will be installed to \l{Library::installDir}{installDir}. + + \defaultvalue \c false + \since Qbs 1.13 +*/ + +/*! + \qmlproperty string Library::installDir + + Where to install the library, if \l{Library::install}{install} is enabled. On Unix, + the symbolic links are also installed to this location. + + The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} + when constructing the actual installation directory. + + \defaultvalue \c Library/Frameworks if the library is a \l{bundle::isBundle}{bundle}, + otherwise \c bin for Windows and \c lib for Unix-like targets. + \since Qbs 1.13 +*/ + +/*! + \qmlproperty bool Library::installDebugInformation + + If \c{true}, the debug information will be installed to + \l{Library::debugInformationInstallDir}{debugInformationInstallDir}. + + \defaultvalue \c false + \since Qbs 1.16 + \sa{How do I separate and install debugging symbols?} +*/ + +/*! + \qmlproperty string Library::debugInformationInstallDir + + Where to install the debug information if \l installDebugInformation is enabled. + + The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} + when constructing the actual installation directory. + + \defaultvalue \l installDir. + \since Qbs 1.16 + + \sa{How do I separate and install debugging symbols?} +*/ + +/*! + \qmlproperty bool Library::installImportLib + + If \c{true}, the import library will be installed to \l importLibInstallDir. + This property is only relevant for Windows targets. + Enable it if you want to create a development package. + + \defaultvalue \c false + \since Qbs 1.13 +*/ + +/*! + \qmlproperty string Library::importLibInstallDir + + Where to install the import library, if \l installImportLib is enabled. + + The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} + when constructing the actual installation directory. + + This property is only relevant for Windows targets. + + \defaultvalue \c lib + \since Qbs 1.13 +*/ + diff --git a/doc/reference/items/convenience/loadablemodule.qdoc b/doc/reference/items/convenience/loadablemodule.qdoc index d02dbae1c..2921051fd 100644 --- a/doc/reference/items/convenience/loadablemodule.qdoc +++ b/doc/reference/items/convenience/loadablemodule.qdoc @@ -26,11 +26,10 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html - \previouspage JavaJarFile + \previouspage Library \nextpage QtApplication \qmltype LoadableModule - \inherits Product + \inherits Library \inqmlmodule QbsConvenienceItems \ingroup list-of-items \keyword QML.LoadableModule diff --git a/doc/reference/items/convenience/qtapplication.qdoc b/doc/reference/items/convenience/qtapplication.qdoc index 09640a8c1..0cef3080b 100644 --- a/doc/reference/items/convenience/qtapplication.qdoc +++ b/doc/reference/items/convenience/qtapplication.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage LoadableModule \nextpage QtGuiApplication \qmltype QtApplication @@ -42,7 +41,7 @@ \code CppApplication { - Depends { name: "Qt.core" } } + Depends { name: "Qt.core" } } \endcode diff --git a/doc/reference/items/convenience/qtguiapplication.qdoc b/doc/reference/items/convenience/qtguiapplication.qdoc index e69b9214c..62fb5cee7 100644 --- a/doc/reference/items/convenience/qtguiapplication.qdoc +++ b/doc/reference/items/convenience/qtguiapplication.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage QtApplication \nextpage StaticLibrary \qmltype QtGuiApplication diff --git a/doc/reference/items/convenience/staticlibrary.qdoc b/doc/reference/items/convenience/staticlibrary.qdoc index cd459cf6e..c2ff1e63b 100644 --- a/doc/reference/items/convenience/staticlibrary.qdoc +++ b/doc/reference/items/convenience/staticlibrary.qdoc @@ -25,39 +25,16 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage QtGuiApplication \nextpage XPCService \qmltype StaticLibrary - \inherits Product + \inherits Library \inqmlmodule QbsConvenienceItems \ingroup list-of-items \keyword QML.StaticLibrary \brief Static library. - A StaticLibrary item is a \l{Product}{product} of the \l{Product::}{type} + A StaticLibrary item is a \l{Library}{library} of the \l{Product::}{type} \c "staticlibrary". */ - -/*! - \qmlproperty bool StaticLibrary::install - - If \c{true}, the library will be installed to \l installDir. - - \defaultvalue \c false - \since Qbs 1.13 -*/ - -/*! - \qmlproperty string StaticLibrary::installDir - - Where to install the library, if \l install is enabled. - - The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} - when constructing the actual installation directory. - - \defaultvalue \c Library/Frameworks if the library is a \l{bundle::isBundle}{bundle}, - \c lib otherwise. - \since Qbs 1.13 -*/ diff --git a/doc/reference/items/convenience/xpcservice.qdoc b/doc/reference/items/convenience/xpcservice.qdoc index f786cf9ae..682d161b9 100644 --- a/doc/reference/items/convenience/xpcservice.qdoc +++ b/doc/reference/items/convenience/xpcservice.qdoc @@ -26,7 +26,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-convenience-items.html \previouspage StaticLibrary \qmltype XPCService \inherits Application diff --git a/doc/reference/items/language/artifact.qdoc b/doc/reference/items/language/artifact.qdoc index f64e2f0c9..6a6d80cd2 100644 --- a/doc/reference/items/language/artifact.qdoc +++ b/doc/reference/items/language/artifact.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \nextpage Depends \ingroup list-of-language-items \qmltype Artifact diff --git a/doc/reference/items/language/depends.qdoc b/doc/reference/items/language/depends.qdoc index 8a3e23ba9..937828b8c 100644 --- a/doc/reference/items/language/depends.qdoc +++ b/doc/reference/items/language/depends.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Artifact \nextpage Export \qmltype Depends @@ -128,7 +127,19 @@ The \l required and \l profiles properties are ignored if this property is set. - Product types attached via Module::additionalProductTypes are not considered. + \note This property does not work recursively. Consider this example: + \code + Product { + name: "A" + type: "x" + Depends { productTypes: "someTag" } + } + Product { + name: "B" + Depends { productTypes: "x" } + } + \endcode + It is not guaranteed that \c A will show up in \c B's dependencies. \nodefaultvalue */ @@ -186,12 +197,3 @@ \nodefaultvalue */ - -/*! - \qmlproperty bool Depends::enableFallback - - Whether to fall back to a pkg-config based \l{Module Providers}{module provider} - if the dependency is not found. - - \defaultvalue \c true -*/ diff --git a/doc/reference/items/language/export.qdoc b/doc/reference/items/language/export.qdoc index d8ed4c33d..e3648fc3e 100644 --- a/doc/reference/items/language/export.qdoc +++ b/doc/reference/items/language/export.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Depends \nextpage FileTagger \qmltype Export @@ -45,8 +44,8 @@ name: "A" Export { Depends { name: "cpp" } - cpp.includePaths: product.sourceDirectory - cpp.defines: ["USING_" + product.name.toUpperCase()] + cpp.includePaths: exportingProduct.sourceDirectory + cpp.defines: ["USING_" + exportingProduct.name.toUpperCase()] } } @@ -56,16 +55,45 @@ } \endcode - The sources in product B will be able to use headers from product A without specifiying + The sources in product B will be able to use headers from product A without specifying the full path to them, because the include path has been made known to the compiler via A's Export item. Additionally, product B will be compiled with the define \c{USING_A}. - \note This relationship is transitive, so a product C depending on product B will also - get the include paths and preprocessor macros via A's Export item. + The dependent \l{Product}'s modules are not exported unless explicitly specified within the + \l{Export} item: + \code + Product { + name: "B-Exporting-A" + Depends { name: "A" } + Export { + Depends { name: "A" } + } + } + \endcode + + The relationship of the exported dependencies is transitive. A product C depending on a + product B-Exporting-A will also get a direct dependency on A and thus inherit include + paths and preprocessor macros exported by A. + + \code + Product { + name: "C" + Depends { name: "B-Exporting-A" } + } + \endcode - In contrast to Module items, \c{product} within Export items refers to the product which defines - the Export item. Use the \c{importingProduct} variable to refer to the product that - pulls in the resulting module. + Within an Export item, you can use the \c exportingProduct variable to refer to + the product which defines the Export item. Use the \c{importingProduct} variable + to refer to the product that pulls in the resulting module: + \code + Product { + name: "D" + Export { + Depends { name: "cpp" } + cpp.includePaths: [exportingProduct.sourceDirectory, importingProduct.buildDirectory] + } + } + \endcode */ /*! @@ -81,10 +109,10 @@ project against it), you would write something like the following: \code Export { - Depends { name: cpp" } - cpp.includePaths: [product.sourceDirectory] + Depends { name: "cpp" } + cpp.includePaths: [exportingProduct.sourceDirectory] prefixMapping: [{ - prefix: product.sourceDirectory, + prefix: exportingProduct.sourceDirectory, replacement: FileInfo.joinPaths(qbs.installPrefix, "include") }] } diff --git a/doc/reference/items/language/filetagger.qdoc b/doc/reference/items/language/filetagger.qdoc index 1f01037b5..5b2b4cb1f 100644 --- a/doc/reference/items/language/filetagger.qdoc +++ b/doc/reference/items/language/filetagger.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Export \nextpage Group \qmltype FileTagger diff --git a/doc/reference/items/language/group.qdoc b/doc/reference/items/language/group.qdoc index caeffcfaa..fa6784ca6 100644 --- a/doc/reference/items/language/group.qdoc +++ b/doc/reference/items/language/group.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage FileTagger \nextpage JobLimit \qmltype Group @@ -49,21 +48,21 @@ } Group { name: "Windows files" - condition: qbs.targetOS.contains("windows") + condition: qbs.targetOS.includes("windows") files: "myclass_win_impl.cpp" } Group { name: "Unix files" - condition: qbs.targetOS.contains("unix") + condition: qbs.targetOS.includes("unix") files: "unixhelper.cpp" Group { name: "Linux files" - condition: qbs.targetOS.contains("linux") + condition: qbs.targetOS.includes("linux") files: "myclass_linux_impl.cpp" } Group { name: "FreeBSD files" - condition: qbs.targetOS.contains("freebsd") + condition: qbs.targetOS.includes("freebsd") files: "myclass_freebsd_impl.cpp" } } @@ -75,10 +74,13 @@ } } \endcode - When specifying files, you can use the wildcards "*", "?" and "[]", which have their usual meaning. - By default, matching files are only picked up directly from the parent directory, but you can tell \QBS to - consider the whole directory tree. It is also possible to exclude certain files from the list. - The pattern ** used in a pathname expansion context will match all files and zero or more + When specifying files, you can use the wildcards \c "*", \c "?" and \c "[]", which + have their + \l{https://en.wikipedia.org/wiki/Wildcard_character#File_and_directory_patterns}{usual meaning} + as in Unix Shell. By default, matching files are only picked up directly from the + parent directory, but you can tell \QBS to consider the whole directory tree. + It is also possible to exclude certain files from the list. + The pattern \c "**" used in a pathname expansion context will match all files and zero or more directories and subdirectories. For example: \snippet reference/items/language/group.qbs 0 @@ -115,13 +117,15 @@ */ /*! - \qmlproperty list Group::files + \qmlproperty pathList Group::files The files in the group. Mutually exclusive with \l{fileTagsFilter}. Relative paths are resolved using the parent directory of the file that contains the Group item. However, if the \l{prefix} property is set to an absolute path, then that one becomes the base directory. + The values can contain wildcards. + \defaultvalue An empty list */ @@ -147,7 +151,7 @@ */ /*! - \qmlproperty list Group::fileTagsFilter + \qmlproperty stringList Group::fileTagsFilter List of \l{Artifact::fileTags}{artifact.fileTags} to match. Any properties set in this group will be applied to the product's artifacts whose file tags @@ -171,7 +175,7 @@ */ /*! - \qmlproperty list Group::fileTags + \qmlproperty stringList Group::fileTags A list of file tags to attach to the group's files. These can then be matched by a \l{Rule}{rule}. @@ -197,10 +201,13 @@ */ /*! - \qmlproperty list Group::excludeFiles + \qmlproperty pathList Group::excludeFiles + + A list of files that are \e subtracted from the \l{files} list. - A list of files that are \e subtracted from the files list. Useful when - using wildcards. + The values can contain wildcards. + + This property is ignored if \l{fileTagsFilter} is set. \defaultvalue An empty list */ diff --git a/doc/reference/items/language/joblimit.qdoc b/doc/reference/items/language/joblimit.qdoc index cd68bae31..5ac3689e0 100644 --- a/doc/reference/items/language/joblimit.qdoc +++ b/doc/reference/items/language/joblimit.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Group \nextpage Module \qmltype JobLimit diff --git a/doc/reference/items/language/module.qdoc b/doc/reference/items/language/module.qdoc index 18706b4b8..48ad583c8 100644 --- a/doc/reference/items/language/module.qdoc +++ b/doc/reference/items/language/module.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage JobLimit \nextpage ModuleProvider \qmltype Module @@ -170,64 +169,15 @@ \qml Module { property bool featureEnabled: - (product.type.contains("application")) ? true : false + (product.type.includes("application")) ? true : false } \endqml - \section1 Special Property Values - - For every property defined in a module, \QBS provides the following special - built-in values: - - \list - \li \l base - \li \l original - \li \l outer - \endlist - - \section2 \c base - This value is useful when making use of inheritance. It stands for the value of the respective - property in the item one level up in the inheritance chain. For instance: - \code - Product { // defined in MyProduct.qbs - Depends { name: "mymodule" } - mymodule.someProperty: ["value1"] - } - ------ some other file ------ - MyProduct { - mymodule.someProperty: base.concat(["value2"]) // => ["value1", "value2"] - } - \endcode - - \section2 \c original - This is the value of the property in the module itself (possibly overridden from a profile or - the command line). Use it to set a module property conditionally: - \code - Module { // This is mymodule - property string aProperty: "z" - } - ---------- - Product { - Depends { name: "mymodule" } - Depends { name: "myothermodule" } - mymodule.aProperty: myothermodule.anotherProperty === "x" ? "y" : original // => "y" if myothermodule.anotherProperty is "x", "z" otherwise - \endcode - - \section2 \c outer - This value is used in nested items, where it refers to the value of the respective property - in the surrounding item. It is only valid in \l{Group} and \l{Properties} items: - \code - Product { - Depends { name: "mymodule" } - mymodule.someProperty: ["value1"] - Group { - name: "special files" - files: ["somefile1", "somefile2"] - mymodule.someProperty: outer.concat(["value"]) // => ["value1", "value2"] - } - } - \endcode + \section2 Special Property Values + For every property defined in a module, \QBS provides the special + \l{Special Property Values#original}{original} value containing the value of the property in + the module itself (possibly overridden from a profile). \section1 Dependency Parameters diff --git a/doc/reference/items/language/moduleprovider.qdoc b/doc/reference/items/language/moduleprovider.qdoc index ddbc25959..09cabb39b 100644 --- a/doc/reference/items/language/moduleprovider.qdoc +++ b/doc/reference/items/language/moduleprovider.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Module \nextpage Parameter \qmltype ModuleProvider @@ -41,6 +40,8 @@ The actual module creation is done on the right-hand side of the \l{ModuleProvider::relativeSearchPaths}{relativeSearchPaths} property. + A ModuleProvider item may contain \l{Probe} items. + Here is a complete minimal example of a module provider. It just creates an empty module. If you put this item into the file \c {module-providers/mymodule/provider.qbs} in your project source directory, you will be able to successfully build a product which @@ -66,19 +67,46 @@ */ /*! + \qmlproperty bool ModuleProvider::isEager + + Holds whether provider is eager. + + Eager provider is executed only once and should create multiple modules at once when executed). + A non-eager provider is executed multiple times, one time for each module \QBS tries to + instantiate. + + \sa ModuleProvider::moduleName + \default true +*/ + +/*! \qmlproperty string ModuleProvider::name The name of the module provider. - This property is set by \QBS. For simple dependency names, it is the name of the dependency - as specified in the \l Depends item. If the dependency name consists of multiple components, - the value is the name up until (and including) the component that corresponds to the directory - the provider was found in. For instance, if the dependency is \c {x.m1} and the provider was - found in \c {module-providers/x/m1/provider.qbs}, then \c name is \c {x.m1}. + This property is set by \QBS. + + If provider is \l{How \QBS Uses Module Providers}{requested} via the + \l{Product::qbsModuleProviders}{qbsModuleProviders} property, it is the name specified in this + property and matches the provider file name, without the \c .qbs extension. + Otherwise, it is the name of the directory the provider was found in, relative to + the particular module-providers base directory. For instance, if the dependency is \c {x.m1} and + the provider was found in \c {module-providers/x/m1/provider.qbs}, then \c name is \c {x.m1}. If the provider was found in \c {module-providers/x/provider.qbs}, then \c name is \c x. */ /*! + \qmlproperty string ModuleProvider::moduleName + + This property is set by QBS for non-eager providers and contains the name of the module + that is currently being instantiated by the provider. + + For eager providers, the value of this property is \c undefined. + + \sa ModuleProvider::isEager +*/ + +/*! \qmlproperty string ModuleProvider::outputBaseDir The path under which the new modules should be created when \l relativeSearchPaths diff --git a/doc/reference/items/language/parameter.qdoc b/doc/reference/items/language/parameter.qdoc index c544af2d7..9a1b0345b 100644 --- a/doc/reference/items/language/parameter.qdoc +++ b/doc/reference/items/language/parameter.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Module \nextpage Parameters \qmltype Parameter diff --git a/doc/reference/items/language/parameters.qdoc b/doc/reference/items/language/parameters.qdoc index bbccb222c..fb7653528 100644 --- a/doc/reference/items/language/parameters.qdoc +++ b/doc/reference/items/language/parameters.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Parameter \nextpage Probe \qmltype Parameters @@ -33,10 +32,10 @@ \ingroup list-of-items \keyword QML.Parameters - \brief Defines default values for dependency parameters within Export items. + \brief Defines default values for dependency parameters within Module and Export items. The Parameters item defines default values for dependency parameters within - \l{Export} items. + \l{Module} and \l{Export} items. Example: \code diff --git a/doc/reference/items/language/probe.qdoc b/doc/reference/items/language/probe.qdoc index 4ebfae319..8e31d8827 100644 --- a/doc/reference/items/language/probe.qdoc +++ b/doc/reference/items/language/probe.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Parameters \nextpage Product \qmltype Probe @@ -36,7 +35,7 @@ \brief Locates files outside the project. - Probe items can appear inside \l{Product} and \l{Project} items. + Probe items can appear inside \l{Product}, \l{Project} and \l{ModuleProvider} items. They are run prior to building, for instance to locate dependent headers, libraries, and other files outside the project directory whose locations are not known ahead of time. Probes can be parameterized via their properties and typically store results in diff --git a/doc/reference/items/language/product.qdoc b/doc/reference/items/language/product.qdoc index 6b87cffc0..1ae29741c 100644 --- a/doc/reference/items/language/product.qdoc +++ b/doc/reference/items/language/product.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Probe \nextpage Profile \qmltype Product @@ -207,9 +206,13 @@ /*! \qmlproperty stringList Product::qbsSearchPaths + A list of paths that are searched for imports, modules and module providers. + The value set here will be merged with the value of \l{Project::qbsSearchPaths}{project.qbsSearchPaths}. + For the details about how to add custom items, see the \l{Custom Modules and Items} page. + \defaultvalue \l{Project::qbsSearchPaths}{project.qbsSearchPaths} */ @@ -280,3 +283,15 @@ The value of this property is automatically set by \QBS and cannot be changed by the user. */ + +/*! + \qmlproperty stringList Product::qbsModuleProviders + + The list of \l{Module Providers} to use for this product. + + Overrides \l{Project::qbsModuleProviders}{Project.qbsModuleProviders}. + + \sa Project::qbsModuleProviders + + \since Qbs 1.21 +*/ diff --git a/doc/reference/items/language/profile.qdoc b/doc/reference/items/language/profile.qdoc index b0eccc803..3c41b312c 100644 --- a/doc/reference/items/language/profile.qdoc +++ b/doc/reference/items/language/profile.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Product \nextpage Project \qmltype Profile diff --git a/doc/reference/items/language/project.qdoc b/doc/reference/items/language/project.qdoc index d2db644f6..b1dc6e9de 100644 --- a/doc/reference/items/language/project.qdoc +++ b/doc/reference/items/language/project.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Profile \nextpage Properties \qmltype Project @@ -92,11 +91,13 @@ /*! \qmlproperty stringList Project::qbsSearchPaths - A list of paths that are searched for imports and modules in addition to the ones listed - in \c{preferences.qbsSearchPaths}. The value set here is merged with the value + A list of paths that are searched for imports, modules and module providers in addition to the + ones listed in \c{preferences.qbsSearchPaths}. The value set here is merged with the value inherited from the parent project, if there is one. The result is inherited by all products in the project. + For the details about how to add custom items, see the \l{Custom Modules and Items} page. + \defaultvalue An empty list */ @@ -124,3 +125,19 @@ \defaultvalue \c "1.3.0" */ + +/*! + \qmlproperty stringList Project::qbsModuleProviders + + The list of \l{Module Providers} to use for this project. + + Providers contribute to the \l{Product::}{qbsSearchPaths} in the order specified here, so + modules generated by providers specified earlier are prioritized. + Currently, this order also corresponds with the actual execution order of the providers, but + this should not be relied upon. + + \sa Product::qbsModuleProviders + + \since Qbs 1.21 +*/ + diff --git a/doc/reference/items/language/properties.qdoc b/doc/reference/items/language/properties.qdoc index a4d0d46a3..3a71a035b 100644 --- a/doc/reference/items/language/properties.qdoc +++ b/doc/reference/items/language/properties.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Project \nextpage PropertyOptions \qmltype Properties @@ -45,7 +44,7 @@ \code Product { Properties { - condition: qbs.targetOS.contains("windows") + condition: qbs.targetOS.includes("windows") cpp.defines: ["ON_WINDOWS"] cpp.includePaths: ["extraWindowsIncludes"] } @@ -58,12 +57,12 @@ \code Product { Properties { - condition: qbs.targetOS.contains("windows") + condition: qbs.targetOS.includes("windows") cpp.defines: ["ON_WINDOWS"] cpp.includePaths: ["myWindowsIncludes"] } Properties { - condition: qbs.targetOS.contains("linux") + condition: qbs.targetOS.includes("linux") cpp.defines: ["ON_LINUX"] cpp.includePaths: ["myLinuxIncludes"] } @@ -74,32 +73,32 @@ \code Product { cpp.defines: { - if (qbs.targetOS.contains("windows")) + if (qbs.targetOS.includes("windows")) return ["ON_WINDOWS"]; - if (qbs.targetOS.contains("linux")) + if (qbs.targetOS.includes("linux")) return ["ON_LINUX"]; return ["ON_UNKNOWN_PLATFORM"]; } cpp.includePaths: { - if (qbs.targetOS.contains("windows")) + if (qbs.targetOS.includes("windows")) return ["myWindowsIncludes"]; - if (qbs.targetOS.contains("linux")) + if (qbs.targetOS.includes("linux")) return ["myLinuxIncludes"]; return base; } } \endcode - In Properties items, one can access the \l{Module#outer}{outer value} of a + In Properties items, one can access the \l{Special Property Values#outer}{outer} value of a property. \code Product { Properties { - condition: qbs.targetOS.contains("windows") + condition: qbs.targetOS.includes("windows") cpp.defines: outer.concat("ON_WINDOWS") // === ["FOO", "ON_WINDOWS"] } Properties { - condition: qbs.targetOS.contains("linux") + condition: qbs.targetOS.includes("linux") cpp.defines: ["ON_LINUX"] // === ["ON_LINUX"] } cpp.defines: ["FOO"] diff --git a/doc/reference/items/language/propertyoptions.qdoc b/doc/reference/items/language/propertyoptions.qdoc index a953489a0..afbba7104 100644 --- a/doc/reference/items/language/propertyoptions.qdoc +++ b/doc/reference/items/language/propertyoptions.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Properties \nextpage Rule \inqmlmodule QbsLanguageItems diff --git a/doc/reference/items/language/rule.qdoc b/doc/reference/items/language/rule.qdoc index 62a32caf5..ec5865444 100644 --- a/doc/reference/items/language/rule.qdoc +++ b/doc/reference/items/language/rule.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage PropertyOptions \nextpage Scanner \qmltype Rule diff --git a/doc/reference/items/language/scanner.qdoc b/doc/reference/items/language/scanner.qdoc index 9ec575684..d3758ef61 100644 --- a/doc/reference/items/language/scanner.qdoc +++ b/doc/reference/items/language/scanner.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Rule \nextpage SubProject \qmltype Scanner diff --git a/doc/reference/items/language/subproject.qdoc b/doc/reference/items/language/subproject.qdoc index 91c879b55..d2bf018a0 100644 --- a/doc/reference/items/language/subproject.qdoc +++ b/doc/reference/items/language/subproject.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage list-of-language-items.html \previouspage Scanner \qmltype SubProject \inqmlmodule QbsLanguageItems @@ -94,6 +93,20 @@ */ /*! + \qmlproperty bool SubProject::condition + + Whether the sub-project is added. If \c false, the sub-project is not + included. + + Setting this property has the same effect as setting the \c{condition} + property within a \l{Properties} item. If both this property and the + \c{condition} property within a \l{Properties} item are defined, the + sub-project is included only if both properties evaluate to \c{true}. + + \defaultvalue \c true +*/ + +/*! \qmlproperty path SubProject::filePath The file path of the project to add as a sub-project. If the top-level item diff --git a/doc/reference/items/probe/binary-probe.qdoc b/doc/reference/items/probe/binary-probe.qdoc index 930043829..919d0b89e 100644 --- a/doc/reference/items/probe/binary-probe.qdoc +++ b/doc/reference/items/probe/binary-probe.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2019 Ivan Komissarov +** Copyright (C) 2019 Ivan Komissarov (abbapoh@gmail.com) ** Contact: https://www.qt.io/licensing/ ** ** This file is part of Qbs. @@ -26,9 +26,8 @@ ****************************************************************************/ /*! - \contentspage list-of-probes.html \qmltype BinaryProbe - \ingroup list-of-probes + \inqmlmodule QbsProbes \ingroup list-of-items \keyword QML.BinaryProbe \inherits PathProbe @@ -51,6 +50,7 @@ For example, BinaryProbe can be used to search for a protobuf compiler executable as follows: \code + // Assuming module is called "myproto" import qbs.File import qbs.Probes @@ -71,10 +71,10 @@ Rule { // rule input/outputs here... - // run executable + // run executable for the module called "myproto": prepare: { var args = // initialize arguments... - var cmd = new Command(executableFilePath, args); + var cmd = new Command(input.myproto.executableFilePath, args); cmd.highlight = "codegen"; cmd.description = "generating protobuf files for " + input.fileName; return [cmd]; diff --git a/doc/reference/items/probe/conanfile-probe.qdoc b/doc/reference/items/probe/conanfile-probe.qdoc new file mode 100644 index 000000000..cc91b9237 --- /dev/null +++ b/doc/reference/items/probe/conanfile-probe.qdoc @@ -0,0 +1,257 @@ +/**************************************************************************** +** +** Copyright (C) 2020 Richard Weickelt +** 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$ +** +****************************************************************************/ + +/*! + \qmltype ConanfileProbe + \inqmlmodule QbsProbes + \ingroup list-of-items + \keyword QML.ConanfileProbe + + \brief Extracts information about dependencies from a Conan recipe file. + + The \c ConanfileProbe interfaces \QBS to the \l{https://conan.io/}{Conan + package manager}. It runs + \l{https://docs.conan.io/en/latest/reference/commands/consumer/install.html}{conan + install} on a Conan recipe file such as \c conanfile.py or \c conanfile.txt + and extracts all available meta information about package dependencies using + the \l{https://docs.conan.io/en/latest/reference/generators/json.html}{json + generator}. The output may be used to set up \l{Profile} items or module + properties in products. \c ConanfileProbe can also be used to run other + Conan generators and to retrieve their output. + + \section1 Examples + + In the following examples we assume that our project contains a \c conanfile.py. + This file describes all dependencies of our project. The dependency packages are + expected to export meta information to be consumed by our project. + + \section2 Including Files Generated by Conan + + Conan has a built-in + \l{https://docs.conan.io/en/latest/reference/generators/qbs.html}{qbs + generator} that creates a project file containing dummy products. This is + the easiest way to access dependencies, but also the least flexible one. It + requires each Conan package to export correct meta information and works only + if the dependency is a library. + + \qml + import qbs.Probes + + Project { + Probes.ConanfileProbe { + id: conan + conanfilePath: project.sourceDirectory + "/conanfile.py" + generators: "qbs" + } + + references: conan.generatedFilesPath + "/conanbuildinfo.qbs" + + CppApplication { + type: "application" + files: "main.cpp" + Depends { name: "mylib" } + } + } + \endqml + + \section2 Setting Module Properties in Products + + When a product depends on a Conan package that does not have a + dedicated \l{List of Modules}{module}, package meta information may be + directly fed into the \l{cpp} module. + + This approach is very flexible. + + \qml + import qbs.Probes + + CppApplication { + Probes.ConanfileProbe { + id: conan + conanfilePath: product.sourceDirectory + "/conanfile.py" + options: ({opt1: "True"; opt2: "TheValue"}) + } + cpp.includePaths: conan.dependencies["myLib"].include_paths + cpp.libraryPaths: conan.dependencies["myLib"].lib_paths + cpp.dynamicLibraries: conan.dependencies["mylib"].libs + } + \endqml + + \section2 Setting Up a Profile + + When multiple products depend on one or more Conan packages, the dependency + information may be combined in a \l{Profile}. This is especially useful when + \QBS modules are available for some of the packages, but some of their + properties need to be initialized. Otherwise, it would have to be done + manually in global profiles. + + \qml + import qbs.Probes + + Project { + Probes.ConanfileProbe { + id: conan + conanfilePath: project.sourceDirectory + "/conanfile.py" + } + Profile { + name: "arm-gcc" + cpp.toolchainInstallPath: conan.dependencies["arm-none-eabi-gcc"].rootpath + "/bin" + cpp.toolchainPrefix: "arm-linux-gnueabi-" + qbs.toolchainType: "gcc" + } + } + \endqml + + This allows fully automated dependency management, including compiler + toolchains and is very useful when teams work in heterougeneous + environments. + +*/ + +/*! + \qmlproperty stringList ConanfileProbe::additionalArguments + + Additional command line arguments that are appended to the \c{conan install} + command. + + \defaultvalue [] +*/ + +/*! + \qmlproperty path ConanfileProbe::conanfilePath + + Path to a \c conanfile.py or \c conanfile.txt that is used by this probe. + + This property cannot be set at the same time as \l{ConanfileProbe::}{packageReference}. + + \nodefaultvalue +*/ + +/*! + \qmlproperty var ConanfileProbe::dependencies + + This property contains the same information as + \l{ConanfileProbe::}{json}.dependencies, but instead of an array, \c + dependencies is a map with package names as keys for convenient access. + + \readonly + \nodefaultvalue +*/ + +/*! + \qmlproperty path ConanfileProbe::executable + + The name of or the path to the Conan executable. + + \defaultvalue "conan.exe" on Windows, "conan" otherwise +*/ + +/*! + \qmlproperty path ConanfileProbe::generatedFilesPath + + The path of the folder where Conan generators store their files. Each + instance of this probe creates a unique folder under + \l{Project::buildDirectory}{Project.buildDirectory}. The folder name is a + hash of the arguments supplied to \c{conan install}. + + \readonly + \nodefaultvalue +*/ + +/*! + \qmlproperty stringList ConanfileProbe::generators + + Conan generators to be executed by this probe. The + \l{https://docs.conan.io/en/latest/reference/generators/json.html}{JSON + generator} is always enabled. Generated files are written to the + \l{ConanfileProbe::generatedFilesPath}{generatedFilesPath} folder. + + \sa {https://docs.conan.io/en/latest/reference/generators.html}{Available + generators} + + \defaultvalue ["json"] +*/ + +/*! + \qmlproperty var ConanfileProbe::json + + The parsed output of Conan's + \l{https://docs.conan.io/en/latest/reference/generators/json.html}{JSON + generator} as a JavaScript object. + + \readonly + \nodefaultvalue +*/ + +/*! + \qmlproperty var ConanfileProbe::options + + Options applied to \c{conan install} via the \c{-o} flag. + This property is an object in the form \c{key:value}. + + Example: + \qml + options: ({someOpt: "True", someOtherOpt: "TheValue"}) + \endqml + + \nodefaultvalue +*/ + +/*! + \qmlproperty string ConanfileProbe::packageReference + + Reference of a Conan package in the form \c{name/version@user/channel}. + Use this property if you want to probe an existing package in the local + cache or on a remote. + + This property cannot be set at the same time as \l{ConanfileProbe::}{conanfilePath}. + + \nodefaultvalue +*/ + +/*! + \qmlproperty var ConanfileProbe::settings + + Settings applied to \c{conan install} via the \c{-s} flag. + This property is an object in the form \c{key:value}. + + Example: + \qml + settings: ({os: "Linux", compiler: "gcc"}) + \endqml + + \nodefaultvalue +*/ + +/*! + \qmlproperty var ConanfileProbe::verbose + + Set to \c{true} to print all output of `conan install`. + If this property is \c{false} only error output will be printed. + + \defaultvalue \c{false} +*/ diff --git a/doc/reference/items/probe/dmc-probe.qdoc b/doc/reference/items/probe/dmc-probe.qdoc new file mode 100644 index 000000000..36d99cf93 --- /dev/null +++ b/doc/reference/items/probe/dmc-probe.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** Copyright (C) 2021 Denis Shienkov <denis.shienkov@gmail.com> +** 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$ +** +****************************************************************************/ + +/*! + \qmltype DmcProbe + \inqmlmodule QbsProbes + \ingroup list-of-items + \keyword QML.DmcProbe + \inherits PathProbe + \brief Collects Digital Mars toolchain compiler information. + \since Qbs 1.13 + \internal + + Detects the version, supported architecture, the platform + endianness, and other stuff for the specified compiler executable + from the \l{https://www.digitalmars.com/}{Digital Mars} toolchain. +*/ + +/*! + \qmlproperty string DmcProbe::compilerFilePath + + An input property which is a full path to the Digital Mars compiler + executable. + + \nodefaultvalue +*/ + +/*! + \qmlproperty string DmcProbe::architecture + + Detected architecture of the target platform's processor. + + The possible values are \c "x86" and \c "x86_16". + + \nodefaultvalue +*/ + +/*! + \qmlproperty string DmcProbe::targetPlatform + + Detected target platform. + + The possible values are \c "windows" and \c "dos". + + \nodefaultvalue +*/ + +/*! + \qmlproperty int DmcProbe::versionMajor + + Detected major compiler version. + + \nodefaultvalue +*/ + +/*! + \qmlproperty int DmcProbe::versionMinor + + Detected minor compiler version. + + \nodefaultvalue +*/ + +/*! + \qmlproperty int DmcProbe::versionPatch + + Detected patch compiler version. + + \nodefaultvalue +*/ + +/*! + \qmlproperty stringList DmcProbe::includePaths + + Detected compiler include paths. + + \nodefaultvalue +*/ + +/*! + \qmlproperty var DmcProbe::compilerDefinesByLanguage + + Detected set of compiler pre-defined macros depending + on the \c "C" or \c "C++" language. + + \nodefaultvalue +*/ diff --git a/doc/reference/items/probe/framework-probe.qdoc b/doc/reference/items/probe/framework-probe.qdoc index 23ee57b3b..89986f48f 100644 --- a/doc/reference/items/probe/framework-probe.qdoc +++ b/doc/reference/items/probe/framework-probe.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2019 Ivan Komissarov +** Copyright (C) 2019 Ivan Komissarov (abbapoh@gmail.com) ** Contact: https://www.qt.io/licensing/ ** ** This file is part of Qbs. @@ -26,9 +26,8 @@ ****************************************************************************/ /*! - \contentspage list-of-probes.html \qmltype FrameworkProbe - \ingroup list-of-probes + \inqmlmodule QbsProbes \ingroup list-of-items \keyword QML.FrameworkProbe \inherits PathProbe diff --git a/doc/reference/items/probe/iar-probe.qdoc b/doc/reference/items/probe/iar-probe.qdoc index c300f82b7..387e70b89 100644 --- a/doc/reference/items/probe/iar-probe.qdoc +++ b/doc/reference/items/probe/iar-probe.qdoc @@ -25,9 +25,8 @@ ** ****************************************************************************/ /*! - \contentspage list-of-probes.html \qmltype IarProbe - \ingroup list-of-probes + \inqmlmodule QbsProbes \ingroup list-of-items \keyword QML.IarProbe \inherits PathProbe @@ -53,7 +52,10 @@ Detected architecture of the target platform's processor. - The possible values are \c "arm", \c "mcs51" and \c "avr". + The possible values are \c "arm", \c "mcs51", \c "avr", \c "avr32", + \c "stm8", \c "riscv", \c "rl78", \c "rx", \c "rh850", \c "v850", + \c "78k", \c "sh", \c "r32c", \c "m32c", \c "m16c", \c "msp430", + \c "hcs12", \c "hcs8", \c "m68k", and \c "cr16". \nodefaultvalue */ diff --git a/doc/reference/items/probe/include-probe.qdoc b/doc/reference/items/probe/include-probe.qdoc index f84df3f5f..eb8fcf8b9 100644 --- a/doc/reference/items/probe/include-probe.qdoc +++ b/doc/reference/items/probe/include-probe.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2019 Ivan Komissarov +** Copyright (C) 2019 Ivan Komissarov (abbapoh@gmail.com) ** Contact: https://www.qt.io/licensing/ ** ** This file is part of Qbs. @@ -26,9 +26,8 @@ ****************************************************************************/ /*! - \contentspage list-of-probes.html \qmltype IncludeProbe - \ingroup list-of-probes + \inqmlmodule QbsProbes \ingroup list-of-items \keyword QML.IncludeProbe \inherits PathProbe @@ -40,7 +39,6 @@ For example, IncludeProbe can be used to search for a zlib header as follows: \code - import qbs import qbs.Probes CppApplication { diff --git a/doc/reference/items/probe/keil-probe.qdoc b/doc/reference/items/probe/keil-probe.qdoc index f5aa07d83..b4b56e0aa 100644 --- a/doc/reference/items/probe/keil-probe.qdoc +++ b/doc/reference/items/probe/keil-probe.qdoc @@ -25,9 +25,8 @@ ** ****************************************************************************/ /*! - \contentspage list-of-probes.html \qmltype KeilProbe - \ingroup list-of-probes + \inqmlmodule QbsProbes \ingroup list-of-items \keyword QML.KeilProbe \inherits PathProbe @@ -53,7 +52,7 @@ Detected architecture of the target platform's processor. - The possible values are \c "arm" and \c "mcs51". + The possible values are \c "arm", \c "mcs51", \c "mcs251" and \c "c166". \nodefaultvalue */ diff --git a/doc/reference/items/probe/library-probe.qdoc b/doc/reference/items/probe/library-probe.qdoc new file mode 100644 index 000000000..458e3679d --- /dev/null +++ b/doc/reference/items/probe/library-probe.qdoc @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** Copyright (C) 2020 Ivan Komissarov (abbapoh@gmail.com) +** 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$ +** +****************************************************************************/ + +/*! + \qmltype LibraryProbe + \inqmlmodule QbsProbes + \ingroup list-of-items + \keyword QML.IncludeProbe + \inherits PathProbe + + \brief Locates library files outside the project. + + On Windows, searches for library files within directories specified by the \c PATH environment + variable. + + On Unix, searches for library files within directories specified by the \c LIBRARY_PATH + environment variable, as well as in \c "/usr/lib" and \c "/usr/local/lib". + + On Linux, also searches in platform-specific directories, such as \c "/usr/lib64" and + \c "/usr/lib/x86_64-linux-gnu". + + For example, LibraryProbe can be used to search for a \c zlib library as follows: + + \code + import qbs.Probes + + CppApplication { + Probes.LibraryProbe { + id: zlibProbe + names: "z" + } + cpp.libraryPaths: zlibProbe.found ? [zlibProbe.path] : [] + cpp.dynamicLibraries: zlibProbe.found ? [zlibProbe.names] : [] + files: 'main.cpp' + } + \endcode +*/ diff --git a/doc/reference/items/probe/path-probe.qdoc b/doc/reference/items/probe/path-probe.qdoc index eaaee9e54..729f11dde 100644 --- a/doc/reference/items/probe/path-probe.qdoc +++ b/doc/reference/items/probe/path-probe.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2018 Ivan Komissarov +** Copyright (C) 2018 Ivan Komissarov (abbapoh@gmail.com) ** Contact: https://www.qt.io/licensing/ ** ** This file is part of Qbs. @@ -25,9 +25,8 @@ ** ****************************************************************************/ /*! - \contentspage list-of-probes.html \qmltype PathProbe - \ingroup list-of-probes + \inqmlmodule QbsProbes \ingroup list-of-items \keyword QML.PathProbe @@ -37,10 +36,11 @@ locations. PathProbe takes as input lists of paths to search files from and file name patterns. The paths - are specified by using the searchPaths, platformSearchPaths, environmentPaths, and - platformEnvironmentPaths properties. The file name patterns are specified by the \l names and - nameSuffixes properties. Returns the first file that matches the file name patterns. If no such - file is found, the \l {Probe::found}{probe.found} property is set to \c false. + are specified by using the environmentPaths, searchPaths, platformEnvironmentPaths and + platformSearchPaths properties; the path are searched in the same order as listed. The file + name patterns are specified by the \l names and nameSuffixes properties. Returns the first file + that matches the file name patterns. If no such file is found, the + \l {Probe::found}{probe.found} property is set to \c false. For example, a simple PathProbe that searches for the stdio.h header can be used as follows: @@ -81,7 +81,7 @@ For example, when searching for a library, it might be necessary to check its architecture: \code PathProbe { - pathSuffixes: ["*.so", *.dll] + pathSuffixes: [".so", ".dll", ".dylib"] candidateFilter: { function getLibraryArchitecture(file) { ... } return function(file) { @@ -148,7 +148,7 @@ The list of environment variables that contains paths where to search files. Paths in the environment variable should be separated using - \l{qbs::pathListSeparator}{qbs.pathListSeparator}. + \l{pathListSeparator}{FileInfo.pathListSeparator()}. \nodefaultvalue */ @@ -158,7 +158,7 @@ The list of platform environment variables that contains paths where to search files. Paths in the environment variable should be separated using - \l{qbs::pathListSeparator}{qbs.pathListSeparator}. + \l{pathListSeparator}{FileInfo.pathListSeparator()}. \nodefaultvalue */ @@ -169,6 +169,24 @@ This property contains the result list of all paths that were checked before a file was found (including the file names). + This property is set even if the Probe didn't find anything and can be used to give the user + a hint what went wrong: + \code + Module { + Probes.BinaryProbe { + id: pythonProbe + names: "python" + } + validate: { + if (!pythonProbe.found) { + throw ModUtils.ModuleError( + "Could not find python binary at any of the following locations:\n\t" + + pythonProbe.candidatePaths.join("\n\t")); + } + } + } + \endcode + \nodefaultvalue */ diff --git a/doc/reference/items/probe/pkgconfig-probe.qdoc b/doc/reference/items/probe/pkgconfig-probe.qdoc index 7bdaf4e19..66e008601 100644 --- a/doc/reference/items/probe/pkgconfig-probe.qdoc +++ b/doc/reference/items/probe/pkgconfig-probe.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2019 Ivan Komissarov +** Copyright (C) 2019 Ivan Komissarov (abbapoh@gmail.com) ** Contact: https://www.qt.io/licensing/ ** ** This file is part of Qbs. @@ -26,9 +26,8 @@ ****************************************************************************/ /*! - \contentspage list-of-probes.html \qmltype PkgConfigProbe - \ingroup list-of-probes + \inqmlmodule QbsProbes \ingroup list-of-items \keyword QML.PkgConfigProbe @@ -52,8 +51,12 @@ maxVersion: '5.99.99' } files: 'main.cpp' - cpp.cxxFlags: pkgConfig.cflags - cpp.linkerFlags: pkgConfig.libs + cpp.defines : pkgConfig.defines + cpp.includePaths: pkgConfig.includePaths + cpp.dynamicLibraries: pkgConfig.libraries + cpp.libraryPaths: pkgConfig.libraryPaths + cpp.commonCompilerFlags: pkgConfig.compilerFlags + cpp.linkerFlags: pkgConfig.linkerFlags } \endcode */ @@ -111,7 +114,7 @@ \qmlproperty string PkgConfigProbe::exactVersion The exact version of the required package. If set, pkg-config will ignore packages with - version greater than the value of this property. + version that is not equal to the value of this property. \nodefaultvalue */ @@ -120,7 +123,7 @@ \qmlproperty string PkgConfigProbe::maxVersion The maximum version of the required package. If set, pkg-config will ignore packages with - version that is not equal to the value of this property. + version greater than the value of this property. \nodefaultvalue */ @@ -195,9 +198,6 @@ This output property contains the list of library paths that should be passed to a linker when using requested package. - This property sets the value of the PKG_CONFIG_LIBDIR environment variable passed to - the \c pkg-config binary. - \nodefaultvalue */ diff --git a/doc/reference/items/probe/sdcc-probe.qdoc b/doc/reference/items/probe/sdcc-probe.qdoc index 1353eb736..06cb06891 100644 --- a/doc/reference/items/probe/sdcc-probe.qdoc +++ b/doc/reference/items/probe/sdcc-probe.qdoc @@ -25,9 +25,8 @@ ** ****************************************************************************/ /*! - \contentspage list-of-probes.html \qmltype SdccProbe - \ingroup list-of-probes + \inqmlmodule QbsProbes \ingroup list-of-items \keyword QML.SdccProbe \inherits PathProbe @@ -53,7 +52,7 @@ Detected architecture of the target platform's processor. - The possible values are \c "mcs51". + The possible values are \c "mcs51", \c "stm8", and \c "hcs8". \nodefaultvalue */ diff --git a/doc/reference/items/probe/watcom-probe.qdoc b/doc/reference/items/probe/watcom-probe.qdoc new file mode 100644 index 000000000..8f06be974 --- /dev/null +++ b/doc/reference/items/probe/watcom-probe.qdoc @@ -0,0 +1,129 @@ +/**************************************************************************** +** +** Copyright (C) 2022 Denis Shienkov <denis.shienkov@gmail.com> +** 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$ +** +****************************************************************************/ + +/*! + \qmltype WatcomProbe + \inqmlmodule QbsProbes + \ingroup list-of-items + \keyword QML.WatcomProbe + \inherits PathProbe + \brief Collects Oopen Watcom toolchain compiler information. + \since Qbs 1.22 + \internal + + Detects the version, supported architecture, the platform + endianness, and other stuff for the specified compiler executable + from the \l{https://github.com/open-watcom}{Open Watcom} toolchain. +*/ + +/*! + \qmlproperty string WatcomProbe::compilerFilePath + + An input property which is a full path to the Digital Mars compiler + executable. + + \nodefaultvalue +*/ + +/*! + \qmlproperty string WatcomProbe::architecture + + Detected architecture of the target platform's processor. + + The possible values are \c "x86" and \c "x86_16". + + \nodefaultvalue +*/ + +/*! + \qmlproperty string WatcomProbe::endianness + + Detected endianness of the target platform's processor architecture. + + The possible values are \c "big" and \c "little". + + \nodefaultvalue +*/ + +/*! + \qmlproperty string WatcomProbe::targetPlatform + + Detected target platform. + + The possible values are \c "windows", \c "linux", \c "os2" and \c "dos". + + \nodefaultvalue +*/ + +/*! + \qmlproperty int WatcomProbe::versionMajor + + Detected major compiler version. + + \nodefaultvalue +*/ + +/*! + \qmlproperty int WatcomProbe::versionMinor + + Detected minor compiler version. + + \nodefaultvalue +*/ + +/*! + \qmlproperty int WatcomProbe::versionPatch + + Detected patch compiler version. + + \nodefaultvalue +*/ + +/*! + \qmlproperty stringList WatcomProbe::includePaths + + Detected compiler include paths. + + \nodefaultvalue +*/ + +/*! + \qmlproperty var WatcomProbe::compilerDefinesByLanguage + + Detected set of compiler pre-defined macros depending + on the \c "C" or \c "C++" language. + + \nodefaultvalue +*/ + +/*! + \qmlproperty var WatcomProbe::environment + + Detected compiler run environment. + + \nodefaultvalue +*/ diff --git a/doc/reference/jsextensions/jsextension-binaryfile.qdoc b/doc/reference/jsextensions/jsextension-binaryfile.qdoc index 59def1af4..c8c3bd4b1 100644 --- a/doc/reference/jsextensions/jsextension-binaryfile.qdoc +++ b/doc/reference/jsextensions/jsextension-binaryfile.qdoc @@ -28,7 +28,6 @@ ****************************************************************************/ /*! - \contentspage index.html \page jsextension-binaryfile.html \ingroup list-of-builtin-services diff --git a/doc/reference/jsextensions/jsextension-environment.qdoc b/doc/reference/jsextensions/jsextension-environment.qdoc index 8579ecee5..465a157a2 100644 --- a/doc/reference/jsextensions/jsextension-environment.qdoc +++ b/doc/reference/jsextensions/jsextension-environment.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \page jsextension-environment.html \ingroup list-of-builtin-services diff --git a/doc/reference/jsextensions/jsextension-file.qdoc b/doc/reference/jsextensions/jsextension-file.qdoc index c12fcc4ef..f04055593 100644 --- a/doc/reference/jsextensions/jsextension-file.qdoc +++ b/doc/reference/jsextensions/jsextension-file.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \page jsextension-file.html \ingroup list-of-builtin-services @@ -48,6 +47,9 @@ \note \c targetFilePath must be the counterpart of \c sourceFilePath at the new location, \b{not} the new parent directory. This allows the copy to have a different name and is true even if \c sourceFilePath is a directory. + \note The file is not copied if the source file timestamp is older than the destination file + timestamp. If you want to replace the newer file, you need to remove it first via + File.remove(). \section2 exists \code diff --git a/doc/reference/jsextensions/jsextension-fileinfo.qdoc b/doc/reference/jsextensions/jsextension-fileinfo.qdoc index 967606ea7..d58c1a9e9 100644 --- a/doc/reference/jsextensions/jsextension-fileinfo.qdoc +++ b/doc/reference/jsextensions/jsextension-fileinfo.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \page jsextension-fileinfo.html \ingroup list-of-builtin-services @@ -150,4 +149,26 @@ FileInfo.toWindowsSeparators(filePath: string): string \endcode Returns \c filePath with all '/' characters replaced by '\\'. + + \section2 pathListSeparator + \code + FileInfo.pathListSeparator(): string + \endcode + Returns the host operating system separator for a path list that is used in environment + variables or other contexts. + \funsince 1.22 + + \section2 pathSeparator + \code + FileInfo.pathSeparator(): string + \endcode + Returns the host operating system path separator. + \funsince 1.22 + + \section2 executableSuffix + \code + FileInfo.executableSuffix(): string + \endcode + Returns the host operating system executable suffix. + \funsince 1.23 */ diff --git a/doc/reference/jsextensions/jsextension-host.qdoc b/doc/reference/jsextensions/jsextension-host.qdoc new file mode 100644 index 000000000..c011e90eb --- /dev/null +++ b/doc/reference/jsextensions/jsextension-host.qdoc @@ -0,0 +1,139 @@ +/**************************************************************************** +** +** Copyright (C) 2022 Raphaël Cotty <raphael.cotty@gmail.com> +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page jsextension-host.html + \ingroup list-of-builtin-services + + \title Host Service + \brief Provides host information. + + The \c Host service offers various information about the host environment, such as operating + system names, platform name. + + \section1 Available Operations + + \section2 architecture + \code + Host.architecture(): string + \endcode + Returns the host operating system architecture. + + See \l{qbs::architecture}{qbs.architecture} for the target-specific equivalent property. + architecture. + \funsince 1.22 + + \section2 os + \code + Host.os(): string[] + \endcode + Returns the host operating system names. + + See the \l{qbs::targetOS}{qbs.targetOS} for the target-specific equivalent property. + \funsince 1.22 + + \section2 platform + \code + Host.platform(): string + \endcode + Returns the host operating system platform. + + See the \l{qbs::targetPlatform}{qbs.targetPlatform} for the target-specific equivalent property. + \funsince 1.22 + + + \section2 osVersion + \code + Host.osVersion(): string + \endcode + Returns 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". + \funsince 1.22 + + \section2 osBuildVersion + \code + Host.osBuildVersion(): string + \endcode + Returns the host operating system 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". + \funsince 1.22 + + \section2 osVersionParts + \code + Host.osVersionParts(): string[] + \endcode + Returns 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]. + \funsince 1.22 + + \section2 osVersionMajor + \code + Host.osVersionMajor(): number + \endcode + Returns the host operating system major version. + \funsince 1.22 + + \section2 osVersionMinor + \code + Host.osVersionMinor(): number + \endcode + Returns the host operating system minor version. + \funsince 1.22 + + \section2 osVersionPatch + \code + Host.osVersionPatch(): number + \endcode + Returns the host operating system patch level. + \funsince 1.22 + + \section2 nullDevice + \code + Host.nullDevice(): string[] + \endcode + Returns the platform-specific file path corresponding to the null device. + \funsince 1.22 +*/ diff --git a/doc/reference/jsextensions/jsextension-process.qdoc b/doc/reference/jsextensions/jsextension-process.qdoc index dd942ecff..49b47f4b2 100644 --- a/doc/reference/jsextensions/jsextension-process.qdoc +++ b/doc/reference/jsextensions/jsextension-process.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \page jsextension-process.html \ingroup list-of-builtin-services diff --git a/doc/reference/jsextensions/jsextension-propertylist.qdoc b/doc/reference/jsextensions/jsextension-propertylist.qdoc index 869873aec..e1dad6e38 100644 --- a/doc/reference/jsextensions/jsextension-propertylist.qdoc +++ b/doc/reference/jsextensions/jsextension-propertylist.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \page jsextension-propertylist.html \ingroup list-of-builtin-services diff --git a/doc/reference/jsextensions/jsextension-temporarydir.qdoc b/doc/reference/jsextensions/jsextension-temporarydir.qdoc index 750653143..29f62725d 100644 --- a/doc/reference/jsextensions/jsextension-temporarydir.qdoc +++ b/doc/reference/jsextensions/jsextension-temporarydir.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \page jsextension-temporarydir.html \ingroup list-of-builtin-services diff --git a/doc/reference/jsextensions/jsextension-textfile.qdoc b/doc/reference/jsextensions/jsextension-textfile.qdoc index 65758b3bd..b2cf2c729 100644 --- a/doc/reference/jsextensions/jsextension-textfile.qdoc +++ b/doc/reference/jsextensions/jsextension-textfile.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \page jsextension-textfile.html \ingroup list-of-builtin-services diff --git a/doc/reference/jsextensions/jsextension-utilities.qdoc b/doc/reference/jsextensions/jsextension-utilities.qdoc index 793581999..686e17a99 100644 --- a/doc/reference/jsextensions/jsextension-utilities.qdoc +++ b/doc/reference/jsextensions/jsextension-utilities.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \page jsextension-utilities.html \ingroup list-of-builtin-services diff --git a/doc/reference/jsextensions/jsextension-xml.qdoc b/doc/reference/jsextensions/jsextension-xml.qdoc index b5d3891ae..26e2e6de8 100644 --- a/doc/reference/jsextensions/jsextension-xml.qdoc +++ b/doc/reference/jsextensions/jsextension-xml.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \page jsextension-xml.html \ingroup list-of-builtin-services diff --git a/doc/reference/jsextensions/jsextensions-general.qdoc b/doc/reference/jsextensions/jsextensions-general.qdoc index 383f7b2bf..495e90f39 100644 --- a/doc/reference/jsextensions/jsextensions-general.qdoc +++ b/doc/reference/jsextensions/jsextensions-general.qdoc @@ -26,7 +26,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \page jsextensions-general.html \ingroup list-of-builtin-services @@ -58,12 +57,6 @@ \section1 Extensions to JavaScript Built-in Objects - \section2 Array.contains - \code - Array.contains(e: any): boolean - \endcode - Returns \c{true} if the array contains the element \c{e}. Returns \c{false} otherwise. - \section2 Array.containsAll \code Array.containsAll(other: any[]): boolean @@ -86,24 +79,6 @@ Duplicates that would originate from the concatenation are removed. The order of elements is preserved. - \section2 String.contains - \code - String.contains(s: string): boolean - \endcode - Returns \c{true} if the string contains the substring \c{s}. Returns \c{false} otherwise. - - \section2 startsWith - \code - String.startsWith(s: string): boolean - \endcode - Returns \c{true} if the string starts with the substring \c{s}. Returns \c{false} otherwise. - - \section2 endsWith - \code - String.endsWith(s: string): boolean - \endcode - Returns \c{true} if the string ends with the substring \c{s}. Returns \c{false} otherwise. - \section1 Console API diff --git a/doc/reference/module-providers/conan-module-provider.qdoc b/doc/reference/module-providers/conan-module-provider.qdoc new file mode 100644 index 000000000..4edba94d8 --- /dev/null +++ b/doc/reference/module-providers/conan-module-provider.qdoc @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** Copyright (C) 2024 Ivan Komissarov (abbapoh@gmail.com) +** 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$ +** +****************************************************************************/ + +/*! + \qmltype conan + \inqmlmodule QbsModuleProviders + \since 2.4 + + \brief Module provider for the Conan package manager. + + This module provider allows integration with the \l{https://conan.io}{Conan} package manager. + + \section1 Prerequisites + In order to use this provider, you will need to install the + \l{https://github.com/qbs/qbs/blob/master/src/conan/extensions/generators/qbsdeps.py}{QbsDeps generator} + first. In order to do so, clone the \QBS repository and run the following command from the \QBS + source directory: + \code + $ conan config install src/conan/ + \endcode + This will copy the generator to \c .conan2/extensions/generators/qbsdeps.py in the user's home + directory. + Alternatively, you can use \c curl to download the file: + \code + $ curl 'https://github.com/qbs/qbs/raw/master/src/conan/extensions/generators/qbsdeps.py' -o ~/.conan2/extensions/generators/qbsdeps.py + \endcode + + \section1 Example + For details on how to setup a project to use with Conan, see the \ + l{https://github.com/qbs/qbs/blob/master/examples/protobuf/addressbook_conan}{addressbook_conan} + folder in examples. + First, you will need a \l{https://docs.conan.io/2/reference/conanfile_txt.html}{conanfile} as + shown below. + \code + [requires] + protobuf/3.21.12 + [tool_requires] + protobuf/3.21.12 + [generators] + QbsDeps + \endcode + We use the text version for simplicity, but you can use the Python conanfile as well. + + Next, set the \l{Product::qbsModuleProviders}{qbsModuleProviders} property to \c "conan": + \snippet ../examples/protobuf/addressbook_conan/addressbook_conan.qbs 0 + + Install Conan dependencies and run the QbsDeps generator from the \c addressbook_conan dir: + \code + $ conan install . -g=QbsDeps --output-folder=build --build missing + \endcode + This will create the \c{./build/qbs-deps} directory contaning files for provider. Now you can + pass the conan install directory to the provider: + \code + $ qbs moduleProviders.conan.installDirectory:build + \endcode + You should see the following output if everything is correct: + \code + Build graph does not yet exist for configuration 'default'. Starting from scratch. + Resolving project for configuration default + Setting up Conan module 'protobuflib' + Setting up Conan module 'zlib' + ... + Build done for configuration default. + \endcode +*/ + +/*! + \qmlproperty string conan::installDirectory + + The path to the conan install installDirectory. + + \QBS searches for files created by the QbsDeps generator in that directory. + + If not set, the provider will not be run. + + \defaultvalue undefined +*/ diff --git a/doc/reference/module-providers/qbspkgconfig-module-provider.qdoc b/doc/reference/module-providers/qbspkgconfig-module-provider.qdoc new file mode 100644 index 000000000..a7f6fe6b7 --- /dev/null +++ b/doc/reference/module-providers/qbspkgconfig-module-provider.qdoc @@ -0,0 +1,133 @@ +/**************************************************************************** +** +** Copyright (C) 2021 Ivan Komissarov (abbapoh@gmail.com) +** 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$ +** +****************************************************************************/ + +/*! + \qmltype qbspkgconfig + \inqmlmodule QbsModuleProviders + \since 1.20 + + \brief Module provider based on the qbspkg-config library. + + \QBS uses a built-in parser of the \c{*.pc} files and does not require the presence of the + \c pkg-config tool in the system. However, if the \c pkg-config tool is present, \QBS will + use the same libDirs as the system pkg-config uses by default; otherwise, a built-in list of + paths is used. + + In order to enable usage of this provider in your Product, set the + \l{Product::qbsModuleProviders}{qbsModuleProviders} property as shown in the example below: + \snippet ../examples/pkgconfig-provider/pkgconfig-provider.qbs 0 +*/ + +/*! + \qmlproperty string qbspkgconfig::executableFilePath + + The path to the \c {pkg-config} executable. If not set, the pkg-config from PATH is used. + + \defaultvalue undefined +*/ + +/*! + \qmlproperty stringList qbspkgconfig::libDirs + + Set this if you need to overwrite the default search directories. + \note You do not need to set this for cross-compilation in order to point + to the sysroot. \QBS does that for you. + + This property is the equivalent of the \c{PKG_CONFIG_LIBDIR} variable + for the \c{pkg-config} tool. + + \nodefaultvalue +*/ + +/*! + \qmlproperty stringList qbspkgconfig::extraPaths + + Set this if you need to add extra search directories. + + This property is the equivalent of the \c{PKG_CONFIG_PATH} variable + for the \c{pkg-config} tool. + + \nodefaultvalue +*/ + +/*! + \qmlproperty bool qbspkgconfig::staticMode + + If this property is \c true, then \QBS will include "private" libs and dependencies of the + package. This property is the equivalent of the + \c{--static} option for the \c{pkg-config} tool. + + Set this if your product is to be linked statically. + + \defaultvalue \c false +*/ + +/*! + \qmlproperty bool qbspkgconfig::definePrefix + + If this property is \c true, then \QBS will override the ${prefix} variable in the packages + with a value that is guessed based on the location of the .pc file. + + This option corresponds to the \c --define-prefix / \c --dont-define-prefix command line + options of the \c pkg-config tool. + + \defaultvalue \c true on Windows, \c false otherwise +*/ + +/*! + \qmlproperty stringList qbspkgconfig::executableNames + + The names of the \c pkg-config executable to search for. + + Note that since newer distributions use \l{http://pkgconf.org}{pkgconf} by default, it has + higher priority over \c pkg-config. + + \defaultvalue \c{["pkgconf", "pkg-config"]} +*/ + +/*! + \qmlproperty path qbspkgconfig::sysroot + + Set this property if you need to overwrite the default search sysroot path used by + \c pkg-config. + + This can be useful if \c pkg-config files are located in the directory other than qbs.sysroot. + This is the case on macOS platform - all XCode profiles are sysrooted to the SDK + directory, but \c pkg-config is typically intalled using Brew and resides in the + \c /usr/local directory. + + Setting this property to \c undefined or empty (\c "") value will use pkg-config's default + search paths: + \code + qbs resolve moduleProviders.qbspkgconfig.sysroot:undefined + \endcode + + This property is the equivalent of the \c{PKG_CONFIG_SYSROOT_DIR} variable for the + \c{pkg-config} tool. + + \defaultvalue \c "" on macOS, \c qbs.sysroot on other platforms +*/ diff --git a/doc/reference/module-providers/qt-module-provider.qdoc b/doc/reference/module-providers/qt-module-provider.qdoc new file mode 100644 index 000000000..cd77a0d12 --- /dev/null +++ b/doc/reference/module-providers/qt-module-provider.qdoc @@ -0,0 +1,76 @@ +/**************************************************************************** +** +** Copyright (C) 2021 Ivan Komissarov (abbapoh@gmail.com) +** 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$ +** +****************************************************************************/ + +/*! + \qmltype Qt + \inqmlmodule QbsModuleProviders + + \brief Module provider that generates Qt modules. + + Looking up a Qt installation happens via a \l{Module Providers}{module provider}. + By default, if a dependency to a Qt module is encountered, \QBS collects all Qt installations + it can find. This lookup happens by searching for \c qmake executables in the \c PATH + environment variable. Alternatively, you can explicitly tell \QBS which Qt + installations it should consider by setting the qmakeFilePaths + module provider \l{Parameterizing Module Providers}{property}. In that case, + the environment will be ignored. For instance, with the following Linux command line, + \QBS will build the project against a custom Qt instead of the standard one in \c{/usr/bin}: + \code + $ qbs moduleProviders.Qt.qmakeFilePaths:/opt/myqt/bin/qmake + \endcode + You can also set the module provider property in a profile. The simplest way to do + this is via the \l setup-qt tool. For examples of how to use this tool, see the + \l{Managing Qt Versions} section. + + This provider is activated automatically when encountering a dependency on the Qt + module and the \l{Product::qbsModuleProviders}{qbsModuleProviders} property + is \c undefined: + \code + CppApplication { + Depends { name: "Qt.core" } + files: "main.cpp" + } + \endcode + + Alternatively, you can activate this provider explicitly via the + \l{Product::qbsModuleProviders}{qbsModuleProviders} property: + \code + CppApplication { + Depends { name: "Qt.core" } + files: "main.cpp" + qbsModuleProviders: "Qt" + } + \endcode +*/ + +/*! + \qmlproperty stringList Qt::qmakeFilePaths + + List of paths to \c qmake executables. + + \defaultvalue undefined +*/ diff --git a/doc/reference/modules/android-ndk-module.qdoc b/doc/reference/modules/android-ndk-module.qdoc index e3a7ca22d..d3b16e2bf 100644 --- a/doc/reference/modules/android-ndk-module.qdoc +++ b/doc/reference/modules/android-ndk-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Android.ndk \inqmlmodule QbsModules \since Qbs 1.4 @@ -79,6 +78,17 @@ */ /*! + \qmlproperty string Android.ndk::buildId + + Value to pass to the --build-id linker flag. + Plain --build-id option is used when buildId property is empty. + + \since Qbs 1.21 + + \defaultvalue \c "sha1" +*/ + +/*! \qmlproperty string Android.ndk::appStl The library to use for C++. The possible values are: diff --git a/doc/reference/modules/android-sdk-module.qdoc b/doc/reference/modules/android-sdk-module.qdoc index 7733ae75d..ce27b6302 100644 --- a/doc/reference/modules/android-sdk-module.qdoc +++ b/doc/reference/modules/android-sdk-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Android.sdk \inqmlmodule QbsModules \since Qbs 1.4 @@ -119,7 +118,7 @@ */ /*! - \qmlproperty string Android.sdk::assetsDir + \qmlproperty path Android.sdk::assetsDir The base directory for Android assets in the respective product. @@ -201,7 +200,7 @@ */ /*! - \qmlproperty string Android.sdk::resourcesDir + \qmlproperty path Android.sdk::resourcesDir The base directory for Android resources in the respective product. @@ -233,3 +232,49 @@ \qmlproperty stringList Android.sdk::aidlSearchPaths Search paths for import statements to pass to the \c aidl tool via the \c{-I} option. */ + +/*! + \qmlproperty string Android.sdk::aaptName + \since Qbs 1.17 + + Name of the aapt binary. Allowed options: "aapt" and "aapt2". + + \defaultvalue \c "aapt2" +*/ + +/*! + \qmlproperty string Android.sdk::packageType + \since Qbs 1.17 + + Type of the package. Allowed options: "apk" and "aab". + Type "apk" generates a runnable package whereas "aab" generates a package for Google Play. + + \defaultvalue \c "apk" +*/ + +/*! + \qmlproperty string Android.sdk::dexCompilerName + \since Qbs 1.20 + + Name of the dex compiler binary. Allowed options: "dx" and "d8". + + \defaultvalue \c "d8" +*/ + +/*! + \qmlproperty string Android.sdk::minimumVersion + \since Qbs 1.17 + + Minimum API Level required for the application to run. + + \defaultvalue \c "21" +*/ + +/*! + \qmlproperty string Android.sdk::targetVersion + \since Qbs 1.17 + + API Level that the application targets. + + \defaultvalue \c platformVersion +*/ diff --git a/doc/reference/modules/archiver-module.qdoc b/doc/reference/modules/archiver-module.qdoc index 8bec4993d..9a6c59ba3 100644 --- a/doc/reference/modules/archiver-module.qdoc +++ b/doc/reference/modules/archiver-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype archiver \inqmlmodule QbsModules \since Qbs 1.4 diff --git a/doc/reference/modules/asan-module.qdoc b/doc/reference/modules/asan-module.qdoc new file mode 100644 index 000000000..6f6ee66c0 --- /dev/null +++ b/doc/reference/modules/asan-module.qdoc @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** Copyright (C) 2022 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$ +** +****************************************************************************/ + +/*! + \qmltype Sanitizers.address + \inqmlmodule QbsModules + \brief Provides AddressSanitizer support. + + Provides support for the \l{https://clang.llvm.org/docs/AddressSanitizer.html}{AddressSanitizer} + tool, which uses compiler instrumentation to detect memory corruption bugs at runtime. +*/ + + +/*! + \qmlproperty string Sanitizers.address::detectUseAfterReturn + + Controls whether support for detecting problems with stack use after returning + from a function should be built into the application. + + The possible values are: + \list + \li \c "always": Check for this type of problem unconditionally. + \li \c "runtime": Build with this capability, but only do the respective checks if they + are explicitly requested at runtime. + \li \c "never": Do not build with support for this check. + \endlist + + \note Only the clang compiler (starting at 13.0) supports the full set of values. + With GCC and MSVC, "runtime" maps to "always". + + \defaultvalue \c "always" +*/ + +/*! + \qmlproperty bool Sanitizers.address::detectUseAfterScope + + Controls whether to detect bugs relating the use of variables after they've gone out of scope. + + \note This property has no effect when building with with GCC and MSVC. + + \defaultvalue \c true +*/ + +/*! + \qmlproperty bool Sanitizers.address::enabled + + Controls whether to enable AddressSanitizer. + + \note You do not need to check if the current toolchain supports AddressSanitizer: + If \QBS detects that it doesn't, this property has no effect. + + \defaultvalue \c true +*/ diff --git a/doc/reference/modules/autotest-module.qdoc b/doc/reference/modules/autotest-module.qdoc index ddd9e0078..730f2c3bf 100644 --- a/doc/reference/modules/autotest-module.qdoc +++ b/doc/reference/modules/autotest-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype autotest \inqmlmodule QbsModules \since Qbs 1.13 @@ -67,3 +66,14 @@ \nodefaultvalue */ +/*! + \qmlproperty int autotest::timeout + + The time limit for the execution of the autotest. If not specified, the + \l{AutotestRunner::timeout}{timeout} property of the \l AutotestRunner + that invokes the autotest is used. + + \nodefaultvalue + \since Qbs 1.15 +*/ + diff --git a/doc/reference/modules/bundle-module.qdoc b/doc/reference/modules/bundle-module.qdoc index ec0e1083d..fe9bf1354 100644 --- a/doc/reference/modules/bundle-module.qdoc +++ b/doc/reference/modules/bundle-module.qdoc @@ -27,7 +27,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype bundle \inqmlmodule QbsModules \since Qbs 1.4 @@ -97,8 +96,9 @@ A prefix for the product's bundle identifier. If \l{bundle::}{identifier} is left unset, the bundle identifier will be a concatenation of this value - and the \l{bundle::}{identifier} property, separated by a period (.). This - corresponds to the organization identifier in Xcode. + and the \l{Product::targetName}{Product.targetName} property formatted as + an RFC-1034 identifier, separated by a period (.). This corresponds to the + organization identifier in Xcode. \defaultvalue \c{org.example} */ @@ -107,8 +107,9 @@ \qmlproperty string bundle::identifier The bundle's identifier. If left unset, the bundle identifier will be a - concatenation of this value and the \l{bundle::}{identifierPrefix} property, - separated by a period (.). + concatenation of the \l{bundle::}{identifierPrefix} value and the + \l{Product::targetName}{Product.targetName} propertyy formatted as an + RFC-1034 identifier, separated by a period (.). \defaultvalue A combination of \l{bundle::}{identifierPrefix} and the product's target name formatted as an RFC-1034 identifier. @@ -205,7 +206,7 @@ */ /*! - \qmlproperty bool bundle::resources + \qmlproperty pathList bundle::resources A list of resources to copy to a bundle's \c Resources subdirectory. Files will automatically be copied into \c lproj subdirectories corresponding to @@ -464,6 +465,17 @@ */ /*! + \qmlproperty bool bundle::useBuiltinXcodeBuildSpecs + + Set this property to \c true to use Xcode \c .xcspec files shipped with \QBS. + + This property can be used as a workaround when using a new Xcode version that is not supported + by \QBS yet. + + \default false +*/ + +/*! \qmlproperty string bundle::versionsFolderPath \readonly \since Qbs 1.5 diff --git a/doc/reference/modules/capnprotocpp-module.qdoc b/doc/reference/modules/capnprotocpp-module.qdoc new file mode 100644 index 000000000..7635edd9e --- /dev/null +++ b/doc/reference/modules/capnprotocpp-module.qdoc @@ -0,0 +1,123 @@ +/**************************************************************************** +** +** Copyright (C) 2020 Ivan Komissarov (abbapoh@gmail.com) +** 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$ +** +****************************************************************************/ + +/*! + \qmltype capnproto.cpp + \inqmlmodule QbsModules + \since Qbs 1.17 + + \brief Provides support for Cap'n Proto for the C++ language. + + The \c capnproto.cpp module provides support for generating C++ headers + and sources from proto definition files using the \c capnpc tool. + + A simple qbs file that uses Cap'n Proto can be written as follows: + \code + CppApplication { + Depends { name: "capnproto.cpp" } + files: ["foo.capnp", "main.cpp"] + } + \endcode + A generated header now can be included in the C++ sources: + \code + #include <foo.capnp.h> + + int main(int argc, char* argv[]) { + ::capnp::MallocMessageBuilder message; + + auto foo = message.initRoot<Foo>(); + foo.setAnswer(42); + return 0; + } + \endcode + + \section2 Relevant File Tags + + \table + \header + \li Tag + \li Auto-tagged File Names + \li Since + \li Description + \row + \li \c{"capnproto.input"} + \li \c{*.capnp} + \li 1.17.0 + \li Source files with this tag are considered inputs to the \c capnpc compiler. + \endtable + + \section2 Dependencies + This module depends on the \c capnp module and on the \c capnp-rpc module if + \l{capnproto.cpp::useRpc}{useRpc} property is \c true. These modules are created by the + \l{Module Providers} via the \c pkg-config tool. +*/ + +/*! + \qmlproperty string capnproto.cpp::compilerName + + The name of the capnp binary. + + \defaultvalue \c "capnpc" +*/ + +/*! + \qmlproperty string capnproto.cpp::compilerPath + + The path to the protoc binary. + + Use this property to override the auto-detected location. + + \defaultvalue \c auto-detected +*/ + +/*! + \qmlproperty pathList capnproto.cpp::importPaths + + The list of import paths that are passed to the \c capnpc tool via the \c --import-path option. + + \defaultvalue \c [] +*/ + +/*! + \qmlproperty string capnproto.cpp::outputDir + + The directory where the \c capnpc compiler generated files are placed. + + \defaultvalue \c product.buildDirectory + "/capnp" +*/ + +/*! + \qmlproperty bool capnproto.cpp::useRpc + + Use this property to enable support for the RPC framework. + + A simple qbs file that uses rpc can be written as follows: + + \quotefile ../examples/capnproto/calculator_cpp/calculator_cpp.qbs + + \defaultvalue \c false +*/ diff --git a/doc/reference/modules/codesign-module.qdoc b/doc/reference/modules/codesign-module.qdoc new file mode 100644 index 000000000..45e247a6a --- /dev/null +++ b/doc/reference/modules/codesign-module.qdoc @@ -0,0 +1,395 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Copyright (C) 2021 Ivan Komissarov (abbapoh@gmail.com) +** 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$ +** +****************************************************************************/ + +/*! + \qmltype codesign + \inqmlmodule QbsModules + \since Qbs 1.19 + + \brief Provides code signing support. + + The \c codesign module contains properties and rules for code signing on Apple and Android + platforms. + + \section2 Relevant File Tags + + \table + \header + \li Tag + \li Auto-tagged File Names + \li Since + \li Description + \row + \li \c{"codesign.entitlements"} + \li \c{*.entitlements} + \li 1.19.0 + \li \l{https://developer.apple.com/documentation/bundleresources/entitlements}{Xcode entitlements} + \row + \li \c{"codesign.provisioningprofile"} + \li \c{*.mobileprovision, *.provisionprofile} + \li 1.19.0 + \li Xcode provisioning profiles + \row + \li \c{"codesign.signed_artifact"} + \li n/a + \li 1.19.0 + \li This tag is attached to all signed artifacts such as applications or libraries + \endtable +*/ + +/*! + \qmlproperty string codesign::signingTimestamp + + URL of the timestamp authority RFC 3161 server to be contacted to authenticate code signing. + \c undefined or \c empty indicates that a system-specific default should be used; + \c{"none"} explicitly disables the use of timestamp services on Apple platforms. + + \since Qbs 1.19 + + \defaultvalue \c "none" on Apple, \c undefined otherwise +*/ + +/*! + \qmlproperty stringList codesign::codesignFlags + + Additional flags passed to the \c{codesign} tool. + + \since Qbs 1.19 + + \nodefaultvalue +*/ + +/*! + \qmlproperty string codesign::codesignName + + The name of the \c{codesign} binary. + + \since Qbs 1.19 + + \defaultvalue Determined automatically +*/ + +/*! + \qmlproperty string codesign::codesignPath + + Path to the \c{codesign} tool. + + \since Qbs 1.19 + + \defaultvalue Determined automatically +*/ + +/*! + \qmlproperty bool codesign::enableCodeSigning + + Whether to actually perform code signing. + + \since Qbs 1.19 + + \defaultvalue \c false +*/ + +/*! + \qmlproperty string codesign::provisioningProfile + + Name or UUID of the provisioning profile to embed in the product. + Typically this should be left blank to allow \QBS to use automatic provisioning. + + \since Qbs 1.19 + + \defaultvalue \c undefined + + \appleproperty +*/ + +/*! + \qmlproperty path codesign::provisioningProfilesPath + + Path to directory containing provisioning profiles installed on the system. + This should not normally need to be changed. + + \since Qbs 1.19 + + \defaultvalue \c{"~/Library/MobileDevice/Provisioning Profiles"} + + \appleproperty +*/ + +/*! + \qmlproperty string codesign::signingIdentity + + Search string used to find the certificate to sign the product. This does not have to be + a full certificate name like "Mac Developer: John Doe (XXXXXXXXXX)", and can instead be + a partial string like "Mac Developer" or the certificate's SHA1 fingerprint. + The search string should generally be one of the following: + \list + \li 3rd Party Mac Developer Application + \li 3rd Party Mac Developer Installer + \li Developer ID Application + \li Developer ID Installer + \li iPhone Developer + \li iPhone Distribution + \li Mac Developer + \endlist + + It is also possible to use the special \c "-" value to use the ad-hoc signing. + + See \l{https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingCertificates/MaintainingCertificates.html#//apple_ref/doc/uid/TP40012582-CH31-SW41}{Maintaining Your Signing Identities and Certificates} + for complete documentation on the existing certificate types. + In general you should use \l{codesign::signingType}{signingType} instead. + + \since Qbs 1.19 + + \defaultvalue Determined by \l{codesign::signingType}{signingType} + + \appleproperty +*/ + +/*! + \qmlproperty string codesign::signingType + + Type of code signing to use. This should generally be used in preference to an explicit + signing identity like "Mac Developer: John Doe (XXXXXXXXXX)" since it is not user + specific and can be set in a project file. + Possible values include: \c{"app-store"}, \c{"apple-id"}, \c{"ad-hoc"}, which sign for + the App Store or Mac App Store, Developer ID, and Ad-hoc code signing, respectively. + + \section1 Relation between the signingType and signingIdentity + + The following table shows how the signingIdentity's default value is calculated. + + \table + \header + \li \c qbs.targetOS + \li \c codesign.signingType + \li \c qbs.buildVariant + \li \c codesign.signingIdentity + \row + \li {1, 4} \c "macos" + \li \c "ad-hoc" + \li any + \li \c "-" + \row + \li {1, 2} \c "app-store" + \li \c "debug", \c "profiling" + \li \c "Mac Developer" + \row + \li \c "release" + \li \c "3rd Party Mac Developer Application" + \row + \li \c "apple-id" + \li any + \li \c "Developer ID Application" + \row + \li {1, 2} \c "ios", \c "tvos", \c "watchos" + \li {1, 2} \c "app-store" + \li \c "debug", \c "profiling" + \li \c "iPhone Developer" + \row + \li \c "release" + \li \c "iPhone Distribution" + \endtable + + \since Qbs 1.19 + + \defaultvalue Determined automatically + + \appleproperty +*/ + +/*! + \qmlproperty string codesign::teamIdentifier + + Human readable name or 10-digit identifier of the Apple development team that the + signing identity belongs to. This is used to disambiguate between multiple certificates + of the same type in different teams. Typically this can be left blank if the development + machine is only signed in to a single development team, and should be set in a profile + otherwise. + + \since Qbs 1.19 + + \defaultvalue \c undefined + + \appleproperty +*/ + +/*! + \qmlproperty bool codesign::useApksigner + + If \c true, the package is signed using apksignerFilePath binary. + Set this property to \c false to use the jarsignerFilePath one. + Set by the Android.sdk module. + + \since Qbs 1.19 + + \defaultvalue \c true + + \androidproperty +*/ + +/*! + \qmlproperty string codesign::keystorePath + + The absolute path to the keystore file. + + \since Qbs 1.19 + + \defaultvalue \c "${HOME}/.android/debug.keystore" + + \androidproperty +*/ + +/*! + \qmlproperty string codesign::keystorePassword + + The keystore password. + + \since Qbs 1.19 + + \defaultvalue \c "android" + + \androidproperty +*/ + +/*! + \qmlproperty string codesign::keyPassword + + The key password. + + \since Qbs 1.19 + + \defaultvalue \c "android" + + \androidproperty +*/ + +/*! + \qmlproperty string codesign::keyAlias + + The key alias. + + \since Qbs 1.19 + + \defaultvalue \c "androiddebugkey" + + \androidproperty +*/ + +/*! + \qmlproperty string codesign::subjectName + + Specifies the name of the subject of the signing certificate. + This value can be a substring of the entire subject name. + + \since Qbs 1.19 + + \defaultvalue \c undefined + + \windowsproperty +*/ + +/*! + \qmlproperty string codesign::rootSubjectName + + Specifies the name of the subject of the root certificate that + the signing certificate must chain to. This value may be a substring + of the entire subject name of the root certificate. + + \since Qbs 1.19 + + \defaultvalue \c undefined + + \windowsproperty +*/ + +/*! + \qmlproperty string codesign::hashAlgorithm + + Specifies the default hash algorithm used on the signing certificate. + The possible values are \c sha1, \c sha256, \c sha384, and \c sha512. + + \note Only available in Windows 10 kit builds 20236 and later. + + \since Qbs 1.19 + + \defaultvalue \c undefined + + \windowsproperty +*/ + +/*! + \qmlproperty string codesign::timestampAlgorithm + + Specifies the default timestamp algorithm used together with the + \c signingTimestamp property. The possible values are \c sha1, \c sha256. + + \note If this value is not set, then the default sha1 algorithm + will be used. + + \since Qbs 1.19.2 + + \defaultvalue \c undefined + + \windowsproperty +*/ + +/*! + \qmlproperty string codesign::certificatePath + + Specifies the full path to the signing certificate file (*.pfx). + + \since Qbs 1.19 + + \defaultvalue \c undefined + + \windowsproperty +*/ + +/*! + \qmlproperty string codesign::certificatePassword + + Specifies the password to use when opening a signing certificate file (*.pfx). + + \since Qbs 1.19 + + \defaultvalue \c undefined + + \windowsproperty +*/ + +/*! + \qmlproperty string codesign::crossCertificatePath + + Specifies the full path to the additional certificate file (*.cer). + + \since Qbs 1.19 + + \defaultvalue \c undefined + + \windowsproperty +*/ diff --git a/doc/reference/modules/cpp-module.qdoc b/doc/reference/modules/cpp-module.qdoc index 19575a0f8..2b344aac2 100644 --- a/doc/reference/modules/cpp-module.qdoc +++ b/doc/reference/modules/cpp-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype cpp \inqmlmodule QbsModules \since Qbs 1.0 @@ -81,6 +80,7 @@ May contain the values: "weak", "lazy", "reexport", and "upward"; refer to the Apple ld64 man page for full details. \c{undefined} uses normal linking. Currently only applies when linking for Apple platforms. + Note that \c "lazy" mode is deprecated and doesn't work with Xcode 15 and above. \endtable \section2 Relevant File Tags @@ -144,6 +144,14 @@ and Objective-C++, respectively. There can be only one such file per product and language. \row + \li \c{"def"} + \li - + \li 1.17.0 + \li This tag is used for a module-definition file (.def) to be passed to the linker. + Such a file provides the linker with information about exports, attributes, + and other information about the program to be linked. This file tag only has + an effect with the MSVC toolchain. + \row \li \c{"dynamiclibrary"} \li n/a \li 1.0.1 @@ -357,6 +365,15 @@ */ /*! + \qmlproperty bool cpp::createSymlinks + \unixproperty + + Whether to create version alias symlinks when building a dynamic library. + + \defaultvalue \c true +*/ + +/*! \qmlproperty bool cpp::discardUnusedData \since Qbs 1.10 @@ -390,6 +407,8 @@ \defaultvalue \c{true} for MSVC and with GCC or Clang on Apple platforms, otherwise \c{false}. + + \sa debugInformation, {How do I separate and install debugging symbols?} */ /*! @@ -506,6 +525,132 @@ */ /*! + \qmlproperty string cpp::executablePrefix + + A string to prepend to the executable file \l{Product::targetName}{name}. + + \defaultvalue \c "" +*/ + +/*! + \qmlproperty string cpp::dynamicLibraryPrefix + + A string to prepend to the dynamic library file \l{Product::targetName}{name}. + + \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c "" or \c "lib" +*/ + +/*! + \qmlproperty string cpp::loadableModulePrefix + \appleproperty + + A string to prepend to the Darwin loadable module file \l{Product::targetName}{name}. + + \defaultvalue \c "" +*/ + +/*! + \qmlproperty string cpp::staticLibraryPrefix + + A string to prepend to the static library file \l{Product::targetName}{name}. + + \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c "" or \c "lib" +*/ + +/*! + \qmlproperty string cpp::executableSuffix + + A string to append to the executable file \l{Product::targetName}{name}. + + \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c "" or \c ".exe" +*/ + +/*! + \qmlproperty string cpp::dynamicLibrarySuffix + + A string to append to the dynamic library file \l{Product::targetName}{name}. + + \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c ".so", \c ".dll" + or \c "dylib" +*/ + +/*! + \qmlproperty string cpp::dynamicLibraryImportSuffix + \windowsproperty + + A string to append to the dynamic library import file \l{Product::targetName}{name}. + + \defaultvalue \c ".lib" +*/ + +/*! + \qmlproperty string cpp::loadableModuleSuffix + \appleproperty + + A string to append to the Darwin loadable module file \l{Product::targetName}{name}. + + \defaultvalue \c ".bundle" +*/ + +/*! + \qmlproperty string cpp::staticLibrarySuffix + + A string to append to the executable file \l{Product::targetName}{name}. + + \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c ".a" or \c ".lib" +*/ + +/*! + \qmlproperty string cpp::debugInfoSuffix + + A string to append to the debug information file name. + + \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c ".debug", + \c ".pdb" or \c ".dwarf" +*/ + +/*! + \qmlproperty string cpp::debugInfoBundleSuffix + \appleproperty + + A string to append to the debug information bundle name. + + \defaultvalue \c ".dSYM" +*/ + +/*! + \qmlproperty string cpp::objectSuffix + + A string to append to the generated object files. + + \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c ".o" or \c ".obj" +*/ + +/*! + \qmlproperty string cpp::linkerMapSuffix + + A string to append to the generated linker memory map files. + + \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical value is \c ".map" +*/ + +/*! + \qmlproperty string cpp::compilerListingSuffix + + A string to append to the generated compiler listing files. + + \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical value is \c ".lst" +*/ + +/*! + \qmlproperty string cpp::assemblerListingSuffix + + A string to append to the generated assembler listing files. + + \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical value is \c ".lst" +*/ + +/*! \qmlproperty pathList cpp::prefixHeaders \since Qbs 1.0.1 @@ -613,6 +758,15 @@ */ /*! + \qmlproperty string cpp::compilerVersion + + Compiler version string consisting of major, minor and patch numbers, + separated by a dot. + + \nodefaultvalue +*/ + +/*! \qmlproperty int cpp::compilerVersionMajor \since Qbs 1.4 @@ -684,7 +838,7 @@ If the value is left undefined, the compiler default will be used. If the list contains more than one value, the highest version is chosen. - Possible values include: \c{"c89"}, \c{"c99"}, \c{"c11"}. + Possible values include: \c{"c89"}, \c{"c99"}, \c{"c11"}, \c{"c17"}, \c{"c2x"}. \nodefaultvalue */ @@ -701,7 +855,8 @@ If the value is left undefined, the compiler default will be used. If the list contains more than one value, the highest version is chosen. - Possible values include: \c{"c++98"}, \c{"c++11"}, \c{"c++14"}, \c{"c++17"}. + Possible values include: \c{"c++98"}, \c{"c++11"}, \c{"c++14"}, \c{"c++17"}, \c{"c++20"}, + \c{"c++23"}. \nodefaultvalue */ @@ -915,9 +1070,9 @@ If this property is set to \c{undefined}, the default runtime library of the toolchain is used. - \note This property is only functional for MSVC. + \note This property is only functional for MSVC and MinGW. - \defaultvalue \c{"dynamic"} for MSVC, \c{undefined} for other compilers. + \defaultvalue \c{"dynamic"} for MSVC and MinGW, \c{undefined} for other compilers. */ /*! @@ -930,6 +1085,15 @@ */ /*! + \qmlproperty bool cpp::enableSuspiciousLinkerFlagWarnings + \since Qbs 1.8 + + Whether to print warnings about escaped linker flags (such as \c -Xlinker and \c -Wl). + + \defaultvalue \c{true} +*/ + +/*! \qmlproperty string cpp::exceptionHandlingModel \since Qbs 1.5 @@ -1217,8 +1381,6 @@ \qmlproperty string cpp::linkerMode \since Qbs 1.6 - \unixproperty - Controls whether to automatically use an appropriate compiler frontend instead of the system linker when linking binaries. @@ -1237,12 +1399,25 @@ \qmlproperty string cpp::linkerVariant \since Qbs 1.13 - \unixproperty + Set this property to force the use of a specific linker. A non-empty value + will result in the \c {-fuse-ld} option being emitted when linking with \c gcc, + \c clang or \c clang-cl. Other toolchains do not support this property. + + The possible values for \c clang and \c gcc are \c "bfd", \c "gold", \c "lld" + and \c "mold", the possible values for \c clang-cl are \c "link" and \c "lld". - Set this property to force the use of a specific \c ld implementation. A non-empty value - will result in the \c {-fuse-ld} option being emitted when linking with \c gcc or \c clang. + The following example demonstrates how to change the linker for different toolchains: - The possible values are \c "bfd", \c "gold" and \c "lld". + \code + Properties { + condition: qbs.toolchain.includes("gcc") + cpp.linkerVariant: "gold" + } + Properties { + condition: qbs.toolchain.includes("clang-cl") + cpp.linkerVariant: "lld" + } + \endcode \nodefaultvalue */ @@ -1353,6 +1528,8 @@ \l{cpp::}{systemRunPaths} are ignored. \nodefaultvalue + + \sa{How do I make use of rpaths?} */ /*! @@ -1389,6 +1566,8 @@ install names. \nodefaultvalue + + \sa{How do I make use of rpaths?} */ /*! @@ -1428,6 +1607,16 @@ */ /*! + \qmlproperty string cpp::rpathLinkFlag + \since Qbs 1.9 + + The rpath link flag used by the linker. + + \defaultvalue \l{qbs::toolchain}{toolchain}-dependent, typical values are \c "-rpath-link=" + or \c "-L" +*/ + +/*! \qmlproperty string cpp::variantSuffix \since Qbs 1.10 @@ -1702,9 +1891,7 @@ \qmlproperty bool cpp::generateCompilerListingFiles \since Qbs 1.15 - \baremetalproperty - - Whether to auto-generate a compiler listing files. + Whether to auto-generate compiler listing files. \defaultvalue \c{false} */ @@ -1729,3 +1916,28 @@ \defaultvalue \c{true} */ + +/*! + \qmlproperty string cpp::windowsSdkVersion + \since Qbs 1.19 + + Which Windows SDK version should be used with MSVC toolchain. By default, + the latest SDK is used. + + \windowsproperty + \nodefaultvalue +*/ + +/*! + \qmlproperty string cpp::enableCxxLanguageMacro + \since Qbs 1.20 + + Whether to set the \c{/Zc:__cplusplus} macro + (\l{https://docs.microsoft.com/en-us/cpp/build/reference/zc-cplusplus}) + + This property only applies to MSVC toolchain. clang-cl also supports + this option, but it has no effect. + + \windowsproperty + \defaultvalue \c{true} for MSVC, \c{false} for clang-cl +*/ diff --git a/doc/reference/modules/cpufeatures-module.qdoc b/doc/reference/modules/cpufeatures-module.qdoc index 8dcd117f1..c2358e388 100644 --- a/doc/reference/modules/cpufeatures-module.qdoc +++ b/doc/reference/modules/cpufeatures-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype cpufeatures \inqmlmodule QbsModules \since Qbs 1.10 diff --git a/doc/reference/modules/dmg-module.qdoc b/doc/reference/modules/dmg-module.qdoc index 56fd65960..5d18621ab 100644 --- a/doc/reference/modules/dmg-module.qdoc +++ b/doc/reference/modules/dmg-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype dmg \inqmlmodule QbsModules \since Qbs 1.9 diff --git a/doc/reference/modules/exporter-cmake.qdoc b/doc/reference/modules/exporter-cmake.qdoc new file mode 100644 index 000000000..2f4191a76 --- /dev/null +++ b/doc/reference/modules/exporter-cmake.qdoc @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** Copyright (C) 2024 Raphael Cotty (raphael.cotty@gmail.com) +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \qmltype Exporter.cmake + \inqmlmodule QbsModules + \since Qbs 2.3 + + \brief Provides support for generating \CMAKE packages from dynamic, static and header library + products. + + The Exporter.cmake module contains the properties and rules to create a \CMAKE config + \l{https://cmake.org/cmake/help/v3.29/manual/cmake-packages.7.html#config-file-packages}{files} + from the \l Export item of a \l Product. + + For instance, suppose you are creating a library. To allow exporting to \CMAKE, you would write + something like the following: + \code + DynamicLibrary { + name: "mylibrary" + qbs.installPrefix: "/opt/mylibrary" + Depends { name: "Exporter.cmake" } + Exporter.cmake.packageName: "MyLibrary" + property string headersInstallDir: "include" + // ... + Group { + name: "API headers" + files: ["mylib.h"] + qbs.install: true + qbs.installDir: headersInstallDir + } + Group { + fileTagsFilter: ["Exporter.cmake.package"] + qbs.installDir: "lib/cmake/MyLibrary" + } + Export { + Depends { name: "cpp" } + cpp.includePaths: FileInfo.joinPaths( + exportingProduct.qbs.installRoot, + exportingProduct.qbs.installPrefix, + exportingProduct.headersInstallDir) + } + } + \endcode + To build against this library, from within your \CMAKE project, you simply + use \l{https://cmake.org/cmake/help/v3.29/command/find_package.html}{find_package}: + \code + find_package(MyLibrary PATHS REQUIRED) + add_executable(Consumer main.cpp) + target_link_libraries(Consumer MyLibrary) + \endcode + + \section2 Relevant File Tags + \target filetags-exporter-qbs + + \table + \header + \li Tag + \li Since + \li Description + \row + \li \c{"Exporter.cmake.package"} + \li 2.3.0 + \li This tag is attached to all generated module files. + \row + \li \c{"Exporter.cmake.configFile"} + \li 2.3.0 + \li This tag is attached to the generated config file. + \row + \li \c{"Exporter.cmake.versionFile"} + \li 2.3.0 + \li This tag is attached to the generated version file. + \endtable +*/ + +/*! + \qmlproperty string Exporter.cmake::configFileName + + The name of the generated config file. + + \defaultvalue \c{packageName + "Config.cmake"} +*/ + +/*! + \qmlproperty string Exporter.cmake::versionFileName + + The name of the generated version file. + + \defaultvalue \c{packageName + "ConfigVersion.cmake"} +*/ + +/*! + \qmlproperty string Exporter.cmake::packageName + + The name of the \CMAKE package. + + \defaultvalue \l{Product::targetName}{Product.targetName} +*/ + diff --git a/doc/reference/modules/exporter-pkgconfig-module.qdoc b/doc/reference/modules/exporter-pkgconfig-module.qdoc index 9489b4622..1dce5ffd5 100644 --- a/doc/reference/modules/exporter-pkgconfig-module.qdoc +++ b/doc/reference/modules/exporter-pkgconfig-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Exporter.pkgconfig \inqmlmodule QbsModules \since Qbs 1.12 diff --git a/doc/reference/modules/exporter-qbs-module.qdoc b/doc/reference/modules/exporter-qbs-module.qdoc index 610b02dab..cea5aad70 100644 --- a/doc/reference/modules/exporter-qbs-module.qdoc +++ b/doc/reference/modules/exporter-qbs-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Exporter.qbs \inqmlmodule QbsModules \since Qbs 1.12 @@ -58,10 +57,11 @@ } Export { Depends { name: "cpp" } - cpp.includePaths: [product.sourceDirectory] + cpp.includePaths: [exportingProduct.sourceDirectory] prefixMapping: [{ - prefix: product.sourceDirectory, - replacement: FileInfo.joinPaths(qbs.installPrefix, product.headersInstallDir) + prefix: exportingProduct.sourceDirectory, + replacement: FileInfo.joinPaths(exportingProduct.qbs.installPrefix, + exportingProduct.headersInstallDir) }] } } diff --git a/doc/reference/modules/flatbuf-c-module.qdoc b/doc/reference/modules/flatbuf-c-module.qdoc new file mode 100644 index 000000000..d486ab3bf --- /dev/null +++ b/doc/reference/modules/flatbuf-c-module.qdoc @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** Copyright (C) 2024 Ivan Komissarov (abbapoh@gmail.com) +** 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$ +** +****************************************************************************/ + +/*! + \qmltype flatbuf.c + \inqmlmodule QbsModules + \since Qbs 2.4 + + \brief Provides support for \l{https://google.github.io/flatbuffers/}{FlatBuffers} for the + C language. + + The \c flatbuf.c module provides support for generating C headers + and sources from flatbuffers definition files using the \c flatcc tool. + + \section2 Relevant File Tags + + \table + \header + \li Tag + \li Auto-tagged File Names + \li Since + \li Description + \row + \li \c{"flatbuffers.input"} + \li \c{*.fbs} + \li 2.4.0 + \li Source files with this tag are considered inputs to the \c flatcc compiler. + \endtable + + \section2 Dependencies + This module depends on the \c flatcc module which can be created via the \l{conan}{Conan} + module provider. +*/ + +/*! + \qmlproperty string flatbuf.c::compilerName + + The name of the \c flatcc binary. + + \defaultvalue \c "flatcc" +*/ + +/*! + \qmlproperty string flatbuf.c::compilerPath + + The path to the \c flatcc binary. + + Use this property to override the auto-detected location. + + \defaultvalue \c auto-detected +*/ + +/*! + \qmlproperty pathList flatbuf.c::importPaths + + The list of import paths that are passed to the \c flatcc tool via the \c -I option. + + \defaultvalue \c [] +*/ diff --git a/doc/reference/modules/flatbuf-cpp-module.qdoc b/doc/reference/modules/flatbuf-cpp-module.qdoc new file mode 100644 index 000000000..a4b6915ab --- /dev/null +++ b/doc/reference/modules/flatbuf-cpp-module.qdoc @@ -0,0 +1,144 @@ +/**************************************************************************** +** +** Copyright (C) 2024 Ivan Komissarov (abbapoh@gmail.com) +** 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$ +** +****************************************************************************/ + +/*! + \qmltype flatbuf.cpp + \inqmlmodule QbsModules + \since Qbs 2.4 + + \brief Provides support for \l{https://google.github.io/flatbuf/}{flatbuf} for the + C++ language. + + The \c flatbuf.cpp module provides support for generating C++ headers + and sources from flatbuf definition files using the \c flatc tool. + + A simple qbs file that uses flatbuf can be written as follows: + \code + CppApplication { + Depends { name: "flatbuf.cpp" } + files: ["foo.fbs", "main.cpp"] + } + \endcode + A generated header now can be included in the C++ sources: + \code + #include <foo_generated.h> + + int main(int argc, char* argv[]) { + flatbuf::FlatBufferBuilder builder; + + auto foo = QbsTest::CreateFoo(builder, 42); + return 0; + } + \endcode + + \section2 Relevant File Tags + + \table + \header + \li Tag + \li Auto-tagged File Names + \li Since + \li Description + \row + \li \c{"flatbuf.input"} + \li \c{*.fbs} + \li 2.4.0 + \li Source files with this tag are considered inputs to the \c flatc compiler. + \endtable + + \section2 Dependencies + This module depends on the \c flatbuffers module which can be created via the \l{conan}{Conan} + module provider. +*/ + +/*! + \qmlproperty string flatbuf.cpp::compilerName + + The name of the \c flatc binary. + + \defaultvalue \c "flatc" +*/ + +/*! + \qmlproperty string flatbuf.cpp::compilerPath + + The path to the \c flatc binary. + + Use this property to override the auto-detected location. + + \defaultvalue \c auto-detected +*/ + +/*! + \qmlproperty string flatbuf.cpp::filenameExtension + + The extension appended to the generated file names. If not specified, the default extension + (\c ".h") is used. + + This property corresponds to the \c --filename-ext option of the \c flatc tool. + + \nodefaultvalue +*/ + +/*! + \qmlproperty string flatbuf.cpp::filenameSuffix + + The suffix appended to the generated file names. If not specified, the default suffix + (\c "_generated") is used. + + This property corresponds to the \c --filename-suffix option of the \c flatc tool. + + \nodefaultvalue +*/ + +/*! + \qmlproperty pathList flatbuf.cpp::importPaths + + The list of import paths that are passed to the \c flatc tool via the \c -I option. + + \defaultvalue \c [] +*/ + +/*! + \qmlproperty string flatbuf.cpp::includePrefix + + Prefix path prepended to any generated include statements. + + This property corresponds to the \c --include-prefix option of the \c flatc tool. + + \nodefaultvalue +*/ + +/*! + \qmlproperty bool flatbuf.cpp::keepPrefix + + Whether to keep original prefix of schema include statement. + + This property corresponds to the \c --keep-prefix option of the \c flatc tool. + + \defaultvalue \c false +*/ diff --git a/doc/reference/modules/freedesktop-module.qdoc b/doc/reference/modules/freedesktop-module.qdoc new file mode 100644 index 000000000..5b6b14d0f --- /dev/null +++ b/doc/reference/modules/freedesktop-module.qdoc @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** Copyright (C) 2019 Alberto Mardegan +** 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$ +** +****************************************************************************/ + +/*! + \qmltype freedesktop + \inqmlmodule QbsModules + \since Qbs 1.16 + + \brief Provides support for some freedesktop.org specifications. + + The \c freedesktop module contains properties and rules for building and working with + applications compliant to freedesktop.org specifications on UNIX platforms. + The areas in which this module can be of use include: + + \list + \li Creation or post-processing of + \l{https://specifications.freedesktop.org/desktop-entry-spec/latest/}{\c{.desktop} + files} + \li Installation of \l{https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html}{AppStream} metadata + \li Defining the location for + \l{https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html#directory_layout} + {application icons} + \endlist + + This module is available on all platforms but is currently only useful on UNIX platforms. + + \section2 Example usage + \target example-freedesktop + + \code + Application { + ... + Depends { name: "freedesktop" } + + Group { + files: [ + ... + + // Declare the desktop and appstream files + "data/my-app.desktop", + "data/my-app.metainfo.xml", + ] + } + + // Add/change some fields in the desktop file + freedesktop.desktopKeys: ({ + 'Exec': FileInfo.joinPaths(qbs.installPrefix, + product.installDir, + product.targetName) + ' --argument', + 'X-Application-Version': product.version, + }) + + // Declare the application icon + Group { + files: "icons/my-application.svg" + fileTags: "freedesktop.appIcon" + } + } + \endcode + + \section2 Relevant File Tags + \target filetags-freedesktop + + \table + \header + \li Tag + \li Auto-tagged File Names + \li Since + \li Description + \row + \li \c{"freedesktop.desktopfile_source"} + \li \c{*.desktop} + \li 1.16 + \li A source file with this tag is a \c{.desktop} file or fragment that + will be merged into the application's final \c{.desktop} file. + \row + \li \c{"freedesktop.desktopfile"} + \li - + \li 1.16 + \li Attached to the output artifacts of the rule that produces the + merged \c{.desktop} file. + \row + \li \c{"freedesktop.appstream"} + \li \c{*.metainfo.xml}, \c{*.appdata.xml} + \li 1.16 + \li Source files with this tag are AppStream metadata files which will + be installed under \l{qbs::}{installPrefix}\c{/share/metainfo} + \row + \li \c{"freedesktop.appIcon"} + \li - + \li 1.16 + \li Source files with this tag are application icons and will be + installed under \l{qbs::}{installPrefix}\c{/share/icons/hicolor/scalable/apps} + \endtable +*/ + +/*! + \qmlproperty string freedesktop::appName + + The display name of the application which will be stored in the \c{.desktop} file. + + \defaultvalue \l{Product::name}{product.name} +*/ + +/*! + \qmlproperty var freedesktop::desktopKeys + + A dictionary of key-value pairs to add to the application's \c{.desktop} + file. + + The contents of this property will be aggregated with the values from any + \c{.desktop} file. If this property and any \c{.desktop} files contain the + same key, this property will take precedence. + + \nodefaultvalue +*/ diff --git a/doc/reference/modules/ib-module.qdoc b/doc/reference/modules/ib-module.qdoc index d6f8d3248..b85f87c71 100644 --- a/doc/reference/modules/ib-module.qdoc +++ b/doc/reference/modules/ib-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype ib \inqmlmodule QbsModules \since Qbs 1.1 diff --git a/doc/reference/modules/ico-module.qdoc b/doc/reference/modules/ico-module.qdoc index ccff608ef..60e4e2958 100644 --- a/doc/reference/modules/ico-module.qdoc +++ b/doc/reference/modules/ico-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype ico \inqmlmodule QbsModules \since Qbs 1.11 diff --git a/doc/reference/modules/innosetup-module.qdoc b/doc/reference/modules/innosetup-module.qdoc index 0f61275fc..fe75ecf0d 100644 --- a/doc/reference/modules/innosetup-module.qdoc +++ b/doc/reference/modules/innosetup-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype innosetup \inqmlmodule QbsModules \since Qbs 1.7 diff --git a/doc/reference/modules/java-module.qdoc b/doc/reference/modules/java-module.qdoc index 28057e089..02ad3227a 100644 --- a/doc/reference/modules/java-module.qdoc +++ b/doc/reference/modules/java-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype java \inqmlmodule QbsModules \since Qbs 1.4 diff --git a/doc/reference/modules/lexyacc-module.qdoc b/doc/reference/modules/lexyacc-module.qdoc index 2d5117641..002e90f05 100644 --- a/doc/reference/modules/lexyacc-module.qdoc +++ b/doc/reference/modules/lexyacc-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype lex_yacc \inqmlmodule QbsModules \since Qbs 1.6 diff --git a/doc/reference/modules/nodejs-module.qdoc b/doc/reference/modules/nodejs-module.qdoc index 0b56ba636..8b3166a81 100644 --- a/doc/reference/modules/nodejs-module.qdoc +++ b/doc/reference/modules/nodejs-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype nodejs \inqmlmodule QbsModules \since Qbs 1.3 diff --git a/doc/reference/modules/nsis-module.qdoc b/doc/reference/modules/nsis-module.qdoc index 359fec46c..d2b979eaa 100644 --- a/doc/reference/modules/nsis-module.qdoc +++ b/doc/reference/modules/nsis-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype nsis \inqmlmodule QbsModules \since Qbs 1.2 diff --git a/doc/reference/modules/pkgconfig-module.qdoc b/doc/reference/modules/pkgconfig-module.qdoc index f30308895..cd24257fc 100644 --- a/doc/reference/modules/pkgconfig-module.qdoc +++ b/doc/reference/modules/pkgconfig-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype pkgconfig \inqmlmodule QbsModules \since 1.13 diff --git a/doc/reference/modules/protobufcpp-module.qdoc b/doc/reference/modules/protobufcpp-module.qdoc index b82ccc9f7..2c96eaeef 100644 --- a/doc/reference/modules/protobufcpp-module.qdoc +++ b/doc/reference/modules/protobufcpp-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype protobuf.cpp \inqmlmodule QbsModules \since Qbs 1.13 @@ -73,32 +72,38 @@ \li \li 1.14.0 \li Source files with this tag are considered as gRPC files. + \row + \li \c{"protobuf.hpp"} + \li + \li 1.18.0 + \li This tag is attached to the header files generated by \c protoc compiler. \endtable -*/ - -/*! - \qmlproperty string protobuf.cpp::grpcIncludePath - The path where grpc++ headers are located. Set this property to override the - default location. + \section2 Dependencies - \defaultvalue \c auto-detected + The \l protobuf.cpp module requires runtime libraries to be operational. It depends on the + \c "protobuflib" module which can be created by the \l qbspkgconfig or fallback module + providers (the corresponding packages are \c protobuf or \c protobuf-lite). If \l useGrpc is + set to true, the \l protobuf.cpp module also depends on the \c "grpc++" module. */ /*! - \qmlproperty string protobuf.cpp::grpcLibraryPath + \qmlproperty string protobuf.cpp::compilerName - The path where the grpc++ library is located. Set this property to override the - default location. + The name of the protoc binary. - \defaultvalue \c auto-detected + \since Qbs 1.17 + \defaultvalue \c "protoc" */ /*! - \qmlproperty string protobuf.cpp::protocBinary + \qmlproperty string protobuf.cpp::compilerPath + + The path to the protoc binary. - The command to invoke when compiling proto definition files. + Use this property to override the auto-detected location. + \since Qbs 1.17 \defaultvalue \c auto-detected */ @@ -115,21 +120,13 @@ */ /*! - \qmlproperty string protobuf.cpp::includePath + \qmlproperty string protobuf.cpp::outputDir + \readonly - The path where protobuf C++ headers are located. Set this property to override the - default location. + The directory where the \c protoc compiler generated files are placed. - \defaultvalue \c auto-detected -*/ - -/*! - \qmlproperty string protobuf.cpp::libraryPath - - The path where the protobuf C++ library is located. Set this property to override the - default location. - - \defaultvalue \c auto-detected + The value of this property is automatically set by \QBS and cannot be + changed by the user. */ /*! diff --git a/doc/reference/modules/protobufnanopb-module.qdoc b/doc/reference/modules/protobufnanopb-module.qdoc new file mode 100644 index 000000000..75c87ba57 --- /dev/null +++ b/doc/reference/modules/protobufnanopb-module.qdoc @@ -0,0 +1,155 @@ +/**************************************************************************** +** +** Copyright (C) 2020 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$ +** +****************************************************************************/ + +/*! + \qmltype protobuf.nanopb + \inqmlmodule QbsModules + \since Qbs 1.18 + + \brief Provides support for protocol buffers for embedded systems. + + The \c protobuf.nanopb module provides support for generating nanopb C headers + and sources from proto definition files using the \l nanopb plugin for the + \l protoc tool suitable for embedded systems. + + A simple qbs file that uses protobuf can be written as follows: + \code + CppApplication { + Depends { name: "protobuf.nanopb" } + files: ["foo.proto", "main.cpp"] + } + \endcode + A generated header now can be included in the C++ sources: + \code + #include <foo.pb.h> + + int main(int argc, char* argv[]) { + Foo bar; + bar.has_answer = true; + bar.answer = 42; + return 0; + } + \endcode + + Nanopb .options files to define nanopb specific proto options are supported. + + \section2 Relevant File Tags + + \table + \header + \li Tag + \li Auto-tagged File Names + \li Since + \li Description + \row + \li \c{"protobuf.input"} + \li \c{*.proto} + \li 1.13.0 + \li Source files with this tag are considered inputs to the \c protoc compiler. + \row + \li \c{"protobuf.hpp"} + \li + \li 1.18.0 + \li This tag is attached to the header files generated by \c protoc compiler. + \endtable +*/ + +/*! + \qmlproperty string protobuf.nanopb::compilerName + + The name of the protoc binary. + + \defaultvalue \c "protoc" +*/ + +/*! + \qmlproperty string protobuf.nanopb::compilerPath + + The path to the protoc binary. + + Use this property to override the auto-detected location. + + \defaultvalue \c auto-detected +*/ + +/*! + \qmlproperty pathList protobuf.nanopb::importPaths + + The list of imports that are passed to the \c protoc tool via the \c --proto_path option. + These imports should contain the proto files. They are used to determine + the relative structure of the generated files. + \note The paths are passed to \c protoc in the same order as specified in this property and + \c protoc output may differ depending on that order. + + \defaultvalue \c [] +*/ + +/*! + \qmlproperty string protobuf.nanopb::includePath + + The path where protobuf nanopb C headers are located. Set this property to override the + default location. + + \defaultvalue \c auto-detected +*/ + +/*! + \qmlproperty string protobuf.nanopb::libraryPath + + The path where the protobuf nanopb runtime library is located. Set this property to override the + default location. + + \defaultvalue \c auto-detected +*/ + +/*! + \qmlproperty string protobuf.nanopb::outputDir + \readonly + + The directory where the \c protoc compiler generated files are placed. + + The value of this property is automatically set by \QBS and cannot be + changed by the user. +*/ + +/*! + \qmlproperty string protobuf.nanopb::pluginName + + The name of the nanopb protoc plugin. + + \defaultvalue \c "protoc-gen-nanopb" +*/ + +/*! + \qmlproperty string protobuf.nanopb::pluginPath + + The path to the nanopb protoc plugin. + + Use this property to override the auto-detected location. + + \defaultvalue \c auto-detected +*/ diff --git a/doc/reference/modules/protobufobjc-module.qdoc b/doc/reference/modules/protobufobjc-module.qdoc index 07e6db759..3666cdb8a 100644 --- a/doc/reference/modules/protobufobjc-module.qdoc +++ b/doc/reference/modules/protobufobjc-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype protobuf.objc \inqmlmodule QbsModules \since Qbs 1.13 @@ -49,14 +48,31 @@ \li \c{*.proto} \li 1.13.0 \li Source files with this tag are considered inputs to the \c protoc compiler. + \row + \li \c{"protobuf.hpp"} + \li + \li 1.18.0 + \li This tag is attached to the header files generated by \c protoc compiler. \endtable */ /*! - \qmlproperty string protobuf.objc::protocBinary + \qmlproperty string protobuf.objc::compilerName + + The name of the protoc binary. + + \since Qbs 1.17 + \defaultvalue \c "protoc" +*/ + +/*! + \qmlproperty string protobuf.objc::compilerPath - The command to invoke when compiling proto definition files. + The path to the protoc binary. + Use this property to override the auto-detected location. + + \since Qbs 1.17 \defaultvalue \c auto-detected */ @@ -99,3 +115,13 @@ \defaultvalue \c auto-detected */ + +/*! + \qmlproperty string protobuf.objc::outputDir + \readonly + + The directory where the \c protoc compiler generated files are placed. + + The value of this property is automatically set by \QBS and cannot be + changed by the user. +*/ diff --git a/doc/reference/modules/qbs-module.qdoc b/doc/reference/modules/qbs-module.qdoc index c1a0b2532..7fc1479d4 100644 --- a/doc/reference/modules/qbs-module.qdoc +++ b/doc/reference/modules/qbs-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage list-of-modules.html \qmltype qbs \inqmlmodule QbsModules \since Qbs 1.0 @@ -56,7 +55,7 @@ name: "Runtime resources" files: "*.qml" qbs.install: true - qbs.installDir: condition: qbs.targetOS.contains("unix") + qbs.installDir: condition: qbs.targetOS.includes("unix") ? "share/myapp" : "resources" } Group { @@ -65,7 +64,7 @@ qbs.install: true qbs.installDir: "bin" } - qbs.installPrefix: condition: qbs.targetOS.contains("unix") + qbs.installPrefix: condition: qbs.targetOS.includes("unix") ? "usr/local" : "MyApp" } \endcode @@ -113,11 +112,13 @@ The name of the build variant for the current build. - Possible values are \c{"debug"} and \c{"release"}. A debug build usually - contains additional debug symbols that are needed for debugging the - application but that can be left out from the release version. Debug builds - are used for testing and release builds for creating the final installation - file. + 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 @@ -129,7 +130,8 @@ Whether to generate debug information. - \defaultvalue \c{true} for debug builds, \c{false} otherwise. + \defaultvalue \c{true} if \l{qbs::buildVariant}{qbs.buildVariant} is \c{"debug"} or + \c{"profiling"}. Otherwise \c{false}. */ /*! @@ -151,7 +153,7 @@ \endlist Typically, this property is enabled for debug builds and disabled for - release builds. + release or profiling builds. \defaultvalue \c{true} for debug builds, \c{false} otherwise. */ @@ -169,11 +171,12 @@ \li \c{"small"} \endlist - \defaultvalue \c{"none"} for debug builds, \c{"fast"} for release builds. + \defaultvalue \c{"none"} if \l{qbs::buildVariant}{qbs.buildVariant} is \c{"debug"}. + Otherwise \c{"fast"}. */ /*! - \qmlproperty stringList qbs::targetPlatform + \qmlproperty string qbs::targetPlatform \since 1.11 The OS you want to build the project for. @@ -207,6 +210,9 @@ \li \c{"android"} \li \c{["android", "linux", "unix"]} \row + \li \c{"dos"} + \li \c{["dos"]} + \row \li \c{"freebsd"} \li \c{["freebsd", "bsd", "unix"]} \row @@ -243,6 +249,9 @@ \li \c{"openbsd"} \li \c{["openbsd", "bsd", "unix"]} \row + \li \c{"os2"} + \li \c{["os2"]} + \row \li \c{"qnx"} \li \c{["qnx", "unix"]} \row @@ -255,6 +264,9 @@ \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 @@ -266,11 +278,19 @@ \row \li \c{"windows"} \li \c{["windows"]} + \row + \li \c{"none"} + \li \c{["none"]} + \row + \li \c{undefined} + \li \c{[]} \endtable + \note The "none" value is usually used for a bare-metal platforms. + \sa {Target Platforms} - \nodefaultvalue + \defaultvalue \l{platform}{Host.platform()} */ /*! @@ -285,77 +305,317 @@ 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{"c166"} + \li 16-bit architecture microcontroller family developed by Infineon + \row + \li \c{"cr16"} + \li 16-bit compact RISC architecture microcontroller family + developed by National Semiconductor + \row + \li \c{"e2k"} + \li 512-bit Russian wide VLIW microprocessor developed by Moscow Center + of SPARC Technologies (MCST) and fabricated by TSMC + \row + \li \c{"hcs8"} + \li 8-bit HC08 and S08 microcontroller family from Freescale Semiconductor + \row + \li \c{"hcs12"} + \li 16-bit HC12 and S12 microcontroller family from Freescale Semiconductor + \row + \li \c{"hppa"} + \li 64-bit PA-RISC processor architecture developed by Hewlett-Packard + \row + \li \c{"ia64"} + \li 64-bit ISA architecture of the Itanium family processors + developed by Intel + \row + \li \c{"m16c"} + \li 16-bit CISC microcontrollers featuring high ROM code + efficiency manufactured by Renesas Electronics + \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{"mcs251"} + \li 8-, 16-, and 32-bit microcontroller family which is a next binary + compatible generation for the \c "mcs51" family + \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{"r32c"} + \li 32-bit CISC microcontrollers with improved code efficiency + and processing performance manufactured by Renesas Electronics + \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_16"} + \li 16-bit ISA architecture processor family developed by Intel + \row + \li \c{"x86_64"} + \li 64-bit ISA architecture processor family developed by AMD + \row + \li \c{"xtensa"} + \li 32-bit architecture with a compact 16- and 24-bit instruction set + developed by Tensilica + \endtable + \nodefaultvalue */ /*! - \qmlproperty string qbs::toolchainType - \since Qbs 1.11 + \qmlproperty stringList qbs::toolchain - The toolchain that is going to be used for this build. + Contains the list of string values describing the toolchain and toolchain + family that is used to build a project. - 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. - - For example, instead of: + 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 - (qbs.toolchainType === "xcode" || qbs.toolchainType === "clang" || qbs.toolchainType === "gcc") + Properties { + // flags for GCC + condition: qbs.toolchain.includes("gcc") + cpp.commonCompilerFlags: ... + } + Properties { + // flags for MSVC + condition: qbs.toolchain.includes("msvc") + cpp.commonCompilerFlags: ... + } \endcode - use: + 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.toolchain.contains("gcc") + (qbs.toolchainType === "xcode" || qbs.toolchainType === "clang" || qbs.toolchainType === "gcc") \endcode - However, there are some cases when using \c toolchainType would be - acceptable, such as when the resulting condition would be simpler while - still being correct: + use: \code - (qbs.toolchainType === "gcc") + qbs.toolchain.includes("gcc") \endcode - versus: + since XCode, GCC and Clang belong to the \c "gcc" family. - \code - (qbs.toolchain.contains("gcc") && !qbs.toolchain.contains("clang")) - \endcode + \section2 Relation between toolchainType and toolchain - Typical values include: \c{"gcc"}, \c{"clang"}, \c{"mingw"}, \c{"msvc"}, and - \c{"xcode"}. + 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{"cosmic"} + \li \c{["cosmic"]} + \row + \li \c{"dmc"} + \li \c{["dmc"]} + \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{"qcc"} + \li \c{["qcc"]} + \row + \li \c{"sdcc"} + \li \c{["sdcc"]} + \row + \li \c{"watcom"} + \li \c{["watcom"]} + \row + \li \c{"xcode"} + \li \c{["xcode", "clang", "llvm", "gcc"]} + \endtable - \defaultvalue Determined automatically. + \nodefaultvalue */ /*! - \qmlproperty string qbs::sysroot + \qmlproperty string qbs::toolchainType + \since Qbs 1.11 - The \c sysroot of the target platform. + The toolchain that is going to be used for this build. - This property is typically set in a profile for cross-compiling. + For example, to build a project using the \c "clang" toolchain, simply do + \code + qbs build qbs.toolchainType:clang + \endcode - \nodefaultvalue -*/ + 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. -/*! - \qmlproperty string qbs::pathListSeparator + 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}. - The platform-specific separator for a path list that is used in environment - variables or other contexts. + 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 \c{";"} on Windows, \c{":"} on Unix. + \defaultvalue Determined automatically. */ /*! - \qmlproperty string qbs::nullDevice - \since Qbs 1.4.2 + \qmlproperty string qbs::sysroot - The platform-specific file path corresponding to the null device. + The \c sysroot of the target platform. + + This property is typically set in a profile for cross-compiling. - \defaultvalue \c{"NUL"} on Windows, \c{"/dev/null"} on Unix. + \nodefaultvalue */ /*! @@ -374,98 +634,6 @@ */ /*! - \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 - - Do not use this property. - - \defaultvalue Determined automatically. -*/ - -/*! \qmlproperty stringList qbs::targetOS \readonly @@ -477,17 +645,17 @@ \code Group { // Includes all Unix-like platforms, such as: Linux, BSD, Apple platforms and others. - condition: qbs.targetOS.contains("unix") + condition: qbs.targetOS.includes("unix") files: ... } Group { // Includes all Apple platforms, such as macOS, iOS, and iOS Simulator. - condition: qbs.targetOS.contains("darwin") + condition: qbs.targetOS.includes("darwin") files: ... } Group { // Includes only macOS - condition: qbs.targetOS.contains("macos") + condition: qbs.targetOS.includes("macos") files: ... } \endcode @@ -500,7 +668,7 @@ use \code - qbs.targetOS.contains("darwin") + qbs.targetOS.includes("darwin") \endcode @@ -513,7 +681,7 @@ versus \code - qbs.targetOS.contains("linux") && !qbs.targetOS.contains("android") + qbs.targetOS.includes("linux") && !qbs.targetOS.includes("android") \endcode For the complete list of possible values, see @@ -523,17 +691,6 @@ */ /*! - \qmlproperty stringList qbs::toolchain - - The attributes of the toolchain that is going to be used for this build. - - Typical values include \c{"llvm"}, in addition to the possible values of - \l{qbs::}{toolchainType}. - - \nodefaultvalue -*/ - -/*! \qmlproperty string qbs::version \readonly \since Qbs 1.4.1 diff --git a/doc/reference/modules/qnx-module.qdoc b/doc/reference/modules/qnx-module.qdoc index d14f44b8f..a8ba75717 100644 --- a/doc/reference/modules/qnx-module.qdoc +++ b/doc/reference/modules/qnx-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype qnx \inqmlmodule QbsModules \since Qbs 1.8 diff --git a/doc/reference/modules/qt-android_support-module.qdoc b/doc/reference/modules/qt-android_support-module.qdoc index 995f73ba5..01d43ab98 100644 --- a/doc/reference/modules/qt-android_support-module.qdoc +++ b/doc/reference/modules/qt-android_support-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Qt.android_support \inqmlmodule QbsModules \brief Provides Qt support for the Android platform. @@ -39,17 +38,6 @@ */ /*! - \qmlproperty bool Qt.android_support::useMinistro - - Whether or not to use the Ministro service. If this property is enabled, then - the Qt libraries required by your application as well as some other resources - will not be packaged into the APK file, but are expected to be present on the - device at run time. - - \defaultvalue \c false -*/ - -/*! \qmlproperty string Qt.android_support::qmlRootDir The root directory of the product's QML files. This information is passed to @@ -86,6 +74,15 @@ */ /*! + \qmlproperty stringList Qt.android_support::qmlImportPaths + + Additional directories to search for QML imports. + + \defaultvalue \c undefined + \since 1.22 +*/ + +/*! \qmlproperty bool Qt.android_support::verboseAndroidDeployQt Enable this property if you want verbose output from the diff --git a/doc/reference/modules/qt-core-module.qdoc b/doc/reference/modules/qt-core-module.qdoc index c8c3dc7de..6aedf2a69 100644 --- a/doc/reference/modules/qt-core-module.qdoc +++ b/doc/reference/modules/qt-core-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Qt.core \inqmlmodule QbsModules \brief Provides Qt Core support. @@ -100,6 +99,12 @@ \li Source files with this tag trigger a re-execution of the rule running the \c moc tool when their timestamp changes. \row + \li \c{"qt.core.metatypes"} + \li n/a + \li 1.16 + \li This tag is attached to the JSON files that are potentially created if + \l{Qt.core::generateMetaTypesFile}{generateMetaTypesFile} is enabled. + \row \li \c{"qt.core.resource_data"} \li - \li 1.7 @@ -196,6 +201,54 @@ */ /*! + \qmlproperty bool Qt.core::generateMetaTypesFile + + If this property is enabled, a JSON file tagged as \c "qt.core.metatypes" will potentially + be generated from metatype information collected by \c moc. + + \nodefaultvalue + \since Qbs 1.16 +*/ + +/*! + \qmlproperty string Qt.core::generatedHeadersDir + + The directory where tools that generate headers (such as \c moc or \c uic) put resulting + files. + + Normally, you don't need to change this property. The one use-case is when there are several + files with the same file name in the Product. The file name produced by \c moc is based + only on the source file's base file name (without the directory path) which leads to a conflict + in the mentioned case. You can resolve the conflict by setting this property to a non-default + value for one of the files. For example: + + \code + QtApplication { + files: ["my_cool_header.h", "main.cpp"] + Group { + name: "legacy" + files: "legacy/my_cool_header.h" + Qt.core.generatedHeadersDir: "qt.legacy.headers" + } + } + \endcode + + \defaultvalue \c product.buildDirectory + "/qt.headers" +*/ + +/*! + \qmlproperty bool Qt.core::metaTypesInstallDir + + The directory to install the metatypes file into. If this property is empty or undefined, + the metatypes file will not be installed. If the + \l{Qt.core::generateMetaTypesFile}{generateMetaTypesFile} property is not \c true, then + this property has no effect. + + \nodefaultvalue + \since Qbs 1.16 +*/ + +/*! \qmlproperty path Qt.core::incPath The base path of the Qt headers. @@ -325,6 +378,14 @@ */ /*! + \qmlproperty string Qt.core::qdocOutputDir + + The directory name where the \c qdoc tool writes its output. + + \defaultvalue \c{product.buildDirectory + "/qdoc_html"} +*/ + +/*! \qmlproperty string Qt.core::qmBaseName The base name of the \c .qm file to be built from the \c .ts files in the @@ -336,6 +397,14 @@ */ /*! + \qmlproperty string Qt.core::qmDir + + The directory name where to put the \c .qm file to be built. + + \defaultvalue \l{Product::destinationDirectory}{product.destinationDirectory} +*/ + +/*! \qmlproperty string Qt.core::qtBuildVariant Specifies the type of Qt libraries to build against: \c "debug" or @@ -441,3 +510,11 @@ \defaultvalue \c{versionParts[2]} */ + +/*! + \qmlproperty bool Qt.core::useRPaths + + Whether to add \l{Qt.core::libPath}{Qt.core.libPath} to \l{cpp::rpaths}{cpp.rpaths}. + + \defaultvalue \c true on Linux, \c false everywhere else. +*/ diff --git a/doc/reference/modules/qt-dbus-module.qdoc b/doc/reference/modules/qt-dbus-module.qdoc index dacf3f095..32e84f950 100644 --- a/doc/reference/modules/qt-dbus-module.qdoc +++ b/doc/reference/modules/qt-dbus-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Qt.dbus \inqmlmodule QbsModules \brief Provides Qt D-Bus support. diff --git a/doc/reference/modules/qt-declarative-module.qdoc b/doc/reference/modules/qt-declarative-module.qdoc index f7996257f..f247f3347 100644 --- a/doc/reference/modules/qt-declarative-module.qdoc +++ b/doc/reference/modules/qt-declarative-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Qt.declarative \inqmlmodule QbsModules \brief Provides Qt Quick 1 support. diff --git a/doc/reference/modules/qt-gui-module.qdoc b/doc/reference/modules/qt-gui-module.qdoc index 16d8cf344..ace3cce08 100644 --- a/doc/reference/modules/qt-gui-module.qdoc +++ b/doc/reference/modules/qt-gui-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Qt.gui \inqmlmodule QbsModules \brief Provides Qt GUI support. diff --git a/doc/reference/modules/qt-modules.qdoc b/doc/reference/modules/qt-modules.qdoc index 099f4e3ce..e3fee3c72 100644 --- a/doc/reference/modules/qt-modules.qdoc +++ b/doc/reference/modules/qt-modules.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \page qt-modules.html \inmodule qbs-modules @@ -36,6 +35,8 @@ The \c{Qt.*} modules contain properties and rules for Qt. + Qt modules are generated by the \l[QML]{Qt} module provider. + \section1 Creating Dependencies to Qt Modules The Qt modules are grouped using the prefix \c Qt. If your product depends @@ -55,22 +56,6 @@ The Qt modules that have properties and relevant file tags are described in separate topics. - \section1 Qt-specific Module Provider Properties - - Looking up a Qt installation happens via a \l{Module Providers}{module provider}. - By default, if a dependency to a Qt module is encountered, \QBS collects all Qt installations - it can find. This lookup happens by searching for \c qmake executables in the \c PATH - environment variable. Alternatively, you can explicitly tell \QBS which Qt - installations it should consider by setting the \c Qt.qmakeFilePaths - \l{Parameterizing Module Providers}{module provider property}. In that case, - the environment will be ignored. For instance, with the following Linux command line, - \QBS will build the project against a custom Qt instead of the standard one in \c{/usr/bin}: - \code - $ qbs moduleProviders.Qt.qmakeFilePaths:/opt/myqt/bin/qmake - \endcode - You can also set the module provider property in a profile. The simplest way to do - this is via the \l setup-qt tool. - \section1 List of Submodules \table diff --git a/doc/reference/modules/qt-plugin_support-module.qdoc b/doc/reference/modules/qt-plugin_support-module.qdoc index 2f41e1cc0..057291820 100644 --- a/doc/reference/modules/qt-plugin_support-module.qdoc +++ b/doc/reference/modules/qt-plugin_support-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Qt.plugin_support \inqmlmodule QbsModules \since Qbs 1.13.0 diff --git a/doc/reference/modules/qt-qml-module.qdoc b/doc/reference/modules/qt-qml-module.qdoc index 722a2eb41..57b3661f0 100644 --- a/doc/reference/modules/qt-qml-module.qdoc +++ b/doc/reference/modules/qt-qml-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Qt.qml \inqmlmodule QbsModules \brief Provides Qt QML support. @@ -60,10 +59,81 @@ \li 1.8 \li Source files with this tag serve as inputs to the QML plugin scanner. + \row + \li \c{"qt.qml.types"} + \li n/a + \li 1.16 + \li This tag is attached to the files created by the \c qmltyperegistrar + tool if the \l importName property is set. \endtable */ /*! + \qmlproperty string Qt.qml::importName + + Setting this value triggers QML type registration via the \c qmltyperegistrar tool, + which results in the creation of a file with the tag \c{"qt.qml.types"}. + The given string is the name under which the registered types can be imported + by QML code that wants to use them. + + \note This functionality is only available with Qt 5.15 or later. + + \since Qbs 1.16 + \nodefaultvalue +*/ + +/*! + \qmlproperty string Qt.qml::importVersion + + Specifies the version of the types to be registered. + Values consist of a major and an optional minor number, separated by dots. + This property has no effect if \l importName is not set. + + \since Qbs 1.16 + \defaultvalue \l {Product::version}{The product version} +*/ + +/*! + \qmlproperty string Qt.qml::typesFileName + + Specifies the name of the file that declares the types registered for this product. + For applications, the default value is \c{<name>.qmltypes}, + where \c{<name>} is the product's \l{Product::targetName}{target name}. + Otherwise, the default value is "plugins.qmltypes". + \note The naming conventions are still in flux. + When in doubt, consult the Qt documentation. + + This property has no effect if \l importName is not set. + + \since Qbs 1.16 +*/ + +/*! + \qmlproperty string Qt.qml::typesInstallDir + + The directory to install the qmltypes file into. If this property is empty or undefined, + the file will not be installed. + This property has no effect if \l importName is not set. + + \since Qbs 1.16 + \nodefaultvalue +*/ + +/*! + \qmlproperty stringList Qt.qml::extraMetaTypesFiles + + Specifies extra metatypes files to pass to the \c qmltyperegistrar tool + via the \c{--foreign-types} option when registering QML types. + \note This property is only needed for external libraries, not products or modules + pulled via \c Depends items. In particular, you don't need to (and should not) + use it to collect the metatypes files of Qt modules. These are found automatically. + This property has no effect if \l importName is not set. + + \since Qbs 1.16 + \nodefaultvalue +*/ + +/*! \qmlproperty string Qt.qml::qmlImportScannerName The base name of the QML import scanner. diff --git a/doc/reference/modules/qt-quick-module.qdoc b/doc/reference/modules/qt-quick-module.qdoc index 8a39b92fc..5e6fa694b 100644 --- a/doc/reference/modules/qt-quick-module.qdoc +++ b/doc/reference/modules/qt-quick-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Qt.quick \inqmlmodule QbsModules \brief Provides Qt Quick 2 support. diff --git a/doc/reference/modules/qt-scxml-module.qdoc b/doc/reference/modules/qt-scxml-module.qdoc index 34f0461d6..b0092ae6e 100644 --- a/doc/reference/modules/qt-scxml-module.qdoc +++ b/doc/reference/modules/qt-scxml-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype Qt.scxml \inqmlmodule QbsModules \brief Provides Qt SCXML support. diff --git a/doc/reference/modules/texttemplate-module.qdoc b/doc/reference/modules/texttemplate-module.qdoc index 652b92863..4c354b261 100644 --- a/doc/reference/modules/texttemplate-module.qdoc +++ b/doc/reference/modules/texttemplate-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype texttemplate \inqmlmodule QbsModules \since Qbs 1.13 diff --git a/doc/reference/modules/typescript-module.qdoc b/doc/reference/modules/typescript-module.qdoc index 4c65c2279..f0f967747 100644 --- a/doc/reference/modules/typescript-module.qdoc +++ b/doc/reference/modules/typescript-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype typescript \inqmlmodule QbsModules \since Qbs 1.3 diff --git a/doc/reference/modules/vcs-module.qdoc b/doc/reference/modules/vcs-module.qdoc index d8ae45b80..fac0979ae 100644 --- a/doc/reference/modules/vcs-module.qdoc +++ b/doc/reference/modules/vcs-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype vcs \inqmlmodule QbsModules \since Qbs 1.10 diff --git a/doc/reference/modules/wix-module.qdoc b/doc/reference/modules/wix-module.qdoc index a09119698..ab6a7497f 100644 --- a/doc/reference/modules/wix-module.qdoc +++ b/doc/reference/modules/wix-module.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! - \contentspage index.html \qmltype wix \inqmlmodule QbsModules \since Qbs 1.2 diff --git a/doc/reference/modules/xcode-module.qdoc b/doc/reference/modules/xcode-module.qdoc index bf38feea1..748226c06 100644 --- a/doc/reference/modules/xcode-module.qdoc +++ b/doc/reference/modules/xcode-module.qdoc @@ -26,7 +26,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \qmltype xcode \inqmlmodule QbsModules \since Qbs 1.5 diff --git a/doc/reference/reference.qdoc b/doc/reference/reference.qdoc index f1975bf3a..f2992b287 100644 --- a/doc/reference/reference.qdoc +++ b/doc/reference/reference.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \previouspage howtos.html \page reference.html \nextpage building-qbs.html @@ -47,7 +46,6 @@ */ /*! - \contentspage reference.html \group list-of-builtin-services \title List of Built-in Services \QBS provides the following built-in JavaScript extensions to simplify operations that @@ -67,7 +65,6 @@ */ /*! - \contentspage reference.html \qmlmodule QbsModules \title List of Modules These are the modules shipped with \QBS. @@ -78,7 +75,12 @@ */ /*! - \contentspage reference.html + \qmlmodule QbsModuleProviders + \title List of Module Providers + These are the module providers shipped with \QBS. +*/ + +/*! \group list-of-items \title List of All Items @@ -88,7 +90,6 @@ */ /*! - \contentspage reference.html \qmlmodule QbsLanguageItems \title List of Language Items @@ -97,7 +98,6 @@ */ /*! - \contentspage reference.html \qmlmodule QbsConvenienceItems \title List of Convenience Items @@ -105,8 +105,7 @@ */ /*! - \contentspage reference.html - \group list-of-probes + \qmlmodule QbsProbes \title List of Probes These are the probes shipped with \QBS. diff --git a/doc/targets/qbs-target-android.qdoc b/doc/targets/qbs-target-android.qdoc index 46081db0d..b306a0ea2 100644 --- a/doc/targets/qbs-target-android.qdoc +++ b/doc/targets/qbs-target-android.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \page qbs-target-android.html \ingroup platforms diff --git a/doc/targets/qbs-target-integrity.qdoc b/doc/targets/qbs-target-integrity.qdoc index 52418a86c..bef92ee82 100644 --- a/doc/targets/qbs-target-integrity.qdoc +++ b/doc/targets/qbs-target-integrity.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \page qbs-target-integrity.html \ingroup platforms diff --git a/doc/targets/qbs-target-ios.qdoc b/doc/targets/qbs-target-ios.qdoc index 1b55a7d0e..56908f01d 100644 --- a/doc/targets/qbs-target-ios.qdoc +++ b/doc/targets/qbs-target-ios.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \page qbs-target-ios.html \ingroup platforms diff --git a/doc/targets/qbs-target-linux.qdoc b/doc/targets/qbs-target-linux.qdoc index 8b15da444..025c77909 100644 --- a/doc/targets/qbs-target-linux.qdoc +++ b/doc/targets/qbs-target-linux.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \page qbs-target-linux.html \ingroup platforms diff --git a/doc/targets/qbs-target-macos.qdoc b/doc/targets/qbs-target-macos.qdoc index 8d956fc63..82fa6ee3c 100644 --- a/doc/targets/qbs-target-macos.qdoc +++ b/doc/targets/qbs-target-macos.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \page qbs-target-macos.html \ingroup platforms diff --git a/doc/targets/qbs-target-platforms.qdoc b/doc/targets/qbs-target-platforms.qdoc index 7e556aea9..92fc7b1f1 100644 --- a/doc/targets/qbs-target-platforms.qdoc +++ b/doc/targets/qbs-target-platforms.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \previouspage installing-files.html \group platforms \nextpage shell.html diff --git a/doc/targets/qbs-target-qnx.qdoc b/doc/targets/qbs-target-qnx.qdoc index c7e28d905..a4d75de23 100644 --- a/doc/targets/qbs-target-qnx.qdoc +++ b/doc/targets/qbs-target-qnx.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \page qbs-target-qnx.html \ingroup platforms diff --git a/doc/targets/qbs-target-tvos.qdoc b/doc/targets/qbs-target-tvos.qdoc index 76744637e..6529663ad 100644 --- a/doc/targets/qbs-target-tvos.qdoc +++ b/doc/targets/qbs-target-tvos.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \page qbs-target-tvos.html \ingroup platforms diff --git a/doc/targets/qbs-target-vxworks.qdoc b/doc/targets/qbs-target-vxworks.qdoc index 100ecfcc3..299f4fe7a 100644 --- a/doc/targets/qbs-target-vxworks.qdoc +++ b/doc/targets/qbs-target-vxworks.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \page qbs-target-vxworks.html \ingroup platforms diff --git a/doc/targets/qbs-target-watchos.qdoc b/doc/targets/qbs-target-watchos.qdoc index 9afec3f46..f0997b1cf 100644 --- a/doc/targets/qbs-target-watchos.qdoc +++ b/doc/targets/qbs-target-watchos.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \page qbs-target-watchos.html \ingroup platforms diff --git a/doc/targets/qbs-target-windows.qdoc b/doc/targets/qbs-target-windows.qdoc index 258a5b445..8bd788877 100644 --- a/doc/targets/qbs-target-windows.qdoc +++ b/doc/targets/qbs-target-windows.qdoc @@ -25,7 +25,6 @@ ** ****************************************************************************/ /*! - \contentspage index.html \page qbs-target-windows.html \ingroup platforms diff --git a/doc/tutorial.qdoc b/doc/tutorial.qdoc new file mode 100644 index 000000000..b17cf4faf --- /dev/null +++ b/doc/tutorial.qdoc @@ -0,0 +1,647 @@ +/**************************************************************************** +** +** Copyright (C) 2024 Ivan Komissarov (abbapoh@gmail.com). +** 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$ +** +****************************************************************************/ + +/*! + \previouspage module-providers.html + \page tutorial.html + \nextpage tutorial-1.html + + \title Tutorial + + The tutorial describes the process of creating a typical \QBS project and explains core + concepts. + + \list + \li \l{tutorial-1.html}{Console Application} + \li \l{tutorial-2.html}{Static Library} + \li \l{tutorial-3.html}{Dynamic Library} + \li \l{tutorial-4.html}{Convenience Items} + \li \l{tutorial-5.html}{Autotest} + \li \l{tutorial-6.html}{Project Properties} + \li \l{tutorial-7.html}{Buildconfig Module} + \li \l{tutorial-8.html}{Configurable Library} + \li \l{tutorial-9.html}{Version Header} + \endlist +*/ + +/*! + \previouspage tutorial.html + \page tutorial-1.html + \nextpage tutorial-2.html + + \title Console Application + + Let's start with a mandatory Hello World example. There is a Hello World example in the + \l{overview.html#well-defined-language}{overview section}, but this time we will create a + real-world project. + + We will start with a simple \QBS project file: + \snippet ../tutorial/chapter-1/myproject.qbs 0 + + Here, we set the \l{Project::name}{name} of the project to \c "My Project" - it is mainly + used for IDEs but can also be used to reference a project when setting properties from + command-line. We also set the \l{Project::minimumQbsVersion}{minimumQbsVersion} - this property + can be useful if the project depends on features that are not present in earlier \QBS + versions. + + The \l{Project::references}{references} property contains the path to a file + that describes our application. This file is located in a separate \c app directory - + typically, projects tend to have quite a complicated structure but \QBS does not enforce any + specific layout, so we will simply put each product in a separate directory. + + The application file sets several properties: + \snippet ../tutorial/chapter-1/app/app.qbs 0 + + The \l{Product::name}{name} property identifies the product. + The \l{Product::targetName}{targetName} property sets the name of the resulting binary + (without the \c .exe extension on Windows, which is appended automatically). By default, + \l{Product::targetName}{targetName} defaults to \l{Product::name}{name}. The + \l{Product::files}{files} property contains a single \c main.c file which is a trivial + \e{hello world} application: + \snippet ../tutorial/chapter-1/app/main.c 0 + + We set \l{Product::consoleApplication}{consoleApplication} to \c true to indicate that our + application is going to be used from a terminal. For example, on Windows, this will spawn a + new console window if you double-click the resulting binary, while on macOS it will create a + standalone binary file instead of an + \l{https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html}{application bundle}. + + By default, the \l{Application::install}{CppApplication.install} property is \c false and thus + \QBS does not install the binary. If the \l{Application::install}{install} property is + \c true, when building a project, \QBS will also install it into an \e{installation root} + folder which by default is named \c install-root and located under the build directory. This + folder will contain only resulting artifacts without the build leftovers and files will have + the same layout as in the target system. The \l{Application::install}{install} property should + be set to \c true for all products that are to be distributed. + See the \l{installing-files.html}{Installing Files} section for more details. + + We can now build and run our application from the project directory: + \code + chapter-1 $ qbs build + ... + Building for configuration default + compiling main.c [My Application] + ... + linking myapp [My Application] + ... + Build done for configuration default. + + chapter-1 $ qbs run + ... + Starting target. Full command line: .../default/install-root/usr/local/bin/myapp + Hello, world + \endcode + + The \QBS output to console and default installation location may vary between different + platforms. + + In most cases, \QBS should be able to find the default compiler (for example, GCC or + Clang on Linux, Visual Studio on Windows, or Xcode on macOS), but if that's not the + case, see the \l{configuring.html}{configuring} section. + + In the following chapters, we will continue to improve our project: we will add a library and + make it configurable. +*/ + +/*! + \previouspage tutorial-1.html + \page tutorial-2.html + \nextpage tutorial-3.html + + \title Static Library + + Let's add a static library to our project so we can reuse some code. Analogous to what we did + for the application, we put the file into the \c{lib} directory and add it to the + \l{Project::references}{references} property in our project. The modified project may look + like this: + + \snippet ../tutorial/chapter-2/myproject.qbs 0 + + Let's take a look at the the library file now: + + \snippet ../tutorial/chapter-2/lib/lib.qbs 0 + It contains the \l{StaticLibrary} item which sets the \l{Product::type}{type} of the product + to \c "staticlibrary" and sets some defaults like where to install that library. + As before, we set the \l{Product::files}{files} property with a header: + \snippet ../tutorial/chapter-2/lib/lib.h 0 + And we set the implementation file of our library: + \snippet ../tutorial/chapter-2/lib/lib.c 0 + + We will keep our library really simple - it only contains one function, which we will later use + in our application. The source file requires a \c "CRUCIAL_DEFINE" to be + passed to a preprocessor. That is why we set the \l{cpp::defines}{cpp.defines} property: + \snippet ../tutorial/chapter-2/lib/lib.qbs 1 + + Note that unlike the \l{CppApplication} item, the \l{StaticLibrary} does not pull in the + dependency on the \l{cpp} module automatically - that is why we have to pull it in manually + using the \l{Depends} item. Without the \l{cpp} module, \QBS would not know how to turn a + \c{.c} file into an object file and the object file into a library. See + \l{Rules and Product Types} for details. + + Next, we need to tell \QBS where to look for public headers of our library when building + products that depend on it. By default, \QBS knows nothing about the layout of our + library, so we tell it to look for headers in the library's source directory using the + \l{Export} item: + + \snippet ../tutorial/chapter-2/lib/lib.qbs 2 + You can export any \l{Module} property within the \l{Export} item - it will be merged in the + depending product with other properties. For example, you can export + \l{cpp::defines}{cpp.defines} or specific \l{cpp::commonCompilerFlags}{compiler flags} that + are required to use this product. + + We depend on the \l{cpp} module twice - once within the \l{StaticLibrary} + item and once in the \l{Export} item. This is because by default \QBS does not export anything + when depending on this product and the dependencies in this item (as well as + properties set in this item) are private to this product while dependencies and properties + set in the \l{Export} item are for export only. + + Finally, we have some Apple-specific settings. You can skip this part of the tutorial if you + are using some other platform. We depend on the \l{bundle} module and set the + \l{bundle::isBundle}{bundle.isBundle} to false: + \snippet ../tutorial/chapter-2/lib/lib.qbs 3 + By default, \QBS builds static and dynamic libraries as + \l{https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html}{Frameworks} + on macOS. So, to keep things simple, we disable the framework build and build a plain old + static library file here. +*/ + +/*! + \previouspage tutorial-2.html + \page tutorial-3.html + \nextpage tutorial-4.html + + \title Dynamic Library + + Let's now turn our static library into a dynamic library. It is a bit trickier with dynamic + libraries since several things should be tweaked. First, we need to be able to mark methods + (or classes) in our library as exported. Second, we need to tell our application where to look + for our library at run time using \l{https://en.wikipedia.org/wiki/Rpath}{rpaths}. + + Some compilers, like MSVC, require us to mark which symbols we want to export or import. The + \l{https://stackoverflow.com/a/6840659}{canonical} way would be to define some helper macros. + Let's start with a header that defines those helper macros: + \snippet ../tutorial/chapter-3/lib/lib_global.h 0 + + This header defines the \c MYLIB_EXPORT macro that expands either to an "export" or to an + "import" directive based on the presence of the \c MYLIB_LIBRARY macro. We can use this macro + to mark a function as follows: + \snippet ../tutorial/chapter-3/lib/lib.h 0 + + The modified library product may look like this: + + \snippet ../tutorial/chapter-3/lib/lib.qbs 0 + + The most important change is that we changed the item type from \l{StaticLibrary} to + \l{DynamicLibrary}. We also added the \c MYLIB_LIBRARY to the list of + \l{cpp::defines}{defines}. We do this only when building the library but we are not exporting + it - that way the users of our library will have methods marked for import rather than export. + + Finally, we set \l{cpp::sonamePrefix}{cpp.sonamePrefix} to \c "@rpath". This is required only + for Apple platforms, see + \l{https://developer.apple.com/library/archive/documentation/DeveloperTools/Conceptual/DynamicLibraries/100-Articles/RunpathDependentLibraries.html}{Run-Path Dependent Libraries} + for details. + + It is also required to set \l{cpp::rpaths}{cpp.rpaths} in our application file. Since the + library is installed to the \c{lib} directory and the application is installed to the \c{bin} + directory, we need to tell the loader to look in the \c{lib} directory. The + \l{jsextension-fileinfo.html#relativePath}{FileInfo.relativePath} method can help us: + \snippet ../tutorial/chapter-3/app/app.qbs 0 + + On Linux, this expression would be equivalent to this: \c{cpp.rpaths: ["$ORIGIN/../lib"]}. + Don't forget to \c{import qbs.FileInfo} in order to be able to use the + \l{jsextension-fileinfo.html} extension. + + To make the example complete, here's how the full \c app/app.qbs file should look like: + \snippet ../tutorial/chapter-3/app/app.qbs 1 +*/ + +/*! + \previouspage tutorial-3.html + \page tutorial-4.html + \nextpage tutorial-5.html + + \title Convenience Items + + As you might have noticed, we are repeating ourselves when setting the same properties in our + products - we set \l{Product::version}{version}, \l{Application::install}{install}, + \l{cpp::rpaths}{cpp.rpaths}, and so on. For a single application and a library, that is not a + big deal, but what if we have a dozen libraries? Luckily, this can be achieved using item + \l{language-introduction.html#reusing-project-file-code}{inheritance} - we move the common code + to the base item and in the real product we will only set what is specific to that product (for + example, the list of \l{Product::files}{files}). + + First, we need to tell \QBS where to look for our new base items. This can be achieved using + the \l{Project::qbsSearchPaths}{qbsSearchPaths} property. We set this property to \c "qbs" so + that \QBS will search our items in the \c{qbs} directory located in the project directory: + \snippet ../tutorial/chapter-4/myproject.qbs 0 + + \note This directory has a pre-defined structure: base items should be located under the + \c{imports} subdirectory. See \l{Custom Modules and Items} for details. + + Let's create a base item for all our applications and move common code there: + \snippet ../tutorial/chapter-4/qbs/imports/MyApplication.qbs 0 + + As you see, we managed to extract most of the code here, and our application file now only + contains what's relevant to it: + \snippet ../tutorial/chapter-4/app/app.qbs 0 + + Now let's do the same for our library: + \snippet ../tutorial/chapter-4/qbs/imports/MyLibrary.qbs 0 + + Here, we introduce a helper property, \c libraryMacro, with a default value calculated based + on the capitalized product name. Since the name of out library product is \c "mylib", this + property will expand to \c "MYLIB_LIBRARY". We can also override the default value + for the macro in products that inherit our item like this: + \code + MyLibrary { + libraryMacro: "SOME_OTHER_LIBRARY_MACRO" + } + \endcode + + Let's take a look at the refactored library file: + \snippet ../tutorial/chapter-4/lib/lib.qbs 0 + + We managed to extract the reusable parts to common base items leaving the actual products clean + and simple. + + Unfortunately, item inheritance comes with a price - when both parent and child items set the + same property (\l{cpp::defines}{cpp.defines} in our case), the value in the child item wins. + To work around this, the special \l{special-property-values.html#base}{base} value + exists - it gives access to the base item's value of the current property and makes it possible + to extend its value rather than override it. Here, we concatenate the list of defines from the + base item \c{["MYLIB_LIBRARY"]} with a new list, specific to this product (namely, + \c{['CRUCIAL_DEFINE']}). +*/ + +/*! + \previouspage tutorial-4.html + \page tutorial-5.html + \nextpage tutorial-6.html + + \title Autotest + + Now that we can re-use our base items, let's add a simple autotest. We inherit the new item + from the \c MyApplication item and add an \c "autotest" type: + + \snippet ../tutorial/chapter-5/qbs/imports/MyAutoTest.qbs 0 + + This additional type is required for the helper \l{AutotestRunner} item. This item runs all + products with the \c "autotest" type when it is being built. It also implicitly depends on all + such products, so they will be built before running as well. + + Let's add this item to our top-level \l{Project} item: + + \code + Project { + name: "My Project" + minimumQbsVersion: "2.0" + // ... + AutotestRunner { + timeout: 60 + } + } + \endcode + Here we set the \l{AutotestRunner::timeout}{timeout} property to 60 seconds so that our runner + kills tests that run way too long. + + Now we need to add our first test. Let's create a new product with the following content: + + \snippet ../tutorial/chapter-5/test/test.qbs 0 + + Here we depend on our library (which we are going to test), set the product + \l{Product::name}{name}, and specify the source file, which looks like this: + \snippet ../tutorial/chapter-5/test/test.c 0 + + The test compares the value from the library with the value from the command line. + + Don't forget to add the new test product to the references property in the Project: + \snippet ../tutorial/chapter-5/myproject.qbs 0 + + Now we can build the autotest product - this will also launch our test: + \code + $ qbs build -p "autotest-runner" + ... + running test mytest [autotest-runner] + Build done for configuration default. + \endcode +*/ + +/*! + \previouspage tutorial-5.html + \page tutorial-6.html + \nextpage tutorial-7.html + + \title Project Properties + + It would be nice if our project was configurable. Let's add some properties to our root project + file: + \snippet ../tutorial/chapter-6/myproject.qbs 0 + + Now we can use those properties in our helper items and in products: + + \snippet ../tutorial/chapter-6/qbs/imports/MyApplication.qbs 0 + + Here, we access the project file using the special + \l{special-property-values.html#project}{project} value. If the nearest project in the project + tree does not have the desired property, \QBS looks it up in the parent project, potentially + all the way up to the top-level project. + We also use the \l{Application::installDebugInformation}{installDebugInformation} + property here. By default, it has the same value as \l{Application::install}{install} but we + want to make the debug information install optional. + + Let's now disable the tests if \c project.withTests is \c false: + + \snippet ../tutorial/chapter-6/myproject.qbs 1 + + Here we use the \l{Properties} item within the \l{SubProject} item. This item allows to + override a subproject's properties which can be useful when adding some other \QBS project as a + Git submodule. Of course, it is not very useful in our particular case since we only set the + \l{Project::condition}{Project.condition} property. We could achieve the same effect by + setting the \l{SubProject::condition}{condition} property of the \l{SubProject} item: + \code + SubProject { + filePath: "test/test.qbs" + condition: parent.withTests + } + \endcode + Another way would be to disable the test product. That way, an IDE would still show the whole + project tree including disabled tests: + \code + // qbs/imports/MyAutoTest.qbs + MyApplication { + condition: project.withTests + type: base.concat(["autotest"]) + } + \endcode + + Let's finally make our \l{AutotestRunner} configurable too: + \snippet ../tutorial/chapter-6/myproject.qbs 2 + + There are several ways to override project properties from the command line. First, the special + \c project variable can be used to set the properties of the top-level project: + \code + $ qbs resolve project.withTests:false + \endcode + + You can also refer to properties using project's \l{Project::name}{name}: + + \code + $ qbs resolve "projects.My Project.withTests:false" + \endcode + + This can again be useful for accessing the properties of external sub-projects. Note that since + the project name contains spaces, we use quotes here. +*/ + +/*! + \previouspage tutorial-6.html + \page tutorial-7.html + \nextpage tutorial-8.html + + \title Buildconfig Module + + In the previous chapter, we added some properties to our main \l{Project} file. While this is a + perfect approach for \e public properties of the project, sometimes we want + to add some \e private properties for better tuning. Of course, we could put everything + in the \l{Project} file, but that would make it very convoluted. Also, accessing the top-level + project all the way from products makes things strongly tied. + + You can also use a \l{Module} that \l{Product}{products} may depend on. That way, a + \l{Product} only uses properties of the module it depends on without the need to know about + the top-level project. + + Let's create a file named \c{mybuildconfig.qbs} and put it into the + \c{qbs/modules/mybuildconfig} directory, near the \c{qbs/imports} directory: + \code + // qbs/modules/mybuildconfig.qbs + Module { + } + \endcode + + So far, this is just an empty \l{Module} so let's add some properties to it: + \snippet ../tutorial/chapter-7/qbs/modules/mybuildconfig/mybuildconfig.qbs 0 + + We added the \c appInstallDir and \c libInstallDir properties that will allow us to configure + the installation location of the our application and library, respectively. + + Now we can use our module in the \c{MyApplication.qbs} item: + \snippet ../tutorial/chapter-7/qbs/imports/MyApplication.qbs 0 + + We pull in the new module using the \l{Depends} item, similar to how we pulled in + the \l{cpp} module dependency earlier. We also set the \l{Application::installDir}{installDir} + property to the corresponding module property, namely to \c{mybuildconfig.appInstallDir}. + + \QBS \l{Module}{modules} have the feature to automatically export properties of other modules. + Those exported properties are merged in the resulting product. We can use this feature to set + the \l{cpp::rpaths}{cpp.rpaths} in our module rather than in products: + + \snippet ../tutorial/chapter-7/qbs/modules/mybuildconfig/mybuildconfig.qbs 1 + + Here, we inject the dependency on the \l{cpp} module and calculate the \c{libRPaths} property. + This is a relative path from the \c{product.installDir} (which is either \c{"bin"} + or \c{"lib"}, depending on product type to \c{libInstallDir}). Finally, we set + \l{cpp::rpaths}{cpp.rpaths} to this property. This way, those \c rpaths will be automatically + exported to all products that depend on the \c{mybuildconfig} module. + + Now, we can also use our new module in the library item: + \snippet ../tutorial/chapter-7/qbs/imports/MyLibrary.qbs 0 + + Let's change the library folder name from \c{"lib"} to \c{"lib64"} when building our project: + \code + $ qbs modules.mybuildconfig.libDirName:lib64 + ... + $ ls default/install-root/usr/local/ + bin lib64 + \endcode +*/ + +/*! + \previouspage tutorial-7.html + \page tutorial-8.html + \nextpage tutorial-9.html + + \title Configurable Library + + In this chapter, we will make our library more configurable. We will add configuration options + to be able to choose between static and dynamic builds. + + We start with some new properties in the \c mybuildconfig module: + \code + Module { + ... + property bool staticBuild: false + property bool installStaticLib: true + ... + } + \endcode + + We need to do some modifications to export macros in the \c lib/lib_global.h header: + \snippet ../tutorial/chapter-8/lib/lib_global.h 0 + + Here' we added a new branch when \c MYLIB_STATIC_LIBRARY is defined. In that case, we make + the \c MY_LIB_EXPORT macro empty. + + Now, let's modify the \c qbs/imports/MyLibrary.qbs file as follows: + \snippet ../tutorial/chapter-8/qbs/imports/MyLibrary.qbs 0 + + First thing to notice is that we changed the type of the item from \l{DynamicLibrary} to the + \l{Library} item which is a common base item for dynamic and static libraries. + + Second, we change the \l{Product::type}{type} of the product so it depends on the \c staticBuild + property: + \code + type: mybuildconfig.staticBuild ? "staticlibrary" : "dynamiclibrary" + \endcode + + Third, we change our \e{export macro} to be different in the static and dynamic builds to + correspond with the changes we made to the \c lib_global.h: + \code + readonly property string _nameUpper : name.replace(" ", "_").toUpperCase() + property string libraryMacro: _nameUpper + "_LIBRARY" + property string staticLibraryMacro: _nameUpper + "_STATIC_LIBRARY" + cpp.defines: mybuildconfig.staticBuild ? [staticLibraryMacro] : [libraryMacro] + \endcode + + Note that in a static build we export the \c MYLIB_STATIC_LIBRARY macro so that the dependent + products will know whether they link to a static or dynamic library: + \code + Export { + ... + cpp.defines: exportingProduct.mybuildconfig.staticBuild + ? [exportingProduct.staticLibraryMacro] : [] + } + \endcode + + Now we can build our project in dynamic or static mode: + \code + $ qbs resolve modules.mybuildconfig.staticBuild:false && qbs build + ... + $ ls default/install-root/usr/local/lib/ + libmylib.1.0.0.so + libmylib.1.0.so + libmylib.1.so + libmylib.so + $ rm -r default + $ qbs resolve modules.mybuildconfig.staticBuild:true && qbs build + ... + $ $ ls default/install-root/usr/local/lib/ + libmylib.a + \endcode +*/ + +/*! + \previouspage tutorial-8.html + \page tutorial-9.html + \nextpage howtos.html + + \title Version Header + + To create new files, such as version headers, during the build, use \l{Rules}. Every command + \QBS executes, such as compile or linker commands, is described by a corresponding Rule in a + Module or a Product. + + In this section, we will create a simple header with a string constant based on the variable + in our project. + + First, we add this variable to our \c mybuildconfig module: + \snippet ../tutorial/chapter-9/qbs/modules/mybuildconfig/mybuildconfig.qbs 0 + + Next, we create a new file, \c{version.h.in}, located in the \c{version-header} directory. This + file contains the template for our header: + \snippet ../tutorial/chapter-9/version-header/version.h.in 0 + + Now we create a file called \c{version-header.qbs} in the same directory. This file contains + a \l{Product} with a \l{Rule} that turns the \c{version.h.in} into a real header. + Let's go through the contents of the file: + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 0 + + First, we import \l{TextFile Service}{TextFile}. We will need this class to read the template + and write the resulting header. Second, we declare a new \l{Product} named \c{"version_header"} + and with the \c{"hpp"} type. This is the type of the artifact we will create in the Rule. + Third, we add the dependency on the \c mybuildconfig module to use the new + \c mybuildconfig.productVersion variable. + + We also add a \l{Group} with the template file and assign the \c{version_h_in} tag to the file: + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 1 + + \QBS Rules work with file tags, instead of working with files directly, which makes + it easy to reuse rules. The name of the tag is chosen arbitrarily here. We could use the name + of the file as a tag, but to avoid confusion between file name and file tag, we use underscores + in the tag instead of dots. + + Now we can create a Rule itself: + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 2 + Here, we specify that our Rule takes files tagged as \c "version_h_in" and produces an + \l{Artifact} with the name \c "version.h" and tagged \c "hpp". By default, files are created in + the \l{Product::destinationDirectory}{Product.destinationDirectory} folder. We add the \c "hpp" + tag for the header as this is the tag the \l{cpp}{cpp module} uses for headers. That way, \QBS + can track changes and process our generated file the same way it treats all other + headers. Note that earlier we set the product type to \c "hpp" as well. \QBS requires that + artifact type should match the product type directly or be accessible via the chain of Rules. + Otherwise, the Rule won't be executed. For details, see the \l{Rules and Product Types} + section. + + The actual code generation happens in the \l{Rule::prepare}{Rule.prepare} script: + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 3 + + In this script, we create a \l {JavaScriptCommand} object and set some meta properties, such as + the description and highlight. For details about Commands, see + \l{Command and JavaScriptCommand}. In the sourceCode variable, we create a JavaScript + function that opens the \l{The inputs and outputs Variables}{input file}, reads its content + using the \l{TextFile Service}{TextFile} object, replaces the \c "${PRODUCT_VERSION}" + placeholder with the actual value in the \c product.mybuildconfig.productVersion variable, and + writes the resulting content into the \l{The inputs and outputs Variables}{output file}. + + Finally, we export the \l{Product::buildDirectory}{exportingProduct.buildDirectory} so that + products that depend on this product can include our generated header: + + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 4 + + The full content of the file should look like this: + + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 5 + + Let's now add our Product into the root project so \QBS will be aware of it: + \snippet ../tutorial/chapter-9/myproject.qbs 0 + + We also need to add the dependency on the \c "version_header" to our application: + \snippet ../tutorial/chapter-9/app/app.qbs 0 + + Now we can include the header in the \c main.c file and print the contents of the string + constant: + + \snippet ../tutorial/chapter-9/app/main.c 0 + + Let's try and run our application. You should see something like this: + \code + $ qbs run -p "My Application" + Starting target. Full command line: .../default/install-root/usr/local/bin/myapp + Hello, world + Hello from library + ProductVersion = 1.0.0 + \endcode +*/ |