RoboJournal 0.2.1 Installation Guide for Source Distribution
Document revision: 3
May 11, 2012
By Will Kraft
Thank you for downloading RoboJournal 0.2.1. The purpose of this guide is to assist users in the process of compiling and installing RoboJournal on an operating system. This guide contains all instructions necessary to compile RoboJournal from its source code. Although RoboJournal depends on Qt, this guide assumes that you have a complete, fully-functional Qt environment available before you begin the RoboJournal compile process. Although this guide provides Qt-related recommendations and requirements, it does not provide start-to-finish instructions for building Qt from source.
You should compile RoboJournal from source only if you have no other options. Those who wish to modify RoboJournal and use their own customized version will also have to build from source.
If you wish to use standard RoboJournal, you should use pre-compiled binaries for best results. There is an installer available for Microsoft Windows and you may obtain packages compatible with Debian-based Linux from SourceForge. You should try these options first to see if they work. If not, or if you are using an operating system for which no RoboJournal installer package exists, your only option will be to build from source.
1. RoboJournal source code (robojournal-0.2.1.tar.gz) and any extra software required to un-compress the tar.gz archive
2. GNU compiler collection (or at the bare minimum: GNU make and g++)
Windows users should use the MinGW toolkit instead of the .NET compiler toolchain. The .NET toolkit should be considered experimental/unsupported for the purpose of building RoboJournal.
If you need to install MinGW on this computer, you may download an installation package here:
http://sourceforge.net/projects/mingw/files/Installer/mingw-get-inst/mingw-get-inst-20111118/
This guide assumes that all compilers in use are 32-bit unless indicated otherwise.
3. Win32 dependencies (robojournal-win32-depends.tar.gz) if compiling for Windows.
Note: if you build a 64-bit RoboJournal for Windows, the files inside robojournal-win32-depends.tar.gz will not work with it.
4. MySQL headers and libraries
Headers and libraries should be installed in a convenient location. Headers consist of the .h files found in the MySQL development module; libraries are found in the file libmysql.lib. The location of these objects on your system (assuming they are available) will vary depending on your situation.
If you are using a 32-bit compiler, (MinGW) MySQL libraries must be 32-bit even on 64-bit Windows systems. Compiling against 64-bit libraries will cause the build attempt to fail because MinGW can only produce 32-bit binaries. However, if you can obtain 64-bit compilers (64-bit GNU toolkit or MinGW-w64) you could then produce a fully 64-bit RoboJournal binary based on 64-bit Qt and MySQL libraries. However, this should be considered experimental.
5. Qt 4.7.4 (or newer) source code from Nokia's website
6. Perl (ActivePerl is recommended) if building on Windows
You should compile Qt ONLY if you don't have a set of suitable Qt libraries available for use with RoboJournal. Suitable Qt libraries are defined as being compiled for your correct operating system/system architecture and contain complete driver support for both MySQL and SQLite.
Linux users should check their distro repositories first to see if there is a complete set (containing the core SQL module and separate packages for MySQL and SQLite drivers) of up-to-date (>= 4.7.4) Qt libraries available. If so, you will probably be able to compile against these packages so there would be no reason to build your own Qt environment. A complete Qt environment is usually much harder to find ready-made for Microsoft Windows, so you will probably have to compile your own if you feel the need to build RoboJournal from source. Linux and Windows Qt environments are not interchangeable; you may not use a set of Windows libraries on Linux and vice versa. The official Qt SDK offered by Nokia does not offer database support so it may not be used to build RoboJournal.
Before you compile Qt, you will be given the option to build debug and/or release libraries. Most of the time, you should only compile release libraries since programs compiled from debug libraries can be much larger in terms of file size due to containing testing/debug data that you will not need on production systems.
The Qt compile process can be simple or fairly complicated depending on the configuration you plan to use. You will first need to specify the path to the headers/libraries in the configuration process, and once the build begins you should expect the process to take several hours. If you need help, please follow the steps on: http://www.rag.com.au/linux/qt4howto.html
Although RoboJournal will work if you compile the MySQL/SQLite driver as a plugin, for best results you should compile the drivers into the main Qt SQL module. (e.g. use -qt-sql-mysql instead of –qt-plugin-mysql during the Qt configuration process) That way, you are much less likely to run into any unexpected problems caused by Qt not being able to find the MySQL/SQLite plugins at runtime. If RoboJournal is built using a flawed Qt where the drivers are compiled improperly, failed to compile, or are otherwise missing, RoboJournal will not be able to make any database connections.
The procedure for building RoboJournal varies widely depending on operating system. The process generally consists of generating a Makefile, compiling the source, and installing the new binary.
A Makefile consists of the necessary instructions required to build a program for a given operating system. Makefiles are operating system specific; a Makefile generated on a Linux system will not build a valid Windows executable or vice versa. RoboJournal’s Makefiles are generated by a program called QMake, which is part of the Qt development environment you should have at this point.
For this example, assume Qt is located at C:\Qt, MinGW is located at C:\MinGW, and RoboJournal is located at C:\robojournal-0.2.1. In your situation, these locations may vary depending on where you installed everything. In such a situation, revise the paths accordingly.
1. Open a terminal (cmd.exe)
2. Navigate to the RoboJournal source folder. Type "cd c:\robojournal-0.2.1" and hit enter.
3. Next, you need to set the path to qmake.exe. Type "path C:\Qt\bin" and hit enter. Cmd.exe will now be able to run programs from the C:\Qt folder even though you should still be in the C:\robojournal-0.2.1 directory.
4. Next, type "qmake –config release robojournal.pro" and hit enter.
5. Type "dir" (hit enter) and look for a Makefile.
6. If there is a Makefile, change the path to MinGW. Type "path C:\MinGW\bin" and hit enter.
7. Type "mingw32-make" and hit enter.
8. Mingw32-make should produce lots of compile output. Wait for it to finish.
9. At this point, you should have a robojournal.exe file in the robojournal-0.2.1 directory.
10. Add the contents of the roboJournal-win32-depends.tar.gz archive to the robojournal-0.2.1 folder. You need all of the following files:
a. libgcc_s_dw2-1.dll
b. libmysql.dll
c. libstdc++-6.dll
d. QtCore4.dll
e. QtGui4.dll
f. QtSql4.dll
11. RoboJournal should display the Welcome to RoboJournal dialog when you choose to start the program. If not, something went wrong during the compile process.
Important: You should use only the files from the robojournal-win32-depends.tar.gz package because they have been specially built for use with RoboJournal. A QtCore4.dll, QtGui4.dll, or a QtSql4.dll from another source will not work properly. If necessary, you may obtain libstdc++-6.dll and libgcc_s_dw2-1.dll from your MinGW installation while libmysql.dll comes packaged with MySQL.
The build process on Linux of Mac OSX is much more straightforward. There is no reason to set a path since all the programs you will need (except qmake) are stored in /bin or /usr/bin. This document assumes that Qt is installed at /usr/local/Trolltech/Qt-4.7.4 (the default install location for Qt 4.7.4). Likewise, this document assumes that RoboJournal’s source code is found at ~/robojournal-0.2.1. (~ indicates the user’s home directory)
1. Open a terminal application (xterm or similar)
2. Type "cd ~/robojoural-0.2.1" and hit enter.
3. You should be in the robojournal-0.2.1 directory. Type "ls | grep robojournal.pro" and hit enter. You should get "robojournal.pro" as a response.
4. Type "/usr/local/Trolltech/Qt-4.7.4/bin/qmake robojournal.pro" and hit enter.
5. Wait for the qmake process to finish. It should only take a few seconds.
6. Type "ls | grep Makefile" and hit enter. You should get "Makefile" back as a response if qmake finished correctly.
7. Type "make" and hit enter.
8. GNU make will compile the program and produce lots of output. Wait for it to finish.
9. Run "make install" as root or superuser to install. If you ever want to uninstall, run "make uninstall" from the robojournal-0.2.1 directory as root or superuser.
10. To see if the program compiled properly, type "robojournal" once the compile/install process is done. The Welcome to RoboJournal dialog should display.