content: -- | 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
  