Gwyddion Unix build system is based on
GNU autotools
(autoconf,
automake,
libtool), like
most of current Unix Free and Open Source Software. If you have ever
compiled software from source code, you very likely met autotools and
already know how to proceed. This section shall describe the
compilation procedure in enough detail even for the uninitiated though.
File INSTALL
in the top-level directory of the
source tarball contains generic GNU autotools installation instructions.
If you know the drill:
tar -jxvf gwyddion-2.49.tar.xz
cd gwyddion-2.49
./configure
make
make install
Unpack the source code tarball with
tar -Jxvf gwyddion-2.49.tar.xz
replacing 2.49 with the actual version number. It will create directory
gwyddion-2.49 (again, with the actual version
number in place of 2.49), cd to this directory.
All other compilation actions will take place there.
If your operating system does not come with xz you might want to
download gwyddion-2.49.tar.gz (compressed with
gzip) instead and unpack it with
tar -zxvf gwyddion-2.49.tar.gz
However, modern Unix and Unix-like systems come with both xz and
gzip, so the considerably smaller
gwyddion-2.49.tar.xz should be normally the
better choice.
Run
./configure
to configure Gwyddion.
The configure shell script attempts to guess correct
values for various system-dependent variables used during compilation.
It uses those values to create a Makefile in each
directory of the package, a couple of header .h
files containing system-dependent definitions and a few other
system-dependent auxiliary files.
Finally, it creates a shell script config.status that
you can run in the future to recreate the current configuration, and
a file config.log. This file contains the details
of the detection process and it is helpful to include it in compilation
related bug reports.
At the end, configure also prints a summary of
enabled/disabled optional features, including the reasons why features
were disabled.
If configure reports missing required packages, install these packages and re-run it. The same applies to the case when configure passes but you find you have not installed an optional package you want to compile Gwyddion with. It is possible a package is not found or it is misdetected even if you have installed it, namely when it is installed into a non-standard directory. In this case it is necessary to adjust certain environment variables to make configure able to find the packages:
PKG_CONFIG_PATH
Most packages come with so called
pkg-config
files (.pc) that describe how programs
should compile and link with them. configure
uses information from these files, therefore
PKG_CONFIG_PATH must be set to list all
non-standard directories with relevant pkg-config files.
To add for instance a GTK+ installation in
/opt/gnome and a FFTW3 installation in
$HOME/opt/fftw3 one can do
PKG_CONFIG_PATH=/opt/gnome/lib/pkgconfig:$HOME/opt/fftw3/lib/pkgconfig
export PKG_CONFIG_PATH
PATH,
LD_LIBRARY_PATH,
DYLD_LIBRARY_PATH
It may be necessary to adjust these variables to include
non-standard directories with executables and libraries of
relevant packages, respectively.
Variables LD_LIBRARY_PATH and
DYLD_LIBRARY_PATH both set the search path for
shared libraries, but the former is used in Linux and BSD
systems, while the latter on OS X.
CPPFLAGS,
LDFLAGS
It may be necessary to adjust these variables to include
non-standard directories with header files and libraries of
packages that do not come with pkg-config files, for example
for libTIFF in /usr/local one can set:
CPPFLAGS=-I/usr/local/include
export CPPFLAGS
LDFLAGS=-L/usr/local/lib
export LDFLAGS
Option --prefix of configure sets the
base installation directory. Program components will be installed into
its bin, lib,
share, etc. subdirectories (that will be created if
they do not exist). More detailed control is possible with options
specifying particular subdirectories as --bindir,
--libdir. The default prefix is
/usr/local/bin, to install
Gwyddion into your home directory you may want
to use for instance
./configure --prefix=$HOME/opt/gwyddion
If you install Gwyddion for personal use it is recommended to use a similar installation directory as no steps need to be performed as root in this case.
Optional features can be enabled/disabled with options such as
--with-foo/--without-foo
or
--enable-foo/--disable-foo.
For instance compilation with zlib can be disabled with:
./configure --without-zlib
By default all optional features are enabled if their prerequisites are found. A brief summary of enabled and disabled optional features is printed near the end of configure output.
The complete list of configure options and important variables can be obtained with:
./configure --help
The list is long and most of the options and variables control
inclusion/exclusion of individual optional features or provide compiler
and linker flags for the various libraries. For instance, by setting
FFTW3_CFLAGS and FFTW3_LIBS you can specify
(or override) how compilation and linking with FFTW3 should be done.
However, this manual specification is only a fallback if the much more
convenient pkg-config method does not work.
Some interesting general options are explained in the following paragraphs.
Gwyddion comes with various desktop integration files defining MIME types, menu entries, file associations, thumbnailers, etc. If you install Gwyddion to a system prefix they usually end up in the correct location. However, if you install it somewhere to your home directory then these files need to be placed elsewhere, namely into certain dot-directories in your home.
This can be requested using --enable-home-installation
option of configure.
Note that using this option causes installation of files outside the
specified prefix.
If Gwyddion is installed into a staging area for a subsequent packaging it is necessary to disable certain post-installation actions that need to be done on the target system, not while packaging.
Updating of Freedesktop files can be
disabled with --disable-desktop-file-update.
Installation of GConf2 schemas can be disabled with
--disable-schemas-install. Usually, this
does not have to be done explicitly as installations into a staging
area use non-empty DESTDIR (see
installation).
If DESTDIR is found to be non-empty the
build system skips post-installation actions automatically.
Pasing --enable-library-bloat to
configure enforces linking modules with all
libraries. This is automatically enabled on MS Windows where it is
required. On Unix systems, linking modules with libraries that are
loaded into the main program anyway only needlessly slows things down
(both during build and program execution). So modules are not
explicitly linked with base libraries such as GLib. If your
environment or policy demands linking modules with all libraries using
this option will ensure it.
Pasing --disable-module-bundling to
configure prevents the bundling of all modules of
the same class (file, process, …) to a single shared library, which is
normally done to save space and speed up program startup. Although
bundling changes nothing functionally, it changes the set of installed
files considerably. If you, for whatever reason, depend on the file
gwyfile.so existing on disk then please stop.
But meanwhile you can use this option to force the traditional
installation where each module was in a separate file.
If you intend to patch or otherwise modify Gwyddion source code pass
option --enable-maintainer-mode to
configure
to enable various update and rebuild rules that are not used in plain
compilation. Depending on the nature of the modifications, some of the
additional tools described in section
Subversion Checkout, Development
may be necessary.
By default, the C API reference documentation is not rebuilt.
Pre-built HTML is distributed in the tarball, the documentation seldom
changes and generating it takes a rather long time. To enable
the generation of API documentation pass option
--enable-gtk-doc to
configure. Of course, you also need gtk-doc.
Note that configure warns if you enable the
maintainer mode but disable gtk-doc (which can be useful to avoid
pointless repeated documentation rebuilds). Unless you are going to
do make dist, this is harmless.
Run
make
and wait until Gwyddion is compiled. If configure finished without errors the compilation should pass too. To shorten the wait, enable parallel compilation by running make as
make -j6
replacing 6 with the number of processor cores.
If you find you need to do unusual things to compile the package, please try to figure out how configure could detect whether and what to do, and e-mail patches or instructions to the bug-report address so they can be considered for the next release.
Gwyddion has to be installed to be run, it is not possible to run it uninstalled.
Run
make install
to install Gwyddion to the target directory. If you install Gwyddion to a system directory you have to become root for running this command. This is the only command that you might have to run as root during the installation. For example using sudo:
sudo make install
To install Gwyddion to a staging area,
for example for packaging, set make
DESTDIR variable to a prefix that will be
prepended to all target directories:
make install DESTDIR=/var/tmp/gwyddion-buildroot
Do not override individual directory variables as
bindir, libdir.
If you do not install to a system directory, e.g. to a subdirectory of your home directory, you may need to adjust the following variables during installation:
GCONF_SCHEMA_CONFIG_SOURCE – location of GConf2
schemas
KDE4_MODULE_DIR – location of KDE4 modules
Also, variable XDG_DATA_DIRS might need to be
adjusted after installation to get full desktop integration.
If you install Gwyddion into /usr/local and get
error message that libgwyapp.so.0 cannot be found
your system probably lacks standard library directories in the dynamic
linker configuration. Notably, this happens on Ubuntu. Edit file
/etc/ld.so.conf and add the line
/usr/local/lib
there.
Running Gwyddion does not normally require any additional setup.
The misfeatures of some desktop environments, however, may render
Gwyddion unusable and need to be disabled.
The hijacking of program main menu in Unity
makes most of Gwyddion menus inaccessible. It
can be disabled by by unsetting UBUNTU_MENUPROXY while
running Gwyddion:
UBUNTU_MENUPROXY= gwyddion
Run
make uninstall
in the directory you previously compiled
Gwyddion to remove it. If you have lost
the source directory meanwhile you can try to unpack, configure and
build it exactly as before and then issue
make uninstall, although this relies on your
ability to reproduce the build process.
It is possible to build RPM packages on RPM-based GNU/Linux distributions directly from source code tarballs with
rpmbuild -tb gwyddion-2.49.tar.xz
where 2.49 is to be replaced with the actual version as above. This method was tested mainly on Fedora, openSuSE and Mandriva and the RPM spec file contains some specific provisions for these systems. Specific support for other RPM-based systems can be added on request.