README

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

Prerequisites
-------------

The dragonegg plugin works with gcc 4.5, 4.6, 4.7 or 4.8, so you will need to
have one of these installed.  Many linux distributions ship one or both of them,
perhaps as an addon package; binaries can be downloaded for most platforms.
Otherwise you can always build gcc yourself.  Plugin support (--enable-plugin)
needs to be enabled in gcc, but since it is enabled by default on most platforms
you usually won't need to do this explicitly.

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

I'm assuming anyone reading this knows how to build and install llvm.  The
version of llvm must match the version of the plugin, so if you are building
dragonegg-3.0 then you should use llvm-3.0, while if you are building the
development version of dragonegg then use the development version of llvm.


Step 1: Build the plugin
------------------------

Build the plugin like this:
  GCC=PATH_TO_INSTALLED_GCC make
This command should be executed 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 your version of gcc 4.5/4.6 via the GCC variable like
this.  For example, if the version of gcc you want to load the plugin into is
/usr/local/gcc-4.6/bin/gcc, then you should do
  GCC=/usr/local/gcc-4.6/bin/gcc make
If you don't set the GCC variable then by default "gcc" is used, so you
can just do
  make
if you plan to use the plugin with whatever version of gcc is in your path.

The plugin makes use of various gcc headers that are usually shipped with gcc.
However some linux distributions, for example debian and ubuntu, have split the
headers out of gcc into a separate package.  So if you get errors along the
lines of "config.h not found", check whether gcc headers like "config.h" and
"tree.h" are installed.  On debian the package containing headers is called
gcc-4.5-plugin-dev or gcc-4.6-plugin-dev.

The plugin is compiled using the system compiler, and not with the gcc specified
in the GCC variable (which wouldn't work if it is a cross compiler).  If you
want to also compile the plugin with your copy of gcc 4.5/4.6, you can do:
  CXX=PATH_TO_INSTALLED_GCC GCC=PATH_TO_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.

If you want the dragonegg plugin to be able to load LLVM plugins then pass
ENABLE_LLVM_PLUGINS=1 to make.


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

Run gcc as usual, but pass -fplugin=./dragonegg.so as an extra command line
argument.  Make sure you use the gcc you built dragonegg against (see step 1)!


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

-specs=/path/to/integrated-as.specs 
  Use the LLVM integrated assembler rather than the system assembler.

-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-llvm-ir-optimize=N
  Run the LLVM IR optimizers at optimization level N, overriding the GCC
  optimization level.  Usually if you pass -O1, -O2 etc to GCC then the
  LLVM IR level optimizers are also run at -O1, -O2 etc.  Use this option
  to change this, disassociating the LLVM optimization level from the GCC
  one.  For example, -fplugin-arg-dragonegg-llvm-ir-optimize=0 disables
  all LLVM IR optimizations.

-fplugin-arg-dragonegg-llvm-codegen-optimize=N
  Run the LLVM code generator optimizers at optimization level N, overriding
  the GCC optimization level.  Usually if you pass -O1, -O2 etc to GCC then
  the LLVM code generators optimize at a corresponding level.  Use this option
  to change this, disassociating the LLVM optimization level from the GCC one.

-fplugin-arg-dragonegg-enable-gcc-optzns
  Run the GCC tree optimizers rather than the LLVM IR optimizers (normally all
  GCC optimizations are disabled).  By default this reduces the amount of LLVM
  IR optimization.  Use -O4 to have LLVM optimize harder, or explicitly set a
  level using the -fplugin-arg-dragonegg-llvm-ir-optimize option.

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

-fplugin-arg-dragonegg-llvm-option=options
  Pass command line options through to LLVM.  If you want to pass an option that
  contains equals signs then you need to use colons (':') instead of '='.