gccint: Plugins building

1 
1 24.10 Building GCC plugins
1 ==========================
1 
1 If plugins are enabled, GCC installs the headers needed to build a
1 plugin (somewhere in the installation tree, e.g.  under '/usr/local').
1 In particular a 'plugin/include' directory is installed, containing all
1 the header files needed to build plugins.
1 
1  On most systems, you can query this 'plugin' directory by invoking 'gcc
1 -print-file-name=plugin' (replace if needed 'gcc' with the appropriate
1 program path).
1 
1  Inside plugins, this 'plugin' directory name can be queried by calling
1 'default_plugin_dir_name ()'.
1 
1  Plugins may know, when they are compiled, the GCC version for which
1 'plugin-version.h' is provided.  The constant macros
1 'GCCPLUGIN_VERSION_MAJOR', 'GCCPLUGIN_VERSION_MINOR',
1 'GCCPLUGIN_VERSION_PATCHLEVEL', 'GCCPLUGIN_VERSION' are integer numbers,
1 so a plugin could ensure it is built for GCC 4.7 with
1      #if GCCPLUGIN_VERSION != 4007
1      #error this GCC plugin is for GCC 4.7
1      #endif
1 
1  The following GNU Makefile excerpt shows how to build a simple plugin:
1 
1      HOST_GCC=g++
1      TARGET_GCC=gcc
1      PLUGIN_SOURCE_FILES= plugin1.c plugin2.cc
1      GCCPLUGINS_DIR:= $(shell $(TARGET_GCC) -print-file-name=plugin)
1      CXXFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -fno-rtti -O2
1 
1      plugin.so: $(PLUGIN_SOURCE_FILES)
1         $(HOST_GCC) -shared $(CXXFLAGS) $^ -o $@
1 
1  A single source file plugin may be built with 'g++ -I`gcc
1 -print-file-name=plugin`/include -fPIC -shared -fno-rtti -O2 plugin.c -o
1 plugin.so', using backquote shell syntax to query the 'plugin'
1 directory.
1 
1  Plugin support on Windows/MinGW has a number of limitations and
1 additional requirements.  When building a plugin on Windows we have to
1 link an import library for the corresponding backend executable, for
1 example, 'cc1.exe', 'cc1plus.exe', etc., in order to gain access to the
1 symbols provided by GCC. This means that on Windows a plugin is
1 language-specific, for example, for C, C++, etc.  If you wish to use
1 your plugin with multiple languages, then you will need to build
1 multiple plugin libraries and either instruct your users on how to load
1 the correct version or provide a compiler wrapper that does this
1 automatically.
1 
1  Additionally, on Windows the plugin library has to export the
1 'plugin_is_GPL_compatible' and 'plugin_init' symbols.  If you do not
1 wish to modify the source code of your plugin, then you can use the
1 '-Wl,--export-all-symbols' option or provide a suitable DEF file.
1 Alternatively, you can export just these two symbols by decorating them
1 with '__declspec(dllexport)', for example:
1 
1      #ifdef _WIN32
1      __declspec(dllexport)
1      #endif
1      int plugin_is_GPL_compatible;
1 
1      #ifdef _WIN32
1      __declspec(dllexport)
1      #endif
1      int plugin_init (plugin_name_args *, plugin_gcc_version *)
1 
1  The import libraries are installed into the 'plugin' directory and
1 their names are derived by appending the '.a' extension to the backend
1 executable names, for example, 'cc1.exe.a', 'cc1plus.exe.a', etc.  The
1 following command line shows how to build the single source file plugin
1 on Windows to be used with the C++ compiler:
1 
1      g++ -I`gcc -print-file-name=plugin`/include -shared -Wl,--export-all-symbols \
1      -o plugin.dll plugin.c `gcc -print-file-name=plugin`/cc1plus.exe.a
1 
1  When a plugin needs to use 'gengtype', be sure that both 'gengtype' and
1 'gtype.state' have the same version as the GCC for which the plugin is
1 built.
1