Build in a Linux/Unix environment

The Gwyddion build system on Unix is based on GNU autotools (autoconf, automake, libtool), just like most modern free and open source software on Unix. If you have ever built software from source, you have probably already encountered autotools and know what to do next. This section, however, will describe the build process in enough detail to be understandable to those who haven’t done it yet. TheINSTALL file in the top-level directory of the source archive contains general instructions for installing with the GNU autotools.

Quick instructions

If you are already familiar with the sequence of steps:

tar -jxvf gwyddion-2.49.tar.xz
cd gwyddion-2.49
./configure
make
make install

Unpack the source code

Unpack the archive with the source code with the command

tar -Jxvf gwyddion-2.49.tar.xz

replacing 2.49 with the current version number. This will create the directory gwyddion-2.49 (again with the current version number instead of 2.49), use cd to navigate to this directory. All other build activities will take place there.

If your operating system does not have xz, you can load gwyddion-2.49.tar.gz (compressed with gzip) instead of the previous archive and unpack it with

tar -zxvf gwyddion-2.49.tar.gz

However, modern Unix and similar systems support both gzip and xz, and the noticeably smaller gwyddion-2.49.tar.xz will usually be a better option.

Configuring

Run

./configure

to configure the build of Gwyddion.

The shell script configure tries to guess the correct values for the different variables that change from system to system and that are used during the compilation. It uses these variables to create a Makefile in each package directory, a set of header files with an .h extension that contain system-dependent definitions and some other auxiliary files. At the end it creates another shell script config.status, which can then be used to repeat the current configuration, and a file config.log, which contains details about the detection process and is useful to include in compilation error messages. At the end, configure also outputs a summary of the optional options enabled and disabled, including the reasons why the option was disabled.

If configure writes that the required packages are missing, install those packages and restart it. The same is true if configure succeeds but you find that you forgot to install the optional component you wanted to build Gwyddion with. It is possible that the package was not found or was incorrectly defined even if you installed it, namely if it was installed in a non-standard directory. In this case you should set up certain environment variables to allow you to find these packages:

PKG_CONFIG_PATH

Most packages come with so-called pkg-config (.pc) files which describe how programs are to be built and linked to them. Configure uses the information from these files, therefore the PKG_CONFIG_PATH must be set up so that all the non-standard pkg-config files are listed there. To add e.g. the installed GTK+ library to /opt/gnome and the installed FFTW3 library to $HOME/opt/fftw3, run PKG_CONFIG_PATH=/opt/gnome/lib/pkgconfig:$HOME/opt/fftw3/lib/pkgconfig export PKG_CONFIG_PATH

PATH, LD_LIBRARY_PATH, DYLD_LIBRARY_PATH

You might have to adjust these variables to include non-standard directories with executables and libraries of corresponding packages. The variables LD_LIBRARY_PATH and DYLD_LIBRARY_PATH both specify a search path for shared libraries, but the former is used on Linux and BSD-based systems, whereas the latter on OS X.

CPPFLAGS, LDFLAGS

It may be necessary to set these variables to include non-standard directories with header files and package libraries that have no pkg-config files, e.g. for libTIFF in /usr/local you can set CPPFLAGS=I/usr/local/include export CPPFLAGS LDFLAGS=L/usr/local/lib export LDFLAGS

The –prefix option of configure specifies the base directory for the installation. The program components will be installed in its subdirectories bin, lib, share, etc. (which will be created if they do not exist). More detailed control is possible with options specifying individual subdirectories, such as –bindir, –libdir. The default prefix is /usr/local/bin and if you want to install Gwyddion in the user’s home directory you can use e.g. the command

./configure –prefix=$HOME/opt/gwyddion

If you are installing Gwyddion for personal use this is the recommended option, as it does not require superuser privileges.

Configuration process settings

Optional features can be enabled/disabled with options like –with-foo/–without-foo or –enable-foo/–disable-foo. For example, compiling with zlib can be disabled with the command:

./configure –without-zlib

By default, all optional features are enabled if all libraries required to implement them are found. A summary of the enabled and disabled options is printed in the output of configure near its end.

A complete list of options and important configure variables can be obtained with the command:

./configure –help

The list will be long and most of the options control the enabling/disabling of individual options or passing the necessary compilation and linking flags for the various libraries. For example, by setting FFTW3_CFLAGS and FFTW3_LIBS it is possible to specify (or override) how FFTW3 will be compiled and linked. However, this manual configuration is just a fallback to a much more convenient method based on pkg-config in case this does not work for some reason.

Some interesting general options are described in the following paragraphs.

User settings

Gwyddion comes with various desktop environment interaction files that define MIME types, menu items, file bindings, thumbnail generation, etc. If Gwyddion is installed in the system directory, they are usually in the correct locations on the file system. However, if you install it somewhere in your user directory, these files need to be put in a different location. namely, in certain hidden directories beginning with a dot in your home directory.

This can be set using the –enable-home-installation option of the configure command. Note that using this option will cause files to be installed in directories outside the given prefix.

Package creator settings

If Gwyddion is installed in a temporary directory for further package creation, certain post-installation steps must be disabled on the system where the package will be installed and not at the time of package creation.

FreeDesktop file updating can be disabled using –disable-desktop-file-update. The installation of GConf2 schemas can be disabled with –disable-schemas-install. Normally this need not be done explicitly because installs to a temporary directory use the non-empty DESTDIR variable (see installation section). If the DESTDIR variable is not empty, the build system will skip the post-installation steps automatically. However, a common reason to disable these actions is that Gwyddion is installed in a temporary location instead of the final directory (which is usually the case when building packages in Linux). In this case the helper actions are turned off automatically when the DESTDIR variable is not empty (see the installation section) and therefore there is no need to turn them off in configure.

By passing the –enable-library-bloat parameter to the configure script, it forces modules to link to all libraries. This is automatically enabled on MS Windows, where it is a requirement. On Unix-based systems, linking modules with all the libraries already loaded by the main program only slows things down in vain (both at build time and run time). Thus, modules are not linked directly to main libraries like GLib. If your system or build rules require linking modules to all libraries (on AltLinux based systems for example), using this option enables this behavior.

By passing the –disable-module-bundling option to configure, you can prevent all modules of the same type (file, data processing, …) from being bundled into the same shared library, which is usually done to save disk space and speed up booting. Although this does not change the functionality, it does noticeably change the set of files to be installed. If you are relying on gwyfile.so for whatever reason, it is time to stop doing this. However, you can use this option to force a traditional install where each module is in a separate file.

Settings for developers

If you plan to patch or otherwise modify the source code of Gwyddion run configure with –enable-maintainer-mode to include various update and rebuild rules that are not used in normal compilation. Depending on the type of changes, you may need some additional tools, described in Subversion Snapshot, development.

By default, the C API reference guide is not rebuilt. Prepared HTML files are distributed with the archive, documentation is rarely changed and its generation requires quite a long time. In order to enable API documentation generation, the –enable-gtk-doc option must be passed to the configure script. Of course, you will need gtk-doc. Note that configure will warn you if you have enabled maintainer mode but not gtk-doc (which can be useful to avoid having to rebuild documentation pointlessly and overly). If you do not intend to do make dist, this warning is harmless.

Compiling

Run

make

and wait for Gwyddion to compile. If the configure command completes without errors, the compilation should also succeed. To reduce your waiting time, you can enable a parallel compilation by running make with

make -j6

where 6 should be replaced by the real number of processor cores available.

If you need to do something unusual to build a package, try to figure out how to find out when and what to do, and send patches or instructions to the bug reporting email address so you can include them in the next release.
Installing

Gwyddion must be installed before running, it cannot be run uninstalled.

Run

make install

to install Gwyddion into the target directory. If you install Gwyddion in the system directory, you will need to become root in order to run this command. This is the only command you have to run as root when installing. For example, using sudo

sudo make install

To install Gwyddion to a temporary location, for example to build a package, set the make variable DESTDIR to a prefix that will be added to all target directories:

make install DESTDIR=/var/tmp/gwyddion-buildroot

Do not override individual directory variables such as bindir, libdir.

If you are not installing into the system directory, i.e. installing into a subdirectory of your home directory, you may need to configure the following environment variables during the installation

GCONF_SCHEMA_CONFIG_SOURCE – the location of the GConf2 schemas KDE4_MODULE_DIR – location of KDE4 modules

You may also need to set the XDG_DATA_DIRS variable for full integration with the desktop environment.

If you install Gwyddion to /usr/local and get the error message libgwyapp.so.0 cannot be found, your system seems to be missing standard directories for libraries in the dynamic linker setup. This has been seen on Ubuntu. Edit your /etc/ld.so.conf file and add the line

/usr/local/lib

Running

Running Gwyddion normally requires no additional configuration.

But some desktop environments that are implemented incorrectly can render Gwyddion unusable and this functionality should be disabled. Hijacking the program’s main menu in Unity makes most of the Gwyddion menus inaccessible. This can be turned off by resetting the environment variable UBUNTU_MENUPROXY when you start Gwyddion:

UBUNTU_MENUPROXY= gwyddion

Cancel installation

Run

make uninstall

in the directory where Gwyddion was previously built to remove it. If you have already lost the contents of this directory, you can try to unpack, configure and build it exactly the same way as before and then run make uninstall afterwards, though the result depends on your ability to exactly repeat the build process.

RPM packages

With GNU/Linux RPM-based distributions, it is possible to build RPM packages directly from the source archives by invoking

rpmbuild -tb gwyddion-2.49.tar.xz

where 2.49 is the current version, as mentioned before. This method has been tested with Fedora, openSuSE and Mandriva and the RPM spec file contains some specific directives for those systems. Specific support for other RPM-based systems can be added on request.