Download and build GCC MELT
with GCC MELT examples

Audience: you are expected to be familiar with building free software from source code on GNU/Linux systems on the command line (so at ease with g++, make, bash, awk), and you should have root access to your computer. Please read this entire section before starting the build. If your GCC compiler is not invoked by gcc or g++, replace these appropriately (e.g. with /usr/local/bin/g++-4.9 if your systam has that).

Prerequisites for compiling (and using) GCC MELT

A recent GCC compiler (version 4.8, 4.9, 5. or later) is required. Check with gcc -v and g++ -v that you have a 4.8 or later version of the compiler, and (with gcc -v 2>&1 | grep plugin) that your compiler has enabled plugins.

Don't expect to make GCC MELT run on an earlier version of GCC (like 4.7). If your gcc or g++ configuration, as reported by e.g. g++ -v, does not say Configured with: .... --enable-plugin complain to your Linux vendor and recompile your GCC compiler from a recent FSF source release, preferably 4.8 or later. This might not be easy, and probably takes hours.

You should be sure that your gcc and g++ commands are running the real GCC compiler. Remember that on some systems the gcc (or g++) command is actually using a ccache or a distcc utility. Please disable such things on your system, perhaps by using a full path like /usr/bin/gcc-4.9 or whatever.

Some Gnu/Linux distributions are overloading their gcc command with ccache. Double-check that this is not the case on your system (because GCC MELT often compiles an empty file to get some other things done).

Please use a powerful computer to build the GCC MELT plugin. You need at least 6Gbytes of RAM, and 9Gbytes of disk space. A successful build of GCC MELT plugin may take more than 15 - 30 minutes on the clock.

Building GCC MELT needs some resources, mostly because the building process is translating MELT → C++ the MELT translator several times, and because the generated C++ code contain very long initialization routines, which take time and memory to be compiled to dlopen-able shared objects.

Ensure that you have all the dependencies to build GCC plugins, which also requires the dependencies to build the GCC compiler itself. If you have a recent Debian or compatible (Ubuntu, Mint, ....) distribution, run as root apt-get build-dep g++-4.9 gcc-4.9-plugin-dev then apt-get install g++-4.9 gcc-4.9 gcc-4.9-plugin-dev. If you have some other distribution, try to find the equivalent commands to get the build dependencies, and the binary packages, of the g++ compiler (if you don't have a g++-4.9 but a g++-5 replace 4.9 by 5 in these commands). These dependencies are also needed to use MELT, because MELT is routinely emitting C++ code suited for your compiler, then make-ing some shared object from that emitted code, and at last dlopen-ing that shared object module.

If you cannot get help from your distribution to have the build dependencies of your compiler installed, you'll need to install a lot of (GNU or other) utilities, notably make, gcc, g++, bash, autotools, awk, indent, sed, perl, svn, binutils (i.e. ld and as), autogen, m4, ed, texinfo, texi2html, unifdef, astyle etc. You'll also need the required libraries -in development form- for your compiler, perhaps PPL and/or ISL, CLOOG, GMP, and more. Run gcc -v to understand how your particular GCC compiler was configured and built, then install all the build dependencies.

Compiling and installing the GCC MELT plugin

Since GCC MELT is a [meta-]plugin, it is installed in the directory for plugins, as obtained by gcc -print-file-name=plugin. Ensure that the path obtained by this command is a absolute file path to a directory containing a non empty include sub-directory by running successfully ls -l $(gcc -print-file-name=plugin)/include/gcc-plugin.h. Since GCC MELT is installed in a plugin/ sub-tree suited for your GCC compiler it does not need any configure step.

We say (pedantically) that GCC MELT is a meta-plugin since it is a plugin for gcc which itself dynamically loads, with dlopen, other shared object modules.

Optional: The GCC MELT build may notify you about some important steps. If you like (Gnome/Kde/Xfce4) desktop "bubble" notifications, you may want to set your GCCMELT_BUILD_NOTIFICATION environment variable to some script accessible thru your $PATH, like e.g. my $HOME/bin/meltbuild-notification containing

#!/bin/bash
#file meltbuild-notification
# first arg title, second arg message
if [ "$DISPLAY" = ":0.0" -a -n "$DESKTOP_SESSION" -a $(which notify-send) ]; then
   notify-send -t 3500 -i info "MELT BUILD: $1" "$2"
else
   logger -t meltbuild -p user.info "$1=" "$2"
fi

But this is only eye candy. You don't need that meltbuild-notification script. If you want it,
export GCCMELT_BUILD_NOTIFICATION=$HOME/bin/meltbuild-notification or similar. The GCC MELT building won't notify you if you don't have any GCCMELT_BUILD_NOTIFICATION environment variable.

Notice that MELT should be built in a fresh directory, independent (and outside of...) of the source or installed binary of the gcc compiler you are building it for. Often, you'll build MELT in a fresh subdirectory of /tmp/ or of your $HOME/tmp/. You don't need to be root to compile MELT (but you probably need to be root to install it...). Be aware that MELT is tightly coupled with GCC and should have a version compatible with your particular gcc and g++ (etc..., perhaps named gcc-4.8 and so on...) compilers.. Some MELT plugin for GCC 4.7 and 4.8 at most cannot work with a GCC 4.9.

1. You should download (e.g. with cd /tmp; wget http://starynkevitch.net/Basile/gcc-melt/melt-1.1.3-plugin-for-4.8-or-4.9.tar.bz2 or whatever is appropriate) and un-tar your GCC MELT plugin source archive (perhaps with tar xjvf melt-1.1.3-plugin-for-4.8-or-4.9.tar.gz) in some fresh directory to obtain a directory (such as melt-1.1.3-plugin-for-4.8-or-4.9/, perhaps /tmp/melt-1.1.3-plugin-for-4.8-or-4.9/ etc...) containing (amongst others) two files melt-runtime.{h,cc} and a sub-directory melt/ with notably melt/generated/meltrunsup.h and melt/warmelt-outobj.melt (and many other files, etc...). This directory also contains MELT-Plugin-Makefile which is symlinked from Makefile.
2. Go into that directory with e.g. cd melt-1.1.3-plugin-for-4.8-or-4.9/ then list it with ls -lF and carefully read the README-MELT-PLUGIN file there using your favorite pager (less, ...) or editor (emacs, vim, gedit etc....). Your README-MELT-PLUGIN file may contain additional installation instructions or caveats.
3. Inspect the Makefile (it is a symlink), and edit it if you want. You probably don't need to change anything in that file, but you could (e.g. you might want to change the MELTGCC_PLUGIN_DIR make variable to have MELT installed elsewhere).
4. If your GCC compiler is a cross-compiler, set your environment variable MELTGCC_NO_CHECK_RUNTIME with export MELTGCC_NO_CHECK_RUNTIME=yes to avoid having the melt-runtime.c be checked by an existing MELT pass. Most users have a straight compiler (not a cross-compiler) so should not have any MELTGCC_NO_CHECK_RUNTIME environment variable.
5. compile your GCC MELT plugin: run make all; you don't need to be root for that. You could specify the particular compiler you want to extend with e.g. make CC=/usr/bin/gcc-4.9 CXX=/usr/bin/g++-4.9 or something similar (read the Makefile please). This make should not be parallel (no make -j) and takes some time (e.g. more than 20 minutes). The last dozen of output lines should say that MELT plugin compilation completed and may give additional advice.
6. Installation step: run (without being root) make install DESTDIR=/tmp/meltpluginst (where the given DESTDIR is some fresh installation temporary directory (outside of your GCC or MELT source or build or installation directories!) then copy as root (e.g. using sudo) that directory, e.g. with sudo cp -r -v -p /tmp/meltpluginst/. /.). Actually, only the $(gcc -print-file-name=plugin) directory (and perhaps some documentation directory) will be filled.
7. (much later) optional uninstallation: the $(gcc -print-file-name=plugin) directory contains files and subdirectories named melt*. You can remove them. Notice that melt.so is actually a symlink (e.g. to melt-1.1.3.so). Advanced users might explicit their particular version of the GCC MELT plugin with options like gcc -fplugin=melt-1.1.3 (so in principle you could have several MELT versions for the same GCC compiler version, even if this is adventurous).

You should rebuild (from a pristine MELT source code tree) your GCC MELT plugin at every change (even very minor ones!) of your GCC compiler, even a minor "patchlevel" evolution from gcc-4.9.1 to gcc-4.9.2.

The installed GCC MELT plugin contains notably the MELT source code, a Makefile fragment, and its C++ translation in some melt-sources/ sub-directory (containing e.g. warmelt-outobj.melt, warmelt-outobj+01.cc and warmelt-outobj+meltdesc.c and warmelt-outobj+meltbuild.mk, etc....), and many shared object MELT modules in some melt-modules/ sub-directory. All are needed to run GCC MELT. The modules shared object file names contain an MD5 signature in their path, like e.g. warmelt-genobj.meltmod-d5e04ab838f69c0d24aa4b0d30d9ae85.quicklybuilt.so - of course, the actual MD5 checksum may differ, it is the checksum of the catenation of generated C++ files.

GCC MELT is a GCC plugin and also an experimental GCC development branch (free software GPLv3 licensed and FSF copyrighted), and most users want the MELT plugin. The MELT branch is mostly useful for potential contributors to GCC MELT willing to improve MELT itself. The MELT plugin source code is extracted from the MELT branch. You could get the latest code snapshot of the experimental MELT branch using subversion: svn co svn://gcc.gnu.org/svn/gcc/branches/melt-branch gcc-melt and you can browse that branch at gcc.gnu.org/viewcvs/branches/melt-branch

You probably need 4 gigabytes of disk space, and dozens of minutes, to retrieve the MELT branch using the above svn command. You should build a gcc-melt compiler as you build the GCC trunk, in a build tree outside of the source tree.

To get the source tarball for a GCC MELT plugin, run contrib/make-melt-plugin-source-tar.sh $PWD /tmp/meltpluginsource from inside the MELT branch source code to get the /tmp/meltpluginsource.tar.gz tarball. A similar command is used to get every MELT plugin release tarball.

The GCC trunk (on which the GCC community actively works to prepare the next release of GCC) is often merged (usually once a week) into the MELT branch. So that MELT branch may be unstable. You probably want to pass --program-suffix=-melt to ..../gcc-melt/configure when building that branch (outside of its source tree).

Small tutorial examples

Simple tutorial examples are available on melt-examples at GitHub, notably

• The hello world in MELT
• Counting functions thru a simple GCC pass written in MELT
• Showing the actually executed GCC passes
• Searching some functions thru another simple GCC pass written in MELT
• Typechecking some variadic functions for the Jansson library (for JSON serialization)
• etc...

Software written in MELT

Pierre Vittet has developped Talpo (available on Gitorious) using GCC MELT. Talpo is a MELT extension giving some warnings about your code (e.g. find misuse of untested fopen-s). This is a GSOC 2011 project on Customizable warnings with a GCC plugin

My colleague Emmanuel Haucourt (CEA, LIST, DILS) is using MELT to interface his Alcool tool to GCC.

MELT in MELT

Most of GCC MELT is coded MELT itself. In particular, files melt/warmelt-*.melt contain the MELT → C++ translator, and files melt/xtramelt-*.melt contain other things (notably the probe, most of the glue between Gimple and Tree internal GCC representations, a pass to check the GCC MELT runtime against its coding rules, and some simple other passes).