How to create a library with Qt and use it in an application

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

Introduction

This tutorial illustrates different approaches for using a custom library in your application on Windows. The first part explains how to create a shared library and how to link against it in your application. The second part is about creating and using a static library.

To organize a bigger project with libraries and executables, take a look at SUBDIRS - handling dependencies

Creating a shared library

When creating a shared library that you would like to link against, then you need to ensure that the symbols that are going to be used outside the library are properly exported when the library is created. Subsequently imported when you are linking against the library. This can be done using Q_DECL_EXPORT and Q_DECL_IMPORT as shown in the following example:

test.h

#include <QWidget>

#if defined MAKE_TEST_LIB
    #define TEST_LIB_EXPORT Q_DECL_EXPORT
#else
    #define TEST_LIB_EXPORT Q_DECL_IMPORT
#endif
    
class TEST_LIB_EXPORT Widget : public QWidget
{
    Q_OBJECT
public:
    Widget(QWidget *parent = nullptr);
};

test.cpp

#include "test.h"
#include <QtWidgets>

Widget::Widget(QWidget *parent) : QWidget(parent) {}

test.pro

TEMPLATE = lib
SOURCES += test.cpp
HEADERS += test.h
DEFINES += MAKE_TEST_LIB
QT += widgets

On Windows, MinGW will output .a and .dll, MSVC will output .lib and .dll.

On Linux, gcc/clang will output .so, .so.1, .so.1.0 and .so.1.0.0

.lib, .a and .so are import libraries. They are needed to link your code against the library.

See also the documentation on Creating Shared Libraries.

Linking your application against the shared library

In order to use the shared library in your application, you can include the headers of your library in your code and use the methods/classes from there. Also you need to link against the import library file (.lib, .a and .so). At runtime this loads the shared library (.so.1.0.0 / .dll) which has the implementation.

To set this up, you have to modify your application's .pro file. You need to inform qmake where to find the headers and the library. The INCLUDEPATH needs to point to the directory where the headers are installed, and the LIBS variable needs to point to the directory of the import library file. In addition you need to ensure that the shared library is found by either putting it in the application's directory or in the global PATH on windows and the LD_LIBRARY_PATH on linux.

For example:

loadTestLib.pro

TEMPLATE = app
TARGET =
DEPENDPATH += . ../testLib
INCLUDEPATH += ../testLib
LIBS += -L../testLib/debug -ltestLib
#Input
SOURCES += main.cpp

main.cpp

#include <QtWidgets>
#include "test.h"

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    Widget w;
    w.resize(100, 100);
    w.show();
    return a.exec();
}

alternatively you can right-click your project in Qt Creator and select "Add Library...", choose "External library" and browse for your library file:

• For libraries compiled with MSCV compiler in windows, you look for .lib or .dll
• On Windows, MinGW compiled linking libraries are in .a, but you will need to add it manually (as of Qt Creator 2.7). You could also try simply linking the .dll directly cause it would probably work. Don't try this with a MSVC compiled library .
• On Linux you look for the .so file

This will append the following code to your *.pro file:

win32:CONFIG (release, debug|release): LIBS += -L$$PWD/build-MyLibrary/ -lmylibrary
else:win32:CONFIG (debug, debug|release): LIBS += -L$$PWD/build-MyLibrary/ -lmylibrary
else:unix: LIBS += -L$$PWD/build-MyLibrary/ -lMyLibrary

INCLUDEPATH += $$PWD/build-MyLibrary
DEPENDPATH += $$PWD/build-MyLibrary

$$PWD is used here to specify the full path leading to the directory containing your .pro file.

Note that for Unix/Linux systems the library file name is case sensitive, but for Windows you have to leave in all lower case.

Using QLibrary to load the shared library

QLibrary can be used for loading shared libraries at runtime. In this case you only need access to the .dll, access to the headers and .lib file(s) is not necessary.

The following example shows how to set up a library for usage with QLibrary. For the function names to be resolvable, they must be exported as C functions (i.e., without name mangling) from the library. This means that the functions must be wrapped in an extern "C" block if the library is compiled with a C++ compiler.

Since we are doing this on Windows we also must explicitly export the function from the DLL using Q_DECL_EXPORT and Q_DECL_IMPORT.

qlibraryLibrary.pro

TEMPLATE = lib
HEADERS += widget.h
SOURCES += widget.cpp
DEFINES += MAKE_TEST_LIB
QT += widgets

widget.h

#include <QWidget>

#if defined MAKE_TEST_LIB
 #define TEST_LIB_EXPORT Q_DECL_EXPORT
#else
 #define TEST_LIB_EXPORT Q_DECL_IMPORT
#endif

extern "C" TEST_LIB_EXPORT QWidget *createWidget1();

widget.cpp

#include <QtWidgets>
#include "widget.h"

QWidget *createWidget1()
{
    QWidget *widget = new QWidget();
    widget->resize(100, 100);
    return widget;
}

Loading the library using QLibrary

To load the library using QLibrary, you can simply pass in the .dll to the QLibrary constructor. Make sure the .dll is available in the application directory or in the global PATH. To use functions from the library in your application, you need to resolve them using QLibrary::resolve().

The example below loads the library created above and uses one of its functions to create and show a widget.

#include <QtWidgets>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    QLibrary library("qlibraryLibrary.dll");
    if (!library.load())
        qDebug() << library.errorString();
    if (library.load())
        qDebug() << "library loaded";

    typedef QWidget *(*CreateWidgetFunction)();
    CreateWidgetFunction cwf = (CreateWidgetFunction)library.resolve("createWidget1");
    if (cwf) {
        QWidget *widget = cwf();
        if (widget) 
            widget->show();
    } else {
        qDebug() << "Could not show widget from the loaded library";
    }
    return app.exec();
}

Creating a static library

When creating a static library you need to specify the staticlib option to CONFIG in the .pro file. In contrast to the shared library example, you don't need to set up anything special for exporting and importing symbols in your .h file, since the library will be built into the application, for example:

test.pro

TEMPLATE = lib
CONFIG += staticlib
#Input
HEADERS += test.h
SOURCES += test.cpp

Using the static library in your application

Similar to what we did for the shared library loading, you need to set up the INCLUDEPATH to point to the directory where the headers are installed and the LIBS variable to point to the .lib file, for example:

useStaticLib.pro

TEMPLATE = app
TARGET =
CONFIG += console
QT += widgets
#Input
SOURCES += main.cpp
INCLUDEPATH += ../staticLibrary
LIBS += -L../staticLibrary/debug -lstaticLibrary

main.cpp

#include "test.h"
#include <QtWidgets>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    Widget w;
    w.resize(100, 100);
    w.show();
    return a.exec();
}

Installing a library

When you build your libraries, it could be useful to have one build for one framework and to centralize them : for example, you could having one library for Android, one for Windows and QT5.4 and one for Windows with Qt5.5 without having specific configurations. The easiest way is to put your files in the Qt folders by adding in your *.pro file :

headersDataFiles.path = $$[QT_INSTALL_HEADERS]/MyLib/
headersDataFiles.files = $$PWD/src/*.h
INSTALLS += headersDataFiles

libraryFiles.path = $$[QT_INSTALL_LIBS]
CONFIG(debug, debug|release):libraryFiles.files = $$OUT_PWD/debug/*.a $$OUT_PWD/debug/*.prl
CONFIG(release, debug|release):libraryFiles.files = $$OUT_PWD/release/*.a $$OUT_PWD/release/*.prl
INSTALLS += libraryFiles

You need to specify what files you want to copy with $$OUT_PWD and where you want to put them by using $$QT_INSTALL_HEADERS and $$QT_INSTALL_LIBS.

For more information, see Installing Files.

Which approach to choose

Which approach to choose depends on your needs. When creating a shared library, you need to deploy it with your application. On the plus side, applications and libraries linked against a shared library are small. Whether to use QLibrary to load the .dll or just standard linking, depends on whether you have access to the headers and the .lib files, if you don't have access to those, then QLibrary is an alternative.

Static linking results in a stand-alone executable. The advantage is that you will only have a few files to deploy. The disadvantage is that the executables are large. See the Deployment documentation for more details on shared and static builds.