From 22476fc26fb819961d732296061e18062977533b Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Tue, 1 Aug 2023 17:07:28 +0200 Subject: [PATCH] Doc: Divide "Creating Projects" into an explanation and how-to topics Task-number: QTCREATORBUG-29361 Change-Id: I623d824e423da950df9643c42d85b485daccfe4b Reviewed-by: Eike Ziller Reviewed-by: Christian Kandeler --- .../src/editors/creator-locator.qdoc | 2 +- .../creator-only/creator-beautifier.qdoc | 2 +- doc/qtcreator/src/editors/creator-search.qdoc | 2 +- .../howto/creator-only/creator-how-tos.qdoc | 4 + .../creator-deployment-embedded-linux.qdoc | 2 +- .../creator-how-to-select-build-systems.qdoc | 60 +++++++ .../creator-projects-build-systems.qdocinc | 61 ------- .../creator-projects-creating.qdoc | 158 ++++++++++++------ .../creator-projects-overview.qdoc | 16 +- ...reator-projects-settings-dependencies.qdoc | 4 +- .../src/python/creator-python-run.qdocinc | 2 +- doc/qtcreator/src/qtcreator-toc.qdoc | 4 + .../user-interface/creator-projects-view.qdoc | 2 +- .../vcs/creator-only/creator-vcs-gitlab.qdoc | 2 +- 14 files changed, 186 insertions(+), 135 deletions(-) create mode 100644 doc/qtcreator/src/projects/creator-only/creator-how-to-select-build-systems.qdoc delete mode 100644 doc/qtcreator/src/projects/creator-only/creator-projects-build-systems.qdocinc diff --git a/doc/qtcreator/src/editors/creator-locator.qdoc b/doc/qtcreator/src/editors/creator-locator.qdoc index c7add7c980f..bcc12f9ba14 100644 --- a/doc/qtcreator/src/editors/creator-locator.qdoc +++ b/doc/qtcreator/src/editors/creator-locator.qdoc @@ -104,7 +104,7 @@ or use the handle next to the locator window to increase the window width. \if defined(qtcreator) - If the locator does not find some files, see \l{Specifying Project Contents} + If the locator does not find some files, see \l{Specify project contents} for how to make them known to the locator. \endif diff --git a/doc/qtcreator/src/editors/creator-only/creator-beautifier.qdoc b/doc/qtcreator/src/editors/creator-only/creator-beautifier.qdoc index 8d310917373..d994a175e35 100644 --- a/doc/qtcreator/src/editors/creator-only/creator-beautifier.qdoc +++ b/doc/qtcreator/src/editors/creator-only/creator-beautifier.qdoc @@ -105,7 +105,7 @@ \li Select \uicontrol {Use file *.astylerc defined in project files} or \uicontrol {Use file uncrustify.cfg defined in project files}, - to use the configuration file \l{Specifying Project Contents} + to use the configuration file \l{Specify project contents} {defined in the project file} as the configuration file for the selected tool. diff --git a/doc/qtcreator/src/editors/creator-search.qdoc b/doc/qtcreator/src/editors/creator-search.qdoc index 502a87367aa..904452fbe39 100644 --- a/doc/qtcreator/src/editors/creator-search.qdoc +++ b/doc/qtcreator/src/editors/creator-search.qdoc @@ -122,7 +122,7 @@ \if defined(qtcreator) If you cannot find some files, see - \l{Specifying Project Contents} for how + \l{Specify project contents} for how to declare them as a part of the project. \endif diff --git a/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc b/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc index 88fe789e98b..3d8d84882d9 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc @@ -61,7 +61,11 @@ \list \li \l {Add a license header template for C++ code} + \li \l {Add subprojects to projects} \li \l {Develop Qt for Python applications} + \li \l {Specify project contents} + \li \l {Select the build system} + \li \l {Use project wizards} \endlist \section1 Use \QC diff --git a/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc b/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc index 0944c02a953..38c6823fa30 100644 --- a/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc +++ b/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc @@ -35,7 +35,7 @@ \section1 Adding Missing Files The process to add files to deploy depends on the build system you use. - For more information, see \l{Specifying Project Contents}. + For more information, see \l{Specify project contents}. \section2 CMake Builds diff --git a/doc/qtcreator/src/projects/creator-only/creator-how-to-select-build-systems.qdoc b/doc/qtcreator/src/projects/creator-only/creator-how-to-select-build-systems.qdoc new file mode 100644 index 00000000000..0dfe9178a86 --- /dev/null +++ b/doc/qtcreator/src/projects/creator-only/creator-how-to-select-build-systems.qdoc @@ -0,0 +1,60 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \previouspage creator-project-creating.html + \page creator-how-to-select-build-system.html + \nextpage creator-file-creating.html + + \ingroup creator-how-to-projects + + \title Select the build system + + You can use several build systems to build your projects: + + \list + \li \l {Build with CMake}{CMake} is a cross-platform system for build + automation that helps simplify the build process for development + projects across different platforms. It automates the generation of + build configurations. For more information, see \l {Setting Up CMake}. + \li \l{qmake Manual}{qmake} is an alternative to CMake for automating the + generation of build configurations. Qt installers install and + configure qmake. To use one of the other supported build systems, + you need to set it up. + \li \l {https://mesonbuild.com/}{Meson} is a fast and user-friendly + open-source build system that aims to minimize the time developers spend + writing or debugging build definitions and waiting for the build system + to start compiling code. For more information, see \l {Setting Up Meson}. + \li \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 + information, see \l{Setting Up Qbs}. + \endlist + + Typically, you select the build system when you create a project. + + \section1 Migrate to another build system + + To export a project to some other build system, such as Microsoft Visual + Studio, select \uicontrol Build > \uicontrol {Run Generator}, and select + a generator in the list. \QC generates the build files, such as .vcxproj, + in the project's build directory. + + The tool that you use to build the project (qmake or CMake) provides the + generators. Their availability depends on the version of the build tool, + host platform, and properties of the host system. + Also, a JSON compilation database generator is available if the + \l{Parsing C++ Files with the Clang Code Model}{Clang Code Model plugin} + is enabled (default). + + \section1 Set preferences for building and running + + To change the location of the project directory, and to specify settings + for building and running projects, select \uicontrol Edit > + \uicontrol Preferences > \uicontrol {Build & Run} > \uicontrol General. + + Specify build and run settings for different target platforms, in the + \uicontrol Projects mode. + + \sa {Specifying Build Settings}, {Build Systems}, {Use project wizards} +*/ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-build-systems.qdocinc b/doc/qtcreator/src/projects/creator-only/creator-projects-build-systems.qdocinc deleted file mode 100644 index 05a340d0df2..00000000000 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-build-systems.qdocinc +++ /dev/null @@ -1,61 +0,0 @@ -// Copyright (C) 2023 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -// ********************************************************************** -// NOTE: the sections are not ordered by their logical order to avoid -// reshuffling the file each time the index order changes (i.e., often). -// Run the fixnavi.pl script to adjust the links to the index order. -// ********************************************************************** - -/*! -//! [build systems] - - \section1 Selecting the Build System - - You can use several build systems to build your projects: - - \list - - \li \l{qmake Manual}{qmake} is a cross-platform system for build automation - that helps simplify the build process for development projects across - different platforms. qmake automates the generation of build configurations - so that you need only a few lines of information to create each - configuration. Qt installers install and configure qmake. - To use one of the other supported build systems, you need to set it up. - - \li \l {Build with CMake}{CMake} is an alternative to qmake for automating the - generation of build configurations. For more information, see - \l {Setting Up CMake}. - - \li \l {https://mesonbuild.com/}{Meson} is a fast and user-friendly - open-source build system that aims to minimize the time developers spend - writing or debugging build definitions and waiting for the build system - to start compiling code. For more information, see \l {Setting Up Meson}. - - \li \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 - information, see \l{Setting Up Qbs}. - - \endlist - - To export a project to some other build system, such as Microsoft Visual - Studio, select \uicontrol Build > \uicontrol {Run Generator}, and select - a generator in the list. \QC generates the build files, such as .vcxproj, - in the project's build directory. The tool that you use to build the project - (qmake or CMake) provides the generators. Their availability depends on the - version of the build tool, host platform, and properties of the host system. - Also, a JSON compilation database generator is available if the - \l{Parsing C++ Files with the Clang Code Model}{Clang Code Model plugin} - is enabled (default). - - To change the location of the project directory, and to specify settings - for building and running projects, select \uicontrol Edit > - \uicontrol Preferences > \uicontrol {Build & Run} > \uicontrol General. - - Specify build and run settings for different target platforms, in the - \uicontrol Projects mode. For more information on the options you have, - see \l{Specifying Build Settings}. - -//! [build systems] -*/ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc index 638e4927283..c48a2ead78f 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc @@ -12,9 +12,11 @@ \page creator-project-creating.html \nextpage creator-file-creating.html + \ingroup creator-explanation-projects + \title Creating Projects - Creating a project enables you to: + Create projects to: \list @@ -28,32 +30,57 @@ \endlist + To set up a project, you first have to decide what kind of an application + you want to develop: do you want a user interface based on Qt Quick or + Qt widgets. Second, you have to choose the language to implement the + application logic: C++, JavaScript, or Python. + When you set up a new project in \QC, a wizard guides you step-by-step through the process. The wizard templates prompt you to enter the settings - that you need for that particular type of project and create - the necessary files for you. You can add your own custom wizards to - standardize the way of adding subprojects and classes to a project. + that you need for that particular type of project and create the necessary + files for you. - Most \QC project wizards enable you to choose the build system to use for + \image qtcreator-project-qt-quick.webp {New Project dialog} + + You can add your own custom wizards to standardize the way of adding + subprojects and classes to a project. In the \uicontrol {New Project} and + \uicontrol {New File} dialogs you can see an icon (1), a display name (2), + and a description (3) of the wizard. + + \image qtcreator-custom-wizard.png {Wizard details in the New Project dialog} + + In most project wizards, you can choose the build system to use for building the project: qmake, CMake, or Qbs. If you do not get to choose, the project uses qmake as the build system. + \image qtcreator-new-project-build-system-qt-gui.png {Define Build System dialog} + You can use wizards also to create plain C or C++ projects that use qmake, Qbs, or CMake, but do not use the Qt library. In addition, you can import projects as \e {generic projects} that do not - use qmake, Qbs, or CMake. This enables you to use \QC as a code editor and - to fully control the steps and commands used to build the project. + use qmake, Qbs, or CMake. Use \QC as a code editor and fully control the + steps and commands used to build the project. - You can install tools for \l{glossary-device}{devices} as part of Qt distributions. + To test applications on \l{glossary-device}{devices}, you can install + toolchains for mobile and embedded development as part of Qt distributions. The installers create \l{glossary-buildandrun-kit}{kits} and specify build and run settings for the installed device types. However, you might need to install and configure some additional software on the devices to be able to \l{Connecting Devices}{connect} to them from the development PC. - \include creator-projects-build-systems.qdocinc build systems + \sa {Manage Projects}{How-to: Manage Projects}, {Creating Files}, + {Adding Libraries to Projects}, {Opening Projects}, + {Adding New Custom Wizards} +*/ - \section1 Using Project Wizards +/*! + \page creator-how-to-use-project-wizards.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-projects + + \title Use project wizards To create a new project, select \uicontrol File > \uicontrol{New Project} and select the type of your project. The contents of the wizard dialogs depend @@ -75,7 +102,7 @@ For example, if you choose to create a Qt Quick application, \QC generates a QML file that you can modify in the \uicontrol Edit mode. - \section1 Selecting Project Type + \section1 Select project type The following table lists the types of wizard templates that you can use for creating projects. The \uicontrol {New Project} dialog shows detailed @@ -101,7 +128,7 @@ widgets or widget collections, \l{Qt Quick UI Projects}{Qt Quick UI projects}, \l {Creating Tests}{auto-test projects}, - \l{Adding Subprojects to Projects}{subprojects}, + \l{Add subprojects to projects}{subprojects}, empty qmake projects, or qmake projects for testing code snippets. \row @@ -133,7 +160,28 @@ For more information about creating Qt Quick projects, see \l {Creating Qt Quick Projects}. - \section1 Specifying Project Contents + \section1 Bind keyboard shortcuts to wizards + + If you use a wizard regularly, you can bind a custom keyboard shortcut to + it. Triggering this keyboard shortcut directly opens the wizard, so you do + not need to navigate to \uicontrol File > \uicontrol {New File} or + \uicontrol {New Project}. + + Set keyboard shortcuts for wizards in \uicontrol Edit > + \uicontrol Preferences > \uicontrol Environment > \uicontrol Keyboard > + \uicontrol Wizard. All wizard actions start with \uicontrol Impl there. + + \sa {Assign keyboard shortcuts}, {Activating Kits for a Project}, + {Creating Files}, {Creating Projects} +*/ + +/*! + \page creator-how-to-specify-project-contents.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-projects + + \title Specify project contents A project can have files that should be: @@ -146,8 +194,8 @@ to \QC \endlist - \QC displays all files that you declare to be part of the project by the - project files in the \l Projects view. It sorts the files into categories + The \l Projects view shows all files that you declare to be part of the + project in the project files. It sorts the files into categories by file type (.cpp, .h, .qrc, and so on). To display additional files, edit the project file. Alternatively, you can see all the files in a project directory in the \l {File System} view. @@ -156,7 +204,7 @@ \l{Searching with the Locator}{locator} and \l{Advanced Search} {project-wide search}. - \section2 CMake Projects + \section1 CMake Projects When using CMake, you can specify additional files for a project by either adding them as sources or installing them. @@ -177,7 +225,7 @@ Alternatively, to install the files, use the \l {CMake: install command} {install} command with the \c FILES or \c DIRECTORY property. - \section2 qmake Projects + \section1 qmake Projects Use the following variables in the .pro file: @@ -197,24 +245,33 @@ \endcode - \section1 Adding Subprojects to Projects + \sa {Creating Projects}, {Use project wizards}, {Projects} - In addition to Qt libraries, you can link your application to other - libraries, such as system libraries or your own libraries. Further, your - own libraries might link to other libraries. To be able to compile your - project, you must add the libraries to your project. This also enables - code completion and syntax highlighting for the libraries. - The procedure of adding a library to a project depends on the build +*/ + +/*! + \page creator-how-to-add-subprojects-to-projects.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-projects + + \title Add subprojects to projects + + You can link your application to Qt libraries and other libraries, such as + system libraries or your own libraries. Further, your own libraries might + link to other libraries. To compile your project and benefit from services + such as code completion and syntax highlighting, add the libraries to your + project. The process of adding a library to a project depends on the build system that you use. - \section2 CMake Projects + \section1 CMake projects - You can add CMakeLists.txt files to any project by using the + To add CMakeLists.txt files to any project, use the \l{https://cmake.org/cmake/help/latest/command/add_subdirectory.html} {add_subdirectory} command. The files can define complete projects that you include into the top-level project or any other CMake commands. - \section2 qmake Projects + \section1 qmake projects When you create a new project and select qmake as the build system, you can add it to another project as a subproject in the @@ -222,19 +279,26 @@ must specify that qmake uses the \c subdirs \l{TEMPLATE}{template} to build the project. - To create a root project, select \uicontrol File > - \uicontrol {New Project} > \uicontrol {Other Project} > - \uicontrol {Subdirs Project} > \uicontrol Choose. + To create a root project: - On the \uicontrol Summary page, select \uicontrol {Finish & Add Subproject} to create - the root project and to add another project, such as a C++ library. + \list 1 + \li Select \uicontrol File > \uicontrol {New Project} > + \uicontrol {Other Project} > \uicontrol {Subdirs Project} > + \uicontrol Choose. + + \li On the \uicontrol Summary page, select + \uicontrol {Finish & Add Subproject} to create + the root project and to add another project, such as a C++ library. + \endlist The wizard creates a project file (.pro) that defines a \c subdirs template and the subproject that you add as a value of the \l{Variables#subdirs} {SUBDIRS variable}. It also adds all the necessary files for the subproject. + \section2 Add subprojects to the root project + To create more subprojects, right-click the project name in the - \uicontrol Projects view to open the context menu, and select + \l Projects view to open the context menu, and select \uicontrol {New Subproject}. Follow the steps in the \uicontrol {New Subproject} wizard to create a subproject. @@ -244,31 +308,15 @@ \uicontrol {Add Existing Projects} in the context menu. In the file browser dialog, locate your subproject. + \section2 Remove subprojects + To remove subprojects, right-click the project name in the \uicontrol Projects view, and select \uicontrol {Remove Subproject} in the context menu. - To specify dependencies, use the \uicontrol{Add Library} wizard. For more - information, see \l{Adding Libraries to Projects}. + \section2 Specify dependencies - \section1 Binding Keyboard Shortcuts to Wizards - - If you use a wizard regularly, you can bind a custom keyboard shortcut to - it. Triggering this keyboard shortcut directly opens the wizard, so you do - not need to navigate to \uicontrol File > \uicontrol {New File} or - \uicontrol {New Project}. - - Set keyboard shortcuts for wizards in \uicontrol Edit > - \uicontrol Preferences > \uicontrol Environment > \uicontrol Keyboard > - \uicontrol Wizard. All wizard actions start with \uicontrol Impl there. - - \section1 Related Topics - - \list - \li \l{Creating Files} - \li \l{Opening Projects} - \li \l{Adding Libraries to Projects} - \li \l{Adding New Custom Wizards} - \li \l{Build Systems} - \endlist + To specify dependencies, use the \uicontrol{Add Library} wizard. + \sa {Creating Projects}, {Use project wizards}, + {Adding Libraries to Projects} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-overview.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-overview.qdoc index 7be0b1ba4d9..fb09cb1da62 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-overview.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-overview.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -16,9 +16,9 @@ \image front-projects.png - One of the major advantages of \QC is that it allows a team of designers and - developers to share a project across different development platforms with a - common tool for design, development, and debugging. + You can share projects with other designers and developers across different + development platforms with a common tool for design, development, and + debugging. \list @@ -40,7 +40,7 @@ Installation programs and project wizards create default configurations for \QC and your projects. You can modify - the settings in the Projects mode. + the settings in the \uicontrol Projects mode. \li \l{Managing Sessions} @@ -50,10 +50,6 @@ \endlist - \section1 Related Topics - - \list - \li \l{Build Systems} - \endlist + \sa {Build Systems} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-dependencies.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-dependencies.qdoc index bda2c5b5e71..61763c87579 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-dependencies.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-dependencies.qdoc @@ -45,7 +45,7 @@ specify for the projects loaded in the session. \note You cannot use this view to specify subprojects for projects. - For more information on how to add subprojects, see \l{Adding Subprojects - to Projects}. + + \sa {Add subprojects to projects} */ diff --git a/doc/qtcreator/src/python/creator-python-run.qdocinc b/doc/qtcreator/src/python/creator-python-run.qdocinc index 2356607a837..760587e08bb 100644 --- a/doc/qtcreator/src/python/creator-python-run.qdocinc +++ b/doc/qtcreator/src/python/creator-python-run.qdocinc @@ -6,7 +6,7 @@ \section1 Running Python Projects You can execute Qt for Python applications directly from \QC. If you - used the \l{Using Project Wizards}{new project wizard} + used the \l{Use project wizards}{new project wizard} to create the application project, the \c main.py file is automatically executed when you select the \uicontrol Run button. diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index 294a1b86650..2fa2298a6b6 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -277,7 +277,11 @@ \li Manage Projects \list \li \l {Add a license header template for C++ code} + \li \l {Add subprojects to projects} \li \l {Develop Qt for Python applications} + \li \l {Select the build system} + \li \l {Specify project contents} + \li \l {Use project wizards} \endlist \li Use \QC \list diff --git a/doc/qtcreator/src/user-interface/creator-projects-view.qdoc b/doc/qtcreator/src/user-interface/creator-projects-view.qdoc index 529abfed348..9d632a127e6 100644 --- a/doc/qtcreator/src/user-interface/creator-projects-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-projects-view.qdoc @@ -146,7 +146,7 @@ enables you to specify exactly where to place a new file in the build system. If you cannot see some files, you might have to declare them as part of the - project. For more information, see \l{Specifying Project Contents}. + project. For more information, see \l{Specify project contents}. If the project is under version control, you might see information from the version control system in brackets after the project name. diff --git a/doc/qtcreator/src/vcs/creator-only/creator-vcs-gitlab.qdoc b/doc/qtcreator/src/vcs/creator-only/creator-vcs-gitlab.qdoc index c458d5d0079..8ac5052826f 100644 --- a/doc/qtcreator/src/vcs/creator-only/creator-vcs-gitlab.qdoc +++ b/doc/qtcreator/src/vcs/creator-only/creator-vcs-gitlab.qdoc @@ -92,7 +92,7 @@ open, select \uicontrol File > \uicontrol {New Project} > \uicontrol {Import Project} > \uicontrol {Import Existing Project} to import the project as a generic project. For more information, see - \l {Using Project Wizards}. + \l {Use project wizards}. \section1 Linking Projects with GitLab