GNU Compiler Collection (GCC) Internals: Plugins building

Previous: Plugins tracking, Up: Plugins [Contents][Index]

### 24.10 Building GCC plugins

If plugins are enabled, GCC installs the headers needed to build a plugin (somewhere in the installation tree, e.g. under `/usr/local`). In particular a `plugin/include` directory is installed, containing all the header files needed to build plugins.

On most systems, you can query this `plugin` directory by invoking `gcc -print-file-name=plugin` (replace if needed `gcc` with the appropriate program path).

Inside plugins, this `plugin` directory name can be queried by calling `default_plugin_dir_name ()`.

Plugins may know, when they are compiled, the GCC version for which `plugin-version.h` is provided. The constant macros `GCCPLUGIN_VERSION_MAJOR`, `GCCPLUGIN_VERSION_MINOR`, `GCCPLUGIN_VERSION_PATCHLEVEL`, `GCCPLUGIN_VERSION` are integer numbers, so a plugin could ensure it is built for GCC 4.7 with

    #if GCCPLUGIN_VERSION != 4007
    #error this GCC plugin is for GCC 4.7
    #endif

The following GNU Makefile excerpt shows how to build a simple plugin:

    HOST_GCC=g++
    TARGET_GCC=gcc
    PLUGIN_SOURCE_FILES= plugin1.c plugin2.cc
    GCCPLUGINS_DIR:= $(shell $(TARGET_GCC) -print-file-name=plugin)
    CXXFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -fno-rtti -O2

    plugin.so: $(PLUGIN_SOURCE_FILES)
       $(HOST_GCC) -shared $(CXXFLAGS) $^ -o $@

A single source file plugin may be built with `g++ -I`gcc -print-file-name=plugin`/include -fPIC -shared -fno-rtti -O2 plugin.cc -o plugin.so`, using backquote shell syntax to query the `plugin` directory.

Plugin support on Windows/MinGW has a number of limitations and additional requirements. When building a plugin on Windows we have to link an import library for the corresponding backend executable, for example, `cc1.exe`, `cc1plus.exe`, etc., in order to gain access to the symbols provided by GCC. This means that on Windows a plugin is language-specific, for example, for C, C++, etc. If you wish to use your plugin with multiple languages, then you will need to build multiple plugin libraries and either instruct your users on how to load the correct version or provide a compiler wrapper that does this automatically.

Additionally, on Windows the plugin library has to export the `plugin_is_GPL_compatible` and `plugin_init` symbols. If you do not wish to modify the source code of your plugin, then you can use the `-Wl,--export-all-symbols` option or provide a suitable DEF file. Alternatively, you can export just these two symbols by decorating them with `__declspec(dllexport)`, for example:

    #ifdef _WIN32
    __declspec(dllexport)
    #endif
    int plugin_is_GPL_compatible;

    #ifdef _WIN32
    __declspec(dllexport)
    #endif
    int plugin_init (plugin_name_args *, plugin_gcc_version *)

The import libraries are installed into the `plugin` directory and their names are derived by appending the `.a` extension to the backend executable names, for example, `cc1.exe.a`, `cc1plus.exe.a`, etc. The following command line shows how to build the single source file plugin on Windows to be used with the C++ compiler:

    g++ -I`gcc -print-file-name=plugin`/include -shared -Wl,--export-all-symbols \
    -o plugin.dll plugin.cc `gcc -print-file-name=plugin`/cc1plus.exe.a

When a plugin needs to use `gengtype`, be sure that both `gengtype` and `gtype.state` have the same version as the GCC for which the plugin is built.

Previous: Plugins tracking, Up: Plugins [Contents][Index]