// 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.
// **********************************************************************

/*!
    \page creator-project-qmake-libraries.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-projects-create
    \ingroup creator-how-to-build-with-qmake

    \title Add libraries to qmake projects

    //! [libraries}
    In addition to Qt libraries, you can add other libraries to your projects.
    The process depends on the type and location of the library:

    \list
        \li A system library
        \li Your own library
        \li A 3rd party library
    \endlist

    \QC supports code completion and syntax highlighting for the added
    libraries once your project successfully builds and links to them.
    //! [libraries}

    The library can be located either in the build tree of the current project or
    in another build tree.

    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 location

    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
    includes when you add it. You can use \c{pkg-config} to query system
    libraries during compilation.

    For your own libraries and 3rd party libraries, you need to specify
    the paths. \QC tries to guess the include path for an external library,
    but you need to check it and modify it if necessary. \QC automatically
    adds the include path for an internal library.

    \section1 Target platform

    For all libraries, select the target platforms for the application, library,
    or plugin.

    \section1 Linking

    Specify whether the library is statically or dynamically linked. For a
    statically linked internal library, \QC adds dependencies as the value of
    the \l PRE_TARGETDEPS qmake variable in the project file (.pro).

    \section1 Development platform

    Depending on the development platform, \QC might detect some options
    automatically. For example, on \macos, it detects the library type
    (\uicontrol Library or \uicontrol Framework) automatically and hides the
    option. However, if you develop on another platform than \macos and want
    to build your project for \macos, you must specify the library type.

    The default convention on Windows is that the debug and release versions
    of a library have the same name, but are placed in different subdirectories,
    usually called \e debug and \e release. If the library path does not have
    either of these folders, you cannot select the option to place the libraries
    in separate folders.

    Alternatively, the letter \e d can be added to the library name for the
    debug version. For example, if the release version is called example.lib,
    the debug version is called exampled.lib. You can specify that the letter
    is added for the debug version and removed for the release version.
    If the library name ends in \e d, deselect the \uicontrol {Remove "d" suffix
    for release version} option.

    For more information about the project file settings, see
    \l{Declaring Other Libraries}{qmake Manual: Declaring Other Libraries}.

    \sa {Adding an Internal Library to a qmake Project}{Tutorial: Adding an Internal Library to a qmake Project},
    {Add subprojects to projects}, {Add libraries to CMake projects},
    {Use project wizards}, {Creating Projects}
*/

/*!
    \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 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}. 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-internal-project-location.webp {Project Location dialog}

        \li In the \uicontrol Name field, give a name for the library. For example,
            \e MyLibrary.

        \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 subdirs project. For example, \e MyApplication.
    \endlist

    \section1 Linking an application to the library

    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
            project file.

    \endlist

    When using CMake, the \c target_link_libraries command is added to the
    CMakeLists.txt file:

    \badcode
    target_link_libraries(myapplication PRIVATE mylibrary)
    \endcode

    When using qmake, the following library declaration is added to the .pro
    file:

    \badcode
    win32:CONFIG(release, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/release/ -lmylib
    else:win32:CONFIG(debug, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/debug/ -lmylib
    else:unix: LIBS += -L$$OUT_PWD/../../../projects/mylib/ -lmylib
    INCLUDEPATH += $$PWD/../../../projects/mylib
    DEPENDPATH += $$PWD/../../../projects/mylib
    win32:CONFIG(release, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/release/mylib.lib
    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 qmake projects}, {Add libraries to CMake projects},
    {Add subprojects to projects}, {Select the build system},
    {Use project wizards}, {Creating Projects}
*/
