Doc: Split up the "Adding Libraries to Projects" topic

- Turn the topic into a how-to topic
- Turn the example into a tutorial
- Mark the information as qmake-specific
- Add links to CMake information

Task-number: QTCREATORBUG-29361
Change-Id: I42befbf15ad8a0eba7e26a0a69e6d1963d2ce5be
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>

doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc

@@ -61,6 +61,7 @@
 
     \list
         \li \l {Add a license header template for C++ code}
+        \li \l {Add libraries to projects}
         \li \l {Add subprojects to projects}
         \li \l {Create C++ classes}
         \li \l {Create files}

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

@@ -69,8 +69,7 @@
     install and configure some additional software on the devices to be able to
     \l{Connecting Devices}{connect} to them from the development PC.
 
-    \sa {Manage Projects}{How-to: Manage Projects},
+    \sa {Manage Projects}{How-to: Manage Projects}, {Adding New Custom Wizards}
-    {Adding Libraries to Projects}, {Adding New Custom Wizards}
 */
 
 /*!
@@ -317,5 +316,5 @@
     To specify dependencies, use the \uicontrol{Add Library} wizard.
 
     \sa {Creating Projects}, {Use project wizards},
-    {Adding Libraries to Projects}
+    {Add libraries to projects}
 */

doc/qtcreator/src/projects/creator-only/creator-projects-libraries.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
 
 // **********************************************************************
@@ -8,19 +8,45 @@
 // **********************************************************************
 
 /*!
-    \previouspage creator-project-creating.html
     \page creator-project-qmake-libraries.html
-    \nextpage creator-project-wizards.html
+    \previouspage creator-how-tos.html
 
-    \title Adding Libraries to Projects
+    \ingroup creator-how-to-projects
+
+    \title Add libraries to projects
 
     In addition to Qt libraries, you can add other libraries to your projects.
-    The process depends on the type and location of the
+    The process depends on the type and location of the library:
-    library. You can add a system library, your own library, or a 3rd party
-    library. The library can be located either in the build tree of the
-    current project or in another build tree.
 
-    \image qtcreator-add-library-wizard.png "Add Library wizard"
+    \list
+        \li A system library
+        \li Your own library
+        \li A 3rd party library
+    \endlist
+
+    The library can be located either in the build tree of the current project or
+    in another build tree.
+
+    \section1 CMake projects
+
+    If you use CMake to build the project, use the \l qt_add_library command to
+    create a library and link against it in the CMakeLists.txt file, as
+    instructed in \l{Structuring projects}.
+
+    \section1 qmake projects
+
+    To add libraries to projects that you build with qmake:
+
+    \list 1
+        \li In the \l Projects view, right-click the project name to open the
+            context menu and select \uicontrol {Add Library}.
+            \image qtcreator-add-library-wizard.png {Add Library wizard}
+        \li Specify settings for the library.
+            \image qtcreator-add-library-external.webp {Adding an external library}
+            The settings depend on the library type.
+    \endlist
+
+    \section1 Library settings
 
     Because system libraries do not typically change and are often found by
     default, you do not need to specify the path to the library or to its
@@ -62,49 +88,88 @@
     \QC supports code completion and syntax highlighting for the added
     libraries once your project successfully builds and links to them.
 
-    \section1 To Add Libraries
-
-    \list 1
-
-        \li In the \uicontrol Projects view, right-click the project name to open the
-            context menu and select
-            \uicontrol {Add Library}.
-
-        \li Follow the instructions of the wizard.
-
-    \endlist
-
     For more information about the project file settings, see
     \l{Declaring Other Libraries}.
 
-    \section1 Example of Adding Internal Libraries
+    \sa {Adding an Internal Library to a qmake Project},
+    {Add subprojects to projects}, {Use project wizards}, {Creating Projects}
+*/
 
-    To add an internal library to your project:
+/*!
+    \page creator-tutorial-adding-internal-libraries-to-projects.html
+    \previouspage creator-tutorials.html
+    \nextpage creator-project-managing.html
+
+    \ingroup creator-tutorials
+
+    \title Adding an Internal Library to a qmake Project
+
+    \brief How to create your own library and link your application against it
+    when using qmake as the build system.
+
+    You can add a library into a \e subdirs project. Use wizards to create the
+    project and the library and to link the library against the project.
+
+    \note This tutorial only applies when you select qmake as the the build
+    system for the subdirs project.
+
+    \section1 Creating a shared library
+
+    To create a shared library:
 
     \list 1
 
         \li Select \uicontrol File > \uicontrol {New Project} >
-            \uicontrol Library > \uicontrol {C++ Library}.
+            \uicontrol Library > \uicontrol {C++ Library}. If your top level
+            project is a subdirs project or contains one, you may add the library
+            to the project. However, this does not link other libraries from
+            your project against it.
 
         \li Select \uicontrol Choose to open the \uicontrol {Project Location}
             dialog.
 
-            \image qtcreator-add-library-wizard-ex-1.png "Project Location dialog"
+            \image qtcreator-add-library-internal-project-location.webp {Project Location dialog}
 
         \li In the \uicontrol Name field, give a name for the library. For example,
-            \b mylib.
+            \e MyLibrary.
 
-        \li Follow the instructions of the wizard until you get to the
+        \li Select \uicontrol Next (on Windows and Linux) or \uicontrol Continue
+            (on \macos) to open the \uicontrol {Define Build System} dialog.
+
+        \li Select \uicontrol Next or \uicontrol Continue to use CMake as the
+            build system.
+
+            The \uicontrol {Define Project Details} dialog opens.
+
+            \image qtcreator-add-library-internal-project-details.webp {Define Project Details dialog}
+
+        \li Select the library type and enter information about the classes for
+            which you want to generate source code files: class name, Qt module,
+            and source and header file names.
+
+        \li Select \uicontrol Next or \uicontrol Continue until you get to the
             \uicontrol {Project Management} dialog. In the
             \uicontrol {Add as a subproject to project}
-            list, select a project. For example, \b myapp.
+            list, select a subdirs project. For example, \e MyApplication.
+    \endlist
 
-        \li In the \uicontrol Projects view, right-click the project name to open the
+    \section1 Linking an application to the library
-            context menu and select
-            \uicontrol {Add Library} > \uicontrol {Internal Library} >
-            \uicontrol Next.
 
-        \li In the \uicontrol Library field, select \b mylib, and then select
+    To link a project to the shared library:
+
+    \list 1
+
+        \li In the \l Projects view, right-click the project name to open
+            the context menu and select \uicontrol {Add Library} >
+            \uicontrol {Internal Library} > \uicontrol Next.
+
+            The wizard instructs the build system to link an existing application
+            project or a library project against the selected library. Here, you
+            add the library that you created above.
+
+            \image qtcreator-add-library-internal.webp {Adding an internal library}
+
+        \li In the \uicontrol Library field, select \e mylibrary, and then select
             \uicontrol Next.
 
         \li Select \uicontrol Finish to add the library declaration to the
@@ -116,7 +181,7 @@
     CMakeLists.txt file:
 
     \badcode
-    target_link_libraries(myapp PRIVATE mylib)
+    target_link_libraries(myapplication PRIVATE mylibrary)
     \endcode
 
     When using qmake, the following library declaration is added to the .pro
@@ -132,4 +197,7 @@
     else:win32:CONFIG(debug, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/debug/mylib.lib
     else:unix: PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/libmylib.a
     \endcode
+
+    \sa {Add libraries to projects}, {Add subprojects to projects},
+    {Select the build system}, {Use project wizards}, {Creating Projects}
 */

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -25,7 +25,6 @@
         \list
             \li \l{Creating Projects}
             \list
-                \li \l{Adding Libraries to Projects}
                 \li \l{Adding New Custom Wizards}
             \endlist
             \li \l{Using Version Control Systems}
@@ -275,6 +274,7 @@
                     \li Manage Projects
                         \list
                             \li \l {Add a license header template for C++ code}
+                            \li \l {Add libraries to projects}
                             \li \l {Add subprojects to projects}
                             \li \l {Create C++ classes}
                             \li \l {Create files}

doc/qtcreator/src/user-interface/creator-projects-view.qdoc

@@ -85,7 +85,7 @@
             {generic projects}.
         \li Add existing files and directories.
         \li Add libraries. For more information, see
-            \l{Adding Libraries to Projects}.
+            \l{Add libraries to projects}.
         \li Add and remove subprojects.
         \li Find unused functions.
         \endif