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

From Qt Wiki
Revision as of 11:46, 18 May 2015 by Julienw (talk | contribs) (add lang="make" to <code>)
Jump to navigation Jump to search



English Español Русский

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.

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 <QtGui>

#if defined TEST
 #define TEST_COMMON_DLLSPEC Q_DECL_EXPORT
#else
 #define TEST_COMMON_DLLSPEC Q_DECL_IMPORT
#endif

class TEST_COMMON_DLLSPEC Widget : public QWidget
{
 Q_OBJECT
 public:
  Widget();
};

test.cpp

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

Widget::Widget() : QWidget() {}

test.pro

TEMPLATE = lib

# Input
SOURCES += test.cpp
HEADERS += test.h
DEFINES += TEST

In windows, MinGW will output .a and .dll, MSVC2010 will ouput .lib and .dll. In linux, MinGW will output .so, .so.1, .so.1.0 and .so.1.0.0 - .lib, .a and .so are import libraries. They help link your code to the library and is needed when you build your file(.a files not all the time).

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, then you can include the headers of your library in your code and use the methods. Compile with linking to the .lib file. At runtime this loads the dll which has the implementation.

To set this up, then in your application's .pro file you need to inform the application 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 .lib file. In addition you need to ensure that the .dll is found by either putting it in the application's directory or in the global PATH.

For example:

loadTestLib.pro

TEMPLATE = app
TARGET =
DEPENDPATH += . ../testLib
INCLUDEPATH += ../testLib
LIBS += -L../testLib/debug -ltestLib

# Input
SOURCES += main.cpp

main.cpp

#include <QtGui>
#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 MSCV2010 compiler in windows, you look for .lib
  • in 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 MSCV2010 compiled library.
  • in 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 small caps.


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 += TEST

widget.h

#include <QtGui>

#if defined TEST
 #define TEST_COMMON_DLLSPEC Q_DECL_EXPORT
#else
 #define TEST_COMMON_DLLSPEC Q_DECL_IMPORT
#endif

extern "C" TEST_COMMON_DLLSPEC QWidget* createWidget1();

widget.cpp

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

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

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 <QtGui>

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

 typedef QWidget*(*CreateWidgetFunction)(void);
 CreateWidgetFunction cwf = (CreateWidgetFunction)library.resolve("createWidget1");
 if (cwf) {
  QWidget* wid = cwf();
  if (wid) wid->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

# Input
SOURCES += main.cpp
INCLUDEPATH += ../staticLibrary
LIBS += -L../staticLibrary/debug -lstaticLibrary

main.cpp

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

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]
Debug:libraryFiles.files = $$OUT_PWD/debug/*.a $$OUT_PWD/debug/*.prl
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.


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.