diff options
24 files changed, 1908 insertions, 34 deletions
diff --git a/doc/doc.qbs b/doc/doc.qbs index 2a0e16587..a02e8f098 100644 --- a/doc/doc.qbs +++ b/doc/doc.qbs @@ -20,6 +20,7 @@ Product { "config/style/qt5-sidebar.html", "reference/**/*", "templates/**/*", + "images/**", ] Group { name: "main qdocconf file" diff --git a/doc/images/qbs-settings-gui.png b/doc/images/qbs-settings-gui.png Binary files differnew file mode 100644 index 000000000..197340882 --- /dev/null +++ b/doc/images/qbs-settings-gui.png diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc index 0be7781d5..b0374eb04 100644 --- a/doc/qbs.qdoc +++ b/doc/qbs.qdoc @@ -76,7 +76,7 @@ \li \l{List of Convenience Items} \endlist \li \l{List of Built-in Services} - \li \l{List of Command-line Tools} + \li \l{Command-Line Interface} \li \l{List of Modules} \li \l{Command and JavaScriptCommand} \endlist diff --git a/doc/reference/cli/builtin/cli-build.qdoc b/doc/reference/cli/builtin/cli-build.qdoc new file mode 100644 index 000000000..dd0489eb8 --- /dev/null +++ b/doc/reference/cli/builtin/cli-build.qdoc @@ -0,0 +1,115 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-build.html + \ingroup cli + + \title build + \brief Builds a project. + + \section1 Synopsis + + \code + qbs build [options] [[configuration-name] [property:value] ...] + \endcode + + \section1 Description + + Builds projects in one or more configurations. + + You can specify \l{Project Item}{project}, \l{Product Item}{product}, or + \l{List of Modules}{module} properties, as well as a \l{Profile Item} + {profile} separately for each configuration. + + This is the default command. + + If the build directory does not exist, it will be created. + + For more information, see \l{Building Applications}. + + \section1 Options + + \include cli-options.qdocinc all-products + \include cli-options.qdocinc build-directory + \include cli-options.qdocinc changed-files + \include cli-options.qdocinc check-outputs + \include cli-options.qdocinc check-timestamps + \include cli-options.qdocinc clean-install-root + \include cli-options.qdocinc command-echo-mode + \include cli-options.qdocinc dry-run + \include cli-options.qdocinc project-file + \include cli-options.qdocinc force-probe-execution + \include cli-options.qdocinc jobs + \include cli-options.qdocinc keep-going + \include cli-options.qdocinc less-verbose + \include cli-options.qdocinc log-level + \include cli-options.qdocinc log-time + \include cli-options.qdocinc more-verbose + \include cli-options.qdocinc no-install + \include cli-options.qdocinc products-specified + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc show-progress + \include cli-options.qdocinc wait-lock + + \section1 Parameters + + \include cli-parameters.qdocinc configuration-name + \include cli-parameters.qdocinc property + + \section1 Examples + + Builds the application specified by the \c .qbs file in the current + directory using the default profile: + + \code + qbs + \endcode + + Builds the application using four concurrent build jobs: + + \code + qbs -j 4 + \endcode + + Builds the default configuration of an application using the profile called + \c Android: + + \code + qbs build profile:Android + \endcode + + Builds the application using different \l{Module cpp}{cpp module} properties + for debug and release configurations. For the debug configuration, warnings + will cause the build to fail, whereas for the release configuration, the + size of the build artifacts will be optimized: + + \code + qbs build debug modules.cpp.treatWarningsAsErrors:true release modules.cpp.optimization:small + \endcode +*/ diff --git a/doc/reference/cli/builtin/cli-clean.qdoc b/doc/reference/cli/builtin/cli-clean.qdoc new file mode 100644 index 000000000..1aa07a802 --- /dev/null +++ b/doc/reference/cli/builtin/cli-clean.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-clean.html + \ingroup cli + + \title clean + \brief Removes the files generated during a build. + + \section1 Synopsis + + \code + qbs clean [options] [configuration-name] + \endcode + + \section1 Description + + Removes build \l{Artifact Item}{artifacts} for the specified build + configuration. + + \section1 Options + + \include cli-options.qdocinc build-directory + \include cli-options.qdocinc dry-run + \include cli-options.qdocinc keep-going + \include cli-options.qdocinc less-verbose + \include cli-options.qdocinc log-level + \include cli-options.qdocinc log-time + \include cli-options.qdocinc more-verbose + \include cli-options.qdocinc products-specified + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc show-progress + + \section1 Parameters + + \include cli-parameters.qdocinc configuration-name + + \section1 Examples + + Removes the build artifacts in the current directory for the default build + configuration: + + \code + qbs clean + \endcode +*/ diff --git a/doc/reference/cli/builtin/cli-dump-nodes-tree.qdoc b/doc/reference/cli/builtin/cli-dump-nodes-tree.qdoc new file mode 100644 index 000000000..fa5d4db29 --- /dev/null +++ b/doc/reference/cli/builtin/cli-dump-nodes-tree.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-dump-nodes-tree.html + \ingroup cli + + \title dump-nodes-tree + \brief Dumps the nodes in the build graph to \c stdout. + + \section1 Synopsis + + \code + qbs dump-nodes-tree [options] [[configuration-name] [property:value] ...] + \endcode + + \section1 Description + + Dumps the nodes in the build graph to \c stdout. + + This is an internal command that is used for debugging purposes only. + + \section1 Options + + \include cli-options.qdocinc build-directory + \include cli-options.qdocinc project-file + \include cli-options.qdocinc less-verbose + \include cli-options.qdocinc log-level + \include cli-options.qdocinc log-time + \include cli-options.qdocinc more-verbose + \include cli-options.qdocinc products-specified + \include cli-options.qdocinc settings-dir + + \section1 Parameters + + \include cli-parameters.qdocinc configuration-name + \include cli-parameters.qdocinc property + + \section1 Examples + + Dumps the nodes tree into a file called \c nodes-tree.log: + + \code + qbs dump-nodes-tree >nodes-tree.log + \endcode + +*/ diff --git a/doc/reference/cli/builtin/cli-generate.qdoc b/doc/reference/cli/builtin/cli-generate.qdoc new file mode 100644 index 000000000..3d7d4cdbf --- /dev/null +++ b/doc/reference/cli/builtin/cli-generate.qdoc @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-generate.html + \ingroup cli + + \title generate + \brief Invokes a project generator, for example to create project files for + another build tool. + + \section1 Synopsis + + \code + qbs generate [options] [[configuration-name] [property:value] ...] + \endcode + + \section1 Description + + Invokes a project generator, for example to create project files for another + build tool. + + For more information, see \l{Generators}. + + \section1 Options + + \include cli-options.qdocinc generator + \include cli-options.qdocinc build-directory + \include cli-options.qdocinc project-file + \include cli-options.qdocinc install-root + \include cli-options.qdocinc less-verbose + \include cli-options.qdocinc log-level + \include cli-options.qdocinc log-time + \include cli-options.qdocinc more-verbose + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc show-progress + + \section1 Parameters + + \include cli-parameters.qdocinc configuration-name + \include cli-parameters.qdocinc property + + \section1 Examples + + Generates a project for Microsoft Visual Studio: + + \code + qbs generate -g visualstudio2015 + \endcode + + Generates a \l{https://clang.llvm.org/docs/JSONCompilationDatabase.html} + {Clang compilation database (clangdb)}: + + \code + qbs generate --generator clangdb + \endcode +*/ diff --git a/doc/reference/cli/builtin/cli-help.qdoc b/doc/reference/cli/builtin/cli-help.qdoc new file mode 100644 index 000000000..c36d03317 --- /dev/null +++ b/doc/reference/cli/builtin/cli-help.qdoc @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-help.html + \ingroup cli + + \title help + \brief Shows general or command-specific help. + + \section1 Synopsis + + \code + qbs help [<command>] + \endcode + + \section1 Description + + Shows a list of available commands with descriptions. Specify a command + name to list the options that the command takes with descriptions. + + \section1 Options + + This command takes no options. + + \section1 Examples + + Shows an overview of all commands: + + \code + qbs help + \endcode + + Lists the options that the \c build command takes: + + \code + qbs help build + \endcode +*/ diff --git a/doc/reference/cli/builtin/cli-install.qdoc b/doc/reference/cli/builtin/cli-install.qdoc new file mode 100644 index 000000000..d68d4d922 --- /dev/null +++ b/doc/reference/cli/builtin/cli-install.qdoc @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-install.html + \ingroup cli + + \title install + \brief Installs a project. + + \section1 Synopsis + + \code + qbs install [options] [[configuration-name] [property:value] ...] + \endcode + + \section1 Description + + Install all files marked as installable to their respective destinations. + The project is built first, if necessary, unless the \c --no-build option is + given. + + For more information, see \l{Installing Files}. + + \section1 Options + + \include cli-options.qdocinc all-products + \include cli-options.qdocinc build-directory + \include cli-options.qdocinc changed-files + \include cli-options.qdocinc check-outputs + \include cli-options.qdocinc check-timestamps + \include cli-options.qdocinc clean-install-root + \include cli-options.qdocinc command-echo-mode + \include cli-options.qdocinc dry-run + \include cli-options.qdocinc project-file + \include cli-options.qdocinc force-probe-execution + \include cli-options.qdocinc install-root + \include cli-options.qdocinc jobs + \include cli-options.qdocinc keep-going + \include cli-options.qdocinc less-verbose + \include cli-options.qdocinc log-level + \include cli-options.qdocinc log-time + \include cli-options.qdocinc more-verbose + \include cli-options.qdocinc no-build + \include cli-options.qdocinc products-specified + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc wait-lock + + \section1 Parameters + + \include cli-parameters.qdocinc configuration-name + \include cli-parameters.qdocinc property + + \section1 Examples + +*/ diff --git a/doc/reference/cli/builtin/cli-resolve.qdoc b/doc/reference/cli/builtin/cli-resolve.qdoc new file mode 100644 index 000000000..fd2035f57 --- /dev/null +++ b/doc/reference/cli/builtin/cli-resolve.qdoc @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-resolve.html + \ingroup cli + + \title resolve + \brief Resolves a project without building it. + + \section1 Synopsis + + \code + qbs resolve [options] [[configuration-name] [property:value] ...] + \endcode + + \section1 Description + + Resolves a \l{Project Item}{project} in one or more configurations. Run this + command to change the properties of an existing build. + + \section1 Options + + \include cli-options.qdocinc build-directory + \include cli-options.qdocinc dry-run + \include cli-options.qdocinc project-file + \include cli-options.qdocinc force-probe-execution + \include cli-options.qdocinc jobs + \include cli-options.qdocinc less-verbose + \include cli-options.qdocinc log-level + \include cli-options.qdocinc log-time + \include cli-options.qdocinc more-verbose + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc show-progress + + \section1 Parameters + + \include cli-parameters.qdocinc configuration-name + \include cli-parameters.qdocinc property + + \section1 Examples + + Resolves the default configuration of the project in the current directory: + + \code + qbs resolve + \endcode +*/ diff --git a/doc/reference/cli/builtin/cli-run.qdoc b/doc/reference/cli/builtin/cli-run.qdoc new file mode 100644 index 000000000..5b9b6456a --- /dev/null +++ b/doc/reference/cli/builtin/cli-run.qdoc @@ -0,0 +1,94 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-run.html + \ingroup cli + + \title run + \brief Runs an executable generated by building a project. + + \section1 Synopsis + + \code + qbs run [options] [configuration-name] [property:value] ... [ -- <arguments>] + \endcode + + \section1 Description + + Runs the specified product's executable with the specified \c <arguments>. + If the project has only one product, the \c --products option may be + omitted. + + The product will be built if it is not up to date, unless the \c --no-build + option is specified. For more information, see \l{build}. + + For more information about running applications, see + \l{Running Applications}. + + \section1 Options + + \include cli-options.qdocinc all-products + \include cli-options.qdocinc build-directory + \include cli-options.qdocinc changed-files + \include cli-options.qdocinc check-outputs + \include cli-options.qdocinc check-timestamps + \include cli-options.qdocinc clean-install-root + \include cli-options.qdocinc command-echo-mode + \include cli-options.qdocinc dry-run + \include cli-options.qdocinc project-file + \include cli-options.qdocinc force-probe-execution + \include cli-options.qdocinc install-root + \include cli-options.qdocinc jobs + \include cli-options.qdocinc keep-going + \include cli-options.qdocinc less-verbose + \include cli-options.qdocinc log-level + \include cli-options.qdocinc log-time + \include cli-options.qdocinc more-verbose + \include cli-options.qdocinc no-build + \include cli-options.qdocinc products-specified + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc wait-lock + + \section1 Parameters + + \include cli-parameters.qdocinc configuration-name + \include cli-parameters.qdocinc property + + \section1 Arguments + + \include cli-parameters.qdocinc arguments + + \section1 Examples + + Runs the Qt Creator application: + + \code + qbs run --products qtcreator + \endcode +*/ diff --git a/doc/reference/cli/builtin/cli-shell.qdoc b/doc/reference/cli/builtin/cli-shell.qdoc new file mode 100644 index 000000000..d0b717901 --- /dev/null +++ b/doc/reference/cli/builtin/cli-shell.qdoc @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-shell.html + \ingroup cli + + \title shell + \brief Opens a shell with a product's environment. + + \section1 Synopsis + + \code + qbs shell [options] [configuration-name] [property:value] + \endcode + + \section1 Description + + Opens a shell in the environment that a build with the specified parameters + would use. + + For more information, see \l{Using the Shell}. + + \section1 Options + + \include cli-options.qdocinc build-directory + \include cli-options.qdocinc changed-files + \include cli-options.qdocinc check-outputs + \include cli-options.qdocinc check-timestamps + \include cli-options.qdocinc clean-install-root + \include cli-options.qdocinc command-echo-mode + \include cli-options.qdocinc dry-run + \include cli-options.qdocinc project-file + \include cli-options.qdocinc force-probe-execution + \include cli-options.qdocinc jobs + \include cli-options.qdocinc keep-going + \include cli-options.qdocinc less-verbose + \include cli-options.qdocinc log-level + \include cli-options.qdocinc log-time + \include cli-options.qdocinc more-verbose + \include cli-options.qdocinc no-install + \include cli-options.qdocinc products-specified + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc show-progress + \include cli-options.qdocinc wait-lock + + \section1 Parameters + + \include cli-parameters.qdocinc configuration-name + \include cli-parameters.qdocinc property + + \section1 Examples + + Opens a shell with the same environment that \QBS uses when building the + project: + + \code + qbs shell + \endcode +*/ diff --git a/doc/reference/cli/builtin/cli-status.qdoc b/doc/reference/cli/builtin/cli-status.qdoc new file mode 100644 index 000000000..ecafe3956 --- /dev/null +++ b/doc/reference/cli/builtin/cli-status.qdoc @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-status.html + \ingroup cli + + \title status + \brief Shows the status of files in the project directory. + + \section1 Synopsis + + \code + qbs status [options] [configuration-name] [property:value] + \endcode + + \section1 Description + + Lists all the files in the project directory and shows whether they are + known to \QBS in the respective configuration. + + \section1 Options + + \include cli-options.qdocinc build-directory + \include cli-options.qdocinc project-file + \include cli-options.qdocinc less-verbose + \include cli-options.qdocinc log-level + \include cli-options.qdocinc more-verbose + \include cli-options.qdocinc settings-dir + + \section1 Parameters + + \include cli-parameters.qdocinc configuration-name + \include cli-parameters.qdocinc property + + \section1 Examples + + To list the files in the project directory and view their status: + + \code + qbs status + \endcode +*/ diff --git a/doc/reference/cli/builtin/cli-update-timestamps.qdoc b/doc/reference/cli/builtin/cli-update-timestamps.qdoc new file mode 100644 index 000000000..6b15cc26b --- /dev/null +++ b/doc/reference/cli/builtin/cli-update-timestamps.qdoc @@ -0,0 +1,70 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-update-timestamps.html + \ingroup cli + + \title update-timestamps + \brief Marks the build as up-to-date. + + \section1 Synopsis + + \code + qbs update-timestamps [options] [[configuration-name] [property:value] ...] + \endcode + + \section1 Description + + Updates the timestamps of all build \l{Artifact Item}{artifacts}, causing + the next builds of the \l{Project Item}{project} to do nothing until source + files are updated again. + + This command is useful if you know that the current changes to source files + are irrelevant to the build. + + \note Using this command causes a discrepancy between the actual state of + source files and the information in the build graph, so be careful. + + \section1 Options + + \include cli-options.qdocinc build-directory + \include cli-options.qdocinc project-file + \include cli-options.qdocinc less-verbose + \include cli-options.qdocinc log-level + \include cli-options.qdocinc more-verbose + \include cli-options.qdocinc products-specified + \include cli-options.qdocinc settings + + \section1 Parameters + + \include cli-parameters.qdocinc configuration-name + \include cli-parameters.qdocinc property + + \section1 Examples +*/ diff --git a/doc/reference/cli/cli-options.qdocinc b/doc/reference/cli/cli-options.qdocinc new file mode 100644 index 000000000..2b8c751cf --- /dev/null +++ b/doc/reference/cli/cli-options.qdocinc @@ -0,0 +1,461 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + +//! [all-products] + + \section2 \c --all-products + + Processes all \l{Product Item}{products}, even if their \c builtByDefault + property is \c false. + +//! [all-products] + +//! [blacklist] + + \section2 \c {--blacklist <blacklist>} + + Ignores files whose names match the patterns specified by \c <blacklist>. + The list entries can contain wildcards and are separated by commas. + + By default, no files are ignored. + +//! [blacklist] + +//! [build-directory] + + \section2 \c {--build-directory|-d <directory>} + + Specifies a \c <directory> where build artifacts are stored. + + The default value is the current directory unless + \c preferences.defaultBuildDirectory is set. + + Relative paths will be interpreted relative to the current directory. + + You can use the following special values as placeholders: + + \list + \li \c @project is expanded to the name of the project file excluding + the extension \c .qbs. + \li \c @path is expanded to the name of the directory containing the + project file. + \endlist + +//! [build-directory] + +//! [changed-files] + + \section2 \c {--changed-files <file>[,<file>...]} + + Assumes that the files specified by \c <file>, and only those files, have + changed. + +//! [changed-files] + +//! [check-outputs] + + \section2 \c --check-outputs + + Forces transformer output \l{Artifact Item}{artifact} checks. + + Verifies that the output artifacts declared by \l{Rule Item}{rules} in the + \l{Project Item}{project} are actually created. + +//! [check-outputs] + +//! [check-timestamps] + + \section2 \c --check-timestamps + + Forces timestamp checks. + + Retrieves the timestamps from the file system, instead of using the file + timestamps that are stored in the build graph. + +//! [check-timestamps] + +//! [clean-install-root] + + \section2 \c --clean-install-root + + Removes the installation base directory before installing. + +//! [clean-install-root] + +//! [command-echo-mode] + + \section2 \c {--command-echo-mode <mode>} + + Determines what kind of output to show when executing commands. + + Possible values of \c <mode> are: + + \list + \li \c silent + \li \c summary (default value) + \li \c command-line + \li \c command-line-with-environment + \endlist + +//! [command-echo-mode] + +//! [detect-qt-versions] + + \section2 \c --detect + + Attempts to auto-detect all known Qt versions, looking them up in the PATH + environment variable. + +//! [detect-qt-versions] + +//! [detect-toolchains] + + \section2 \c --detect + + Attempts to auto-detect all known toolchains, looking them up in the PATH + environment variable. + +//! [detect-toolchains] + +//! [dry-run] + + \section2 \c --dry-run|-n + + Performs a dry run. No commands will be executed and no permanent changes to + the build graph will be done. + +//! [dry-run] + +//! [export] + + \section2 \c {--export <file>} + + Exports settings to the specified \c <file>. + +//! [export] + +//! [project-file] + + \section2 \c {[--file|-f <file>]} + + Uses \c <file> as the project file. If \c <file> is a directory and it + contains a single file with the extension \c .qbs, that file will be used. + + If this option is not given at all, the behavior is the same as for + \c{-f <working-dir>}. + +//! [project-file] + +//! [flat] + + \section2 \c --flat + + Does not create nested project files, even if there are subdirectories and + the top-level directory does not contain any files. + +//! [flat] + +//! [force-probe-execution] + + \section2 \c --force-probe-execution + + Forces re-execution of all \l{Probe Item}{Probe items}' configure scripts, + rather than using the cached data. + +//! [force-probe-execution] + +//! [generator] + + \section2 \c {--generator|-g <generator>} + + Uses the specified build system generator. + + Possible values of \c <generator> include: + + \list + \li \c clangdb + \li \c visualstudio2015 + \endlist + + The available generators are listed if you run the \c {qbs generate} command + without passing a generator to it. + +//! [generator] + +//! [help] + + \section2 \c {--help|-h|-?} + + Displays help for the command. + +//! [help] + +//! [import] + + \section2 \c {--import <file>} + + Imports settings from the specified \c <file>. + +//! [import] + +//! [install-root] + + \section2 \c {--install-root <directory>} + + Installs into the specified \c <directory>. If the directory does not exist, + it will be created. + + The default value is \c <build dir>/install-root. + + Use the special value \c @sysroot to install into the \c sysroot. That is, + the value of the \l{Module qbs}{qbs.sysroot} property. + +//! [install-root] + +//! [jobs] + + \section2 \c {--jobs|-j <n>} + + Uses \c <n> concurrent build jobs, where \c <n> must be an integer greater + than zero. + + The default is the number of logical cores. + +//! [jobs] + +//! [keep-going] + + \section2 \c --keep-going|-k + + Keeps going when errors occur, if at all possible. + +//! [keep-going] + +//! [less-verbose] + + \section2 \c --less-verbose|-q + + Becomes more quiet by decreasing the log level by one. This option can be + given more than once. Excessive occurrences have no effect. + + If the option \c --log-level appears anywhere on the command line in + addition to this option, its value is taken as the base for the decrease. + +//! [less-verbose] + +//! [list-root] + + \section2 \c {--list [<root> ...]} + + Lists keys under the key \c <root> or all keys if the root is not specified. + + Possible values are: + + \list + \li \c defaultProfile is the default \l{Profile Item}{profile} to use + if a profile is not specified + \li \c preferences accepts build preferences as second-level keys + \li \c profiles accepts profile names as second-level keys + + \endlist + +//! [list-root] + +//! [log-level] + + \section2 \c {--log-level <level>} + + Uses the specified log level. + + Possible values of \c <level> are: + + \list + \li \c error + \li \c warning + \li \c info (default value) + \li \c debug + \li \c trace + \endlist + +//! [log-level] + +//! [log-time] + + \section2 \c --log-time + + Logs the time that the operations involved in this command take. + + This option is implied in log levels \c debug and higher. + + This option is mutually exclusive with \c --show-progress. + +//! [log-time] + +//! [more-verbose] + + \section2 \c --more-verbose|-v + + Becomes more verbose by increasing the log level by one. This option can be + given more than once. Excessive occurrences have no effect. + + If the option \c --log-level appears anywhere on the command line in + addition to this option, its value is taken as the base for the increase. + +//! [more-verbose] + +//! [ndk-dir] + + \section2 \c {--ndk-dir <directory>} + + Specifies a \c <directory> that contains an Android NDK. + +//! [ndk-dir] + +//! [no-build] + + \section2 \c --no-build + + Does not re-build the project before installing or running it. + +//! [no-build] + +//! [no-install] + + \section2 \c --no-install + + Does not install any artifacts as part of the build process. + +//! [no-install] + +//! [products-specified] + + \section2 \c {--products|-p <name>[,<name>...]} + + Takes only the \l{Product Item}{products} specified by \c <name> and their + dependencies into account. + +//! [products-specified] + +//! [qt-dir] + + \section2 \c {--qt-dir <directory>} + + Specifies a \c <directory> that contains a Qt version. + +//! [qt-dir] + +//! [sdk-dir] + + \section2 \c {--sdk-dir <directory>} + + Specifies a \c <directory> that contains an Android SDK. + +//! [sdk-dir] + +//! [settings-dir] + + \section2 \c {--settings-dir <directory>} + + Reads all settings (such as \l{Profile Item}{profile} information) from the + specified \c <directory>. If the directory does not exist, it will be + created. + + The default value is system-specific. For example: + + \list + \li Linux: \c $HOME/.config/QtProject/qbs + \li Windows: \c %APPDATA%\QtProject\qbs + \li macOS: \c $HOME/Library/Preferences/qbs + \endlist + +//! [settings-dir] + +//! [show-progress] + + \section2 \c --show-progress + + Shows how command execution is progressing. + + This option is mutually exclusive with \c --log-time. + + \note This option is not available on a Windows host. + +//! [show-progress] + +//! [type] + + \section2 \c {--type <toolchain type>} + + Specifies the type of the toolchain. Needed if \QBS cannot determine the + compiler from the name of the executable file located in the specified + directory. + + Possible values include: + + \list + \li \c clang + \li \c gcc + \li \c mingw + \li \c msvc + \endlist + +//! [type] + +//! [unset] + + \section2 \c {--unset <key>} + + Removes the specified \c <key>. + +//! [unset] + +//! [wait-lock] + + \section2 \c --wait-lock + + Waits indefinitely for other processes to release the build graph lock. + + This option is typically used by \l{Generators}{generators}, which may + re-invoke multiple \QBS processes on the same project simultaneously. + +//! [wait-lock] + +//! [whitelist] + + \section2 \c {--whitelist <whitelist>} + + Considers only files whose names match the patterns specified by + \c <whitelist>. The list entries can contain wildcards and are separated by + commas. + + By default, all files are considered. + +//! [whitelist] + +*/ diff --git a/doc/reference/cli/cli-parameters.qdocinc b/doc/reference/cli/cli-parameters.qdocinc new file mode 100644 index 000000000..bf1d67a11 --- /dev/null +++ b/doc/reference/cli/cli-parameters.qdocinc @@ -0,0 +1,92 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! + +//! [arguments] + + \section2 \c -- <arguments> + + Command-line arguments to be passed to the program to be run. + +//! [arguments] + + +//! [configuration-name] + + \section2 \c configuration-name + + Specifies the build configuration to use. + + The \c debug and \c release configuration names imply the respective build + variant. A debug build contains additional debug symbols that are needed for + debugging the application but that can be left out from the release + version. Generally, debug builds are used for testing and release builds + for creating the final installation file. + + The build variant can also be specified explicitly by using the + \l{Module qbs}{qbs.buildVariant} property. + + When naming configurations created for special purposes, follow the + rules for legal names generally used in programming languages: + + \list + \li The first character must be a letter (a-z), an underscore (_), or a + dollar sign ($). + \li Subsequent characters may be letters, digits, underscores, or dollar + signs. + \endlist + +//! [configuration-name] + +//! [key] + + \section2 \c <key> + + Typically, a \c <key> consists of several levels separated by periods. The + first level shows a \e root value, such as \e preferences or \e profiles. + The root determines whether the second-level keys are build preferences or + profile names. The lower level keys consist of a module name, followed by a + property name. + +//! [key] + +//! [property] + + \section2 \c {property:value} + + Property values set in project files or profiles can be overridden on the + command line. The syntax is: + + \code + <prefix>.<property-name>:<property-value> + \endcode + + For more information, see + \l{Overriding Property Values from the Command Line}. + +//! [property] +*/ diff --git a/doc/reference/cli/cli.qdoc b/doc/reference/cli/cli.qdoc new file mode 100644 index 000000000..c93b51cd0 --- /dev/null +++ b/doc/reference/cli/cli.qdoc @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage reference.html + \group cli + + \title Command-Line Interface + \brief A list of available command-line commands. + + The \c qbs command-line commands can be invoked as \c{qbs <command_name>}. + + This reference summarizes the command-line commands. The authoritative + source of up-to-date information is the respective help screen, which you + get by calling \c{qbs help <command_name>}. + + Some commands are described in context in the \l{Usage} section of the + manual. +*/ diff --git a/doc/reference/cli/tools/cli-config-ui.qdoc b/doc/reference/cli/tools/cli-config-ui.qdoc new file mode 100644 index 000000000..29c0ed732 --- /dev/null +++ b/doc/reference/cli/tools/cli-config-ui.qdoc @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-config-ui.html + \ingroup cli + + \title config-ui + \brief Opens a GUI application for managing \QBS settings, such as + preferences and profiles. + + \section1 Synopsis + + \code + qbs config-ui [--settings-dir <directory>] + \endcode + + \section1 Description + + Opens the \QBS Settings application for managing \QBS settings, such as + preferences and profiles, in a hierarchical view. This makes it easier to + manage a large number of settings than using the \l{config} command from + the command line. + + \image qbs-settings-gui.png + + For more information, see \l{Configuring}. + + \section1 Options + + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc help + + \section1 Examples + + Opens \QBS Settings: + + \code + qbs config-ui + \endcode + +*/ diff --git a/doc/reference/cli/tools/cli-config.qdoc b/doc/reference/cli/tools/cli-config.qdoc new file mode 100644 index 000000000..0d2ba9989 --- /dev/null +++ b/doc/reference/cli/tools/cli-config.qdoc @@ -0,0 +1,104 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-config.html + \ingroup cli + + \title config + \brief Manages \QBS settings, such as preferences and profiles. + + \section1 Synopsis + + \code + qbs config [--settings-dir <directory>] [--list [<root> ...]] + [--unset <key>] [--export <file>] [--import <file>] + qbs config [--settings-dir <directory>] <key> + qbs config [--settings-dir <directory>] <key> <value> + \endcode + + \section1 Description + + Manages \QBS settings, such as preferences and profiles. You can list all + keys and remove the specified key, as well as import settings from a file + or export them to a file. + + The second form of this command displays the specified \c <key>. + + The third form sets the specified \c <key> with the specified \c <value>. + + You can use the \l{config-ui} command to open the Qbs Settings tool for + managing settings in a hierarchical view. + + For more information, see \l{Configuring}, \l{Managing Qt Versions}, + \l{Modules}, \l {List of Modules}, and \l{Custom Modules and Items}. + + \section1 Options + + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc list-root + \include cli-options.qdocinc unset + \include cli-options.qdocinc export + \include cli-options.qdocinc import + \include cli-options.qdocinc help + + \section1 Parameters + + \include cli-parameters.qdocinc key + + \section1 Examples + + Lists the existing profiles: + + \code + qbs config --list profiles + \endcode + + Shows the default profile: + + \code + qbs config defaultProfile + \endcode + + \note If no output is shown, the default profile used is the built-in + profile \c none, which sets no properties. + + Sets the profile called \c gcc as the base profile of the Qt profile called + \c myqt: + + \code + qbs config profiles.myqt.baseProfile gcc + \endcode + + Adds the location of a custom module to your preferences, to make the module + accessible in several projects: + + \code + qbs config preferences.qbsSearchPaths /usr/local/share/custom-qbs-extensions + \endcode +*/ diff --git a/doc/reference/cli/tools/cli-create-project.qdoc b/doc/reference/cli/tools/cli-create-project.qdoc new file mode 100644 index 000000000..db3af2284 --- /dev/null +++ b/doc/reference/cli/tools/cli-create-project.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-create-project.html + \ingroup cli + + \title create-project + \brief Creates a \QBS project from an existing set of source files. + + \section1 Synopsis + + \code + qbs create-project [--blacklist <blacklist>] [--whitelist <whitelist>] + [--flat] + \endcode + + \section1 Description + + Automatically generates \QBS project files from an arbitrary directory + structure. You can filter the files to add to the project by blacklisting + or whitelisting them. The command creates nested project files, unless you + use the \c --flat option. + + This is a useful starting point when migrating from other build tools, such + as qmake or CMake. + + \note Run this command from the project directory. + + After generating the initial .qbs files, add the missing configuration + variables and functions to them. + + \section1 Options + + \include cli-options.qdocinc blacklist + \include cli-options.qdocinc whitelist + \include cli-options.qdocinc flat + \include cli-options.qdocinc help + + \section1 Examples + + Creates \c .qbs files in the project directory when run from there: + + \code + qbs create-project + \endcode +*/ diff --git a/doc/reference/list-of-tools.qdoc b/doc/reference/cli/tools/cli-setup-android.qdoc index 5f27a8ee7..8994ac21b 100644 --- a/doc/reference/list-of-tools.qdoc +++ b/doc/reference/cli/tools/cli-setup-android.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of Qbs. @@ -26,46 +26,44 @@ ****************************************************************************/ /*! - \contentspage reference.html - \page list-of-tools.html + \contentspage cli.html + \page cli-setup-android.html + \ingroup cli - \title List of Command-line Tools - \brief Auxiliary tools + \title setup-android + \brief Creates \QBS profiles for Android SDK and NDK installations. - In addition to the \c qbs command itself, a number of auxiliary tools are provided. Their file - names follow the pattern \c{qbs-<tool name>}, and they can be invoked either using that file - name or as \c{qbs <tool name>}. + \section1 Synopsis - This page is intended to give a short overview of these tools. For the supported parameters, - see the respective help screen, which you get by calling \c{qbs help <tool name>}. + \code + qbs setup-android [--settings-dir <directory>] [--ndk-dir <directory>] + [--sdk-dir <directory>] [--qt-dir <directory>] + <profile name> + \endcode - \section1 config - - Manages \QBS settings like preferences and profiles. - - \section1 create-project - - Creates a \QBS project from an existing set of source files. - - \section1 config-ui - - Like \c config, but with a graphical user interface. - - \section1 qmltypes - - Dumps information about the QML types supplied by \QBS. This is not intended as documentation - for users, but as tooling support. - - \section1 setup-android + \section1 Description Creates \QBS profiles for Android SDK and NDK installations. - \section1 setup-qt + If a Qt path is given, these additional profiles will be suitable for + building Qt binaries for the respective architecture, if the Qt + installation has support for it. + + \section1 Options - Creates \QBS profiles for Qt installations. + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc ndk-dir + \include cli-options.qdocinc sdk-dir + \include cli-options.qdocinc qt-dir + \include cli-options.qdocinc help - \section1 setup-toolchains + \section1 Examples - Creates \QBS profiles for toolchains like GCC or MSVC. + Creates a profile with the name \c oreo that specifies the target platforms' + \l{Module qbs}{architectures} and operating systems, as well as the + toolchains available: + \code + qbs setup-android oreo + \endcode */ diff --git a/doc/reference/cli/tools/cli-setup-qt.qdoc b/doc/reference/cli/tools/cli-setup-qt.qdoc new file mode 100644 index 000000000..9673286b3 --- /dev/null +++ b/doc/reference/cli/tools/cli-setup-qt.qdoc @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-setup-qt.html + \ingroup cli + + \title setup-qt + \brief Creates \QBS profiles for Qt installations. + + \section1 Synopsis + + \code + qbs setup-qt [--settings-dir <directory>] --detect + qbs setup-qt [--settings-dir <directory>] <path to qmake> <profile name> + \endcode + + \section1 Description + + Creates \QBS profiles for Qt installations. + + The first form tries to auto-detect all known Qt versions, looking them up + via the PATH variable. + + The second form creates a profile with the name \c {<profile name>} for the + Qt version located at \c {<path to qmake>}. + + For more information, see \l{Managing Qt Versions}. + + \section1 Options + + \include cli-options.qdocinc detect-qt-versions + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc help + + \section1 Examples + + Looks up Qt versions in the PATH and creates profiles for them: + + \code + qbs setup-qt --detect + \endcode + + Creates a profile called \c myqt for the Qt version located in + \c /usr/bin/qmake: + + \code + qbs setup-qt /usr/bin/qmake myqt + \endcode +*/ diff --git a/doc/reference/cli/tools/cli-setup-toolchains.qdoc b/doc/reference/cli/tools/cli-setup-toolchains.qdoc new file mode 100644 index 000000000..15490cc2a --- /dev/null +++ b/doc/reference/cli/tools/cli-setup-toolchains.qdoc @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage cli.html + \page cli-setup-toolchains.html + \ingroup cli + + \title setup-toolchains + \brief Creates \QBS profiles for toolchains, such as GCC or MSVC. + + \section1 Synopsis + + \code + qbs setup-toolchains [--settings-dir <directory>] --detect + qbs setup-toolchains [--settings-dir <directory>] [--type <toolchain type>] + <compiler path> <profile name> + \endcode + + \section1 Description + + The first form tries to auto-detect all known toolchains, looking them up + via the PATH variable. + + The second form creates a profile with the name \c {<profile name>} for the + toolchain located at \c {<compiler path>}. It will attempt to + determine the toolchain type automatically based on the file name or the + compiler executable. If that fails, you need to provide the compiler type as + a value of the \c --type option. + + For more information, see \l{Configuring}. + + \section1 Options + + \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc detect-toolchains + \include cli-options.qdocinc type + \include cli-options.qdocinc help + + \section1 Examples + + Looks up toolchains via the PATH variable and creates profiles for them: + + \code + qbs setup-toolchains --detect + \endcode + + Creates a profile called \c mingw for the toolchain located in + \c C:\mingw530_32\bin on Windows: + + \code + qbs setup-toolchains C:\mingw530_32\bin\g++.exe mingw + \endcode + + Creates a profile called \c g++-mingw-w64 for the toolchain located in + \c /usr/bin/x86_64-w64-mingw32-g++ g++-mingw-w64 on Ubuntu: + + \code + qbs setup-toolchains /usr/bin/x86_64-w64-mingw32-g++ g++-mingw-w64 + \endcode +*/ diff --git a/doc/reference/reference.qdoc b/doc/reference/reference.qdoc index f6222601b..d87efe32e 100644 --- a/doc/reference/reference.qdoc +++ b/doc/reference/reference.qdoc @@ -39,7 +39,7 @@ \li \l{List of Convenience Items} \endlist \li \l{List of Built-in Services} - \li \l{List of Command-line Tools} + \li \l{Command-Line Interface} \li \l{List of Modules} \li \l{Command and JavaScriptCommand} \endlist |
