dragonegg/README

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

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

I'm assuming anyone reading this knows how to build and install llvm.
You need the latest llvm from the subversion repository.

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

Check out gcc from the gcc subversion repository, either gcc mainline:
  svn checkout svn://gcc.gnu.org/svn/gcc/trunk SomeLocalDir
or the gcc-4.5 branch:
  svn checkout svn://gcc.gnu.org/svn/gcc/branches/gcc-4_5-branch SomeLocalDir

Apply the patches in the gcc-patches subdirectory, if any.  The following
command should do the trick ("SomeLocalDir" is where you checked out gcc):
  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
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 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.