source: trunk/doc/src/howtos/sharedlibrary.qdoc@ 846

Last change on this file since 846 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

  • Property svn:eol-style set to native
File size: 6.1 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
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 share 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*/
Note: See TracBrowser for help on using the repository browser.