From 8c7dbea9f193ae21d193453d7a9eb6d2089618d6 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Sun, 26 Nov 2017 13:00:48 +0000 Subject: Plugin support on Windows/MinGW config/ChangeLog: 2017-11-14 Boris Kolpackov * gcc-plugin.m4: Add support for MinGW. gcc/ChangeLog: 2017-11-14 Boris Kolpackov * plugin.c (add_new_plugin): Use platform-specific library extensions. (try_init_one_plugin): Alternative implementation for MinGW. * Makefile.in (plugin_implib): New. (gengtype-lex.c): Fix broken AIX workaround. * configure: Regenerate. * doc/plugins.texi: Document support for MinGW. gcc/c/ChangeLog: 2017-11-14 Boris Kolpackov * Make-lang.in (c.install-plugin): Install backend import library. gcc/cp/ChangeLog: 2017-11-14 Boris Kolpackov * Make-lang.in (c++.install-plugin): Install backend import library. libcc1/ChangeLog: 2017-11-14 Boris Kolpackov * configure: Regenerate. From-SVN: r255154 --- gcc/doc/plugins.texi | 55 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 50 insertions(+), 5 deletions(-) (limited to 'gcc/doc/plugins.texi') diff --git a/gcc/doc/plugins.texi b/gcc/doc/plugins.texi index 6fc7b9a..dc3fa21 100644 --- a/gcc/doc/plugins.texi +++ b/gcc/doc/plugins.texi @@ -34,14 +34,17 @@ can be quite useful. @section Loading Plugins Plugins are supported on platforms that support @option{-ldl --rdynamic}. They are loaded by the compiler using @code{dlopen} -and invoked at pre-determined locations in the compilation -process. +-rdynamic} as well as Windows/MinGW. They are loaded by the compiler +using @code{dlopen} or equivalent and invoked at pre-determined +locations in the compilation process. Plugins are loaded with -@option{-fplugin=/path/to/@var{name}.so} @option{-fplugin-arg-@var{name}-@var{key1}[=@var{value1}]} +@option{-fplugin=/path/to/@var{name}.@var{ext}} @option{-fplugin-arg-@var{name}-@var{key1}[=@var{value1}]} +Where @var{name} is the plugin name and @var{ext} is the platform-specific +dynamic library extension. It should be @code{dll} on Windows/MinGW, +@code{dylib} on Darwin/Mac OS X, and @code{so} on all other platforms. The plugin arguments are parsed by GCC and passed to respective plugins as key-value pairs. Multiple plugins can be invoked by specifying multiple @option{-fplugin} arguments. @@ -49,7 +52,7 @@ specifying multiple @option{-fplugin} arguments. A plugin can be simply given by its short name (no dots or slashes). When simply passing @option{-fplugin=@var{name}}, the plugin is loaded from the @file{plugin} directory, so @option{-fplugin=@var{name}} is -the same as @option{-fplugin=`gcc -print-file-name=plugin`/@var{name}.so}, +the same as @option{-fplugin=`gcc -print-file-name=plugin`/@var{name}.@var{ext}}, using backquote shell syntax to query the @file{plugin} directory. @node Plugin API @@ -508,6 +511,48 @@ A single source file plugin may be built with @code{g++ -I`gcc plugin.so}, using backquote shell syntax to query the @file{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, @file{cc1.exe}, @file{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 +@code{plugin_is_GPL_compatible} and @code{plugin_init} symbols. If you +do not wish to modify the source code of your plugin, then you can use +the @option{-Wl,--export-all-symbols} option or provide a suitable DEF +file. Alternatively, you can export just these two symbols by decorating +them with @code{__declspec(dllexport)}, for example: + +@smallexample +#ifdef _WIN32 +__declspec(dllexport) +#endif +int plugin_is_GPL_compatible; + +#ifdef _WIN32 +__declspec(dllexport) +#endif +int plugin_init (plugin_name_args *, plugin_gcc_version *) +@end smallexample + +The import libraries are installed into the @code{plugin} directory +and their names are derived by appending the @code{.a} extension to +the backend executable names, for example, @file{cc1.exe.a}, +@file{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: + +@smallexample +g++ -I`gcc -print-file-name=plugin`/include -shared -Wl,--export-all-symbols \ +-o plugin.dll plugin.c `gcc -print-file-name=plugin`/cc1plus.exe.a +@end smallexample + When a plugin needs to use @command{gengtype}, be sure that both @file{gengtype} and @file{gtype.state} have the same version as the GCC for which the plugin is built. -- cgit v1.1