dragonegg/README

----------------------
- BUILD INSTRUCTIONS -
----------------------

Step 0: Build and install llvm-2.7
----------------------------------

I'm assuming anyone reading this knows how to build and install llvm.
You need to use the 2.7 release of LLVM, which you can find here:
  http://llvm.org/releases/download.html#2.7

Step 1: Build gcc
-----------------

Obtain a copy of the source code for the gcc-4.5 release.  You can get it from
one of the gcc mirrors, see http://gcc.gnu.org/mirrors.html.  Alternatively, you
can use the gcc-4.5 branch of the gcc subversion repository:
  svn checkout svn://gcc.gnu.org/svn/gcc/branches/gcc-4_5-branch SomeLocalDir
If you are feeling brave then you can try gcc mainline:
  svn checkout svn://gcc.gnu.org/svn/gcc/trunk SomeLocalDir
Changes on gcc mainline occasionally break the plugin, so your mileage may vary.
You can find a subversion revision number that is known to work well in the file
gcc_revision_tested_with (in the same directory as this README).

Apply the patches in the gcc-patches subdirectory, if any.  The following should
do the trick ("SomeLocalDir" is where you checked/unpacked the gcc source):
  cat gcc-patches/*.diff | patch -d SomeLocalDir -p1

Configure gcc with your favorite options and also with --enable-plugin and
--enable-lto.  Build gcc and install it somewhere.  If you don't have libelf
installed then the build will fail, because gcc's LTO code makes use of it,
see
  http://gcc.gnu.org/wiki/LinkTimeOptimization#Building_the_branch
In theory the gcc you build can be a cross-compiler, and the plugin should work
and build code for the targetted platform.  I don't think anyone has ever tried
this though.

Darwin special: the gcc configure script thinks darwin doesn't support dynamic
libraries and concludes that plugins won't work.  You can find patches to fix
this here:
http://gcc.gnu.org/ml/gcc-patches/2010-04/msg00610.html

Step 2: Build the plugin
------------------------

Build the plugin like this:
  GCC=PATH_TO_JUST_INSTALLED_GCC make
This should be done in the directory containing this README.

The plugin needs to know about the version of gcc it will be loaded into, which
is why you need to specify the gcc installed in step 1 via the GCC variable like
this.  If you have arranged for the new gcc to occur in your path with the name
gcc-4.5 (using a symbolic link for example) then you can build the plugin using:
  make
The plugin is compiled using the system compiler, and not with the gcc specified
in the GCC variable (which wouldn't work if you built a cross compiler).  If you
want to also compile the plugin with the new gcc, you can do:
  CC=PATH_TO_JUST_INSTALLED_GCC CXX=PATH_TO_JUST_INSTALLED_GCC GCC=PATH_TO_JUST_INSTALLED_GCC make

The build system runs the "llvm-config" program (which should be in your path if
you installed LLVM properly in step 0) to find out about the copy of LLVM you
installed, so there is no need to tell the build system explicitly about LLVM.
If llvm-config is not in your path then you can specify where to find it using
the LLVM_CONFIG variable.

The end result of the build is a shared library, dragonegg.so.


----------------------
- USAGE INSTRUCTIONS -
----------------------

Run gcc as usual, but pass -fplugin=./dragonegg.so as an extra command line
argument.  Make sure you use the gcc you installed above, not the system gcc!


------------------
- USEFUL OPTIONS -
------------------

If you renamed dragonegg.so to something else, for example llvm.so, replace
-fplugin-arg-dragonegg with -fplugin-arg-llvm in the options below.

-fplugin-arg-dragonegg-emit-ir
-flto
  Output LLVM IR rather than target assembler.  You need to use -S with this,
  since otherwise GCC will pass the output to the system assembler (these don't
  usually understand LLVM IR).  It would be nice to fix this and have the option
  work with -c too but it's not clear how.  If you plan to read the IR then you
  probably want to use the -fverbose-asm flag as well (see below).

-fverbose-asm
  Annotate the target assembler with helpful comments.  Turns on the generation
  of helpful names (the same as in GCC tree dumps) in the LLVM IR.

-fstats
  Output both LLVM and GCC statistics.

-ftime-report
  Output both LLVM and GCC timing information.

-fno-ident
  If the ident global asm in the LLVM IR annoys you, use this to turn it off.

-fplugin-arg-dragonegg-debug-pass-arguments
-fplugin-arg-dragonegg-debug-pass-structure
  Output information about the passes being run.

-fplugin-arg-dragonegg-disable-llvm-optzns
  Do not perform any LLVM IR optimizations even if compiling at -O1, -O2 etc.

-fplugin-arg-dragonegg-enable-gcc-optzns
  Run the GCC tree optimizers as well as the LLVM IR optimizers.  Only early GCC
  optimizations are performed.  Normally all GCC optimizations are disabled.

-fplugin-arg-dragonegg-save-gcc-output
  GCC assembler output is normally redirected to /dev/null so that it doesn't
  clash with the LLVM output.  This option causes GCC output to be written to
  a file instead.  Good for seeing which GCC output we've failed to turn off.