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