Installation

To use PlanarRad, first choose an installation method:

  • build locally

  • prebuilt appimage

  • build (docker) container

Building from source

Install Dependencies

You will need to download the package dependencies. Some example for certain OS’s are below.

Ubuntu 22.04 and 24.04 specific packages

sudo apt-get install g++ libsm-dev libjpeg-dev libboost-all-dev make

Fedora/RHEL/etc specific packages

sudo yum install gcc gcc-c++ libjpeg-devel boost-devel make

πŸ‘©β€πŸ’» Windows/OS X

If you’re on windows see Windows Installation.

For windows users, you may be able to get away with using and running it through WSL (Windows subsystem for Linux - many guides online).

If on Mac, you may need brew to install the dependencies.

Set install location(s)

On Ubuntu add something like the following to the end of the ~/.bashrc file in your home directory (or add it to ~/.zshrc for zsh).

export JUDE2DIR=$HOME/jude2_install
export LD_LIBRARY_PATH=$JUDE2DIR/lib:$LD_LIBRARY_PATH
export PATH=$JUDE2DIR/bin:$PATH

Then reload your terminal environment with source ~/.bashrc

With the prerequisite packages installed and the path set, simply navigate to the main directory in a terminal run the install script example_build:

bash example_build $JUDE2DIR

πŸ“œ A note on downloading from github

If you download the files from github, sometimes the timestamps will all reset (due to how git works). This upsets autotools immensly, as it may think the aclocal.m4 and other files are out of date and need to be regenerated. If you have this issue when building manually, then before running configure run a simple:

touch src/aclocal.m4 src/Makefile.am src/configure src/Makefile.in

This will correctly fool autotools into thinking that the files are up to date, which should fix the issue. This is run before configure in example_build. NB: If you DO edit aclocal makefile’s, etc, you will need to re-run autotools as mentioned above.

Bear all this in mind if you want to run the ./configure, make, make install yourself.

πŸ•Έ Multithreaded compiling

PlanarRad now comes with OpenMP support. The default build script example_build.sh automatically comes with multithreaded compilation. There is some non-parallel overhead in the multithreaded program, so it is recommended to turn off multi-threading if you are batching large numbers of program runs across across cores/nodes, as then you will have better throughput. For a single-run, keep it on for faster latency.

To change number of threads, set the environment variable OMP_NUM_THREADS at runtime, e.g. for only one run you can use:

OMP_NUM_THREADS=1 <PlanarRad command>

Alternatively, export the enviornment variable, or turn off multi-threaded support during build. Turn it off during build by not including the --enable-openmp CFLAGS="-fopenmp" flags in the configure command (see example_build.sh).

πŸ‹ Docker installation

πŸ”₯ NB: Pre-alpha, not ready for user testing. Installation via Docker will currently not work with the test scripts, as they work with planarRad binaries (slabtool_free etc) directly. Use this method if you have issues with other installation methods.

In the main repo directory, build and run the image with:

docker build . -t planarrad
docker run -v src:/data planarrad <planarrad command>

Note that this will map the src directory on your computer (replace with your chosen directory) with the /data directory in the docker container. Make sure your chosen planarrad command (e.g. slabtool blah blah... ) is reading and writing to the mounted volume in /data.

Additionally, check if you are on a root installation of docker with:

docker version | grep rootlesskit

If you are on a root install (usually the default), on linux preserve user permissions with generated files by mapping your user id to the docker container with --user $(id -u):$(id -g) after docker run, e.g.:

docker run --user $(id -u):$(id -g) -v src:/data planarrad <planarrad command>