Meson/Doc: Initial documentation for Meson build plugin

Mostly copied from CMake and adapted to Meson.

qtcreator-kits.png screenshot has been taken on Linux but
https://doc.qt.io/qtcreator/creator-targets.html#specifying-kit-settings
has Windows specific stuff (item 11. "Select the Force UTF-8 MSVC compiler").

Fixes: QTCREATORBUG-24216
Change-Id: Ie6c3c48fea7f1732f010eb10cbb152406e08810c
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>

doc/qtcreator/src/meson/creator-projects-meson-building.qdocinc

@@ -0,0 +1,78 @@
+/****************************************************************************
+**
+** 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.
+**
+****************************************************************************/
+/*!
+//! [meson build configuration]
+
+    \section2 Meson Build Configuration
+
+    \image qtcreator-meson-build-settings.png
+
+    Settings are grouped by category by Meson. All items are user modifiable
+    except \c backend which is forced to Ninja, \c {buildtype}, \c debug as well
+    as \c optimization to ensure a good compatibility with \QC.
+
+    Each setting type has its own editor. To modif any setting, double-click it,
+    either edit the field, or select your choice depending on the control. To
+    apply changes, select \uicontrol {Apply configuration changes}. This will
+    trigger a \c {meson configure} command if there were any configuration
+    changes. If for any reason the build directory configuration is broken,
+    select \uicontrol {Wipe project}. This should fix any build directory.
+
+    \note Any modified setting will remain in bold until \uicontrol
+    {Apply configuration changes} is selected.
+
+//! [meson build configuration]
+
+
+//! [meson build steps]
+
+    \section2 Meson Build Steps
+
+    \QC builds Meson projects by running \c {ninja -v target}.
+
+    You can add arguments and targets for the build command in
+    \uicontrol {Build Steps}.
+
+    \image qtcreator-meson-build-steps.png
+
+    The build errors and warnings are parsed and displayed in the
+    \uicontrol Issues output pane.
+
+//! [meson build steps]
+
+//! [meson clean steps]
+
+    \section2 Meson Clean Steps
+
+    When building with Meson, you can add arguments and targets for the clean
+    command in \uicontrol {Clean Steps}.
+
+    \image qtcreator-meson-clean-steps.png
+
+    The build errors and warnings are parsed and displayed in the
+    \uicontrol Issues output pane.
+
+//! [meson clean steps]
+*/

doc/qtcreator/src/meson/creator-projects-meson.qdoc

@@ -0,0 +1,117 @@
+/****************************************************************************
+**
+** 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-nimble.html
+    \page creator-project-meson.html
+    \nextpage creator-cli.html
+
+    \title Setting Up Meson
+
+    \l{https://mesonbuild.com/}{Meson} is an open source and multi-platform build
+    system generator using Ninja as main backend. Build definitions are located
+    in \c {meson.build} files while build options are located in
+    \c {meson_options.txt}.
+
+    Meson build support in \QC is not mature yet, you can only use it to build
+    native desktop applications. Many features available with Meson build or
+    usually available from \QC are missing.
+
+    \QC automatically detects the Meson and Ninja executables specified in the
+    \c PATH. You can add paths to other Meson or Ninja executables and use them
+    in different build and run \l{glossary-buildandrun-kit}{kits}.
+
+    \note Meson build plugin is disabled by default, see
+    \l{Enabling and Disabling Plugins}.
+
+    \section1 Adding Meson Tools
+
+    \QC does not have strong requirements on Meson build's version, any version
+    above 0.49.0 should be compatible.
+
+    To specify paths to Meson or Ninja executables:
+
+    \list 1
+
+        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Meson >
+            \uicontrol Tools > \uicontrol Add.
+
+            \image qtcreator-mesonexecutable.png
+
+        \li In the \uicontrol Name field, specify a name for the tool.
+
+        \li In the \uicontrol Path field, specify the path to the Meson or Ninja
+            executable.
+
+        \li Select \uicontrol Apply to save your changes.
+
+    \endlist
+
+    Select the
+    \uicontrol Tools > \uicontrol Options > \uicontrol Kits > \uicontrol Kits
+    tab to add the Meson and Ninja tools to a build and run kit:
+
+    \image qtcreator-kits.png
+
+    For more information, see \l {Adding Kits}.
+
+    \section1 Editing Meson Build Descriptions
+
+    To open a meson.build file for editing, double-click it from project tree.
+    Only plain text editor is available now.
+
+
+   \section1 Code Completion and External Libraries
+
+    Through external libraries, \QC can support code completion and syntax
+    highlighting as if they were part of the current project or the Qt library.
+
+    \QC handles code completion from compilation flags in Meson introspection
+    data. Any external library added with \c {dependency()} or found in include
+    path will be known by \QC for code completion.
+
+    Syntax completion and highlighting work once your project configures successfully.
+
+    \section1 Current Meson Support Limitations
+
+    The following features are not supported yet:
+
+    \list
+        \li Cross compilation.
+        \li Showing header files in project tree.
+        \li Configuration change detection, for example when building triggers a
+        Meson configuration first.
+        \li Actions from locator such as searching or triggering builds.
+        \li Adding files to Meson projects from \QC.
+    \endlist
+
+    \section1 Related Topics
+
+    \list
+        \li \l {Opening Projects}
+        \li \l {Specifying Build Settings}
+        \li \l {Specifying Run Settings}
+    \endlist
+*/

doc/qtcreator/src/projects/creator-only/creator-projects-build-systems.qdocinc

@@ -49,6 +49,13 @@
     generation of build configurations. For more information, see
     \l {Setting Up CMake}.
 
+    \l {https://mesonbuild.com/}{Meson} Meson is an open source build system meant
+    to be both extremely fast, and, even more importantly, as user friendly as
+    possible. The main design point of Meson is that every second a developer
+    spends writing or debugging build definitions is a second wasted. So is every
+    second spent waiting for the build system to actually start compiling code.
+    For more information, see \l {Setting Up Meson}.
+
     \l{Qbs Manual}{Qbs} is an all-in-one build tool that generates a build graph
     from a high-level project description (like qmake or CMake do) and executes
     the commands in the low-level build graph (like make does). For more

doc/qtcreator/src/projects/creator-only/creator-projects-nimble.qdoc

@@ -26,7 +26,7 @@
 /*!
     \previouspage creator-project-generic.html
     \page creator-project-nimble.html
-    \nextpage creator-cli.html
+    \nextpage creator-project-meson.html
 
     \title Setting Up Nimble
 

doc/qtcreator/src/projects/creator-only/creator-projects-opening.qdoc

@@ -82,7 +82,7 @@
         \li Select \uicontrol File > \uicontrol {Open File or Project}
             (\key Ctrl+O or \key Cmd+O on \macos) and select the project file
             for the project to open: \e {.pro} (qmake), \e {CMakeLists.txt}
-            (CMake), \e {.qbs} (Qbs), \e {pyproject} (Python), or
+            (CMake), \e {.qbs} (Qbs), \e {meson.build} (Meson), \e {pyproject} (Python), or
             \e {Makefile.am} (Autotools, experimental).
 
         \li In the \uicontrol {Configure Project} tab, select kits for building

doc/qtcreator/src/projects/creator-only/creator-projects-other.qdoc

@@ -37,7 +37,7 @@
     \title Using Other Build Systems
 
     Most \QC project wizards enable you to choose the build system to use for
-    building the project: qmake, CMake, or Qbs. qmake is installed and
+    building the project: qmake, CMake, Meson, or Qbs. qmake is installed and
     configured when you install Qt. To use one of the other supported build
     systems, you need to set it up, as described in the the following sections:
 
@@ -73,6 +73,11 @@
             the Nimble package manager for generating Nim application
             executables that are supported on Windows, Linux, and \macos.
 
+        \li \l{Setting Up Meson}
+
+            Meson is an open source build system meant to be both extremely fast,
+            and, even more importantly, as user friendly as possible.
+
     \endlist
 
 */

doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc

@@ -113,6 +113,7 @@
     information, see \l{http://doc.qt.io/QtQuickCompiler/}{Qt Quick Compiler}.
 
     \include creator-projects-cmake-building.qdocinc cmake build configuration
+    \include creator-projects-meson-building.qdocinc meson build configuration
 
     \section1 Starting External Processes
 
@@ -145,7 +146,7 @@
     \section1 Build Steps
 
     In \uicontrol{Build Steps} you can change the settings for the build system
-    selected for building the project: qmake, CMake, or Qbs.
+    selected for building the project: qmake, CMake, Meson, or Qbs.
 
     \section2 qmake Build Steps
 
@@ -166,6 +167,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
 
     \section2 Adding Custom Build Steps
 
@@ -211,4 +213,5 @@
 
     \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
 */

doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc

@@ -69,6 +69,9 @@
     \QC automatically adds run configurations for all targets specified in the
     CMake project file, \c {CMakeLists.txt}.
 
+    \QC automatically adds run configurations for all targets declared with
+    \c {executable()} function in Meson build descriptions.
+
     \section1 Creating Run Configurations for Subprojects
 
     To prevent \QC from automatically creating run configurations for SUBDIRS
@@ -113,7 +116,7 @@
 
     \section1 Specifying a Custom Executable to Run
 
-    If you use CMake or the generic project type in \QC, or want
+    If you use CMake, Meson or the generic project type in \QC, or want
     to run a custom desktop executable, create a \uicontrol {Custom Executable}
     run configuration for your project. For example, when working on a library,
     you can run a test application that links against the library.

doc/qtcreator/src/projects/creator-only/creator-projects-targets.qdoc

@@ -178,6 +178,15 @@
             \uicontrol Change to edit the variables of the CMake configuration
             for the kit.
 
+        \li In the \uicontrol {Meson tool} field, select the Meson tool to use
+            for building the project. Select \uicontrol Manage to add installed
+            Meson tools to the list. For more information, see
+            \l{Adding Meson Tools}.
+
+        \li In the \uicontrol {Ninja tool} field, select the Ninja tool to use
+            for building the project with Meson. Select \uicontrol Manage to add installed
+            Ninja tools to the list.
+
     \endlist
 
     \QC uses the \e {default kit} if it does not have enough information to