1 INSTALLATION INSTRUCTIONS
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
7 The directory you choose for the installation will be referred to as
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
16 Unpacking and installation
17 --------------------------
19 1. Unpacking the archive (if you have not done so already).
21 On Unix and Mac OS X (in a terminal window):
24 gunzip some-package.tar.gz
25 tar xvf some-package.tar
27 This creates the subdirectory some-package containing the files.
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.
36 If you are using the infozip tools (in a command prompt window):
38 unzip some-package.zip
40 2. Configuring the package.
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.
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.
54 (Components that are Qt plugins, e.g. styles and image formats,
55 are by default built as a plugin DLL.)
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.
62 3. Building the component and examples (when required).
64 If a DLL is to be built, or if you would like to build the
65 examples, next give the commands
68 make [or nmake if your are using Microsoft Visual C++]
70 The example program(s) can be found in the directory called
71 "examples" or "example".
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.
77 4. Building the Qt Designer plugin (optional).
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
84 make [or nmake if your are using Microsoft Visual C++]
86 Restart Qt Designer to make it load the new widget plugin.
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
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
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.
102 Solutions components are intended to be used directly from the package
103 directory during development, so there is no 'make install' procedure.
106 Using a component in your project
107 ---------------------------------
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):
112 include(your-install-dir/some-package/src/some-package.pri)
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.
121 To include a header file from the package in your sources, you can now
126 or alternatively, in pre-Qt 4 style:
128 #include <some-class.h>
130 Refer to the documentation to see the classes and headers this
135 Install documentation (optional)
136 --------------------------------
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.
142 To install the documentation into Qt Assistant (for Qt version 4.4 and
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
149 For Qt versions prior to 4.4, do instead the following:
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:
155 cd your-install-dir/some-package/doc/html/
156 assistant -addContentFile some-package.dcf
158 The next time you start Qt Assistant, you can access the package's
162 Removing the documentation from assistant
163 -----------------------------------------
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:
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
172 For Qt versions prior to 4.4, do instead the following:
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:
178 cd your-install-dir/some-package/doc/html/
179 assistant -removeContentFile some-package.dcf
183 Using the component as a DLL
184 ----------------------------
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.
195 The following steps are taken by default to help the dynamic
196 linker to locate the DLL at run-time (during development):
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
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.)
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.
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.
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
242 The following command will remove any fils that have been
243 automatically placed outside the package directory itself during
244 installation and building
246 make distclean [or nmake if your are using Microsoft Visual C++]
248 If Qt Assistant documentation or Qt Designer plugins have been
249 installed, they can be uninstalled manually, ref. above.
254 - The Qt Solutions Team.