---------------------- - 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 '='.
A gcc plugin that provides LLVM optimizations