Commit | Line | Data |
---|---|---|
2340bcd3 JVH |
1 | INSTALLATION INSTRUCTIONS |
2 | ||
3 | These instructions refer to the package you are installing as | |
4 | some-package.tar.gz or some-package.zip. The .zip file is intended for use | |
5 | on Windows. | |
6 | ||
7 | The directory you choose for the installation will be referred to as | |
8 | your-install-dir. | |
9 | ||
10 | Note to Qt Visual Studio Integration users: In the instructions below, | |
11 | instead of building from command line with nmake, you can use the menu | |
12 | command 'Qt->Open Solution from .pro file' on the .pro files in the | |
13 | example and plugin directories, and then build from within Visual | |
14 | Studio. | |
15 | ||
16 | Unpacking and installation | |
17 | -------------------------- | |
18 | ||
19 | 1. Unpacking the archive (if you have not done so already). | |
20 | ||
21 | On Unix and Mac OS X (in a terminal window): | |
22 | ||
23 | cd your-install-dir | |
24 | gunzip some-package.tar.gz | |
25 | tar xvf some-package.tar | |
26 | ||
27 | This creates the subdirectory some-package containing the files. | |
28 | ||
29 | On Windows: | |
30 | ||
31 | Unpack the .zip archive by right-clicking it in explorer and | |
32 | choosing "Extract All...". If your version of Windows does not | |
33 | have zip support, you can use the infozip tools available | |
34 | from www.info-zip.org. | |
35 | ||
36 | If you are using the infozip tools (in a command prompt window): | |
37 | cd your-install-dir | |
38 | unzip some-package.zip | |
39 | ||
40 | 2. Configuring the package. | |
41 | ||
42 | The configure script is called "configure" on unix/mac and | |
43 | "configure.bat" on Windows. It should be run from a command line | |
44 | after cd'ing to the package directory. | |
45 | ||
46 | You can choose whether you want to use the component by including | |
47 | its source code directly into your project, or build the component | |
48 | as a dynamic shared library (DLL) that is loaded into the | |
49 | application at run-time. The latter may be preferable for | |
50 | technical or licensing (LGPL) reasons. If you want to build a DLL, | |
51 | run the configure script with the argument "-library". Also see | |
52 | the note about usage below. | |
53 | ||
54 | (Components that are Qt plugins, e.g. styles and image formats, | |
55 | are by default built as a plugin DLL.) | |
56 | ||
57 | The configure script will prompt you in some cases for further | |
58 | information. Answer these questions and carefully read the license text | |
59 | before accepting the license conditions. The package cannot be used if | |
60 | you do not accept the license conditions. | |
61 | ||
62 | 3. Building the component and examples (when required). | |
63 | ||
64 | If a DLL is to be built, or if you would like to build the | |
65 | examples, next give the commands | |
66 | ||
67 | qmake | |
68 | make [or nmake if your are using Microsoft Visual C++] | |
69 | ||
70 | The example program(s) can be found in the directory called | |
71 | "examples" or "example". | |
72 | ||
73 | Components that are Qt plugins, e.g. styles and image formats, are | |
74 | ready to be used as soon as they are built, so the rest of this | |
75 | installation instruction can be skipped. | |
76 | ||
77 | 4. Building the Qt Designer plugin (optional). | |
78 | ||
79 | Some of the widget components are provided with plugins for Qt | |
80 | Designer. To build and install the plugin, cd into the | |
81 | some-package/plugin directory and give the commands | |
82 | ||
83 | qmake | |
84 | make [or nmake if your are using Microsoft Visual C++] | |
85 | ||
86 | Restart Qt Designer to make it load the new widget plugin. | |
87 | ||
88 | Note: If you are using the built-in Qt Designer from the Qt Visual | |
89 | Studio Integration, you will need to manually copy the plugin DLL | |
90 | file, i.e. copy | |
91 | %QTDIR%\plugins\designer\some-component.dll | |
92 | to the Qt Visual Studio Integration plugin path, typically: | |
93 | C:\Program Files\Trolltech\Qt VS Integration\plugins | |
94 | ||
95 | Note: If you for some reason are using a Qt Designer that is built | |
96 | in debug mode, you will need to build the plugin in debug mode | |
97 | also. Edit the file plugin.pro in the plugin directory, changing | |
98 | 'release' to 'debug' in the CONFIG line, before running qmake. | |
99 | ||
100 | ||
101 | ||
102 | Solutions components are intended to be used directly from the package | |
103 | directory during development, so there is no 'make install' procedure. | |
104 | ||
105 | ||
106 | Using a component in your project | |
107 | --------------------------------- | |
108 | ||
109 | To use this component in your project, add the following line to the | |
110 | project's .pro file (or do the equivalent in your IDE): | |
111 | ||
112 | include(your-install-dir/some-package/src/some-package.pri) | |
113 | ||
114 | This adds the package's sources and headers to the SOURCES and HEADERS | |
115 | project variables respectively (or, if the component has been | |
116 | configured as a DLL, it adds that library to the LIBS variable), and | |
117 | updates INCLUDEPATH to contain the package's src | |
118 | directory. Additionally, the .pri file may include some dependencies | |
119 | needed by the package. | |
120 | ||
121 | To include a header file from the package in your sources, you can now | |
122 | simply use: | |
123 | ||
124 | #include <SomeClass> | |
125 | ||
126 | or alternatively, in pre-Qt 4 style: | |
127 | ||
128 | #include <some-class.h> | |
129 | ||
130 | Refer to the documentation to see the classes and headers this | |
131 | components provides. | |
132 | ||
133 | ||
134 | ||
135 | Install documentation (optional) | |
136 | -------------------------------- | |
137 | ||
138 | The HTML documentation for the package's classes is located in the | |
139 | your-install-dir/some-package/doc/html/index.html. You can open this | |
140 | file and read the documentation with any web browser. | |
141 | ||
142 | To install the documentation into Qt Assistant (for Qt version 4.4 and | |
143 | later): | |
144 | ||
145 | 1. In Assistant, open the Edit->Preferences dialog and choose the | |
146 | Documentation tab. Click the Add... button and select the file | |
147 | your-install-dir/some-package/doc/html/some-package.qch | |
148 | ||
149 | For Qt versions prior to 4.4, do instead the following: | |
150 | ||
151 | 1. The directory your-install-dir/some-package/doc/html contains a | |
152 | file called some-package.dcf. Execute the following commands in a | |
153 | shell, command prompt or terminal window: | |
154 | ||
155 | cd your-install-dir/some-package/doc/html/ | |
156 | assistant -addContentFile some-package.dcf | |
157 | ||
158 | The next time you start Qt Assistant, you can access the package's | |
159 | documentation. | |
160 | ||
161 | ||
162 | Removing the documentation from assistant | |
163 | ----------------------------------------- | |
164 | ||
165 | If you have installed the documentation into Qt Assistant, and want to uninstall it, do as follows, for Qt version 4.4 and later: | |
166 | ||
167 | 1. In Assistant, open the Edit->Preferences dialog and choose the | |
168 | Documentation tab. In the list of Registered Documentation, select | |
169 | the item com.nokia.qtsolutions.some-package_version, and click | |
170 | the Remove button. | |
171 | ||
172 | For Qt versions prior to 4.4, do instead the following: | |
173 | ||
174 | 1. The directory your-install-dir/some-package/doc/html contains a | |
175 | file called some-package.dcf. Execute the following commands in a | |
176 | shell, command prompt or terminal window: | |
177 | ||
178 | cd your-install-dir/some-package/doc/html/ | |
179 | assistant -removeContentFile some-package.dcf | |
180 | ||
181 | ||
182 | ||
183 | Using the component as a DLL | |
184 | ---------------------------- | |
185 | ||
186 | 1. Normal components | |
187 | ||
188 | The shared library (DLL) is built and placed in the | |
189 | some-package/lib directory. It is intended to be used directly | |
190 | from there during development. When appropriate, both debug and | |
191 | release versions are built, since the run-time linker will in some | |
192 | cases refuse to load a debug-built DLL into a release-built | |
193 | application or vice versa. | |
194 | ||
195 | The following steps are taken by default to help the dynamic | |
196 | linker to locate the DLL at run-time (during development): | |
197 | ||
198 | Unix: The some-package.pri file will add linker instructions to | |
199 | add the some-package/lib directory to the rpath of the | |
200 | executable. (When distributing, or if your system does not support | |
201 | rpath, you can copy the shared library to another place that is | |
202 | searched by the dynamic linker, e.g. the "lib" directory of your | |
203 | Qt installation.) | |
204 | ||
205 | Mac: The full path to the library is hardcoded into the library | |
206 | itself, from where it is copied into the executable at link time, | |
207 | and ready by the dynamic linker at run-time. (When distributing, | |
208 | you will want to edit these hardcoded paths in the same way as for | |
209 | the Qt DLLs. Refer to the document "Deploying an Application on | |
210 | Mac OS X" in the Qt Reference Documentation.) | |
211 | ||
212 | Windows: the .dll file(s) are copied into the "bin" directory of | |
213 | your Qt installation. The Qt installation will already have set up | |
214 | that directory to be searched by the dynamic linker. | |
215 | ||
216 | ||
217 | 2. Plugins | |
218 | ||
219 | For Qt Solutions plugins (e.g. image formats), both debug and | |
220 | release versions of the plugin are built by default when | |
221 | appropriate, since in some cases the release Qt library will not | |
222 | load a debug plugin, and vice versa. The plugins are automatically | |
223 | copied into the plugins directory of your Qt installation when | |
224 | built, so no further setup is required. | |
225 | ||
226 | Plugins may also be built statically, i.e. as a library that will be | |
227 | linked into your application executable, and so will not need to | |
228 | be redistributed as a separate plugin DLL to end users. Static | |
229 | building is required if Qt itself is built statically. To do it, | |
230 | just add "static" to the CONFIG variable in the plugin/plugin.pro | |
231 | file before building. Refer to the "Static Plugins" section in the | |
232 | chapter "How to Create Qt Plugins" for explanation of how to use a | |
233 | static plugin in your application. The source code of the example | |
234 | program(s) will also typically contain the relevant instructions | |
235 | as comments. | |
236 | ||
237 | ||
238 | ||
239 | Uninstalling | |
240 | ------------ | |
241 | ||
242 | The following command will remove any fils that have been | |
243 | automatically placed outside the package directory itself during | |
244 | installation and building | |
245 | ||
246 | make distclean [or nmake if your are using Microsoft Visual C++] | |
247 | ||
248 | If Qt Assistant documentation or Qt Designer plugins have been | |
249 | installed, they can be uninstalled manually, ref. above. | |
250 | ||
251 | ||
252 | Enjoy! :) | |
253 | ||
254 | - The Qt Solutions Team. |