CTools:ICI:Start

From cTuning.org

Revision as of 15:40, 30 March 2009

Navigation: cTuning.org > CTools > ICI

Quick tutorial about how to quickly start using ICI and plugins:

ICI plugins are simply shared object files with distinguished functions:

• in mainstream ICI and the GCC 4.2.4 backport, the name and location of the plugin is specified by the value of the environment variable "ICI_PLUGIN"; plugin support is activated using either the "-fici" flag, or by setting the environment variable "USE_ICI" to value 1. The plugin must define at least the following parameter- and result-less functions:
  • the initialisation function "void start(void)",
  • the termination (cleanup) function "void stop(void)".
• in the GCC plugin flavour, the plugin is specified by means of the flag "-fplugin=<filepath>". Only the initialisation function "plugin_init must be defined, with the following signature: "int plugin_init(char plugin_name, int argc, plugin_arg *argv)".

For a quickstart:

• download the sources for the ICI flaviour you need/prefer (see here)
• build the compiler (the instructions assume that you have a working GCC on your platform):
  • for ICI mainline ("master" branch) and GCC plugin compatibility mode ("gcc-submission" branch), cd to the "mainline" directory and run the script "_build_all.sh" located in that directory (typically, do "./_build_all.sh"
  • for ICI gcc-4.2.4 backport, build the GCC as usual (create a build directory - preferably outside the ICI source tree, cd to that directory, configure GCC with an installation prefix to which you have write permissions, build and install); no special flags are necessary;
• cd to directory "mainline/plugins/examples/trivial"
• run "make"; this will generate the plugin file "trivial.so" in the current direcory;
• invoke the plugin-capable GCC on the "trivial.c" source file with the newly generated plugin (we assume the default installation path of new GCC as coded in the script "_build_all.sh"):

# ICI mainline - use -fici or USE_ICI=1 to enable plugins, and ICI_PLUGIN to select the plugin file
me@mymachine:trivial$  export USE_PLUGIN=./trivial.so
me@mymachine:trivial$  ../../../../install-x8664/bin/gcc -fici -I../../include -c trivial.c
... output from the plugin ...
me@mymachine:trivial$  export USE_ICI=1 ; ../../../../install-x8664/bin/gcc -I../../include -c trivial.c
... output from the plugin ...
# ICI in the GCC plugins-branch flavour: use -fplugin=
me@mymachine:trivial$  ../../../../install-x8664/bin/gcc -fplugin=./trivial.so -I../../include -c trivial.c

• • to increase plugin verbosity in ICI mainline and gcc-4.2.4 mode, set the environment variable "ICI_PLUGIN_VERBOSE" to a non-empty value:

# this feature is only available with ICI mainline (branch "master") and gcc-4.2.4 (branch "gccc-4.2.4")
me@mymachine:trivial$  ../../../../install-x8664/bin/gcc -fici -I../../include -c trivial.c
... very verbose output from the plugin ...

If you got thus far, congratulations! You have built and run your first ICI plugin(s)!