Update copyright headers
[qt:qt.git] / doc / src / howtos / sharedlibrary.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page sharedlibrary.html
30     \title Creating Shared Libraries
31     \brief How to create shared libraries.
32     \ingroup best-practices
33
34     The following sections list certain things that should be taken into
35     account when creating shared libraries.
36
37     \section1 Using Symbols from Shared Libraries
38
39     Symbols - functions, variables or classes - contained in shared libraries
40     intended to be used by \e{clients}, such as applications or other
41     libraries, must be marked in a special way. These symbols are called
42     \e{public symbols} that are \e{exported} or made publicly visible.
43
44     The remaining symbols should not be visible from the outside. On most
45     platforms, compilers will hide them by default. On some platforms, a
46     special compiler option is required to hide these symbols.
47
48     When compiling a shared library, it must be marked for \e{export}. To use
49     the shared library from a client, some platforms may require a special
50     \e{import} declaration as well.
51
52     Depending on your target platform, Qt provides special macros that contain
53     the necessary definitions:
54     \list
55         \o  \c{Q_DECL_EXPORT} must be added to the declarations of symbols used
56             when compiling a shared library.
57         \o  \c{Q_DECL_IMPORT} must be added to the declarations of symbols used
58             when compiling a client that uses the shared library.
59     \endlist
60
61     Now, we need to ensure that the right macro is invoked -- whether we
62     compile a shared library itself, or just the client using the shared
63     library.
64     Typically, this can be solved by adding a special header.
65
66     Let us assume we want to create a shared library called \e{mysharedlib}.
67     A special header for this library, \c{mysharedlib_global.h}, looks like
68     this:
69
70     \code
71         #include <QtCore/QtGlobal>
72
73         #if defined(MYSHAREDLIB_LIBRARY)
74         #  define MYSHAREDLIB_EXPORT Q_DECL_EXPORT
75         #else
76         #  define MYSHAREDLIB_EXPORT Q_DECL_IMPORT
77         #endif
78     \endcode
79
80     In the \c{.pro} file of the shared library, we add:
81
82     \code
83         DEFINES += MYSHAREDLIB_LIBRARY
84     \endcode
85
86     In each header of the library, we specify the following:
87
88     \code
89         #include "mysharedlib_global.h"
90
91         MYSHAREDLIB_EXPORT void foo();
92         class MYSHAREDLIB_EXPORT MyClass...
93     \endcode
94     This ensures that the right macro is seen by both library and clients. We
95     also use this technique in Qt's sources.
96
97
98     \section1 Header File Considerations
99
100     Typically, clients will include only the public header files of shared
101     libraries. These libraries might be installed in a different location, when
102     deployed. Therefore, it is important to exclude other internal header files
103     that were used when building the shared library.
104
105     For example, the library might provide a class that wraps a hardware device
106     and contains a handle to that device, provided by some 3rd-party library:
107
108     \code
109         #include <footronics/device.h>
110
111         class MyDevice {
112         private:
113             FOOTRONICS_DEVICE_HANDLE handle;
114         };
115     \endcode  
116
117     A similar situation arises with forms created by Qt Designer when using
118     aggregation or multiple inheritance:
119
120     \code
121         #include "ui_widget.h"
122
123         class MyWidget : public QWidget {
124         private:
125             Ui::MyWidget m_ui;
126         };
127     \endcode  
128
129     When deploying the library, there should be no dependency to the internal
130     headers \c{footronics/device.h} or \c{ui_widget.h}.
131
132     This can be avoided by making use of the \e{Pointer to implementation}
133     idiom described in various C++ programming books. For classes with
134     \e{value semantics}, consider using QSharedDataPointer.
135
136
137     \section1  Binary compatibility
138
139     For clients loading a shared library, to work correctly, the memory
140     layout of the classes being used must match exactly the memory layout of
141     the library version that was used to compile the client. In other words,
142     the library found by the client at runtime must be \e{binary compatible}
143     with the version used at compile time.
144
145     This is usually not a problem if the client is a self-contained software
146     package that ships all the libraries it needs.
147
148     However, if the client application relies on a shared library that belongs
149     to a different installation package or to the operating system, then we
150     need to think of a versioning scheme for shared libraries and decide at
151     which level \e{Binary compatibility} is to be maintained. For example, Qt
152     libraries of the same \e{major version number} are guaranteed to be binary
153     compatible.
154
155     Maintaining \e{Binary compatibility} places some restrictions on the changes
156     you can make to the classes. A good explanation can be found at
157     \l{http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++}
158     {KDE - Policies/Binary Compatibility Issues With C++}. These issues should
159     be considered right from the start of library design.
160     We recommend that the principle of \e{Information hiding} and the
161     \e{Pointer to implementation} technique be used wherever possible.
162 */