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

From Qt Wiki
Revision as of 14:10, 23 February 2015 by Maintenance script (talk | contribs)
Jump to navigation Jump to search

English Español Русский


[toc align_right="yes" depth="2"]

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

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 ":http://doc.qt.io/qt-4.8/qtglobal.html#Q_DECL_EXPORT and "Q_DECL_IMPORT":http://doc.qt.io/qt-4.8/qtglobal.html#Q_DECL_IMPORT as shown in the following example:

test.h

<br />#include &lt;QtGui&amp;gt;

#if defined TEST<br />#define TEST_COMMON_DLLSPEC Q_DECL_EXPORT<br />#else<br />#define TEST_COMMON_DLLSPEC Q_DECL_IMPORT<br />#endif

class TEST_COMMON_DLLSPEC Widget : public QWidget<br />{<br /> Q_OBJECT<br />public:<br /> Widget();<br />};

test.cpp

<br />#include &lt;QtGui&amp;gt;<br />#include &quot;test.h&amp;quot;

Widget::Widget() : QWidget()<br />{}<br />

test.pro

TEMPLATE = lib<br /># Input<br />SOURCES ''= test.cpp<br />HEADERS''= test.h<br />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&amp;#40;.a files not all the time&amp;#41;.
See also the documentation on "Creating Shared Libraries&quot;:http://doc.qt.io/qt-4.8/sharedlibrary.html.
h3. 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&quot;:http://doc.qt.io/qt-4.8/qmake-variable-reference.html#includepath needs to point to the directory where the headers are installed, and the "LIBS ":http://doc.qt.io/qt-4.8/qmake-variable-reference.html#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

<br />TEMPLATE = app<br />TARGET =<br />DEPENDPATH''= . ../testLib<br />INCLUDEPATH ''= ../testLib<br />LIBS''= -L../testLib/debug -ltestLib<br /># Input<br />SOURCES ''= main.cpp<br />


main.cpp

<br />#include &lt;QtGui&amp;gt;<br />#include &quot;test.h&amp;quot;
<br />int main(int argc, char '''argv[])<br />{<br /> QApplication a(argc, argv);<br /> Widget w;<br /> w.resize(100,100);<br /> w.show();<br /> return a.exec&amp;amp;#40;&amp;#41;;<br />}<br />


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:


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

INCLUDEPATH ''= $$PWD/build-MyLibrary<br />DEPENDPATH''= $$PWD/build-MyLibrary<br />

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 ":http://doc.qt.io/qt-4.8/qlibrary.html#details 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&amp;#40;s&amp;#41; 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&quot; 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&quot;:http://doc.qt.io/qt-4.8/qtglobal.html#Q_DECL_EXPORT and "Q_DECL_IMPORT&quot;:http://doc.qt.io/qt-4.8/qtglobal.html#Q_DECL_IMPORT

qlibraryLibrary.pro

<br />TEMPLATE = lib<br />HEADERS ''= widget.h<br />SOURCES''= widget.cpp<br />DEFINES ''= TEST<br />


widget.h

<br />#include &lt;QtGui&amp;gt;
<br />#if defined TEST<br />#define TEST_COMMON_DLLSPEC Q_DECL_EXPORT<br />#else<br />#define TEST_COMMON_DLLSPEC Q_DECL_IMPORT<br />#endif
<br />extern &quot;C&amp;quot; TEST_COMMON_DLLSPEC QWidget* createWidget1();
<br />


widget.cpp

<br />#include &lt;QtGui&amp;gt;<br />#include &quot;widget.h&amp;quot;
<br />QWidget* createWidget1()<br />{<br /> QWidget '''wid = new QWidget();<br /> wid-&gt;resize(100,100);<br /> return wid;<br />}
<br />


h3. 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()":http://doc.qt.io/qt-4.8/qlibrary.html#resolve.
The example below loads the library created above and uses one of its functions to create and show a widget.


<br />#include &lt;QtGui&amp;gt;
<br />int main(int argc, charargv)<br />{<br /> QApplication app(argc, argv);<br /> QLibrary library(&quot;qlibraryLibrary.dll&amp;quot;);<br /> if (!library.load())<br /> qDebug() &lt;&lt; library.errorString();<br /> if (library.load())<br /> qDebug() &lt;&lt; &quot;library loaded&amp;quot;;
<br /> typedef QWidget'''('''CreateWidgetFunction)(void);<br /> CreateWidgetFunction cwf = (CreateWidgetFunction)library.resolve(&quot;createWidget1&amp;quot;);<br /> if (cwf) {<br /> QWidget''' wid = cwf();<br /> if (wid)<br /> wid-&gt;show();<br /> } else {<br /> qDebug() &lt;&lt; &quot;Could not show widget from the loaded library&amp;quot;;<br /> }<br /> return app.exec&amp;amp;#40;&amp;#41;;<br />}<br />


h2. Creating a static library
When creating a static library you need to specify the staticlib option to "CONFIG ":http://doc.qt.io/qt-4.8/qmake-variable-reference.html#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

<br />TEMPLATE = lib<br />CONFIG''= staticlib<br /># Input<br />HEADERS ''= test.h<br />SOURCES''= test.cpp<br />

Using the static library in your application

Similar to what we did for the shared library loading, you need to set up the "INCLUDEPATH&quot;:http://doc.qt.io/qt-4.8/qmake-variable-reference.html#includepath to point to the directory where the headers are installed and the "LIBS&quot;:http://doc.qt.io/qt-4.8/qmake-variable-reference.html#libs variable to point to the .lib file, for example:

useStaticLib.pro

<br />TEMPLATE = app<br />TARGET =<br />CONFIG+= console<br /># Input<br />SOURCES ''= main.cpp<br />INCLUDEPATH''= ../staticLibrary<br />LIBS+= -L../staticLibrary/debug -lstaticLibrary

main.cpp

<br />#include &lt;QtGui&amp;gt;<br />#include &quot;test.h&amp;quot;

int main(int argc, char *argv[])<br />{<br /> QApplication a(argc, argv);<br /> Widget w;<br /> w.resize(100,100);<br /> w.show();<br /> return a.exec&amp;amp;#40;&amp;#41;;<br />}<br />

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&quot;:http://doc-snapshot.qt.io/4.8/deployment.html for more details on shared and static builds.