From 3f24752247a109cf3e21e2f2508a74bad737a6b0 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Thu, 14 Dec 2023 17:05:17 +0100 Subject: [PATCH] Doc: Update info about importing generic projcts Move the topic from Build Systems to How To: Manage Projects. Task-number: QTCREATORBUG-29361 Change-Id: Ia91ef716a2907c9ae9296852ca137d3fa1f3e4c1 Reviewed-by: Eike Ziller --- .../src/cmake/creator-projects-cmake.qdoc | 2 +- .../creator-projects-generic.qdoc | 122 +++++++----------- .../creator-projects-settings-run.qdoc | 12 +- .../user-interface/creator-projects-view.qdoc | 2 +- 4 files changed, 58 insertions(+), 80 deletions(-) diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc index 78bd0e54ea2..69bcfb3be43 100644 --- a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc +++ b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc @@ -42,7 +42,7 @@ \c{qmake -project} and \l{Open projects}{open} that in \QC. Typically, you cannot compile such projects without manual changes. \li Manually create an ad-hoc project file for a - \l{Setting Up a Generic Project}{generic project} and + \l{Import an existing project}{generic project} and open that in \QC. Typically, you cannot compile such projects without manual changes. \endlist diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc index 094526334b5..e4e682d2a6f 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -11,25 +11,19 @@ \page creator-project-generic.html \previouspage creator-reference.html - \ingroup creator-reference-build-systems + \ingroup creator-how-to-projects - \title Setting Up a Generic Project + \title Import an existing project - \brief \QC supports generic projects, so you can import existing projects - that do not use qmake 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. - - Generic project support allows you to use \QC as a code editor. You - can change the way your project is built by modifying the \c make command + Import existing projects that do not use CMake, qmake, or one of the other + directly supported build tools to use \QC as a code editor and to fully + control the steps and commands for building the project. + To change the way the project is built, change the \c make command in the \uicontrol{Projects} mode under \uicontrol{Build Settings}. - When you import a project, \QC creates the following files that - allow you to specify which files belong to your project and which include - directories or defines you want to pass to your compiler: - \tt{.files}, \tt{.includes}, and \tt{.config}. - - \section1 Importing a Generic Project + With the following files, you can specify which files belong to your project + and which include directories or defines to pass to your compiler: + \c {.files}, \c {.includes}, and \c {.config}. To import an existing generic project: @@ -42,62 +36,54 @@ and select the location of the project file you want to import. \QC automatically generates the following files in the - project directory: + project directory and shows them in the \l Projects view: \list - \li \l{Specifying Files}{.files} + \li \c {.files} - \li \l{Specifying Include Paths and Framework Paths}{.includes} + \li \c {.includes} - \li \l{Specifying Defines}{.config} + \li \c {.config} - \li .creator + \li \c .creator - \li \l{Forwarding Flags to Clang Code Model}{.cflags} + \li \c {.cflags} - \li \l{Forwarding Flags to Clang Code Model}{.cxxflags} + \li \c {.cxxflags} \endlist \endlist - When the project is successfully imported, \QC creates the project - tree in the sidebar. + The \c .creator file is considered the \e {project file}, so you need to open + it when you want to open the project later. - After importing a generic project into \QC, open it by selecting the - \tt{.creator} file. - - \section1 Working with Generic Project Files + \section1 Specify files For a generic project, you have to manually specify which files belong to - your project and which include directories or defines you want to pass to - your compiler. + your project in the \c {.files} file. When you import a generic project, + \QC adds any files it recognizes to your project. - \section1 Specifying Files + To add or remove files, edit the \c {.files} file in \QC. \QC updates the + contents of \uicontrol Projects when you save the \c {.files} file. + Or, use the context menu in \uicontrol Projects to add and remove files or + directories. - The list of files for a generic project is specified in the \tt{.files} - file. When you first create a generic project, \QC adds any files it - recognizes to your project. + \section2 Use a script - To add or remove files, edit the \tt{.files} file in \QC. - \QC recreates your project tree when you save the \tt{.files} file. - Alternatively, you can add and remove files or directories using the - context menu in the project tree. + If you frequently need to update the \c {.files} file, use a script. If the + file is modified externally, you have to close and reopen the project for the + changes to take effect. - If you frequently need to update the \tt{.files} file, you can do so - efficiently by using a script that updates the file for you. If the file - is modified externally, you have to restart \QC for the changes to - take effect. - - To update the \tt{.files} on the \uicontrol Git repository use the following - script: + To update the \c {.files} file in the \uicontrol Git repository, use the + following script: \code git ls-files "*.cpp" "*.h" > MyProject.files \endcode - \section2 Precompiled Headers + \section2 Precompiled headers To use precompiled headers in a generic project, add the \c pch tag after a file path in the \c .files file, separated by the pipe character (|). @@ -107,55 +93,47 @@ src/pch.h|pch \endcode - \section1 Specifying Include Paths and Framework Paths + \section1 Specify include paths and framework paths - The include paths are specified in the \tt{.includes} file, one include + Specify include paths in the \c {.includes} file, one include path per line. The paths can be either absolute or relative to the - \tt{.includes} file. + \c {.includes} file. - Lines starting with "-F" are interpreted as framework paths. + Lines starting with \c -F are interpreted as framework paths. - \section1 Specifying Defines + \section1 Specify defines - The defines are specified in the \tt{.config} file. The \tt{.config} file is + Specify defines in the \c {.config} file. It is a regular C++ file, prepended to all your source files when they are parsed. - Only use the \tt{.config} file to add lines as in the example below: + Only use the \c {.config} file to add lines as in the example below: \code #define NAME value \endcode - \section1 Forwarding Flags to Clang Code Model + \section1 Forward flags to Clang code model The \c {.cxxflags} and \c {.cflags} files have command-line flags for the Clang code model on a single line. - For example, specify the \c {-std=c++11} to set the language version + For example, add the \c {-std=c++11} line to set the language version for parsing as C++11. - \section1 Providing Deployment Information + \section1 Provide deployment information - If you want to run your application on a remote Linux device, + To run an application on a remote Linux device, you first need to deploy your executable and possibly other files. \QC does that for you automatically if you enter the necessary information. This works the same way as explained for CMake in \l {Deploying to Remote Linux}, except that you also need to include your application binary in the list. - \section1 Creating a Run Configuration + \section1 Create a run configuration - \QC cannot automatically determine which executable to run. - - In the \uicontrol{Projects} mode under \uicontrol{Run Settings}, define the executable - file to run: - - \list 1 - - \li Click \uicontrol Add and select \uicontrol{Custom Executable}. - - \li Define the configuration name, the location of the executable, any - additional arguments and the working directory. - - \endlist + \QC cannot automatically determine which executable to run, so you must + set the executable in \uicontrol {Projects} > \uicontrol {Run} > + \uicontrol Add > \uicontrol {Custom Executable}. + \sa {Specify a custom executable to run}, {Use project wizards}, + {Configuring Projects} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc index 18a0455163c..8075c09b9ea 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc @@ -109,11 +109,11 @@ \title Specify a custom executable to run - If you use \l{Meson} or the - \l{Setting Up a Generic Project}{generic project type}, 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. + If you use \l{Meson} or the \l{Import an existing project} + {generic project type}, 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. To specify a custom executable to run: @@ -125,5 +125,5 @@ file to run. \endlist - \sa {Configure projects for running} + \sa {Configure projects for running}, {Import an existing project} */ diff --git a/doc/qtcreator/src/user-interface/creator-projects-view.qdoc b/doc/qtcreator/src/user-interface/creator-projects-view.qdoc index 286cefa30b8..b0a66c421cc 100644 --- a/doc/qtcreator/src/user-interface/creator-projects-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-projects-view.qdoc @@ -81,7 +81,7 @@ \QC also changes corresponding include statements accordingly. \li Remove existing files. \if defined(qtcreator) - \li Remove existing directories from \l{Setting Up a Generic Project} + \li Remove existing directories from \l{Import an existing project} {generic projects}. \li Add existing files and directories. \li Add libraries. For more information, see