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