source: tspsg/doc/dox/install.dox @ b9167cec6d

appveyorimgbot
Last change on this file since b9167cec6d was b9167cec6d, checked in by Oleksii Serdiuk, 8 years ago

Update copyright years

  • Property mode set to 100644
File size: 10.9 KB
Line 
1/*! \page install TSPSG Installation Guide
2
3\author Copyright &copy; 2007-2016 Oleksii Serdiuk <contacts[at]oleksii[dot]name>
4$Id: $Format:%h %ai %an$ $
5$URL: http://tspsg.info/ $
6
7Thank you for trying \b TSPSG. This document will guide you through the
8steps necessary to compile and run \b TSPSG.
9
10<hr>
11
12\section i_toc Table of Contents
13
14  -# \ref i_s1
15  -# \ref i_s2
16  -# \ref i_s3
17  -# \ref i_s4
18     -# \ref i_s41
19     -# \ref i_s42
20     -# \ref i_s43
21     -# \ref i_s44
22        -# \ref i_s441
23        -# \ref i_s442
24     -# \ref i_s45
25     -# \ref i_s46
26     -# \ref i_s47
27  -# \ref i_s5
28  -# \ref i_s6
29     -# \ref i_s61
30  -# \ref i_s7
31  -# \ref i_s8
32
33<hr>
34
35\section i_s1 REQUIREMENTS
36
37To be able compile \b TSPSG you need to have <em>Qt libraries</em>\anchor cr1<sup>\ref r1 "[1]"</sup>. The minimum
38supported version of \em Qt is <b>4.5.0</b>. The recommended version is <b>4.6.x</b>
39or higher.
40
41\note Please, note that there will be some regressions in functionality
42if your version of \em Qt is lower than the recommended.
43
44<hr><hr>
45
46\section i_s2 ASSUMPTIONS
47
48This guide assumes that you already have <em>Qt libraries</em> and all necessary
49prerequisites installed.
50
51Also, the following assumptions are made:
52
53  - For \b Linux/UNIX/BSD: \c lrelease and \c qmake are avilable in \c $PATH.
54  - For \b Windows (\em minGW) and \b Symbian: you have installed <em>Qt SDK</em> or
55    prebuilt libraries and have Start Menu items for Qt tools.
56  - For \b Windows (<em>Visual Studio</em>) and <b>Windows Mobile</b>: the <em>Qt libraries</em>
57    reside in <tt>C:\\Qt\\</tt>.
58  - For <b>Windows Mobile</b>: <em>Windows Mobile 5.0 Pocket PC SDK</em> or later is
59    installed.
60
61<hr><hr>
62
63\section i_s3 SUPPORTED PLATFORMS
64
65\b TSPSG is oficially supported and tested on the following platforms:
66
67  - <b>Linux</b>: <em>Gentoo AMD64</em> and <em>Kubuntu 9.10 64-bit AMD</em>.
68  - <b>Windows</b>: <em>Windows XP 32-bit</em> and <em>Windows 7 64-bit</em>.
69  - <b>Windows Mobile</b>: <em>Windows Mobile 6.5 Professional Edition</em>.
70
71<hr><hr>
72
73\section i_s4 BUILDING AND INSTALLATION
74
75\subsection i_s41 GENERAL INSTALLATION PROCEDURE
76
77To be able ot build \b TSPSG you need to have the following Qt modules:
78\em QtCore, \em QtGui and \em QtSvg. The first two are required, the last one is
79optional. To get support for additional image formats (i.e., \b JPEG and
80\b TIFF) you'll additionally need corresponding <em>Qt imageformats</em> plugins.
81
82If you want to build \b TSPSG without \b SVG support add \c nosvg to \c qmake
83\c CONFIG parameter, so that qmake command will typically be:
84
85\verbatim
86qmake CONFIG+=release CONFIG+=nosvg
87\endverbatim
88
89This way you will not depend on \em QtSvg module but will not be able to
90export solution graph in \b SVG format.
91
92
93\b TSPSG uses \c qmake \c PREFIX parameter to determine installation path for
94make install command. If you don't specify it when running \c qmake, it
95will be assigned the default value depending on the platform:
96
97<table>
98<tr><th>Platform</th><th>Default \c PREFIX value</th></tr>
99<tr><td>\b Linux/UNIX/BSD</td><td>\c /usr</td></tr>
100<tr><td>\b Windows</td><td></td>\c \%PROGRAMFILES\% environment variable (usually, it is <tt>C:\\Program Files</tt>)</tr>
101<tr><td><b>Windows CE/Mobile</b></td><td><tt>\\Program Files</tt></td></tr>
102<tr><td>\b Symbian</td><td></td><em>\<ignored></em></tr>
103</table>
104
105\note Please, note that there are no installation and/or packaging
106rules for \b MacOS and other platforms not mentioned in this table.
107
108
109By default, \b TSPSG uses precompiled header when being built. If you
110experience problems with it you may add \c CONFIG+=nopch parameter to
111\c qmake to disable the generation and use of the precompiled header.
112
113<hr>
114
115\subsection i_s42 GENERAL INSTALLATION PROCEDURE
116
117On most platforms the general building and installation procedure is:
118
119  -# Run \c lrelease to generate binary translation files (.qm) from the
120     source (.ts).
121  -# Run \c qmake with \c CONFIG+=release parameter to generate makefiles.
122  -# Run make utility (e.g., \c make, \c nmake, \c mingw32-make) to build \b TSPSG.
123  -# Run make utility with \c install parameter.
124
125\note It is important to run \c lrelease before \c qmake, or \c qmake will not
126"pick up" the translations when generating installation rules.
127
128<hr>
129
130\subsection i_s43 LINUX/UNIX/BSD
131
132Open a shell, navigate to the directory where you have \b TSPSG source
133downloaded and type
134
135\verbatim
136tar xvjf tspsg-<VERSION>-src.tar.bz2
137cd tspsg-<VERSION>-src
138\endverbatim
139
140where \<VERSION> is the version of \b TSPSG you downloaded. Now run
141
142\verbatim
143lrelease tspsg.pro
144qmake tspsg.pro
145make
146\endverbatim
147
148In some cases you may need to type
149
150\verbatim
151qmake tspsg.pro CONFIG+=release
152\endverbatim
153
154If make step finished without errors you can install \b TSPSG by running
155
156\verbatim
157sudo make install
158\endverbatim
159
160or
161
162\verbatim
163su
164make install
165\endverbatim
166
167depending on your distribution.
168
169The executable goes to \c \<PREFIX>/bin; \c COPYING, \c ChangeLog.txt, \c README.txt
170and \c INSTALL.txt go to \c \<PREFIX>/share/doc/TSPSG-\<VERSION>.
171
172<hr>
173
174\subsection i_s44 WINDOWS
175
176\b TSPSG will be installed to \c \<PREFIX>\\TSPSG folder.
177
178\note Please, read the section \ref i_s7 after reading this section.
179
180\subsubsection i_s441 USING MINGW
181
182Unpack the downloaded source code of \b TSPSG with your favourite
183compression software. Now launch the <em>Qt Command Prompt</em> from the Start
184Menu, navigate to the directory where you unpacked the source and run
185
186\verbatim
187lrelease tspsg.pro
188qmake tspsg.pro CONFIG+=release
189mingw32-make
190\endverbatim
191
192\note Make process may fail with a crash of \c windres.exe. If you've run
193into this issue, please, read the section \ref i_s61.
194
195If make step finished without errors you can install \b TSPSG by running
196
197\verbatim
198mingw32-make install
199\endverbatim
200
201
202\subsubsection i_s442 USING VISUAL STUDIO
203
204Unpack the downloaded source code of \b TSPSG with your favourite
205compression software. Now launch the <em>Visual Studio Command Prompt</em> from
206the Start Menu, navigate to the directory where you unpacked the source
207and run
208
209\verbatim
210C:\Qt\bin\lrelease tspsg.pro
211C:\Qt\bin\qmake tspsg.pro CONFIG+=release
212nmake
213\endverbatim
214
215If make step finished without errors you can install \b TSPSG by running
216
217\verbatim
218nmake install
219\endverbatim
220
221<hr>
222
223\subsection i_s45 WINDOWS CE/MOBILE
224
225Unpack the downloaded source code of \b TSPSG with your favourite
226compression software. Now launch the <em>Visual Studio Command Prompt</em> from
227the Start Menu and run
228
229\verbatim
230set PATH=C:\Qt\bin;\%PATH\%
231setcepaths wincewm50pocket-msvc2008
232\endverbatim
233
234Now navigate to the directory where you unpacked the source and run
235
236\verbatim
237lrelease tspsg.pro
238qmake tspsg.pro CONFIG+=release
239nmake
240\endverbatim
241
242There is no automated installation process for Windows Mobile build. To
243install \b TSPSG on your PDA you need to create a folder on your device
244and copy the following files to it:
245
246  - \b tspsg.exe from \c release folder in the source directory.
247  - \b QtCore4.dll and \c QtGui4.dll from \c C:\\Qt\\bin folder.
248  - \b msvcr90.dll from <tt>C:\\Program Files\\Microsoft Visual Studio 9.0\\VC\\ce\\dll\\armv4i</tt> folder.
249  - all <b>*.qm</b> files from \c l10n folder in the source directory to \c l10n subfolder.
250
251<hr>
252
253\section i_s46 SYMBIAN
254
255Unpack the downloaded source code of \b TSPSG with your favourite
256compression software. Now launch the <em>Qt for Symbian Command Prompt</em> from
257the Start Menu, navigate to the directory where you unpacked the source
258and run
259
260\verbatim
261lrelease tspsg.pro
262qmake tspsg.pro CONFIG+=release
263make release-gcce
264\endverbatim
265
266\warning You need to unpack the source to the <em>same drive</em> as <em>Symbian SDK</em>
267and the path <em>must not contain any spaces</em> or \b TSPSG won't build.
268
269If make step finished without errors you can generate sis installation
270file by running
271
272\verbatim
273make sis
274\endverbatim
275
276You'll get \c tspsg.sis file in the source directory. Copy it to your
277phone and run or install it using <em>Nokia PC Suite</em>.
278
279\note You need to install <em>Qt libraries</em> on your device before installing
280\b TSPSG. Usually, it should be enough to install \c qt_installer.sis from
281the Qt installation directory.
282
283Alternatively, if you have installed <em>Nokia Smart Installer</em>\anchor cr2<sup>\ref r2 "[2]"</sup> you can run
284
285\verbatim
286make installer_sis
287\endverbatim
288
289You'll get an \c tspsg_installer.sis that will automatically download and
290install the required <em>Qt libraries</em> on \b TSPSG installation.
291
292\note Please, be aware that you have to sign the sis file to be able to
293install it on your device. You can use <em>Open Signed Online</em>\anchor cr3<sup>\ref r3 "[3]"</sup> to quickly
294sign the sis file for your device. Alternatively, you can try to enable
295the installation of self-signed files in the phone settings. Please,
296reffer to your phone manual on the instructions how to do this.
297
298<hr>
299
300\subsection i_s47 OTHER PLATFORMS, SUPPORTED BY QT
301
302While \b TSPSG is oficially supported only on \b Linux, \b Windows and <b>Windows
303Mobile</b> it should be possible to compile it on any platform, supported
304by \em Qt. To do so, please, refer to the section \ref i_s41 for the general build
305and installation procedure.
306
307<hr><hr>
308
309\section i_s5 UNINSTALLATION
310
311Usually, it is enough to replace \c install parameter with \c uninstall
312in the installation command from the section \ref i_s4. Alternatively, you can manually
313delete all installed \b TSPSG files and directories.
314
315<hr><hr>
316
317\section i_s6 TROUBLESHOOTING
318
319\subsection i_s61 WINDRES.EXE CRASH
320
321When building under \b Windows using <em>minGW</em> toolchain make process may fail
322with \c windres.exe crash (access violation). This is a known bug in
323\c windres.exe regarding processing resource files with \c UTF-8 (\c cp65001)
324encoding\anchor cr4<sup>\ref r4 "[4]"</sup>. To be able to successfully build \b TSPSG you will need to
325download and replace \c windres.exe with a fixed version. To do this:
326
327  -# Open https://sourceforge.net/projects/mingw/files/ in your
328     favourite browser.
329  -# Find and download the latest version of <em>GNU Binutils</em>. At the time
330     of writing this guide it was \c binutils-2.20.1-2-mingw32-bin.tar.gz.
331  -# Unpack the file \c bin\windres.exe from the downloaded archive to
332     <tt>\<Your Qt installation path>\\mingw\\bin\\</tt> replacing the existing one.
333  -# Now run
334\verbatim
335mingw32-make distclean
336\endverbatim
337     in the \b TSPSG directory and repeat the installation process.
338
339<hr><hr>
340
341\section i_s7 NOTES
342
343\c qmake doesn't always enclose installation paths in quotes. This may
344cause some files not to be installed or removed when their path
345contains spaces. In this case it is safe to delete these files and \b TSPSG
346installation directory manually.
347
348<hr><hr>
349
350\section i_s8 REFERNECES
351
352  -# \ref cr1 "^" \anchor r1 http://qt.nokia.com/
353  -# \ref cr1 "^" \anchor r2 http://qt.nokia.com/developer/nokia-smart-installer-for-symbian
354  -# \ref cr2 "^" \anchor r3 https://www.symbiansigned.com/app/page/public/openSignedOnline.do
355  -# \ref cr3 "^" \anchor r4 http://sourceware.org/bugzilla/show_bug.cgi?id=10165
356*/
Note: See TracBrowser for help on using the repository browser.