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