Installation from source on Linux
This page describes the steps required to get PlanarRad running on a fresh install of Ubuntu 13.04 or Fedora 19. It should also work on similar recent versions of Ubuntu or Fedora, and for other Linux distros the information here may help you to get PlanarRad working.
Contents
1. Install required packages
PlanarRad is part of a codebase called 'jude2' which is a set of libraries and executables written in C++. Installing PlanarRad on Linux involves compiling these libraries and executables from the source code, which is what is in the PlanarRad tarball downloadable here. The PlanarRad code requires some other software libraries and tools to be installed. Possibly some of these are on your system already, but for a fresh install of Ubuntu 13.04 or Fedora 19 the following lists the packages that need to be installed.
Ubuntu
- g++
- libqt4-dev
- libsm-dev
- libjpeg-dev
- libboost-all-dev
To install them you need super-user priviliges on your system. Either 'su' to become root or if you can 'sudo' then type, for example.
sudo apt-get install g++ libqt4-dev libsm-dev libjpeg-dev libboost-all-dev
You do not need super-user privilidges again, so if you used 'su' do not stay as the root user.
Fedora
- gcc
- gcc-c++
- qt-devel
- libjpeg-devel
- boost-devel
Fedora uses 'yum' instead of 'apt-get', so to install these is:
sudo yum install gcc gcc-c++ qt-devel libjpeg-devel boost-devel
2. Set environmental variable JUDE2DIR
The PlanarRad compilation process needs to know where to put the software when it has compiled it, and also your system needs to know how to find the software executables and libraries so you can run it. The install location is specified by the environmental variable 'JUDE2DIR'. Setting JUDE2DIR isn't strictly necessary but it is advised, in particular the scripts to generate the Hydrolight comparison document require it to be set.
On Ubuntu add something like the following to the end of the '.profile' file in your home directory. On Fedora add it to the file '.bash_profile'.
export JUDE2DIR=$HOME/jude2_install export LD_LIBRARY_PATH=$JUDE2DIR/lib:$LD_LIBRARY_PATH export PATH=$JUDE2DIR/bin:$PATH
Then log out and back in again. Check that JUDE2DIR has been set by typing:
echo $JUDE2DIR
The result should be similar to '/home/john/jude2_install', if it's a blank line something went wrong. With JUDE2DIR set as above the compilation process will install the software in the directory 'jude2_install' under your home directory. Another reasonable choice would be '/usr/local/jude2_install' but in that case create the directory first and set it so you have write permissions.
3. Unpack sources and build
Type:
tar xvzf planarrad_free_src_0.9.1beta_2013_09_20.tar.gz
Then change to the directory:
cd planarrad_free_src_0.9.1beta_2013_09_20
Now the code can be compiled. PlanarRad uses autotools to manage the build process so the usual steps of './configure' and 'make' should work. However there is frequently an issue in finding the required Qt libraries as their location has varied over the years and on different Linux distros. I don't use autotools in new projects so I can't be bothered to fix the finder script (if you want to have a go it's 'm4/gwqt.m4'). Instead, there is a build script called 'example_build' which creates a pretend Qt4 directory by symlinking to the required components, and then passes that directory to ./configure. It's been tested on fresh installs of Ubuntu 13.04 and Fedora 19, so on systems like those building should be as simple as typing:
./example_build
After which if it seems to have worked (may take around 15 minutes) and you find under 'jude2_install/bin' some executables including 'planarrad_free' then you are done. Specifically, the bin directory should look like this:
If the build fails, in particular if the error is something to do with Qt, look at the contents of the directory 'pretend_qt4_dir'. It may be that some of the symlinks need to point somewhere else on your system. Note that 'exmaple_build' as it stands will write over any changes you make there, so modify that as well if you make changes.
One possible complication is if you have Qt5 and Qt4 on your system, I haven't tested that, but the symlinks attempt to point directly to the qt4 versions of the Qt tools (PlanarRad needs Qt4).
4. Test PlanarRad
If you set up the path directory in your .profile file as in step 2, then just type 'planarrad_free' and something like this should appear:
Command-line only build
If you only intend to run PlanarRad from the command line or scripts then it isn't necessary to build the Qt-based GUI version. In which case you can circumvent any issues in finding Qt by passing the option '--disable-qt' to configure, For example, edit example_build to contain this configure command:
../configure --prefix=$JUDE2DIR --disable-qt
Then to build and install, as before, type:
./example_build
