Munipack ‒ Building of Munipack from source code

# Building of Munipack from source code

Building Munipack from a source code

This is a way for an independent installation of Munipack on any target platform. No packaging system is used. Alternative, the canonical way for Debian based GNU/Linux distributions is described in DebBuilder and analogically RPMbuilder are instructions for RPM based distributions.

As prerequisite, it is supposed to run commands introduced by # as root

    # id
    uid=0(root) ..

and ones denoted by $ as an ordinary user:

    $ id
    uid=12345(user) ...

## Summary

There is a short summary of installation steps which will install latest stable release (replace X.Y by an appropriate number) of Munipack to a system:

    $ cd /usr/src
    $ wget https://integral.physics.muni.cz/ftp/munipack/munipack-0.X.Y.tar.gz
    $ tar zxf munipack-0.X.Y.tar.gz
    $ cd munipack-0.X.Y
    $ ./configure
    $ make
    # make install

More detailed description is below.

# Source building

## Introduction

This page describes how to build Munipack from source codes. The source code distribution is the most portable way how to get Munipack. Some experiences with a software building are required.

The building takes phases:

- preparing helper tools
- getting sources
- initialisation
- configure
- compile

At the moment, Munipack can be clearly compiled under GNU/Linux, g++, gfortran and wxWidgets ver. 3.0.0 (and above) only.

Other combinations compilers, operating systems, etc. should require some additional tuning. Munipack is designed pretty much portable and multiplatform (Mac OS X, MS Windows) but every platform should need a fine tuning of details.

## Download

There are two ways how to get sources of Munipack. Source tarball offers more reliable way opposite to Mercurial's way which is on the cutting edge.

The preferred path for placing sources is `/usr/src`, for example `/usr/src/munipack-0.6.X`. The path is available only for system administrator. If you haven't root privileges, use `src` (for example) directory in your home `$HOME/src`

    $ mkdir $HOME/src

and replace all references `/usr/src` to `$HOME/src` in following text.

### Tarball

The tarball contains the stable branch (a relative stable and updated) version of Munipack.

Download: https://integral.physics.muni.cz/ftp/munipack/

To get source tree, download archive and unpack the tarball as:

    # cd /usr/src
    # wget https://integral.physics.muni.cz/ftp/munipack/munipack-0.6.X.tar.gz
    # gzip -dc munipack-0.6.XXX.tar.gz | tar -xf -

### Mercurial

Sources stored in Mercurial repository contains the development branch. The branch contains latest development files which can be unstable, bug compilation, etc.

To get source tree, follow instructions for Mercurial or try:

    # cd /usr/src
    # hg clone https://integral.physics.muni.cz/hg/munipack munipack-Z.Y.X/

## Prerequisites

Following tools are required for compiling of Munipack:

- Any Linux distribution or Unix-like system
- Fortran 2008 and C++ compilers
- Autoconf and automake (optional)
- cfitsio library
- Oak Leaf library
- minpack library
- PLplot library including Cairo driver
- wxWidgets library (ver. >= 3.0.0)

All libraries must be installed in development version. Your package system probably contains development libraries as -dev (-devel) packages. Without development libraries, the building will be unsuccessful.

The requirement for the latest version of wxWidgets is mainly due to support of the event handling system for the command-line interface. The instructions for its installation can be found on wiki: http://wiki.wxwidgets.org/Prerequisites.

Minpack is auto-detected: If minpack library is found on target system, the system wide is used, else the internal source is used. Minpack needs Fortran 77 compiler (provided by modern Fortran compilers due backward-compatibility).

PLplot is necessary for advanced plotting. The default driver is Cairo which provides high quality graphs having anti-aliasing or alpha transparency. If the driver is unsuitable, user is prompted; an alternative driver can be selected in `xmunipack/plplot.cpp`.

Autoconfig is required for bootstrap (the `configure` script generation) when source is downloaded via Mercurial version system.

## Initialisation

Required only in case of Mercurial's source tree.

Requires:

- Autotools (automake, autoconf) installation.

Munipack building is on base of Autotools which is most widely portable way working under all common environments. The initialisation of building framework is required.

The building is controlled by configure.ac (top) and set of Makefile.am-s (all building directories).

This phase creates regular configure script and Makefiles by processing of the control files.

    $ ./bootstrap --dev

Last step is initialisation of Autotools:

      autoreconf -i

## Configure and install

The unpacked and initialised source is ready for compilation. This can be done quite easy on Linux based distributions, same as other Unix's systems. The configuration, compilation and installation is provided by the standard GNU way. Simply, run the following sequence of commands:

    $ ./configure
    $ make
    $ make install

Munipack will check available tools and will be installed by default under tree `/usr/local`.

The phase will work under any supported system. C++ and Fortran compilers and appropriate development libraries needs to be installed, of course.

There is limited possibility to fit the installation according to your needs. Running of the command

    ./configure --help

will display possible switches to fine tuning of building.

Some setting of the environment variables can also affect of the compilation process. For example, more progressive optimisation of the output code for 32-bit machines (64-bit machines are optimised on the level by default) and GNU compilers (g++, gfortran) is provided by `FCFLAGS` and `CFLAGS` variables

    $ ./configure CXXFLAGS="-march=i686 -O3" FCFLAGS="-march=i686 -O3"

The installation under FreeBSD would work with parameters:

    csh:> ./configure LDFLAGS=-L/usr/local/lib CPPFLAGS=-I/usr/local/include

The installation under Fedora/RHEL will require

    ./configure CXXFLAGS=-I/usr/include/cfitsio

The --enable-bundle switch provides a way to install full Munipack package to a separate directory. See Binary Builder section.

On finish, the configure command will print some summary:

    Configured Munipack:

                          Virtual Observatory support enabled: yes
                               Command line interface enabled: yes
                             Graphical User Interface enabled: yes
                                          Bundle installation: no

When the configure script had found successfully wxWidgets library, the first and second options will be set to `yes`. Note that both command line and graphical interfaces requires wxWidgets. Without wxWidgets, only processing engines are compiled. Engine utilities has no user interfaces and any communication is released only via standard input and output (which can be very useful for daemons, web interfaces, etc.). The last summary option indicates no presence of --enable-bundle switch.

## Alternatives for configure

To fit a nostandard needs, there are some alternative ways for configure:

- Bundled installation to self-contained directory (everything in one directory only, Unix conventions recommends `/opt` as target directory, intended for binary-packages):

      ./configure --prefix=/opt/munipack --enable-bundle

- No GUI installation for non-iterative analysis (scripts) without support of graphical devices:

      ./configure --disable-gui

- No command-line installation for direct use of modules:

      ./configure --disable-cli

- No Virtual Observatory support:

      ./configure --disable-vo

Together use of all the disable options (`--disable-[gui|cli|vo]`) eliminates completely dependency on wxWidgets. cFITSIO and Oak Leaf libraries are necessary in any case.

## Un-Installation

Use commands

    # cd /usr/src/munipack-0.6.X
    # make uninstall

in the installation directory to uninstall Munipack.

This implying that it is not a good idea to remove the source directory immediately after installation (the reason to use `/usr/src` or an equivalent path).

## Known issues

### Failed compilation when run make with -j flag

The compilation might fail when you run make with parallel build enabled (by -j switch or via `MAKEFLAGS`). Workaround: run make as many as needed or unset the -j option. One usually appears when compiler is looking for Fortran modules.