Remove the SCons build scripts and move include directory
[deb_shairplay.git] / AirTV-Qt / qtsingleapplication / INSTALL.TXT
CommitLineData
2340bcd3
JVH
1INSTALLATION INSTRUCTIONS
2
3These instructions refer to the package you are installing as
4some-package.tar.gz or some-package.zip. The .zip file is intended for use
5on Windows.
6
7The directory you choose for the installation will be referred to as
8your-install-dir.
9
10Note to Qt Visual Studio Integration users: In the instructions below,
11instead of building from command line with nmake, you can use the menu
12command 'Qt->Open Solution from .pro file' on the .pro files in the
13example and plugin directories, and then build from within Visual
14Studio.
15
16Unpacking and installation
17--------------------------
18
191. 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
402. 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
623. 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
774. 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
102Solutions components are intended to be used directly from the package
103directory during development, so there is no 'make install' procedure.
104
105
106Using a component in your project
107---------------------------------
108
109To use this component in your project, add the following line to the
110project's .pro file (or do the equivalent in your IDE):
111
112 include(your-install-dir/some-package/src/some-package.pri)
113
114This adds the package's sources and headers to the SOURCES and HEADERS
115project variables respectively (or, if the component has been
116configured as a DLL, it adds that library to the LIBS variable), and
117updates INCLUDEPATH to contain the package's src
118directory. Additionally, the .pri file may include some dependencies
119needed by the package.
120
121To include a header file from the package in your sources, you can now
122simply use:
123
124 #include <SomeClass>
125
126or alternatively, in pre-Qt 4 style:
127
128 #include <some-class.h>
129
130Refer to the documentation to see the classes and headers this
131components provides.
132
133
134
135Install documentation (optional)
136--------------------------------
137
138The HTML documentation for the package's classes is located in the
139your-install-dir/some-package/doc/html/index.html. You can open this
140file and read the documentation with any web browser.
141
142To install the documentation into Qt Assistant (for Qt version 4.4 and
143later):
144
1451. 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
149For Qt versions prior to 4.4, do instead the following:
150
1511. 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
158The next time you start Qt Assistant, you can access the package's
159documentation.
160
161
162Removing the documentation from assistant
163-----------------------------------------
164
165If you have installed the documentation into Qt Assistant, and want to uninstall it, do as follows, for Qt version 4.4 and later:
166
1671. 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
172For Qt versions prior to 4.4, do instead the following:
173
1741. 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
183Using the component as a DLL
184----------------------------
185
1861. 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
2172. 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
239Uninstalling
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
252Enjoy! :)
253
254- The Qt Solutions Team.