Add support for external static plugins (#20964)

This patch adds a new command-line flag:

  -fplugin-library=<file-path>;<unit-id>;<module>;<args>

used like this:

  -fplugin-library=path/to/plugin.so;package-123;Plugin.Module;["Argument","List"]

It allows a plugin to be loaded directly from a shared library. With
this approach, GHC doesn't compile anything for the plugin and doesn't
load any .hi file for the plugin and its dependencies. As such GHC
doesn't need to support two environments (one for plugins, one for
target code), which was the more ambitious approach tracked in #14335.

Fix #20964

Co-authored-by: Josh Meredith <joshmeredith2008@gmail.com>

1 files changed, 13 insertions, 1 deletions

diff --git a/docs/users_guide/extending_ghc.rst b/docs/users_guide/extending_ghc.rst
index acc8791fb0..3f8a4a5000 100644
--- a/docs/users_guide/extending_ghc.rst
+++ b/docs/users_guide/extending_ghc.rst
@@ -268,7 +268,6 @@ option. The list of enabled plugins can be reset with the
     the command line is not possible. Instead ``:set -fclear-plugins`` can be
     used.
 
-
 As an example, in order to load the plugin exported by ``Foo.Plugin`` in
 the package ``foo-ghc-plugin``, and give it the parameter "baz", we
 would invoke GHC like this:
@@ -286,6 +285,19 @@ would invoke GHC like this:
     Linking Test ...
     $
 
+
+Plugins can be also be loaded from libraries directly. It allows plugins to be
+loaded in cross-compilers (as a workaround for #14335).
+
+.. ghc-flag:: -fplugin-library=⟨file-path⟩;⟨unit-id⟩;⟨module⟩;⟨args⟩
+    :shortdesc: Load a pre-compiled static plugin from an external library
+    :type: dynamic
+    :category: plugins
+
+    Arguments are specified in a list form, so a plugin specified to
+    :ghc-flag:`-fplugin-library=⟨file-path⟩;⟨unit-id⟩;⟨module⟩;⟨args⟩` will look
+    like ``'path/to/plugin;package-123;Plugin.Module;["Argument","List"]'``.
+
 Alternatively, core plugins can be specified with Template Haskell.
 
 ::