191
192
<li><a href="#build">Building RoboJournal From Source</a>
193
194
<li><a href="#windows">Manual Windows Procedure</a> </li>
197
<p>Thank you for downloading RoboJournal. The purpose of this documentation is
198
to assist users in the process of compiling RoboJournal from its source code.
199
Since building RoboJournal requires a Qt environment with full MySQL support,
200
this documentation also explains how to properly prepare and compile Qt from
201
its base source code. If you need to compile Qt, please consult the "How to
202
Build Qt with MySQL Support" section. You may require Internet access to fetch
203
one or more required components.</p>
205
<p>This documentation uses various styles to clearly differentiate portions of
206
the text. Sections with a <span class="console">black background</span> are
207
literal commands meant to be entered at a command prompt (xterm or cmd.exe). In
208
practical usage, the entire command inside a black section is meant to be one
209
line with <em>absolutely no line breaks</em>, even if the section wraps to the
210
next line in the documentation. Sections with a <span class="arg">green
211
background</span> are used to reference specific portions of a command but are
212
not complete commands themselves.</p>
214
<h2 id="L7606"> Table of Contents</h2>
218
<li><a href="#prereq">Prerequisites</a></li>
219
<li><a href="#prepare">Preparing Qt</a>
221
<li><a href="#config">How to Build Qt with MySQL Support</a></li>
222
<li><a href="#L7776">Qt Assistant and QCollectionGenerator on
224
<li><a href="#reprocess">Preparing the MySQL Libraries for
228
<li><a href="#build">Building RoboJournal From Source</a>
230
<li><a href="#windows">Manual Windows Procedure</a></li>
194
232
<li><a href="#depends">Resolving Windows Dependencies</a></li>
195
233
<li><a href="#debian_requirements">Debian, Ubuntu, and Linux Mint
196
234
Requirements</a></li>
197
235
<li><a href="#fedora_requirements">Fedora Requirements</a></li>
198
<li><a href="#linux">Manual Linux Procedure</a> </li>
236
<li><a href="#linux">Manual Linux Procedure</a></li>
202
241
<h2 id="prereq"> Prerequisites</h2>
203
242
<p>Before you can compile RoboJournal, you must have <em>all</em> of
235
274
for Windows. You will need to edit the script before using it for the
236
275
first time. The Linux Build Helper Script (linux_compile.pl) rarely
237
276
requires any modification prior to use.</li>
281
<h2 id="prereq"> Prerequisites</h2>
283
<p>Before you can compile RoboJournal, you must have <em>all</em> of the
284
following components:</p>
286
<li>RoboJournal source tarball (and any extra software required to unpack the
287
tar.gz archive). The current stable version at the time of this writing is
290
Alternatively, you can acquire RoboJournal's source code by cloning the
292
href="https://github.com/pwizard2/robojournal">RoboJournal GitHub
293
repository</a> directly into a folder. Be advised that the RoboJournal
294
"experimental" branch on GitHub frequently contains components that are
295
incomplete and/or buggy because they are in an active state of development.
296
Because of this, those who wish to get RoboJournal from GitHub should clone
297
from the "master" branch that is kept synchronized with the current stable
299
<li>A Qt 4.7,or 4.8 environment to compile against (RoboJournal has
300
<em>not</em> been ported to Qt 5 yet). Consult the "<a
301
href="#prepare">Preparing Qt</a>" section in this documentation for details
302
on what is required.</li>
303
<li>GNU Compiler Toolkit. On Linux, the package containing the full kit is
304
called "build-essential" on several distros, including Ubuntu and Debian.
305
In addition to compilers, build-essential contains other utilities that
306
will help you create a software package; you should only package your
307
custom build if you plan to eventually redistribute it.<br />
309
Windows users should use the <a
310
href="http://sourceforge.net/projects/mingwbuilds/">MinGW toolkit</a>
311
(Minimalist GNU for Windows) instead of other compiler toolchains. This
312
guide only provides instructions for MinGW. Alternative toolkits may also
313
work but you should still consider them to be experimental/unsupported for
314
the purpose of building RoboJournal. </li>
315
<li>A text editor (<a href="http://notepad-plus-plus.org/">Notepad++</a> is
316
ideal) if you wish to use the Build Helper Script to compile for Windows.
317
You <em>must</em> edit the script before using it for the first time. The
318
Linux Build Helper Script (linux_compile.pl) rarely requires any
319
modification prior to use.</li>
238
321
<li>A reasonable amount of experience with command line interfaces.</li>
240
323
<p>RoboJournal has been tested extensively on Linux and Windows XP (and
242
325
RoboJournal should operate reliably and correctly on the aforementioned
243
327
operating systems but others should be considered experimental at this
245
329
If you build and deploy RoboJournal on an experimental operating
247
331
should be ready for unexpected bugs even if everything appears to work
333
operating systems but others should be considered experimental at this point.
334
If you build and deploy RoboJournal on an experimental operating system, you
335
should be ready for unexpected bugs even if everything appears to compile
249
338
<p>If you wish to use standard RoboJournal, you should use pre-compiled
250
340
binaries for best results. There is an installer available for
252
342
Windows and you can obtain packages compatible with Debian-based Linux
290
380
and SQLite drivers) of Qt libraries available. If so, they
292
382
compile RoboJournal and building from source is unnecessary. </p>
384
binaries for best results. There is an installer available for Microsoft
385
Windows and you can obtain packages compatible with Debian-based Linux from the
386
Debian repositories. These packages work with Ubuntu, Linux Mint, or any other
387
Debian-based Linux. You should try these options first to see if they work.
388
Your only option is to build from source if you are using an operating system
389
for which no RoboJournal installer package exists. Debian users need to build
390
from source if the unstable or experimental repositories do not contain the
391
current version of RoboJournal.</p>
393
<h2 id="prepare"> Preparing Qt</h2>
395
<p>You should compile Qt <em>only</em> if you don't have a set of suitable Qt
396
libraries available for use with RoboJournal. Suitable Qt libraries are
397
defined as being compiled for your correct operating system/system architecture
398
and contain complete driver support for both MySQL and SQLite. Linux and
399
Windows Qt environments are not interchangeable; you <em>cannot</em> use a set
400
of Windows libraries on Linux and vice versa. A complete Qt environment is
401
much harder to find ready-made for Microsoft Windows, so Windows users will
402
probably have to compile their own from scratch. <strong>The official Qt
403
Software Development Kit (SDK) offered by Digia is unsuitable for building
404
RoboJournal because the SDK lacks adequate database support.</strong> </p>
406
<p>Linux users should check their distro repositories first to see if there is
407
a <em>complete</em> set of Qt libraries available (containing the core SQL
408
module and separate packages for MySQL and SQLite drivers). If so, they can
409
be used to compile RoboJournal and building from source is unnecessary. </p>
294
412
<h3 id="config">How to Build Qt with MySQL Support</h3>
295
414
<p>Since Qt is modular, the capabilities of a Qt environment are
297
416
what you decide to include during its configuration process. In other
349
468
<li>On Windows: <span class="console">configure.exe -opensource
350
469
-platform win32-g++ -release -qt-sql-mysql -qt-sql-sqlite -l mysql -I
351
470
C:\MySQL\include -L C:\MySQL\lib</span></li>
473
<p>Since Qt is modular, the capabilities of a Qt environment are limited by
474
what you decide to include during its configuration process. In other words, if
475
you omit support for a SQL driver, that driver will not be available in the
476
finished build. SQLite support is built-in and requires no headers/libraries
477
(although you still have to instruct the configure command to build it).
478
However, you must specify the path to the headers/libraries for all other SQL
479
drivers you wish to include.</p>
481
<p>For best results, you should use <a
482
href="http://sourceforge.net/projects/mingwbuilds/">MinGW-Builds</a> as your
483
compiler toolkit since other variants of MinGW may not compile Qt properly.
484
Building a custom Qt environment from source requires all of the following:</p>
486
<li>Basic (or better) proficiency with command line interfaces.</li>
487
<li>MySQL or MariaDB headers and libraries. Headers consist of the *.h files
488
found in the MySQL or MariaDB include directory; libraries are stored as
489
the file "libmysql.lib". The location of these objects on your system
490
(assuming they are available) will vary depending on your situation.
493
FYI: If you are using a 32-bit compiler, (MinGW) MySQL/MariaDB libraries
494
<em>must</em> be 32-bit even on 64-bit Windows systems. Compiling against
495
64-bit libraries will cause the build attempt to fail because MinGW can
496
only produce 32-bit binaries. However, if you can obtain 64-bit compilers
497
(64-bit GNU toolkit or MinGW-w64) you could then produce a fully 64-bit
498
RoboJournal binary based on 64-bit Qt and MySQL/MariaDB libraries. </div>
500
<li>Qt 4.7 or 4.8 source code from the Qt Project's <a
501
href="http://qt-project.org/downloads">website</a> or the <a
502
href="https://qt.gitorious.org/">Qt Git repository</a>. Since the source
503
code comes packaged in a zip or tar.gz file (unless you downloaded it with
504
Git), you also need the appropriate software to extract these archives.
506
<li>A Perl interpreter (like <a
507
href="http://www.activestate.com/activeperl/downloads">ActivePerl</a>) is
508
required in order to configure Qt on Windows. The built-in Perl interpreter
509
included in most Linux distributions is adequate for the task when
510
compiling on Linux. </li>
512
href="http://sourceware.org/binutils/docs-2.16/binutils/dlltool.html">dlltool</a>
513
and <a href="http://olex.openlogic.com/packages/mingw-utils">reimp</a> (if
514
building on Windows). Sometimes you must acquire one or both of these tools
515
separately from the MinGW bundle. It is often difficult to find a working
516
copy of Reimp these days, so you may need to build it from <a
517
href="http://wyw.dcweb.cn/download.asp?path=&file=reimp_new.zip">source</a>
518
(you can use MinGW for this) in advance. You must <a
519
href="#reprocess">convert your MySQL/MariaDB library file to a useful
520
format</a> <em>before</em> starting the Qt compile process on Windows.</li>
523
<p>Open a command prompt (xterm or similar on Linux, cmd.exe on Windows). The
524
entire compile process takes place in this command line environment. Even
525
though there is no graphical user interface to assist you, the process is not
526
difficult (assuming everything is configured correctly prior to building)
527
because the build process is mostly automated.</p>
529
<p>First, the Qt configuration process on Windows requires you to set the
530
cmd.exe PATH to the location of your Perl and MinGW installations
531
<em>before</em> you start the compile process (the cmd.exe from the recommended
532
version of MinGW does this automatically). Both MinGW and Perl store their
533
executables in their "bin" folders, so be sure to explicitly reference that in
534
the PATH. Each directory you want the build process to have access to in the
535
PATH should be separated by a semicolon. For instance, assume Perl is installed
536
at C:\Perl64 and MinGW is installed at C:\MinGW; you would run <span
537
class="console">path C:\MinGW\bin;C:\Perl64\bin</span> at the cmd.exe command
538
prompt because the compiler needs to access programs from both directories at
539
once (change these directory locations as needed to fit your actual system
540
configuration). Linux users do <strong><em>not</em></strong> need to set a
541
custom path because all the necessary programs are stored in the same place
542
(/usr/bin). You do <em><strong>not</strong></em> need to set the path if
543
cmd.exe is able to locate and run perl.exe and mingw32-make.exe. </p>
545
<p>Next, you must configure Qt before you can compile it. Navigate to the
546
directory where you extracted the Qt source code, and run one of the following
549
<li>On Linux: <span class="console">./configure -opensource -platform
550
linux-g++ -release -qt-sql-mysql -plugin-sql-sqlite -I /usr/include/mysql
551
-L /usr/lib/mysql</span></li>
552
<li>On Windows: <span class="console">configure.exe -opensource -platform
553
win32-g++ -release -qt-sql-mysql -plugin-sql-sqlite -l mysql -I
554
C:\MySQL\include -L C:\MySQL\lib</span></li>
353
557
<p>In the above commands, <span class="arg">-I</span> refers to
437
642
/usr/bin/collectiongenerator</span></li>
648
<strong>FYI:</strong> You <em>must</em> compile SQLite as a plugin on Windows
649
(as <span class="arg">-plugin-sql-sqlite</span>) instead of embedding it
650
directly into Qt with <span class="arg">-qt-sql-sqlite</span>.</div>
652
<p>Once configuration is finished, the configure script instructs you to begin
653
the compile procedure. This is done by running <span
654
class="console">make</span> (or <span class="console">mingw32-make</span> on
655
Windows). You should expect the build process to take several hours depending
656
on your processor speed and the number of cores devoted to the process. If you
657
have a multi-core CPU, you can put all of your cores to work on the build by
658
adding a <span class="arg">-j <em>x</em></span> argument to the make command,
659
where <em>x</em> is the number of cores your CPU has. For instance, you would
660
enter <span class="console">make -j 4</span> or <span
661
class="console">mingw32-make -j 4</span> if you have a quad-core CPU and want
662
to process four jobs at once.</p>
664
<p>Finally, you must install Qt once the complile process is finished by
665
running <span class="console">make install</span> or <span
666
class="console">mingw32-make install</span>. The new Qt environment is ready
667
for use once the installation process is finished.</p>
670
<h3 id="L7776">Qt Assistant and QCollectionGenerator on Linux</h3>
672
<p>RoboJournal 0.5 and later no longer require QCollectionGenerator or Qt
673
Assistant to be installed during the build process.<br />
441
676
External Resource: <a href="http://www.rag.com.au/linux/qt4howto.html">Qt
443
678
Tutorial</a>.</p>
445
681
<h3 id="reprocess">Preparing the MySQL Libraries for Windows</h3>
446
682
<p>MySQL header files are compatible with any operating system and
498
753
system but do not change anything else). After that, run
499
754
win32_compile.bat to
500
755
compile RoboJournal in one easy step.</p>
501
757
<p>The build helper script builds robojournal.exe inside a separate
503
759
folder in the robojournal-0.4.2 directory. After the helper script is
505
761
you must locate the required <a href="#depends">dependency</a> files
765
<p>The build helper script builds robojournal.exe inside a separate "release"
766
folder in the robojournal-0.5 directory. After the helper script is finished,
767
you must locate the required <a href="#depends">dependency</a> files if
508
770
<p>You can run the win32_cleanup.bat file to completely clean the
509
772
robojournal-0.4.2 folder between builds.</p>
774
robojournal-0.5 folder between builds.</p>
511
777
<div class="FYI">
512
779
<p><strong>FYI:</strong> RoboJournal 0.4.1 introduces a similar build
514
781
for Unix/Linux. It is stored as a Perl-based script in the RoboJournal
557
833
C:\robojournal-0.4.2 directory.</li>
558
834
<li>When QMake is finished, type <span class="console">dir</span>
559
835
(and press Enter) to display the file list.</li>
838
<p>If you wish to compile RoboJournal manually instead of using the build
839
helper script, follow the procedure below. For the sake of simplicity in this
840
procedure, assume Qt is located in C:\Qt, MinGW is located in C:\MinGW, and
841
RoboJournal's source code is located in C:\robojournal-0.5. In a real-world
842
situation, these locations vary depending on where you installed everything.
843
You will receive errors if you fail to revise the paths to match your actual
846
<li>Click the Start Menu » All Programs » Accessories » Command Prompt. A
847
cmd.exe window is displayed. From this point on, all input should be
848
directed to the cmd.exe window unless otherwise indicated.</li>
849
<li>Navigate to the RoboJournal source folder. Type <span
850
class="console">cd C:\robojournal-0.5</span> and press Enter.</li>
851
<li>Type <span class="console">path C:\Qt\bin</span> and press Enter. This
852
changes the current path for cmd.exe and allows you to run any program from
853
C:\Qt\bin even though you should still be in the C:\robojournal-0.5
855
<li>Type <span class="console">qmake –config release robojournal.pro</span>
856
and press Enter. QMake will create a Makefile in the C:\robojournal-0.5
858
<li>When QMake is finished, type <span class="console">dir</span> (and press
859
Enter) to display the file list.</li>
560
861
<li>If there is a Makefile in the file list (look for a file called
561
862
"Makefile"), type <span class="console">path C:\MinGW\bin</span> and
562
863
press Enter.</li>
668
1003
<p><small>* Most systems include Perl support out of the box so
669
1004
you rarely have to install it manually.</small><br />
1008
<p>Newer versions of Ubuntu, Debian, and Linux Mint allow you to install Qt
1009
4.x.x and Qt 5.x in parallel. Since RoboJournal has not been ported to Qt 5.x
1010
yet, you <em>must</em> use the Qt 4.x.x version of QMake for all RoboJournal
1011
builds. On systems that have multiple versions of Qt installed, the correct
1012
version of QMake is called "qmake-qt4". It is usually installed at
1013
/usr/bin/qmake-qt4.</p>
1016
<h3 id="fedora_requirements">Fedora Requirements</h3>
1018
<p>The Qt environment on Fedora is unusual because certain utilities have
1019
slightly different names: QMake is called "qmake-qt4" while Qt Assistant is
1020
called "assistant-qt4". Be sure to take these name changes into consideration
1021
in order to prevent problems during the build process. </p>
1022
>>>>>>> experimental
673
1025
<h3 id="fedora_requirements">Fedora Requirements</h3>
764
1124
be placed in /usr/bin (unless you are creating a package build for
765
1125
Debian). The following steps require root or superuser permissions to
1129
<p>The build process for Linux is much more straightforward. Unlike most source
1130
packages, there is no configure script that must be used prior to the compile
1131
process (QMake handles this role instead). For the purpose of this example,
1132
assume that the RoboJournal source code is located in your home directory
1133
(~/robojournal-0.5) and all utilities are stored in /usr/bin. </p>
1135
<li>Open a terminal application (xterm or similar). There is no specific
1136
shell requirement; most systems use Bash by default. From this point on,
1137
all input should be directed to the terminal unless otherwise
1139
<li>Type <span class="console">cd ~/robojoural-0.5</span> and press
1141
<li>Type <span class="console">qmake robojournal.pro</span> and press Enter
1142
(substitute "qmake" with "qmake-qt4" on Fedora and on systems where Qt 5 is
1146
<strong>FYI:</strong> If you need to create a package build for Debian, you
1147
should substitute the regular Qmake command with <span
1148
class="console">qmake CONFIG+=package robojournal.pro</span> (change the
1149
path to Qmake if necessary). You should not create a package build
1150
<em>unless</em> you are a Debian maintainer and you need to package
1151
RoboJournal for inclusion in the repositories. </div>
1153
<li>Wait for the QMake process to finish.</li>
1154
<li>Type <span class="console">make</span> and press Enter. You can
1155
accelerate the compile process by running <span class="console">make -j
1156
2</span> instead. This instructs the compiler to process two jobs at once,
1157
thereby cutting the build time in half. However, running more than three
1158
jobs simultaneously rarely yields additional speed benefits and may cause
1160
<li>Wait for the compiler to finish (the build is done when text stops
1161
auto-scrolling and the terminal accepts input again).</li>
1162
<li>Type <span class="console">./robojournal</span> and press Enter to start
1163
the program for the first time. You can also start the program by opening a
1164
graphical file manager like Nautilus or Dolphin, navigating to the
1165
~/robojournal-0.5 folder, and clicking the "robojournal" file.
1166
<p>The build process is complete after Step 7. The next three steps are
1167
completely optional and deal with system-wide installation. Properly
1168
installing RoboJournal makes it available to all users whereas running it
1169
out of the build directory limits its availability to your own user
1170
account. /usr/local/bin is the default install location for all software
1171
programs that have been compiled from source, including RoboJournal. Under
1172
no circumstances should the RoboJournal executable be placed in /usr/bin
1173
(unless you are creating a package build for Debian). The following steps
1174
require root or superuser permissions to complete:</p>
1175
>>>>>>> experimental
768
1177
<li>Type <span class="console">su</span> and press Enter to switch
769
1178
to root. If the root account is not configured (as is typical on Ubuntu
807
1217
build folder. This
808
1218
action cleans the ~/robojournal-0.4.2 folder but spares the Makefile
1222
<p>RoboJournal is now installed for all users. For convenience, the install
1223
process places a launcher for RoboJournal in the Office sub-group of your
1224
Applications list. This launcher is available to all users and points to the
1225
installed copy of RoboJournal (not the one in the ~/robojournal-0.5 build
1226
folder). The installed copy is henceforth referred to as the "global copy" in
1227
this documentation. You can also launch the global copy of RoboJournal by
1228
entering <span class="console">robojournal</span> at any command prompt (do not
1229
precede the command with ./).</p>
1231
<p>To uninstall, navigate to the ~/robojournal-0.5 directory, switch to root
1232
(or use sudo), type <span class="console">make uninstall</span>, and press
1233
Enter. This completely removes the global copy and any shortcuts that point to
1234
it. You should always uninstall prior to upgrading to a newer version of
1235
RoboJournal; do not install a new global copy over an existing one. If you wish
1236
to clean up the object code (*.o files) left behind by the compiler, type <span
1237
class="console">make clean</span> (and press Enter) in the build folder. This
1238
action cleans the ~/robojournal-0.5 folder but spares the Makefile and the
1239
>>>>>>> experimental
810
1240
executable made during the most recent build.</p>
811
1241
<p>Type <span class="console">make distclean</span> (and press Enter)
added
removed
compile-instructions.xhtml
