path: root/INSTALL/README-MELT-PLUGIN

Short installation instructions for MELT as a plugin to an installed
gcc-4.6 enabled for plugins.

See also http://gcc.gnu.org/wiki/MELT and http://gcc-melt.org/

MELT is a plugin and domain specific language for extending GCC (the
Gnu Compiler Collection), free software GPLv3+ licensed, FSF
copyrighted. MELT is a lispy, high-level, language providing pattern
matching and enabling functional/applicative/reflective programming
styles, to ease development of GCC extensions.  MELT is translated to
C code (and the MELT translator is implemented in MELT).

If installing MELT as plugin to some existing gcc-4.6 installation
tree, with the support of plugins enabled.

################ step 1

First, ensure that GCC 4.6 is correctly installed and has been built
with plugins enabled, for example (on a Debian Unstable or
Experimental, package gcc-4.6):

 % gcc-4.6 -v
Using built-in specs.
COLLECT_GCC=/usr/bin/gcc-4.6
COLLECT_LTO_WRAPPER=/usr/lib/x86_64-linux-gnu/gcc/x86_64-linux-gnu/4.6.1/lto-wrapper
Target: x86_64-linux-gnu
Configured with: ../src/configure -v --with-pkgversion='Debian 4.6.1-2' --with-bugurl=file:///usr/share/doc/gcc-4.6/README.Bugs --enable-languages=c,c++,fortran,objc,obj-c++,go --prefix=/usr --program-suffix=-4.6 --enable-shared --enable-multiarch --with-multiarch-defaults=x86_64-linux-gnu --enable-linker-build-id --with-system-zlib --libexecdir=/usr/lib/x86_64-linux-gnu --without-included-gettext --enable-threads=posix --with-gxx-include-dir=/usr/include/c++/4.6 --libdir=/usr/lib/x86_64-linux-gnu --enable-nls --enable-clocale=gnu --enable-libstdcxx-debug --enable-libstdcxx-time=yes --enable-plugin --enable-objc-gc --with-arch-32=i586 --with-tune=generic --enable-checking=release --build=x86_64-linux-gnu --host=x86_64-linux-gnu --target=x86_64-linux-gnu
Thread model: posix
gcc version 4.6.1 (Debian 4.6.1-2) 

Be sure that you have all the development packages for all libraries
used by GCC (e.g. run 'apt-get build-dep gcc' on Debian). In
particular, you'll need the headers of CLOOG, PPL, MPC, MPFR, GMP
libraries.

################ step 2

Then, be sure that the GCC plugin development support has been
installed. (On Debian, you'll need the gcc-4.6-plugin-dev package).

So you should have something like
% gcc-4.6 -print-file-name=plugin 
/usr/lib/gcc/x86_64-linux-gnu/4.6.1/plugin

Be sure that this plugin subdirectory is populated correctly since it
contains an include file.

% ls -l $(gcc-4.6 -print-file-name=plugin)
total 4
drwxr-xr-x 8 root root 4096 Mar 30 14:16 include

Be sure that this include subdirectory contains meaningful files for
GCC, like those for GIMPLE
% ls -l $(gcc-4.6 -print-file-name=plugin)/include/gimple.* 
-rw-r--r-- 1 root root  13735 Mar 30 04:02 /usr/lib/gcc/x86_64-linux-gnu/4.6.1/plugin/include/gimple.def
-rw-r--r-- 1 root root 123008 Mar 30 04:02 /usr/lib/gcc/x86_64-linux-gnu/4.6.1/plugin/include/gimple.h

Be sure that the gengtype executable and its gtype.state textual data
file is available somewhere. On Debian/Sid the package
gcc-4.6-plugin-dev provides: 
% ls -l /usr/lib/x86_64-linux-gnu/gcc/x86_64-linux-gnu/4.6/gengtype /usr/lib/x86_64-linux-gnu/gcc/x86_64-linux-gnu/4.6/gtype.state

-rwxr-xr-x 1 root root 163840 Jul  5 16:48 /usr/lib/x86_64-linux-gnu/gcc/x86_64-linux-gnu/4.6/gengtype
-rw-r--r-- 1 root root 614004 Jul  5 16:48 /usr/lib/x86_64-linux-gnu/gcc/x86_64-linux-gnu/4.6/gtype.state

and you get these files with 
  $(gcc-4.6 -print-file-name=gengtype) 
and 
  $(gcc-4.6 -print-file-name=gtype.state) 
respectively

Look with an editor, or just with the head command, that this gtype.state
file is indeed the one related to your gcc-4.6:
% head /usr/lib/x86_64-linux-gnu/gcc/x86_64-linux-gnu/4.6/gtype.state
;;;;@@@@ GCC gengtype state
;;; DON'T EDIT THIS FILE, since generated by GCC's gengtype
;;; The format of this file is tied to a particular version of GCC.
;;; Don't parse this file wihout knowing GCC gengtype internals.
;;; This file should be parsed by the same gengtype which wrote it.
;;; file gtype.state generated on Tue Jul  5 09:03:22 2011


(!version  "4.6.1")


################ step 3

Your plugin MELT directory should contain a Makefile which is a
symlink to a MELT-Plugin-Makefile file. Please look into that file.
(Most of the work is done in melt-build.mk, included from it).

Use
    make all
to build the MELT plugin which takes some time, because MELT is
retranslating itself.

Use
   make install
to install the MELT plugin. The usual DESTDIR behave as expected.

For packagers: notice that the MELT plugin should be entirely rebuilt
even for small changes of the compiler (e.g. when upgrading gcc from
4.6.0 to 4.6.1).


###
Previous releases of MELT plugin have been built with the
built-melt-plugin.sh script, using
# building the plugin
 ./build-melt-plugin.sh -v -b -s GCC=gcc-4.6 \
    -G $(gcc-4.6 -print-file-name=gengtype) \
    -T $(gcc-4.6 -print-file-name=gtype.state) \
    -M $PWD

# installing the plugin
 ./build-melt-plugin.sh -v -i -s DESTDIR=/tmp/meltplugindestdir -M $PWD
# or perhaps
 ./build-melt-plugin.sh -v -i -s HOSTADMINCMD=sudo -M $PWD


################

To prepare a source tree of the MELT plugin from the GCC MELT branch,
run contrib/gcc_update then read and run
contrib/make-melt-source-tar.sh from the GCC MELT branch. For
instance, I am running it with something similar to

   /usr/src/Lang/gcc-melt-branch/contrib/make-melt-source-tar.sh \
       /usr/src/Lang/gcc-melt-branch \
       /tmp/gcc-melt-plugin  \
        $(gcc-4.6 -print-file-name=gengtype) \ 
        -v -r $(gcc-4.6 -print-file-name=gtype.state)

If all goes well, you get a /tmp/gcc-melt-plugin.tgz gnuzipped tar
archive for the MELT plugin. This is only needed to people making a
new MELT plugin source archive.

################ 

Comments about the MELT plugin (including its installation script) are
welcome by email to <basile@starynkevitch.net> [please mention MELT in
the subject line]

#######################################################################
NEWS for 0.9.2.b MELT plugin for gcc-4.6 (and future gcc-4.7)

December 08th, 2011: Release of MELT plugin 0.9.2 for gcc-4.6 (& future gcc-4.7)
	dedicated to the memory of John McCarthy
        http://en.wikipedia.org/wiki/John_McCarthy_(computer_scientist)

Several bug fixes.

New features:

    cloning of values
    =================

The CLONE_WITH_DISCRIMINANT primitive -whose implementation is mostly
generated- enables creating new values, nearly clones of old
ones. Usage is

    (clone_with_discriminant <old-value> <new-discriminant>)

If the new discriminant is compatible with the old value's
discriminant, a new value is allocated. If it is not compatible nor
not a discriminant, the old value is returned. In particular, it is
possible to use 
   (clone_with_discriminant (lambda ....) discr_debug_closure) 
to make a debugging closure.

   debugging closures 
   ==================

The DEBUG macro (and the underlying MELT_DEBUG_FUN which you should
not use directly) handles closure with the DISCR_DEBUG_CLOSURE
discriminant specially (somehow like C++ manipulators for
ostream-s). If an argument is a debugging closure of exactly the
DISCR_DEBUG_CLOSURE discriminant, the next argument is displayed using
that debugging closure.

   Walking SSA use-def chains
   ==========================

The primitives WALK_USE_DEF_CHAIN_BREADTH_FIRST &
WALK_USE_DEF_CHAIN_DEPTH_FIRST enables to walk thru the use-def chains
in SSA passes.

   More support notably for Gimple & Tree
   ======================================

Several functions, cmatchers, primitives have been defined, notably
GIMPLE_ASSIGN_TO, WALK_USE_DEF_CHAIN_BREADTH_FIRST &
WALK_USE_DEF_CHAIN_DEPTH_FIRST, EACHGIMPLEPHI_IN_BASICBLOCK


  New MELT hooks for PLUGIN_FINISH_TYPE & PLUGIN_FINISH_DECL
  ==========================================================

MELT functions can be registered using
REGISTER_FINISH_TYPE_HOOK_FIRST, REGISTER_FINISH_TYPE_HOOK_LAST,
REGISTER_FINISH_DECL_HOOK_FIRST, REGISTER_FINISH_DECL_HOOK_LAST. The
argument is a boxed tree value. The PLUGIN_FINISH_DECL don't exist in
GCC 4.6 (only in GCC 4.7 and later).

  New MELT hooks for other events
  ===============================
 
MELT functions can be register for PLUGIN_ALL_PASSES_START,
     PLUGIN_ALL_PASSES_END, PLUGIN_ALL_IPA_PASSES_START,
     PLUGIN_ALL_IPA_PASSES_END, PLUGIN_EARLY_GIMPLE_PASSES_START,
     PLUGIN_EARLY_GIMPLE_PASSES_END event using
 REGISTER_ALL_IPA_PASSES_END_HOOK_FIRST
 REGISTER_ALL_IPA_PASSES_END_HOOK_LAST
 REGISTER_ALL_IPA_PASSES_START_HOOK_FIRST
 REGISTER_ALL_IPA_PASSES_START_HOOK_LAST
 REGISTER_ALL_PASSES_END_HOOK_FIRST
 REGISTER_ALL_PASSES_END_HOOK_LAST
 REGISTER_ALL_PASSES_START_HOOK_FIRST
 REGISTER_ALL_PASSES_START_HOOK_LAST
 REGISTER_EARLY_GIMPLE_PASSES_END_HOOK_FIRST
 REGISTER_EARLY_GIMPLE_PASSES_END_HOOK_LAST
 REGISTER_EARLY_GIMPLE_PASSES_START_HOOK_FIRST
 REGISTER_EARLY_GIMPLE_PASSES_START_HOOK_LAST


  More runtime code generated
  ===========================
More runtime code is generated internally.

  Additional translating MELT modes
  =================================

The translatetomodule mode produces all three flavors (.quicklybuilt.so, .debugnoline.so, .optimized.so) of modules

The translateoptimized mode produces .optimized.so flavor of modules

#######################################################################
NEWS for 0.9.1 MELT plugin for gcc-4.6

October 24, 2011: Release of MELT plugin 0.9.1 for gcc-4.6
	dedicated to the memory of Dennis M. Ritchie
	http://en.wikipedia.org/wiki/Dennis_Ritchie

New features:

    variadic MELT functions. 
    =======================
A formal arguments list (i.e. formals for LAMBDA or DEFUN) ending with
:REST is for variadic functions with a variable number and type of
arguments (so :REST in MELT is similar to the ellipsis ... notation in
C prototypes).  At least one first formal argument should be provided
and should be a value.

The (VARIADIC ....) macro is used to fetch actual variadic
arguments. A variadic cursor is internally maintained to parse the
variadic actual arguments. The VARIADIC macro has a sequence of
variadic cases. Each variadic case starts with an ordinary
[non-variadic] formal arguments list, and has a body which is
evaluated for side effects if the current arguments at the cursor
position fits into the formal. The last variadic case can also starts
with an :ELSE.  See also
http://groups.google.com/group/gcc-melt/browse_thread/thread/c124ea6af940c08e

    variadic (DEBUG ....) macro.
    ============================

Debugging messages should go thru the variadic (DEBUG ...) macro which
accepts an arbitrary kind and number of arguments. The DEBUG_MSG macro
is obsolete.

   variadic ADD2OUT function
   =========================

The ADD2OUT variadic function add to an output (either a file value;
or a string buffer values) arbitrary things.

#######################################################################
NEWS for 0.9 MELT plugin for gcc-4.6

September 27th, 2011: Release of MELT plugin 0.9 for gcc-4.6

New features:

    Documentation is generated

    The PLUGIN_PRE_GENERICIZE event is interfaced.

    The build machinery and the binary module loading has been
    significantly updated.  Modules shared objects are like
    warmelt-macro.3461497d8ef7239dc1f2f132623e6dd5.quicklybuilt.so and
    they contain the md5sum of the catenation of all C files. They
    also come in various flavor: quicklybuilt (the generated C is
    compiled with -O0 -DMELT_HAVE_DEBUG), optimized (the generated C
    is compiled with -01 and without -DMELT_HAVE_DEBUG), debugnoline
    (the generated C is compiled with -g and -DMELT_HAVE_DEBUG but no
    #line directives).

    Conceptually, a module is loaded by loading its +meltdesc.c
    file. That file (e.g. warmelt-macro+meltdesc.c corresponding to
    warmelt-macro.melt) should never be moved or even edited.  It is
    parsed at module load time, and contains the various md5sum of
    real generated C files.

    New option -fplugin-arg-melt-workdir= for the work directory,
    where every .c or .so files are generated.

    The DISCR_BOX discriminant has been removed. Use containers instead.

    Containers, that is instances of class_container having one single field 
    :container_value, are supported by syntactic macros and sugar & function.
       (container V)   
          =equivalent=   (instance class_container :container_value V)
       (content C)
          =equivalent=   (get_field :container_value C)
       (set_content C V)
          =equivalent=   (put_fields C :container_value V)
    You can write exclaim instead of content, and there is a new syntactic 
    sugar
       !X

     is the same as (content X) - the exclamation mark should be
     followed by spaces, letters, or left parenthesis to be parsed as
     exclaim -that is as the content macro above.

    In patterns, ?(container ?v) means 
    ?(instance class_container :container_value ?v)

    Fields can be accessed by their name, so
      (:F C)
   is the same as (get_field :F C)
   Hence (:container_value foo) is the same as !foo or 
   (get_field :container_value foo)

   Experimental syntactic sugar: inside an s-expr, a macro string
   written ##{...}# is expanded as several components, not a single
   list.

   Experimental: ability to (define ...) values like in Scheme.

   Ability to create gimple-s and to modify gimple_seq.

   Slow boxed arithmetic operations are available (e.g. +iv gets two
   boxed integer and gives the boxed integer of their sum).

Many bug fixes.

The build system has been revamped. The generated .c files should be
available when running MELT.


Thanks to Pierre Vittet, Alexandre Lissy, Romain Geissler for
feedback, patches, suggestions.

#######################################################################
NEWS for 0.8 MELT plugin for gcc-4.6

July 11th, 2011: Release of MELT plugin 0.8 for GCC 4.6
as melt-0.8-plugin-for-gcc-4.6 on http://gcc-melt.org/


New features:
 * support for pragmas for MELT

 * the MELT garbage collector is called less often, using the
   PLUGIN_GGC_START hook.

 * several new c-iterators and c-matchers.

 * added static analyzing pass gccframe, useful for melt-runtime.c

 * reject nested defun-s, you should use letrec or let...

 * the MELT plugin is built with its MELT-Plugin-Makefile

 * debug_msg, assert_msg ... should work, thanks to MELT_HAVE_DEBUG
   preprocessor flag, even when melt.so is a plugin for a GCC without
   checks enabled.

 * melt-runtime.h has a melt_gcc_version integer variable and
   melt-runtime.c should be given MELT_GCC_VERSION preprocessor
   constant.

 * runfile mode compiles quickly (with debug_msg support). Add new mode
   translatequickly to compile quickly (with debug_msg & assert_msg
   support).

 * the MELT building procedure builds various variants of MELT modules,

   The 'optimized' variant is built with -O2 but don't support
   (debug_msg ...)  or (assert_msg ...). The 'quicklybuilt' variant is
   built with -O0 and supports debug_msg & assert_msg.  The
   'debugnoline' variant is mostly useful with gdb, and also supports
   debug_msg & assert_msg. These variants should be interoperable, you
   could have a warmelt* module with 'optimized' variant and an
   xtramelt* module in 'quicklybuilt' bariant.

Many bugfixes
  (but some bugs remain)

Thanks to Pierre Vittet for code contributions (notably thru Google
Summer of Code), Alexandre Lissy and Allan McRae for bug reports.

(MELT development is partly funded thru OpenGPU [FUI call] & GlobalGCC
[ITEA call] projects by French DGCIS).

#######################################################################
NEWS for 0.7 MELT plugin for gcc-4.6

April 29th, 2011: first release, melt-0.7-plugin-for-gcc-4.6