source: tspsg/INSTALL.md

appveyor
Last change on this file was 2aeaea9572, checked in by leppa, 3 years ago

Added formatting to README, INSTALL and ChangeLog? files.

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