1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
|
-- | External plugins
--
-- GHC supports two kinds of "static" plugins:
-- 1. internal: setup with GHC-API
-- 2. external: setup as explained below and loaded from shared libraries
--
-- The intended use case for external static plugins is with cross compilers: at
-- the time of writing, GHC is mono-target and a GHC cross-compiler (i.e. when
-- host /= target) can't build nor load plugins for the host using the
-- "non-static" plugin approach. Fixing this is tracked in #14335. If you're not
-- using a cross-compiler, you'd better use non-static plugins which are easier
-- to build and and safer to use (see below).
--
-- External static plugins can be configured via the command-line with
-- the -fplugin-library flag. Syntax is:
--
-- -fplugin-library=⟨file-path⟩;⟨unit-id⟩;⟨module⟩;⟨args⟩
--
-- Example:
-- -fplugin-library=path/to/plugin;package-123;Plugin.Module;["Argument","List"]
--
-- Building the plugin library:
-- 1. link with the libraries used to build the compiler you target. If you
-- target a cross-compiler (stage2), you can't directly use it to build the
-- plugin library. Use the stage1 compiler instead.
--
-- 2. if you use cabal to build the library, its unit-id will be set by cabal
-- and will contain a hash (e.g. "my-plugin-unit-1345656546ABCDEF"). To force
-- the unit id, use GHC's `-this-unit-id` command line flag:
-- e.g. -this-unit-id my-plugin-unit
-- You can set this in the .cabal file of your library with the following
-- stanza: `ghc-options: -this-unit-id my-plugin-unit`
--
-- 3. To make your plugin easier to distribute, you may want to link it
-- statically with all its dependencies. You would need to use `-shared`
-- without `-dynamic` when building your library.
--
-- However, all the static dependencies have to be built with `-fPIC` and it's
-- not done by default. See
-- https://www.hobson.space/posts/haskell-foreign-library/ for a way to modify
-- the compiler to do it.
--
-- In any case, don't link your plugin library statically with the RTS (e.g.
-- use `-fno-link-rts`) as there are some global variables in the RTS that must
-- be shared between the plugin and the compiler.
--
-- With external static plugins we don't check the type of the `plugin` closure
-- we look up. If it's not a valid `Plugin` value, it will probably crash badly.
--
module GHC.Driver.Plugins.External
( ExternalPluginSpec (..)
, parseExternalPluginSpec
)
where
import GHC.Prelude
import Text.Read
-- | External plugin spec
data ExternalPluginSpec = ExternalPluginSpec
{ esp_lib :: !FilePath
, esp_unit_id :: !String
, esp_module :: !String
, esp_args :: ![String]
}
-- | Parser external static plugin specification from command-line flag
parseExternalPluginSpec :: String -> Maybe ExternalPluginSpec
parseExternalPluginSpec optflag =
case break (== ';') optflag of
(libPath, _:rest) -> case break (== ';') rest of
(libName, _:pack) -> case break (== ';') pack of
(modName, _:args) -> case readMaybe args of
Just as -> Just (ExternalPluginSpec libPath libName modName as)
Nothing -> Nothing
_ -> Nothing
_ -> Nothing
_ -> Nothing
|
