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