qt-everywhere-src-5.15.1/qtdoc/doc/src/howtos/third-party-libraries.qdoc

/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page third-party-libraries.html
    \title Third Party Libraries
    \brief A guide to using third party libraries with Qt

    Using a third-party library with Qt is a simple process. Suppose you know
    of a cross-platform library that accepts audio samples of a cat's meows and
    translates them into English words. This library is named \c CatWhisperer,
    and has several files that it provides as part of its library.
    Your project, \c MyQtApp, stores these files in a folder named \c 3rdparty:

    \list
    \li MyQtApp/
        \list
        \li MyQtApp.pro
        \li src/
            \list
            \li main.cpp
            \endlist
        \li 3rdparty/
            \list
            \li CatWhisperer
                \list
                \li include/
                    \list
                    \li CatWhisperer.h
                    \endlist
                \li lib/
                    \list
                    \li libCatWhisperer.so
                    \li CatWhisperer.lib
                    \endlist
                \li bin/
                    \list
                    \li CatWhisperer.dll
                    \endlist
                \endlist
            \endlist
        \endlist
    \endlist

    To use the \c CatWhisperer library in \c MyQtApp, \c qmake requires the
    location and names of the \c CatWhisperer libraries.
    Optionally, you can also:

    \list
    \li Provide the location of the \c CatWhisperer source code so that you
    don't have to type out the full path to each file when you include them
    in your own code.
    \li Choose the destination in which the \c MyQtApp executable will be
    created.
    \endlist

    The information above is provided in the \c .pro file, so that \c qmake can
    parse it and produce makefiles. Makefiles contain all the information
    needed by your compiler and linker to produce output, whether it is an
    executable, another library file, etc. The next sections explain the syntax
    with which \c qmake expects you to provide this information.

    \section1 Source Code

    To be able to write

    \code
    #include <CatWhisperer.h>
    \endcode

    instead of

    \code
    #include <3rdparty/CatWhisperer/include/CatWhisperer.h>
    \endcode

    you can provide the path to the \c CatWhisperer \c include directory,
    using the \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} variable:

    \code
    INCLUDEPATH += 3rdparty/CatWhisperer/include
    \endcode

    \section1 Library Files

    To let \c qmake know where to find the \c CatWhisperer library files,
    use the \l{qmake Variable Reference#LIBS}{LIBS} variable:

    \code
    LIBS += -L"3rdparty/CatWhisperer/lib" -lCatWhisperer
    \endcode

    The first part of the expression lets the linker know in which directory
    it should look for the library files. The double quotes are only necessary
    when the path contains spaces, so we could have omitted them in this
    example.

    The second part tells the linker which libraries to link against. We have
    two different library files for UNIX platforms and Windows, respectively:
    \c libCatWhisperer.so and \c CatWhisperer.lib. It is not necessary
    to specify the \c .lib extension, nor the \c lib prefix
    (on UNIX platforms).

    \section1 Destination Directory

    By default, \c qmake creates the executable in the same directory as the
    \c .pro file. We can choose our own directory using the
    \l{qmake Variable Reference#DESTDIR}{DESTDIR} variable:

    \code
    DESTDIR = bin
    \endcode

    That's it! You can now use the \c CatWhisperer library in your project.
    The final \c .pro file looks like this:

    \code
    TARGET = MyQtApp

    TEMPLATE = app

    INCLUDEPATH += 3rdparty/CatWhisperer/include

    SOURCES += src/main.cpp

    LIBS += -L"3rdparty/CatWhisperer/lib" -lCatWhisperer
    \endcode

    \sa {qmake Manual}, {Qt Creator: Adding Libraries to Projects}
*/