TSPSG Installation Guide ======================== Thank you for trying **TSPSG**. This document will guide you through the steps necessary to compile and run **TSPSG**. 1. Requirements --------------- To be able compile **TSPSG** you need to have *[Qt libraries](http://qt-project.org/)*. The minimum supported version of *Qt* is **4.5.0**. The recommended version is **4.6.x** or higher. **NOTE**: Please, note that there will be some regressions in functionality if your version of *Qt* is lower than the recommended. 2. Assumptions -------------- This guide assumes that you already have *Qt* libraries and all necessary prerequisites installed. Also, the following assumptions are made: - For **Linux/UNIX/BSD**: `lrelease` and `qmake` are avilable in `$PATH`. - For **Windows** (*MinGW*) and **Symbian**: you have installed *Qt SDK* or prebuilt libraries and have Start Menu items for Qt tools. - For **Windows** (*Visual Studio*) and **Windows Mobile**: the *Qt* libraries reside in `C:\Qt\`. - For **Windows Mobile**: *Windows Mobile 5.0 Pocket PC SDK* or later is installed. 3. Supported Platforms ---------------------- **TSPSG** is oficially supported and tested on the following platforms: - **Linux**: *Gentoo AMD64* and *Kubuntu 9.10 64-bit AMD*. - **Windows**: *Windows XP 32-bit* and *Windows 7 64-bit*. - **Windows Mobile**: *Windows Mobile 6.5 Professional Edition*. 4. Building and Installation ---------------------------- ### 4.1. Common Information ### To be able ot build **TSPSG** you need to have the following *Qt* modules: *QtCore*, *QtGui* and *QtSvg*. The first two are required, the last one is optional. To get support for additional image formats (i.e., **JPEG** and **TIFF**) you'll additionally need corresponding *Qt imageformats* plugins. If you want to build **TSPSG** without **SVG** support add `nosvg` to *qmake* `CONFIG` parameter, so that *qmake* command will typically be: qmake CONFIG+=release CONFIG+=nosvg This way you will not depend on *QtSvg* module but will not be able to export solution graph in **SVG** format. **TSPSG** uses *qmake* `PREFIX` parameter to determine installation path for make install command. If you don't specify it when running qmake, it will be assigned the default value depending on the platform: | Platform | Default `PREFIX` value | |-----------------------|-----------------------------------------| | **Linux/UNIX/BSD** | `/usr` | | **Windows** | `%PROGRAMFILES%` environment variable\* | | **Windows CE/Mobile** | `\Program Files` | | **Symbian** | *\* | \* - usually, it is `C:\Program Files`. **NOTE**: Please, note that there are no installation and/or packaging rules for **MacOS** and other platforms not mentioned in this table. By default, **TSPSG** uses precompiled header when being built. If you experience problems with it you may add `CONFIG+=nopch` parameter to *qmake* to disable the generation and use of the precompiled header. ### 4.2. General Procedure ### On most platforms the general building and installation procedure is: 1. Run `lrelease` to generate binary translation files (*.qm*) from the source (*.ts*). 2. Run `qmake` with `CONFIG+=release` parameter to generate makefiles. 3. Run `make` utility (e.g., *make*, *nmake*, *mingw32-make*) to build **TSPSG**. 4. Run `make` utility with `install` parameter. NOTE: It is important to run `lrelease` before `qmake`, or `qmake` will not "pick up" the translations when generating installation rules. ### 4.3. Linux/UNIX/BSD ### Open a shell, navigate to the directory where you have **TSPSG** source downloaded and type tar xvjf tspsg--src.tar.bz2 cd tspsg--src where *\* is the version of **TSPSG** you downloaded. Now run lrelease tspsg.pro qmake tspsg.pro make In some cases you may need to type qmake tspsg.pro CONFIG+=release If make step finished without errors you can install TSPSG by running sudo make install or su make install depending on your distribution. The executable goes to `/bin`; *COPYING*, *ChangeLog.md*, *README.md* and *INSTALL.md* go to `/share/doc/TSPSG-`. ### 4.4. Windows ### TSPSG will be installed to \TSPSG folder. NOTE: Please, read the Section 7 after reading this Section. #### 4.4.1. Using MinGW #### Unpack the downloaded source code of TSPSG with your favourite compression software. Now launch the Qt Command Prompt from the Start Menu, navigate to the directory where you unpacked the source and run lrelease tspsg.pro qmake tspsg.pro CONFIG+=release mingw32-make NOTE: Make process may fail with a crash of windres.exe. If you've run into this issue, please, read the Section 6.1. If make step finished without errors you can install TSPSG by running mingw32-make install #### 4.4.2. Using Visual Studio #### Unpack the downloaded source code of TSPSG with your favourite compression software. Now launch the Visual Studio Command Prompt from the Start Menu, navigate to the directory where you unpacked the source and run C:\Qt\bin\lrelease tspsg.pro C:\Qt\bin\qmake tspsg.pro CONFIG+=release nmake If make step finished without errors you can install TSPSG by running nmake install ### 4.5. Windows CE/Mobile ### Unpack the downloaded source code of TSPSG with your favourite compression software. Now launch the Visual Studio Command Prompt from the Start Menu and run set PATH=C:\Qt\bin;%PATH% setcepaths wincewm50pocket-msvc2008 Now navigate to the directory where you unpacked the source and run lrelease tspsg.pro qmake tspsg.pro CONFIG+=release nmake There is no automated installation process for Windows Mobile build. To install TSPSG on your PDA you need to create a folder on your device and copy the following files to it: - tspsg.exe from release folder in the source directory. - QtCore4.dll and QtGui4.dll from C:\Qt\bin folder. - msvcr90.dll from C:\Program Files\Microsoft Visual Studio 9.0\VC\ce\dll\armv4i folder. - all *.qm files from l10n folder in the source directory to l10n subfolder. ### 4.6. Symbian ### Unpack the downloaded source code of TSPSG with your favourite compression software. Now launch the Qt for Symbian Command Prompt from the Start Menu, navigate to the directory where you unpacked the source and run lrelease tspsg.pro qmake tspsg.pro CONFIG+=release make release-gcce WARNING: You need to unpack the source to the same drive as Symbian SDK and the path must not contain any spaces or TSPSG won't build. If make step finished without errors you can generate sis installation file by running make sis You'll get tspsg.sis file in the source directory. Copy it to your phone and run or install using Nokia PC Suite. NOTE: You need to install Qt libraries on your device before installing TSPSG. Usually, it should be enough to install qt_installer.sis from the Qt installation directory. Alternatively, if you have installed Nokia Smart Installer you can run make installer_sis You'll get an tspsg_installer.sis that will automatically download and install the required Qt libraries on TSPSG installation. NOTE: Please, be aware that you have to sign the sis file to be able to install it on your device. You can use Open Signed Online[2] to quickly sign the sis file for your device. Alternatively, you can try to enable the installation of self-signed files in the phone settings. Please, reffer to your phone manual on the instructions how to do this. ### 4.7. Other Platforms, Supported by Qt ### While TSPSG is oficially supported only on Linux, Windows and Windows Mobile it should be possible to compile it on any platform, supported by Qt. To do so, please, refer to the Section 4.1 for the general build and installation procedure. 5. Uninstallation ----------------- Usually, it is enough to replace 'install' parameter with 'uninstall' in the installation command from the Section 4. Also, you can manually delete all installed TSPSG files and directories. 6. Troubleshooting ------------------ ### 6.1. WINDRES.EXE Crash ### When building under Windows using minGW toolchain make process may fail with windres.exe crash (access violation). This is a known bug in windres.exe regarding processing resource files with UTF-8 (cp65001) encoding [1]. To be able to successfully build TSPSG you will need to download and replace windres.exe with a fixed version. To do this: 1. Open https://sourceforge.net/projects/mingw/files/ in your favourite browser. 2. Find and download the latest version of GNU Binutils. At the time of writing this guide it was binutils-2.20.1-2-mingw32-bin.tar.gz. 3. Unpack the file bin\windres.exe from the downloaded archive to \mingw\bin\ replacing the existing one. 4. Now run mingw32-make distclean in the TSPSG directory and repeat the installation process. 7. Notes -------- qmake doesn't always enclose installation paths in quotes. This may cause some files not to be installed or removed when their path contains spaces. In this case it is safe to delete these files and TSPSG installation directory manually. 8. References ------------- [1] http://sourceware.org/bugzilla/show_bug.cgi?id=10165 [2] https://www.symbiansigned.com/app/page/public/openSignedOnline.do