----------------------
- 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:
  svn checkout svn://gcc.gnu.org/svn/gcc/trunk 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
Hopefully one day the plugin will work with an unpatched gcc, but for the
moment a small patch needs to be applied.  Configure gcc with your favorite
options and also with --enable-lto.  Build gcc and install it somewhere.

Darwin special: the gcc configure script thinks darwin doesn't support dynamic
libraries and concludes that plugins won't work.  Delete or improve the check.
If you improve it, please send your patch to the gcc developers!

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

Build the plugin like this:
  GCC=PATH_TO_JUST_INSTALLED_GCC make
If the gcc installed in step 1 occurs in your path with the name gcc-4.5 (maybe
via a symbolic link) then you can build the plugin like this:
  make
The end result of the build is a shared library, dragonegg.so.

Darwin special: "-shared" doesn't result in a correct dynamic library on darwin,
use "-Wl,-flat_namespace -Wl,-undefined -Wl,suppress -dynamiclib" instead.

----------------------
- 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.