Troubleshooters.Com, T.C Linux Library and Litt's LyX Library Present

Compiling LyX 1.5x:
Avoiding the Landmines

Copyright (C) 2008 by Steve Litt, All rights reserved. Material provided as-is, use at your own risk.

Contents

Introduction

This document will help you avoid the landmines in compiling LyX 1.5.x.

LyX 1.5 has Unicode and outline mode, making it desireable and even necessary for many. However, it drops all support of the xforms front end, and Qt versions before Qt4. I personally made LyX 1.5.3 with Mandriva 2007's Qt 4.1.4-12. The Requirements section of LyX 1.5.3's README file says "LyX has been tested with Qt 4.1.5". It goes on to say: "The only special point to make is that you must ensure that both LyX and the Qt libraries are compiled with the same C++ compiler."

If you have Qt version 4, no matter what the minor version, your best bet is to try the instructions in this document before drawing any conclusions as to whether your Qt is new enough. On some distributions, such as my Mandriva 2007, upgrading Qt is a huge and risky undertaking, especially if, like me, you're on dialup. If you don't have Qt version 4, you must either install it or upgrade your distro in order to compile LyX 1.5.x.

Most modern (early 2008) distros have both Qt 3 and Qt 4. LyX might choose the wrong one, especially if you do not reset the $QT4DIR environment variable. If it chooses the wrong one, either ./configure or make fails with a deducible but not obvious error message.

Adding to the frustration is that on my Athlon XP2600+ box, ./configure takes about 5 minutes, and make takes around 20 minutes. You do not want to repeatedly compile during troubleshooting.

Compilation involves a gotcha that can ruin your day if you're not aware of it. A blown ./configure or maybe a blown compile leaves "stuff" in your source tree that will error out further compiles even after you've repaired the initial problem. Therefore, unless you're absolutely sure it's not necessary, best practice is to delete and recreate the source tree after a bad ./configure or make.

Procedure

Here's how to minimize the time wasting effects of compilation landmines:
  1. Prepare
  2. Make a clean source tree if necessary
  3. Run the configure script
  4. Make
  5. Test your new executable
  6. Make-install
  7. Fix menu fonts and user interface

Prepare

Extract the LyX 1.5.x tarball and read the INSTALL document that comes with the tarball. Verify and correct if necessary the following:

gcc

If you use gcc, the gcc compiler must be version 2.95.x or better. Here's how you determine your version:
[slitt@mydesk ~]$ gcc -v
Using built-in specs.
Target: i586-mandriva-linux-gnu
Configured with: ../configure --prefix=/usr --libexecdir=/usr/lib --with-slibdir=/lib --mandir=/usr/share/man --infodir=/usr/share/info --enable-shared --enable-threads=posix --enable-checking=release --enable-languages=c,c++,ada,fortran,objc,obj-c++,java --host=i586-mandriva-linux-gnu --with-cpu=generic --with-system-zlib --enable-long-long --enable-__cxa_atexit --enable-clocale=gnu --disable-libunwind-exceptions --enable-java-awt=gtk --with-java-home=/usr/lib/jvm/java-1.4.2-gcj-1.4.2.0/jre --enable-gtk-cairo --enable-ssp --disable-libssp
Thread model: posix
gcc version 4.1.1 20060724 (prerelease) (4.1.1-3mdk)
[slitt@mydesk ~]$
The preceding shows me using gcc version 4.1.1, which is good enough. If the preceding command shows you below 2.95, you probably can't compile LyX

Qt

You need Qt 4.x. I've been unable to ascertain the exact earliest minor version of Qt4 that will work, but the documentation says LyX has been tested with Qt 4.1.5, and I personally built LyX with Qt 4.1.4-12. You need to determine the following:
On RPM based systems your first step is to find all packages related to Qt, as follows:
[slitt@mydesk ~]$ rpm -qa | grep -i qt
libqtopengl4-4.1.4-12mdv2007.0
qt4-common-4.1.4-12.3mdv2007.0
libqttest4-4.1.4-12mdv2007.0
libqt3support4-4.1.4-12mdv2007.0
lsb-qt4-3.1-7mdv2007.0
qt3-common-3.3.6-18mdv2007.0
libqt3-devel-3.3.6-18mdv2007.0
libavahi-qt3_1-devel-0.6.13-4mdv2007.0
aqbanking-qt3-2.2.1-1mdv2007.0
libqt3-3.3.6-18mdv2007.0
libqtcore4-4.1.4-12mdv2007.0
libqt4-devel-4.1.4-12mdv2007.0
libqtnetwork4-4.1.4-12mdv2007.0
libavahi-qt3_1-0.6.13-4mdv2007.0
libpoppler-qt1-0.5.3-5mdv2007.0
libqtxml4-4.1.4-12mdv2007.0
python-qt-3.5.4-1mdv2007.0
libqtsql4-4.1.4-12mdv2007.0
pinentry-qt-0.7.2-6mdv2007.0
libqtdesigner1-4.1.4-12mdv2007.0
libdbus-qt-1_1-0.70-1mdv2007.0
libqtuitools4-4.1.4-12mdv2007.0
libqtgui4-4.1.4-12mdv2007.0
libqtsvg4-4.1.4-12mdv2007.0
[slitt@mydesk ~]$

In the preceding you'll notice my qt4-common package is version 4.1.4-12.3, and my libqt4-devel package is version 4.1.4-12, which was close enough. I don't know exactly how close you have to get.

If you don't use rpm, use whatever package tools you know to find out, or if necessary, perform the following command:
find /usr | grep -i qt4 | tee myfinds.txt
If you need to install Qt4, that is beyond the scope of this document. If you need to install libqt4-devel, be sure to get the package with the same version number as your qt4-common package. If you need to install libqt4-devel, there are many dependencies, but my experience is it's doable even using oldstyle rpm. I found all my RPM files using pbone.net's advanced search.

Do not proceed until you have the qt4-common and libqt4-devel packages installed, and they are the same or close to the same version number. How close is good enough, I'm not sure, but I'd guess if the versions are 4.x.y-z.a, at least x and y should match.

C++ Standard Template Library

The C++ STL must be installed. To find out, do this:
find /usr | grep -i libstdc++ | tee myfind.txt
When I performed that command, the following are some of the files I saw:

Fonts

Briefly read the information on fonts and fontconfig in the INSTALL file. Personally, it looks to me like this can be handled post-installation. I base this opinion on the fact that the word "font" does not appear, in upper or lower case or any combination, in configure or configure.ac. Assuming the font config can be handed post-installation, I believe it's best to wait until post-installation.

Make a Clean Source Tree if Necessary

If a ./configure or a make errors out, it's likely that bad stuff will be left in your source tree. Even if you fix the root cause of the blown configuration or compilation, that bad stuff can still prevent compilation. By deleting the source tree and re-extracting it from the tarball, you eliminate this source of frustration.

Unless you're absolutely positive it's not necessary in your particular case, always lay down a brand new source tree after every configuration or compilation failure. Configuration takes 5 minutes, compilation takes 25 minutes. Restoring the source tree to pristine condition takes less than a minute.

Assuming you build the LyX source tree in directory $HOME/junk/lyx-1.5.3, you'd do this:
cd $HOME/junk && rm -f lyx-1.5.3
If your tarball were a tarred bz2 located in $HOME/tarballs/lyx, you'd lay down the new tarball like this:
cd $HOME/junk && tar xjvf $HOME/tarballs/lyx/lyx-1.5.3.tar.bz2

Run the Configure Script


WARNING

Read this entire article before running the the configure script!

You know how on most packages you can run the configure script with no arguments? Don't try that here! Now that you have Qt4, you want to make absolutely, positively sure that it goes to the Qt4 directory for everything. Also, if you're compiling LyX 1.5.x, it probably means that an older LyX version came with your Linux distribution, and you want the two versions to play nice with each other. That means they don't clobber each others' configurations. You need to add a prefix so LyX 1.5.x uses a different directory for config info. Assuming you don't want to change the destinations of the binaries, man pages, libraries and the like, here's how you do it:
UIC4=/usr/lib/qt4/bin/uic \
MOC4=/usr/lib/qt4/bin/moc \
./configure \
  --with-qt4-dir=/usr/lib/qt4 \
  --with-qt4-includes=/usr/lib/qt4/include \
  --with-qt4-libraries=/usr/lib/qt4/lib \
  --with-version-suffix=1.5.3
In the preceding:
UIC4=/usr/lib/qt4/bin/uic
Set the $UIC4 environment var to the full path of the uic executable, and pass it to ./configure. This is probably unnecessary because ./configure should deduce it from the --with-qt4-dir option. If you get an error mentioning that the uic is not found, specify this explicitly and check the validity of the  --with-qt4-dir option.
MOC4=/usr/lib/qt4/bin/moc
  Set the $MOC4 environment var to the full path of the moc executable, and pass it to ./configure. This is probably unnecessary because ./configure should deduce it from the --with-qt4-dir option. If you get an error mentioning that the moc is not found, specify this explicitly and check the validity of the  --with-qt4-dir option.
./configure
The configure script
--with-qt4-dir=/usr/lib/qt4
Specify the Qt4 directory overall
--with-qt4-includes=/usr/lib/qt4/include
Specify the location of Qt4 include files
--with-qt4-libraries=/usr/lib/qt4/lib
Specify the location of Qt4 library files
--with-version-suffix=1.5.3
Specify a version suffix (in this example 1.5.3). This configures LyX to use a user configuration directory called $HOME/.lyx-1.5.3, leaving $HOME/.lyx to the exclusive use of your current LyX. If you don't yet have a LyX program, or if you want to decommission it completely, you don't need this option.

The command just discussed strongarms everything to the value consistent with Qt4, so Qt3 locations doesn't creep in and ruin either your ./configure or your make.

Remember once again, if either ./configure or make error out, you need to delete and restore the entire source tree and rerun from the configuration script.

Specifying Destinations with the Configure Script

By default, LyX's make install command puts all files in the /usr/local tree. Assuming your distribution has put the existing LyX in /usr/bin, that default is probably what you want. If for some reason you want to put the new LyX's files in non-default locations, those locations must be specified as arguments to the configure script.

The shotgun approach is to specify -prefix=whatever. For instance, if you want the files to go in a tree below /usr/local/lyx153, you'd add this option to ./configure:
-prefix=/usr/local/lyx153
That would require you to modify the $PATH and $MANPATH environment variables to include /usr/local/lyx123/bin and /usr/local/lyx153/share/man respectively.

For finer control of locations, you can specify these:
The preceding only scratches the surface. Before specifying any destination directories, study the documentation provided by the following command:
./configure --help | less

Make

This is both simple and a pain in the posterior, because it takes 25 minutes (on my Athlon XP2600+) to run, so you don't know whether it worked or not until that time has elapsed. After a clean ./configure performed on a clean source tree, just do this:
make
The compilation will go on and on and on, consuming almost your computer's entire CPU. This would be a good time to do non-computerized things, or else work on programs not requiring much computation. Anything relying on continous typing bottlenecks on the typist and therefore takes little CPU resources. However, make sure all program you'll be using during the compile are loaded and running before the compile starts.

When the compile finishes, look at the last several lines for any evidence of an error. If none, continue...

Test Your New Executable

If the compile worked, in the src subdirectory below your source tree, you should have a file called lyx or lyx-qt4 or something like that. From the top of the source tree, run that program like this:
src/lyx-qt4
The preceding should run your new LyX. It should look fairly normal except the fonts on the menu and in dropdown lists might be squintingly tiny, and dropdown lists may exhibit the strange behavior of not having a reverse video bar. These two abnomolies can be configured away after installation.

Create a new document and verify that it can be created and assigned a document style. From there test as much as you feel is necessary.

Make Install

This step can overwrite things. Before performing this step, make sure that if you wanted anything but the default placement of executables, man pages and other files, you specified them when running ./configure. Once ready, from the same directory in which you performed the other commands, do this:
su
make install
From then on, you'll run your new LyX with the following command:
lyx-qt4
or, if destinations not on the path were specified, you'll need to use the entire path, like this:
/usr/local/lyx153/bin/lyx-qt4
The make install command takes much longer than most make install commands. It runs a lot of python programs. Be patient.

Fix Menu Fonts and User Interface

You already have a working LyX. However, if your experience is anything like mine, your LyX will seem a little strange. On my installation, menu fonts were so tiny I had trouble reading them quickly, and dropdowns had no reverse video highlight travelling with the mouse.

These anomolies can be configured away with the Qt4 version of qtconfig, which on my computer is called qt4config. When I run qt4config, it pulls up a dialog box with four tabs:
Under Fonts, change the point size to something more visible. My advice is to leave all other settings where they are on the Fonts tab. Then click File->Save on the menu. This will make LyX 1.5.x's menu fonts, dropdown fonts and dialog box fonts readable.

On the Interface tab, check the "Enable" box in the GUI effects section. I'd recommend you not change anything else. Enabling GUI effects gives you back the reverse highlight on dropdowns. Click File->Save to enable the change, and then File->Exit to quit qt4config.

Overview of Qt

This article may help you understand the effect of Qt on compilation and use of LyX.

Qt is an application programming framework, consisting of various objects, methods (subroutines bound to objects), executables, and other "stuff".

Take a look at the executables in Qt4's bin directory:

[slitt@mydesk lyx-1.5.3]$ dir /usr/lib/qt4/bin
moc  qmake  qt3to4  qtconfig  rcc  uic  uic3
[slitt@mydesk lyx-1.5.3]$

PgmExplanation
moc
Meta Object Compiler (moc), this provides introspection and other communications between objects. It works by inspecting C++ header files, and producing C++ source code to handle meta-information as an addition to C++. The moc must be present, in the right version, or Qt dependent apps such as LyX won't compile.
uic
User Interface Compiler. Compiles user Qt userinterface files into C++ headers.  This must be present, in the right version, or Qt dependent apps such as LyX won't compile. 
uic3
Converts a Qt3 user interface file to Qt4 format.
rcc
ResourCe Compiler: Embeds resources defined in a Qt resource file (.qrc) into C++ code.
qmake
The Qt makefile generation program. This program generates makefiles used to generate runnable programs. 
qtconfig
GUI user level global configuration of Qt user interfaces on all Qt apps.
qt3to4
Tool to help convert Qt3 apps to Qt4.

To compile LyX, moc, uic, rcc and qmake must exist in Qt4 version, and must be locatable by the configure script. The existence of Qt3 can cause confusion, so at least some of these must often be directly specified. At the very least, the --with-qt4-dir option is usually necessary if a Qt3 exists.

Summary

Compiling LyX 1.5.x might, depending on your situation, result in hours of uncertainty and frustration. Following the tips in the document can significantly reduce the uncertainty and frustration. Here are the highlights:

Back to Troubleshooters.Com * Back to Linux Library * Litt's LyX Library