From 7ab0658e79f44e98dba9baba05c3e704adc4d0ee Mon Sep 17 00:00:00 2001 From: Arttu Tarkiainen Date: Wed, 5 Aug 2020 18:01:38 +0300 Subject: Add command line interface documentation Task-number: QTIFW-1724 Change-Id: Ief40dc548e93cd189e3b3ca016652c8641face1e Reviewed-by: Tarja Sundqvist Reviewed-by: Iikka Eklund --- doc/installerfw-reference.qdoc | 5 +- doc/installerfw-using.qdoc | 118 ++++++++++++++++++++++++++- doc/installerfw.qdoc | 181 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 300 insertions(+), 4 deletions(-) diff --git a/doc/installerfw-reference.qdoc b/doc/installerfw-reference.qdoc index 1b031f3ce..cb90f1189 100644 --- a/doc/installerfw-reference.qdoc +++ b/doc/installerfw-reference.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. +** Copyright (C) 2020 The Qt Company Ltd. ** Contact: http://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. @@ -29,7 +29,7 @@ \contentspage {index.html}{Qt Installer Framework} \previouspage Qt Installer Framework Examples \page ifw-reference.html - \nextpage ifw-globalconfig.html + \nextpage ifw-cli.html \title Reference @@ -37,6 +37,7 @@ Framework: \list + \li \l{Command Line Interface} \li \l{Configuration File} \li \l{Package Directory} \li \l{Controller Scripting} diff --git a/doc/installerfw-using.qdoc b/doc/installerfw-using.qdoc index e851eb230..de354d32b 100644 --- a/doc/installerfw-using.qdoc +++ b/doc/installerfw-using.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2018 The Qt Company Ltd. +** Copyright (C) 2020 The Qt Company Ltd. ** Contact: http://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. @@ -55,6 +55,8 @@ \li \l{Specifying Settings} + \li \l{Using from Command Line} + \endlist */ @@ -339,7 +341,7 @@ \contentspage index.html \previouspage ifw-use-cases-update.html \page ifw-use-cases-settings.html - \nextpage ifw-tutorial.html + \nextpage ifw-use-cases-cli.html \title Specifying Settings @@ -371,3 +373,115 @@ available. */ + +/*! + \contentspage index.html + \previouspage ifw-use-cases-settings.html + \page ifw-use-cases-cli.html + \nextpage ifw-tutorial.html + + \title Using from Command Line + + Qt Installer Framework 4.0.0 introduces a new command line interface workflow. Most + of the end user use cases can now be performed using a text based interface, either + interactively, or unattended by specifying the desired options beforehand. This + topic describes the basic use cases. For more information about the syntax + and a description of all supported options, see \l{Command Line Interface}. + + \section1 Installing Components + + Both the installer and the maintenance tool support installation of new components from + command line. The following will install the components given as an argument and + their respective dependencies: + + \code + maintenancetool.exe install componentA componentB componentC + \endcode + + If no components are specified, the default set of components will be installed instead. + This includes components with elements \c or \c set to \c true. + The default installation can be only done with an installer binary. The \c --root option can be + used to select an installation target directory: + + \code + installer.exe --root "C:\Users\MyUser\MyInstallation" install + \endcode + + \section1 Checking for Available Updates + + To print information about available component updates, run the \c check-updates + command with the maintenance tool: + + \code + maintenancetool.exe check-updates + \endcode + + \section1 Updating Components + + Running \c update without arguments will update all components that have an update + available. Essential components are always updated first, same way as it is done when + launching updater from GUI. To update only a specific subset of installed components, + they can be provided as an optional argument for \c update: + + \code + maintenancetool.exe update componentA componentB + \endcode + + \section1 Uninstalling Components + + The \c remove command can be used to uninstall selected components. This will + automatically uninstall their children and other components depending on the + components about to be uninstalled: + + \code + // This would also automatically uninstall componentC.subcomponent1, componentC.subcomponent2,... + maintenancetool.exe remove componentC + \endcode + + \section1 Listing Installed Components + + To get a list and print additional information about currently installed components, run the + \c list command with the maintenance tool: + + \code + maintenancetool.exe list + \endcode + + \section1 Searching for Available Components + + The \c search command can be used to search components from available repositories, or + from integrated binary content in case of an offline installer. It can be used with + no arguments to list all available components or with a regular expression to get a list + of only components matching the pattern: + + \code + installer.exe search "expression" + \endcode + + \section1 Performing Full Uninstallation + + To uninstall all components and remove the program directory, including maintenance tool, + run \c purge command: + + \code + maintenancetool.exe purge + \endcode + + \section1 Unattended Usage + + By default, the generated installers may ask for additional information during installation, + which requires user attention. Unattended usage is possible by providing all information + beforehand with appropriate options: + + \code + installer.exe --root "C:\MyInstallation" --accept-licenses --default-answer install componentA + \endcode + + In this example, \c --accept-licenses is used to automatically accept all license agreements + required by components to be installed. The \c --default-answer option is used to answer all + message queries with their default answer. Alternatively, \c --accept-messages and \c --reject-messages + can be used to accept or reject all message queries. To provide unique answers for individual + queries, for example to confirm overwriting of an existing directory, you could use + \c {--auto-answer OverwriteTargetDirectory=Yes}. Automatic answers are shown on the + console output and installation log. +*/ diff --git a/doc/installerfw.qdoc b/doc/installerfw.qdoc index 657d0d3db..33afb951e 100644 --- a/doc/installerfw.qdoc +++ b/doc/installerfw.qdoc @@ -57,6 +57,7 @@ \li \l{Removing Components} \li \l{Updating Components} \li \l{Specifying Settings} + \li \l{Using From Command Line} \endlist \li \l{Tutorial: Creating an Installer} \li \l{Creating Installers} @@ -69,6 +70,7 @@ \li \l{Qt Installer Framework Examples} \li \l{Reference} \list + \li \l{Command Line Interface} \li \l{Configuration File} \li \l{Package Directory} \li \l{Controller Scripting} @@ -136,6 +138,185 @@ /*! \contentspage index.html \previouspage ifw-reference.html + \page ifw-cli.html + \nextpage ifw-globalconfig.html + + \title Command Line Interface + + Installers created with the Qt Installer Framework have the following command + line interface syntax: + + \code + installer.exe [options] command + \endcode + + Here \c [options] is one or a combination of supported options in either short + or long form. In addition some options may require mandatory value(s) that can + be passed using the assignment operator or space. + + The \c command is one of the supported command line installer operations to be + run headless in text mode. Some commands may be provided with optional \c + separated by space. The \c list is used to set internal key-value + pairs by the framework. + + \section1 Summary of Options + + Options marked with \c CLI are only available when running in headless mode, + the rest of the options can be used also in graphical mode. For the most + up-to-date list of available options with a specific version of Qt Installer + Framework, refer \c --help option output of \l installerbase. + + \table + \header + \li Option + \li Usage + \row + \li -?, -h, --help + \li Displays help. + \row + \li -v, --version + \li Displays version information. + \row + \li -d, --verbose + \li Verbose mode. Prints out more information. + \row + \li -g, --logging-rules + \li Enables logging according to passed rules. Comma separated logging rules + have the following syntax: \c{loggingCategory=true/false}. Passing empty logging + rules enables all logging categories. The following rules enable a single + category: \c{ifw.*=false, ifw.category=true}. The available logging categories + can be referenced with --help option. + \row + \li --ar, --add-repository + \li Add a local or remote repository to the list of user defined repositories. + \row + \li --at, --add-temp-repository + \li Add a local or remote repository to the list of temporary available repositories. + \row + \li --st, --set-temp-repository + \li Set a local or remote repository as temporary repository, it is the only one + used during fetch. Note: a URI must be prefixed with the protocol, i.e. file:///, + https://, http:// or ftp://. + \row + \li --sp, --system-proxy + \li Use system proxy on Windows and Linux. This option has no effect on macOS. (Default) + \row + \li --np, --no-proxy + \li Do not use system proxy. + \row + \li --su, --start-updater + \li Start application in updater mode. This will override the internal marker that is used + to distinguish which kind of binary is currently running. + \row + \li --sm, --start-package-manager + \li Start application in package manager mode. This will override the internal marker + that is used to distinguish which kind of binary is currently running. + \row + \li --sr, --start-uninstaller + \li Start application in uninstaller mode. This will override the internal marker + that is used to distinguish which kind of binary is currently running. + \row + \li -t, --root + \li [CLI] Set the installation root directory. + \row + \li -p, --platform + \li Use the specified platform plugin. + \row + \li --nf, --no-force-installations + \li Allow deselecting components that are marked as forced. + \row + \li --no-default-installations + \li Deselects components that are marked as default. + \row + \li --ns, --no-size-checking + \li Disable checking of free space for the installation target. + \row + \li --sv, --show-virtual-components + \li Show virtual components in the installer and the package manager. + \row + \li -i, --install-compressed-repository + \li Installs a QBSP or a 7z file. The QBSP (Board Support Package) file must be a .7z file + which contains a valid repository. + \row + \li -c, --create-local-repository + \li Create a local repository inside the installation directory. This option has no + effect on online installers. + \row + \li --accept-messages + \li [CLI] Accepts all message queries without user input. + \row + \li --reject-messages + \li [CLI] Rejects all message queries without user input. + \row + \li --auto-answer + \li [CLI] Automatically answers the message queries with the message identifier and a button + value. Several \c{identifier=value} pairs can be given separated with a comma, for example + \c{--auto-answer message.id=Ok,message.id2=Cancel}. + \row + \li --default-answer + \li [CLI] Automatically answers to message queries with their default values. + \row + \li --accept-licenses + \li [CLI] Accepts all licenses without user input. + \row + \li --file-query + \li [CLI] Automatically sets the QFileDialog values getExistingDirectory() or + getOpenFileName() requested by the install script. Several \c{identifier=value} pairs can be + given separated with a comma, for example \c{--file-query filedialog.id=C:Temp,filedialog.id2=C:Temp2}. + \row + \li -s, --script + \li Execute the script given as an argument. + \row + \li --ss, --start-server + \li Starts the application as headless process waiting for commands to execute. Mode can + be DEBUG or PRODUCTION. In the DEBUG mode, the option values can be omitted. Note: The + server will not shutdown on its own, you need to quit the process by hand. + \row + \li --sc, --start-client + \li Starts the application to debug the client-server communication. If a value is + omitted, the client will use a default instead. Note: The server process is not started + by the client application in that case, you need to start it on your own. + \row + \li -q, --squish-port + \li Give a port where Squish can connect to. If no port is given, default port 11233 is used. + Note: To enable Squish support, you first need to build IFW with SQUISH_PATH parameter + where SQUISH_PATH is pointing to your Squish installation folder: + \c{/bin/qmake -r SQUISH_PATH=}. + \endtable + + \section1 Summary of Commands + + \table + \header + \li Command + \li Usage + \row + \li in, install + \li Install packages given as an argument. If no packages are given, install the default package set. + \row + \li ch, check-updates + \li Show information about available updates on the maintenance tool. + \row + \li up, update + \li Update packages given as an argument. If no packages are given, install all available updates. + \row + \li rm, remove + \li Uninstall selected packages and their child components. + \row + \li li, list + \li List information about currently installed packages. + \row + \li se, search + \li Search available packages. If no search pattern is given, show all available packages. + \row + \li pr, purge + \li Uninstall all packages and remove the program directory. + \endtable +*/ + +/*! + \contentspage index.html + \previouspage ifw-cli.html \page ifw-globalconfig.html \nextpage ifw-component-description.html -- cgit v1.2.3