From ed95b3e6a1a0902d2a27714318c7b37adb21dcb6 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Fri, 7 Aug 2020 16:33:55 +0200 Subject: Doc: Add info about IncrediBuild plugin Fixes: QTCREATORBUG-24217 Change-Id: I3e9023933db508f14139b719eae0191d4615eab7 Reviewed-by: hjk --- .../qtcreator-incredibuild-build-steps-general.png | Bin 0 -> 6881 bytes .../qtcreator-incredibuild-build-steps-linux.png | Bin 0 -> 2306 bytes .../qtcreator-incredibuild-build-steps-windows.png | Bin 0 -> 11710 bytes .../src/howto/creator-only/creator-cli.qdoc | 2 +- .../creator-projects-incredibuild-building.qdocinc | 141 +++++++++++++++++++++ .../creator-projects-incredibuild.qdoc | 45 +++++++ .../src/meson/creator-projects-meson.qdoc | 2 +- .../creator-only/creator-projects-other.qdoc | 4 + .../creator-projects-settings-build.qdoc | 6 +- doc/qtcreator/src/qtcreator-toc.qdoc | 1 + doc/qtdesignstudio/config/qtdesignstudio.qdocconf | 1 + 11 files changed, 199 insertions(+), 3 deletions(-) create mode 100644 doc/qtcreator/images/qtcreator-incredibuild-build-steps-general.png create mode 100644 doc/qtcreator/images/qtcreator-incredibuild-build-steps-linux.png create mode 100644 doc/qtcreator/images/qtcreator-incredibuild-build-steps-windows.png create mode 100644 doc/qtcreator/src/incredibuild/creator-projects-incredibuild-building.qdocinc create mode 100644 doc/qtcreator/src/incredibuild/creator-projects-incredibuild.qdoc diff --git a/doc/qtcreator/images/qtcreator-incredibuild-build-steps-general.png b/doc/qtcreator/images/qtcreator-incredibuild-build-steps-general.png new file mode 100644 index 0000000000..44be472332 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-incredibuild-build-steps-general.png differ diff --git a/doc/qtcreator/images/qtcreator-incredibuild-build-steps-linux.png b/doc/qtcreator/images/qtcreator-incredibuild-build-steps-linux.png new file mode 100644 index 0000000000..a4849b51a7 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-incredibuild-build-steps-linux.png differ diff --git a/doc/qtcreator/images/qtcreator-incredibuild-build-steps-windows.png b/doc/qtcreator/images/qtcreator-incredibuild-build-steps-windows.png new file mode 100644 index 0000000000..c9767fe860 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-incredibuild-build-steps-windows.png differ diff --git a/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc b/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc index 3ec803df2f..d81a3e6443 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc @@ -30,7 +30,7 @@ // ********************************************************************** /*! - \previouspage creator-project-nimble.html + \previouspage creator-project-incredibuild.html \page creator-cli.html \nextpage creator-keyboard-shortcuts.html diff --git a/doc/qtcreator/src/incredibuild/creator-projects-incredibuild-building.qdocinc b/doc/qtcreator/src/incredibuild/creator-projects-incredibuild-building.qdocinc new file mode 100644 index 0000000000..17d6d52c5b --- /dev/null +++ b/doc/qtcreator/src/incredibuild/creator-projects-incredibuild-building.qdocinc @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +****************************************************************************/ +/*! +//! [incredibuild build steps] + + \section2 IncrediBuild Build Steps + + To use IncrediBuild, select \uicontrol {Add Build Step} > + \uicontrol {IncrediBuild for Linux} or + \uicontrol {IncrediBuild for Windows}. + + \image qtcreator-incredibuild-build-steps-general.png + + IncrediBuild automatically detects the build step by iterating over the + build steps you already defined. The initial build step settings will + be part of your IncrediBuild build step, so your usual build tool will + still be used, but with the added benefit of IncrediBuild's build + acceleration and graphical Build Monitor. + + In the \uicontrol {Target and configuration} group, specify the command + helper and arguments that will be used to construct the build command. + + The build errors and warnings are parsed and displayed in the + \uicontrol Issues output pane. + + Select the \uicontrol {Keep original jobs num} check box to stop + IncrediBuild from overriding the \c {-j} command line switch, which + controls the number of processes that the build tools executed by + \QC run in parallel. The default value set by IncrediBuild is 200. + + The distribution control settings to specify depend on whether you are using + Linux or Windows. + + \section3 Distribution Control Settings on Linux + + \image qtcreator-incredibuild-build-steps-linux.png + + You can specify the following options for Linux builds: + + \list + \li \uicontrol {Nice value} is a numeric value between -20 and 19 + \li \uicontrol {Force remote} forces \c allow_remote tasks to + remote Helpers. + \li \uicontrol {Alternate tasks preference} + \endlist + + \section3 Distribution Control Settings on Windows + + \image qtcreator-incredibuild-build-steps-windows.png + + You can specify the following options for Windows builds: + + \list + \li \uicontrol {Profile.xml} defines how Automatic Interception + Interface handles processes in a distributed job. It is not + necessary for Visual Studio or Make and Build tools builds, but can + be used to provide configuration options if those builds use + additional processes that are not included in those packages. It is + required to configure distributable processes in Dev Tools builds. + \li \uicontrol {Avoid local} frees up resources on the initiator + machine. This might be beneficial for distribution if the initiator + turns into a bottleneck for the build because of high CPU usage. + \li \uicontrol {Maximum CPUs to utilize in the build} specifies the + maximum amount of remote cores to use in the build. Overrides the + corresponding global setting. + \li \uicontrol {Newest allowed Helper machine OS} and + \uicontrol {Oldest allowed Helper machine OS} specify the newest and + oldest operating system installed on a Helper machine to be allowed + to participate as a Helper in the build. + \li \uicontrol {Build Title} specifies a custom header line which will + be displayed in the beginning of the build output text. This title + will also be used for the Build History and Build Monitor displays. + \li \uicontrol {Save IncrediBuild monitor file} writes a copy of the + build progress (\c{.ib_mon}) file to the specified location. + If only a folder name is given, IncrediBuild generates a GUID for + the file name. A message containing the location of the saved + \c{.ib_mon} file is added to the end of the build output. + \li \uicontrol {Suppress STDOUT} does not write anything to the standard + output. + \li \uicontrol {Output log file} writes build output to a file. + \li \uicontrol {Show commands in output} shows the command-line used by + IncrediBuild to build the file. + \li \uicontrol {Show agents in output} shows the Agent used to build + each file. + \li \uicontrol {Show time in output} shows the start and finish time for + each file built. + \li \uicontrol {Hide IncrediBuild Header in output} suppresses the + IncrediBuild header in the build output. + \li \uicontrol {Internal IncrediBuild logging level} overrides the + internal Incredibuild logging level for this build. Does not affect + output or any user accessible logging. Used mainly to troubleshoot + issues with the help of IncrediBuild support. + \li \uicontrol {Set an environment variable} sets or overrides + environment variables for the context of the build. + \li \uicontrol {Stop on errors} stops the execution as soon as an error + is encountered. This is the default behavior in Visual Studio + builds, but not for Make and Build tools or Dev Tools builds. + \li \uicontrol {Additional arguments} are concatenated to the final + buildconsole command line. + \li \uicontrol {Open Monitor} opens an IncrediBuild Build Monitor that + graphically displays the build's progress once the build starts. + \endlist + +//! [incredibuild build steps] + +//! [incredibuild clean steps] + + \section2 IncrediBuild Clean Steps + + When building with IncrediBuild, you can add arguments and targets for the + clean command in \uicontrol {Clean Steps}. + + For more information about the settings, see \l{IncrediBuild Build Steps}. + + The build errors and warnings are parsed and displayed in the + \uicontrol Issues output pane. + +//! [incredibuild clean steps] +*/ diff --git a/doc/qtcreator/src/incredibuild/creator-projects-incredibuild.qdoc b/doc/qtcreator/src/incredibuild/creator-projects-incredibuild.qdoc new file mode 100644 index 0000000000..91cde5ab27 --- /dev/null +++ b/doc/qtcreator/src/incredibuild/creator-projects-incredibuild.qdoc @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +****************************************************************************/ + +/*! + \previouspage creator-project-meson.html + \page creator-project-incredibuild.html + \nextpage creator-cli.html + + \title Setting Up IncrediBuild + + \l{https://www.incredibuild.com/}{IncrediBuild} accelerates process + execution and thus shortens the time you spend on building C++ code. + In addition, you can view the build progress in the graphical Build + Monitor. + + The IncrediBuild plugin is delivered with \QC. For more information, see + \l{https://incredibuild.atlassian.net/wiki/spaces/IUM/pages/19202836/IncrediBuild+for+Qt+Creator} + {IncrediBuild for Qt Creator}. + + To use IncrediBuild, install IncrediBuild Agent on the development + host. Then specify IncrediBuild build steps for your project. For + more information, see \l{IncrediBuild Build Steps}. +*/ diff --git a/doc/qtcreator/src/meson/creator-projects-meson.qdoc b/doc/qtcreator/src/meson/creator-projects-meson.qdoc index 2dd40fa56a..48a9d310d3 100644 --- a/doc/qtcreator/src/meson/creator-projects-meson.qdoc +++ b/doc/qtcreator/src/meson/creator-projects-meson.qdoc @@ -26,7 +26,7 @@ /*! \previouspage creator-project-nimble.html \page creator-project-meson.html - \nextpage creator-cli.html + \nextpage creator-project-incredibuild.html \title Setting Up Meson diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-other.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-other.qdoc index 83b1176e0a..3e373c7952 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-other.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-other.qdoc @@ -78,6 +78,10 @@ Meson is an open source build system meant to be both extremely fast, and, even more importantly, as user friendly as possible. + \li \l{Setting Up IncrediBuild} + + IncrediBuild decreases the time it takes to build C++ code. + \endlist */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc index 5b0a7030b4..c148252405 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc @@ -146,7 +146,8 @@ \section1 Build Steps In \uicontrol{Build Steps} you can change the settings for the build system - selected for building the project: qmake, CMake, Meson, or Qbs. + selected for building the project: qmake, CMake, Meson, or Qbs. You can use + Incredibuild to accelerate the build process when using qmake or CMake. \section2 qmake Build Steps @@ -168,6 +169,7 @@ \include creator-projects-cmake-building.qdocinc cmake build steps \include creator-projects-settings-build-qbs.qdocinc qbs build steps \include creator-projects-meson-building.qdocinc meson build steps + \include creator-projects-incredibuild-building.qdocinc incredibuild build steps \section2 Adding Custom Build Steps @@ -214,4 +216,6 @@ \include creator-projects-cmake-building.qdocinc cmake clean steps \include creator-projects-settings-build-qbs.qdocinc qbs clean steps \include creator-projects-meson-building.qdocinc meson clean steps + \include creator-projects-incredibuild-building.qdocinc incredibuild clean steps + */ diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index e3b1a0da86..1c7e542e5e 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -257,6 +257,7 @@ \li \l{Setting Up a Generic Project} \li \l{Setting Up Nimble} \li \l{Setting Up Meson} + \li \l{Setting Up IncrediBuild} \endlist \li \l{Using Command Line Options} \li \l{Keyboard Shortcuts} diff --git a/doc/qtdesignstudio/config/qtdesignstudio.qdocconf b/doc/qtdesignstudio/config/qtdesignstudio.qdocconf index 7c74d2665e..b3ba045381 100644 --- a/doc/qtdesignstudio/config/qtdesignstudio.qdocconf +++ b/doc/qtdesignstudio/config/qtdesignstudio.qdocconf @@ -41,6 +41,7 @@ excludedirs += ../../qtcreator/examples/accelbubble \ ../../qtcreator/src/debugger/creator-only \ ../../qtcreator/src/editors/creator-only \ ../../qtcreator/src/howto/creator-only \ + ../../qtcreator/src/incredibuild \ ../../qtcreator/src/ios \ ../../qtcreator/src/linux-mobile \ ../../qtcreator/src/mcu \ -- cgit v1.2.3