Changeset 2aeaea9572 in tspsg for INSTALL.md


Ignore:
Timestamp:
Nov 2, 2013, 5:44:47 PM (11 years ago)
Author:
Oleksii Serdiuk
Branches:
appveyor, imgbot, master
Children:
4b975848ad
Parents:
50b202f04d
git-author:
Oleksii Serdiuk <contacts@…> (11/02/13 17:44:47)
git-committer:
Oleksii Serdiuk <contacts@…> (11/03/13 20:48:44)
Message:

Added formatting to README, INSTALL and ChangeLog? files.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • INSTALL.md

    r50b202f04d r2aeaea9572  
    1 TSPSG Installation Guide
    2 ========================
    3 
    4 Thank you for trying TSPSG. This document will guide you through the
    5 steps necessary to compile and run TSPSG.
    6 
    7 TABLE OF CONTENTS:
    8 
    9   1. REQUIREMENTS
    10   2. ASSUMPTIONS
    11   3. SUPPORTED PLATFORMS
    12   4. BUILDING AND INSTALLATION
    13      4.1. COMMON INFORMATION
    14      4.2. GENERAL PROCEDURE
    15      4.3. LINUX/UNIX/BSD
    16      4.4. WINDOWS
    17           4.4.1. USING MINGW
    18           4.4.2. USING VISUAL STUDIO
    19      4.5. WINDOWS MOBILE
    20      4.6. SYMBIAN
    21      4.7. OTHER PLATFORMS, SUPPORTED BY QT
    22   5. UNINSTALLATION
    23   6. TROUBLESHOOTING
    24      6.1. WINDRES.EXE CRASH
    25   7. NOTES
    26   8. REFERENCES
    27 
    28 
    29 
    30 1. REQUIREMENTS
     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
    319---------------
    3210
    33 To be able compile TSPSG you need to have Qt libraries. The minimum
    34 supported version of Qt is 4.5.0. The recommended version is 4.6.x
    35 or higher.
    36 
    37 NOTE: Please, note that there will be some regressions in functionality
    38 if your version of \em Qt is lower than the recommended.
    39 
    40 
    41 
    42 2. ASSUMPTIONS
     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
    4320--------------
    4421
    45 This guide assumes that you already have Qt libraries and all necessary
    46 prerequisites installed.
     22This guide assumes that you already have *Qt* libraries and all
     23necessary prerequisites installed.
    4724
    4825Also, the following assumptions are made:
    4926
    50   - For Linux/UNIX: lrelease and qmake are avilable in $PATH.
    51 
    52   - For Windows (minGW) and Symbian: you have installed Qt SDK or
    53     prebuilt libraries and have Start Menu items for Qt tools.
    54 
    55   - For Windows (Visual Studio) and Windows Mobile: the Qt libraries
    56     reside in C:\Qt\.
    57 
    58   - For Windows Mobile: Windows Mobile 5.0 Pocket PC SDK or later is
    59     installed.
    60 
    61 
    62 
    63 3. SUPPORTED PLATFORMS
     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
    6438----------------------
    6539
    66 TSPSG is oficially supported and tested on the following platforms:
    67 
    68   - Linux: Gentoo AMD64 and Kubuntu 9.10 64-bit AMD.
    69 
    70   - Windows: Windows XP 32-bit and Windows 7 64-bit.
    71 
    72   - Windows Mobile: Windows Mobile 6.5 Professional Edition.
    73 
    74 
    75 
    76 4. BUILDING AND INSTALLATION
    77 ----------------------------
    78 
    79 ### 4.1. COMMON INFORMATION ###
    80 
    81 To be able ot build TSPSG you need to have the following Qt modules:
    82 QtCore, QtGui and QtSvg. The first two are required, the last one is
    83 optional. To get support for additional image formats (i.e., JPEG and
    84 TIFF) you'll additionally need corresponding Qt imageformats plugins.
    85 
    86 If you want to build TSPSG without SVG support add nosvg to qmake
    87 CONFIG parameter, so that qmake command will typically be:
     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:
    8860
    8961    qmake CONFIG+=release CONFIG+=nosvg
    9062
    91 This way you will not depend on QtSvg module but will not be able to
    92 export solution graph in SVG format.
    93 
    94 
    95 TSPSG uses qmake PREFIX parameter to determine installation path for
    96 make install command. If you don't specify it when running qmake, it
     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
    9769will be assigned the default value depending on the platform:
    9870
    99  Platform          | Default PREFIX value
    100 -------------------|-------------------------------------
    101  Linux/UNIX/BSD    | /usr
    102 -------------------|-------------------------------------
    103  Windows           | %PROGRAMFILES% environment variable
    104                    | (usually, it is "C:\Program Files")
    105 -------------------|-------------------------------------
    106  Windows CE/Mobile | "\Program Files"
    107 -------------------|-------------------------------------
    108  Symbian           | <ignored>
    109 -------------------|-------------------------------------
    110 
    111 NOTE: Please, note that there are no installation and/or packaging
    112 rules for MacOS and other platforms not mentioned in this table.
    113 
    114 
    115 By default, TSPSG uses precompiled header when being built. If you
    116 experience problems with it you may add CONFIG+=nopch parameter to
    117 qmake to disable the generation and use of the precompiled header.
    118 
    119 
    120 ### 4.2. GENERAL PROCEDURE ###
     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> ###
    12190
    12291On most platforms the general building and installation procedure is:
    12392
    124   1. Run lrelease to generate binary translation files (.qm) from the
    125      source (.ts).
    126 
    127   2. Run qmake with CONFIG+=release parameter to generate makefiles.
    128 
    129   3. Run make utility (e.g., make, nmake, mingw32-make) to build TSPSG.
    130 
    131   4. Run make utility with 'install' parameter (without quotes).
    132 
    133 NOTE: It is important to run lrelease before qmake, or qmake will not
    134 "pick up" the translations when generating installation rules.
    135 
    136 
    137 ### 4.3. LINUX/UNIX/BSD ###
    138 
    139 Open a shell, navigate to the directory where you have TSPSG source
     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
    140107downloaded and type
    141108
    … …  
    143110    cd tspsg-<VERSION>-src
    144111
    145 where <VERSION> is the version of TSPSG you downloaded. Now run
     112where *\<VERSION\>* is the version of **TSPSG** you downloaded. Now run
    146113
    147114    lrelease tspsg.pro
    … …  
    154121
    155122
    156 If make step finished without errors you can install TSPSG by running
     123If make step finished without errors you can install **TSPSG** by
     124running
    157125
    158126    sudo make install
    … …  
    165133depending on your distribution.
    166134
    167 The executable goes to <PREFIX>/bin; COPYING, ChangeLog.txt, README.txt
    168 and INSTALL.txt go to <PREFIX>/share/doc/TSPSG-<VERSION>.
    169 
    170 
    171 ### 4.4. WINDOWS ###
    172 
    173 TSPSG will be installed to <PREFIX>\TSPSG folder.
    174 
    175 NOTE: Please, read the Section 7 after reading this Section.
    176 
    177 
    178 #### 4.4.1. USING MINGW ####
    179 
    180 Unpack the downloaded source code of TSPSG with your favourite
    181 compression software. Now launch the Qt Command Prompt from the Start
    182 Menu, navigate to the directory where you unpacked the source and run
     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
    183152
    184153    lrelease tspsg.pro
    … …  
    186155    mingw32-make
    187156
    188 NOTE: Make process may fail with a crash of windres.exe. If you've run
    189 into this issue, please, read the Section 6.1.
    190 
    191 If make step finished without errors you can install TSPSG by running
     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
    192162
    193163    mingw32-make install
    194164
    195165
    196 #### 4.4.2. USING VISUAL STUDIO ####
    197 
    198 Unpack the downloaded source code of TSPSG with your favourite
    199 compression software. Now launch the Visual Studio Command Prompt from
    200 the Start Menu, navigate to the directory where you unpacked the source
    201 and run
     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
    202172
    203173    C:\Qt\bin\lrelease tspsg.pro
    … …  
    205175    nmake
    206176
    207 If make step finished without errors you can install TSPSG by running
     177If *make* step finished without errors you can install **TSPSG** by
     178running
    208179
    209180    nmake install
    210181
    211182
    212 ### 4.5. WINDOWS CE/MOBILE ###
    213 
    214 Unpack the downloaded source code of TSPSG with your favourite
    215 compression software. Now launch the Visual Studio Command Prompt from
    216 the Start Menu and run
     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
    217188
    218189    set PATH=C:\Qt\bin;%PATH%
    … …  
    225196    nmake
    226197
    227 There is no automated installation process for Windows Mobile build. To
    228 install TSPSG on your PDA you need to create a folder on your device
    229 and copy the following files to it:
    230 
    231   - tspsg.exe from release folder in the source directory.
    232 
    233   - QtCore4.dll and QtGui4.dll from C:\Qt\bin folder.
    234 
    235   - msvcr90.dll from
    236     C:\Program Files\Microsoft Visual Studio 9.0\VC\ce\dll\armv4i folder.
    237 
    238   - all *.qm files from l10n folder in the source directory to l10n
    239     subfolder.
    240 
    241 
    242 ### 4.6. SYMBIAN ###
    243 
    244 Unpack the downloaded source code of TSPSG with your favourite
    245 compression software. Now launch the Qt for Symbian Command Prompt from
    246 the Start Menu, navigate to the directory where you unpacked the source
    247 and run
     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
    248217
    249218    lrelease tspsg.pro
    … …  
    251220    make release-gcce
    252221
    253 WARNING: You need to unpack the source to the same drive as Symbian SDK
    254 and the path must not contain any spaces or TSPSG won't build.
     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.
    255224
    256225If make step finished without errors you can generate sis installation
    … …  
    259228    make sis
    260229
    261 You'll get tspsg.sis file in the source directory. Copy it to your
    262 phone and run or install using Nokia PC Suite.
    263 
    264 NOTE: You need to install Qt libraries on your device before installing
    265 TSPSG. Usually, it should be enough to install qt_installer.sis from
    266 the Qt installation directory.
    267 
    268 Alternatively, if you have installed Nokia Smart Installer you can run
     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
    269239
    270240    make installer_sis
    271241
    272 You'll get an tspsg_installer.sis that will automatically download and
    273 install the required Qt libraries on TSPSG installation.
    274 
    275 NOTE: Please, be aware that you have to sign the sis file to be able to
    276 install it on your device. You can use Open Signed Online[2] to quickly
    277 sign the sis file for your device. Alternatively, you can try to enable
    278 the installation of self-signed files in the phone settings. Please,
    279 reffer to your phone manual on the instructions how to do this.
    280 
    281 
    282 ### 4.7. OTHER PLATFORMS, SUPPORTED BY QT ###
    283 
    284 While TSPSG is oficially supported only on Linux, Windows and Windows
    285 Mobile it should be possible to compile it on any platform, supported
    286 by Qt. To do so, please, refer to the Section 4.1 for the general build
    287 and installation procedure.
    288 
    289 
    290 
    291 5. UNINSTALLATION
     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
    292261-----------------
    293262
    294 Usually, it is enough to replace 'install' parameter with 'uninstall'
    295 in the installation command from the Section 4. Also, you can manually
    296 delete all installed TSPSG files and directories.
    297 
    298 
    299 
    300 6. TROUBLESHOOTING
     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
    301269------------------
    302270
    303 
    304 ### 6.1. WINDRES.EXE CRASH ###
    305 
    306 When building under Windows using minGW toolchain make process may fail
    307 with windres.exe crash (access violation). This is a known bug in
    308 windres.exe regarding processing resource files with UTF-8 (cp65001)
    309 encoding [1]. To be able to successfully build TSPSG you will need to
    310 download and replace windres.exe with a fixed version. To do this:
    311 
    312   1. Open https://sourceforge.net/projects/mingw/files/ in your
     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
    313281     favourite browser.
    314 
    315282  2. Find and download the latest version of GNU Binutils. At the time
    316      of writing this guide it was binutils-2.20.1-2-mingw32-bin.tar.gz.
    317 
    318   3. Unpack the file bin\windres.exe from the downloaded archive to
    319      <Your Qt installation path>\mingw\bin\ replacing the existing one.
    320 
     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.
    321288  4. Now run
    322289
    323290         mingw32-make distclean
    324291
    325      in the TSPSG directory and repeat the installation process.
    326 
    327 
    328 
    329 7. NOTES
    330 --------
    331 
    332 qmake doesn't always enclose installation paths in quotes. This may
     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
    333299cause some files not to be installed or removed when their path
    334300contains spaces. In this case it is safe to delete these files and
    335 TSPSG installation directory manually.
    336 
    337 
    338 
    339 8. REFERNECES
    340 -------------
    341 
    342 [1] http://sourceware.org/bugzilla/show_bug.cgi?id=10165
    343 [2] https://www.symbiansigned.com/app/page/public/openSignedOnline.do
    344 
    345 
     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<!--
    346309$Id: $Format:%h %ai %an$ $
    347310$URL: http://tspsg.info/ $
     311-->
Note: See TracChangeset for help on using the changeset viewer.