Subversion Checkout, Development

Gwyddion uses Subversion version control system for source code revision management. The organization of the repository is described on project web pages. For example the current head revision of the program itself can be checked out with

svn checkout https://gwyddion.svn.sourceforge.net/svnroot/gwyddion/trunk/gwyddion

The reposition does not contain any generated files, no matter how exotic tools may be necessary to generate them. Therefore additional packages are required and there are also certain platform limitations. The additional tools and packages required for development are the same as for compilation from Subversion checkout. More precisely, one needs all the tools to build from a fresh checkout, while development may require only a subset of them or even none, depending on the type and extent of the changes.

Additional development build dependencies

Linux/Unix

After a fresh checkout, run ./autogen.sh with any arguments you would give to configure. Note it automatically adds --enable-maintainer-mode. This option enables make rules for creation and updates of files that are distributed in the source code tarball (and thus they are not generated during normal compilation). Generally, you should always use this configure option when you intend to change the program in a non-trivial way.

autogen.sh can fail even if you have sufficient versions of autotools installed. Some operating system do not install general autoconf or automake commands, only versioned commands such as autoconf261 or automake19. This makes particularly hard to find for example “automake 1.9 or newer” and therefore autogen.sh does not attempt it at all. You can either create unversioned symbolic links to the versioned commands or run autogen.sh as follows:

AUTOCONF=autoconf261 AUTOHEADER=autoheader261 ./autogen.sh

You may need to set the following variables: ACLOCAL, AUTOCONF, AUTOHEADER, AUTOM4TE, AUTOMAKE, LIBTOOLIZE. In addition, some operating systems may install autoconf macros in a place aclocal does not find them by default. This can be fixed by setting variable ACLOCAL_FLAGS to give aclocal additional search paths:

ACLOCAL_FLAGS="-I /usr/local/share/aclocal" ./autogen.sh

It is often necessary to combine these adjustments. For instance on FreeBSD, where all tools are versioned, one typically invokes (broken to lines for easier reading):

AUTOCONF=autoconf261 \
AUTOHEADER=autoheader261 \
AUTOM4TE=autom4te261 \
AUTOMAKE=automake19 \
ACLOCAL=aclocal19 \
ACLOCAL_FLAGS="-I /usr/local/share/aclocal" \
CPPFLAGS=-I/usr/local/include \
LDFLAGS=-L/usr/local/lib \
./autogen.sh --prefix=...

If autogen.sh passes you can compile the program as usual. However, a few things remain to generate.

Developer documentation is built with make docs. This has to be done explicitly, documentation is never (re)built automatically, option --enable-gtk-doc of configure only makes the docs target available (this option is on by default, therefore docs is made available when gtk-doc is detected).

MSVC files are built with ./utils/update-msvc.py which must be run from the top-level source directory (if you have Python interpreter installed elsewhere than in /usr/bin, run it as python ./utils/update-msvc.py). This tool takes care of keeping MSVC makefiles and other files up to date with Unix files that are taken as the primary source. More precisely update-msvc.py reads

  • lists of source and header files, modules, libraries and data files from Makefile.am
  • compiled libraries in .libs directories
  • gcc-generated compilation dependencies in .deps directories
  • template files to fill, these have extension .gwt, for example makefile.msc.gwt is a template for makefile.msc

and it writes

  • filled template files (namely makefiles)
  • .def files with lists of symbols to export from individual libraries

Evidently, it is necessary to perform a full project build first (with all optional features enabled) to generate these files properly.

One can think of update-msvc.py as a simple custom automake, because its basic task is to generate makefiles from Makefile.am.

MS Windows

As one can see from the previous section, a direct build from a Subversion checkout is not possible on MS Windows due to the inability to generate certain files there. Development is possible, although certain changes, namely additions of new files and refactorizations, require manual synchronization of files that could be updated automatically on a Unix-like system.

Fortunately plenty of free Unix-like systems is available, namely various GNU/Linux distributions. In the most desperate case one can use such a system for the checkout, build all necessary files, make a tarball and transfer it to MS Windows. This is equivalent to the use of nightly tarballs except that these tarballs can be generated any time.

However, it is also possible – and much more convenient – to build on MS Windows in the very same directory as on a GNU/Linux system. It is only necessary to share the build directory (typically in the home directory) with the Windows system using Samba. The GNU/Linux system can run either on a different physical computer or it can run on a virtual machine on the same computer as the host Windows system, for example in WMware player. (This setup can be also reversed by running MS Windows on a virtual machine but this is not the point of this section.)

When one runs builds for several operating systems from one directory, certain care has to be taken to avoid confusion due to the use of files corresponding to a different operating system. Fortunately, the only files that overlap between the Unix and MS Windows build systems are configuration headers config.h and gwyconfig.h. To update them after switch to MS Windows, just delete them, they will be re-created as a part of the build. To update them after switch to GNU/Linux, run ./config.status.