Installation from source on Linux

From PlanarRad
Jump to navigation Jump to search

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.

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.


  • 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.


  • 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 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


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:


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:

Error creating thumbnail: Unable to save thumbnail to destination

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:

Error creating thumbnail: Unable to save thumbnail to destination

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: