SVN checkout 11/12/2010
[monav:monav.git] / routingdaemon / qtservice-2.6_1-opensource / INSTALL.TXT
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.