9. Build System

Vala is built using the standard GNU Autotools. The built executables are actually stored in .libs directories and wrapped by scripts. Therefore, to debug, follow these instructions:

9.1. Include debugging symbols

When compiling the compiler, append the --enable-debug flag to ./autogen.sh like this: ./autogen.sh --enable-debug.

An alternative method would be to use the --enable-coverage flag instead.

This also enables line numbers when generating stacktraces with gdb.

9.2. Enable backtraces for debugging

You can also enable backtraces when debugging with gdb like this:

G_DEBUG=fatal-criticals gdb --args my_valac_version my_test_program.vala

When a CRITICAL occurs, you'll be able to use bt or bt full in gdb to retrieve a backtrace.

9.3. Running a debugger through the libtool wrapper

As mentioned above, the built valac executable in the build tree (e.g. compiler/valac) is not the real binary but a shell script generated by libtool that wraps the actual executable in compiler/.libs/valac. Running a debugger directly on the wrapper script won't work, since it needs the real binary along with its library paths set up correctly.

Use the ./libtool script generated in your build tree (not your system's libtool) with --mode=execute to run gdb through the wrapper instead:

./libtool --mode=execute gdb --args ./compiler/valac my_test_program.vala

This lets libtool set up the correct library paths before handing control to gdb, so breakpoints and backtraces resolve properly.

This means you don't need to make install a debug build of Vala anywhere on your system to debug it. Configuring with --enable-debug and running make is enough - the debug valac and its matching libvala/libvalaccodegen libraries stay in the build tree's .libs directories, and ./libtool --mode=execute runs straight from there, leaving any installed valac you already have untouched.

macOS on Apple Silicon

Homebrew's gdb currently has unreliable support for launching and running processes on Apple Silicon Macs, even when it is codesigned and Developer Mode is enabled (sudo DevToolsSecurity -enable). If run fails with an error like Don't know how to run, use lldb instead, which is preinstalled with Xcode and works natively:

./libtool --mode=execute lldb -- ./compiler/valac my_test_program.vala

Within lldb, use b main, run, and bt in place of gdb's break main, run, and bt/bt full.

9.4. Debugging the generated C code

Since Vala compiles to C, some bugs only show up in the generated code rather than in the compiler itself. Pass -C to valac to keep the intermediate .c files instead of deleting them after compilation:

valac -C my_test_program.vala

You can then compile the generated C with debugging symbols and step through it directly with gdb, which is useful for narrowing down whether a bug is in codegen or in the runtime behavior of the generated program.

./configure uses the AC_PATH_PROG macro to choose the valac which is on your path, or one specified in the VALAC environment variable. Therefore, to build Vala with your own valac, type this, for example:

VALAC=$HOME/dev/vala-x.y.z/compiler/valac ./configure --prefix=$HOME/prefix

9.5. Configuring an isolated install prefix

Running make install installs straight into the system prefix (/usr/local by default), which can overwrite or conflict with a valac you already have installed, especially one managed by a package manager. This makes it easy to end up with a broken or mismatched compiler toolchain on your system.

To avoid this, configure the build with --prefix=PATH pointing at a directory outside your system paths, for example:

./autogen.sh --prefix=$HOME/vala-wip
make
make install

This installs valac and its supporting libraries entirely under $HOME/vala-wip, leaving any system-installed Vala untouched. To use the isolated install, add its bin directory to your PATH and, if needed, point the dynamic linker at its lib directory:

export PATH=$HOME/vala-wip/bin:$PATH
export LD_LIBRARY_PATH=$HOME/vala-wip/lib:$LD_LIBRARY_PATH

On macOS, use DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH.

Since PATH and LD_LIBRARY_PATH are ordered lists, prepending the isolated bin/lib directories makes the shell and dynamic linker resolve valac and its libraries there first, cleanly shadowing any system install for the lifetime of that shell.

If you're also building other projects against the isolated valac, note that pkg-config doesn't follow PATH - it uses its own search path. To make vala-X.Y.pc (and any other .pc files under the prefix) discoverable, also export:

export PKG_CONFIG_PATH=$HOME/vala-wip/lib/pkgconfig:$PKG_CONFIG_PATH

Otherwise, pkg-config --cflags --libs vala-X.Y may still resolve to a system-installed Vala instead of your isolated build.

This is especially useful for quickly testing a work-in-progress version of the compiler: you can switch between your isolated build and your system's valac just by toggling PATH, without ever running make install against system directories.

9.6. Out-of-tree build

An out-of-tree build does not properly work yet. Out-of-tree builds have the advantage that your source tree is not cluttered with built files. Suppose you have vala checked out in ~/dev/vala.

WARNING

The debugging instructions in 9.1 through 9.4 assume an in-tree build, where ./libtool and compiler/.libs/valac are generated directly inside the source tree. Since out-of-tree builds don't properly work yet, those paths would need to point into the separate build directory (e.g. buildvala/libtool, buildvala/compiler/.libs/valac) instead, once out-of-tree builds are fixed.

    rodney@solaria:~/dev % git clone https://gitlab.gnome.org/GNOME/vala.git
    rodney@solaria:~/dev % ls vala
fixme           fixme          fixme                  fixme
aclocal.m4      config.log     gobject-introspection  README
AUTHORS         config.status  INSTALL                stamp-h1
autogen.sh      config.sub     install-sh             tests
autom4te.cache  configure      libtool                vala
ccode           configure.ac   ltmain.sh              vala-1.0.pc
ChangeLog       COPYING        MAINTAINERS            vala-1.0.pc.in
compile         depcomp        Makefile               vapi
compiler        doc            Makefile.am            vapigen
config.guess    gee            Makefile.in            ylwrap
config.h        gen-project    missing
config.h.in     gobject        NEWS
fixme           fixme          fixme                  fixme
    rodney@solaria:~/dev % mkdir buildvala
    rodney@solaria:~/dev % cd buildvala
    rodney@solaria:~/dev/buildvala % ../vala/autogen.sh --prefix=$HOME/dev/prefix
    rodney@solaria:~/dev/buildvala % make

All Makefiles generated by configure will be put in the buildvala directory, and you can run make directly from there.