bap-plugins 2.5.0 (latest)

Plugin loader.

This module handles the set of plugins, visible to the platform.

Plugins are looked at the following locations:

paths explicitly specified by a user (via library parameter);
paths specified by the BAP_PLUGIN_PATH environment variable (same syntax as PATH variable);
$prefix/lib/bap, where $prefix is the installation prefix, specified during the installation.

The latter destination is used by the bapbundle install command, so this is the default repository of plugins.

The plugin loader is an event driven system. Once, Plugins.run function is called, events of type Plugins.events will start to fire. By default they are intercepted by a logger, and by the default handler (see Plugins.run function description about the default handler). The logger will write the information about events, that is useful for debugging issues with plugins.

type event = [

| `Opening of string
(*
a bundle with a plugin is opened
*)
| `Loading of plugin
(*
a plugin loading process is started
*)
| `Linking of string
(*
a library or module is linked in
*)
| `Loaded of plugin
(*
a plugin was successfully loaded
*)
| `Errored of string * Core_kernel.Error.t
(*
failed to load a plugin
*)

]

val sexp_of_event : event -> Sexplib0.Sexp.t

val path : string

path is the default directory where plugins are stored.

val list : 
  ?env:string list ->
  ?provides:string list ->
  ?library:string list ->
  unit ->
  plugin list

list () is a list of available plugins.

Returns all plugins that provide features specified by provides and meet the constraint specified by env. If a non-valid plugin is found in the search path, then it is ignored.

parameter provides
if specified then only those plugins that provide at least one feature from the specified list are selected. Otherwise, all plugins are selected.

parameter env
is a set of features provided by the runtime (defaults to none). If specified, then all plugins that require a set of features that is a subset of env will be selected. Note, usually, plugins do not have any requirements (i.e., the have an empty set of requirements), therefore all are selected.

parameter library
is the list of additional directories in which plugins are searched. If specified then it is prepended to the default search path that contains (in that order):
- the list of paths specified by the BAP_PLUGIN_PATH environment variable;
- the Plugins.directory constant.
Note, any non-files or non-directories are silently excluded from the list.

val run : 
  ?argv:string array ->
  ?env:string list ->
  ?provides:string list ->
  ?don't_setup_handlers:bool ->
  ?library:string list ->
  ?exclude:string list ->
  unit ->
  unit

run () loads all plugins.

This command will load all plugins available in the system (see the load and list functions for more information on which plugins are available). If an error occurs during an attempt to load a plugin and if don't_setup_handlers option is not set to true, an extended error message is printed to the standard error channel and the currently running program is terminated with exit code 1.

This function calls the load function and then observes (unless don't_setup_handlers is set) events that occur during loading to intercept any errors. So see the load function for more detailed information.

parameter don't_setup_handlers
if set to true (defaults to false) then all erros are silently ignored. Don't use it unless you're implementing your own error handling facility via the event subsystem.

val load : 
  ?argv:string array ->
  ?env:string list ->
  ?provides:string list ->
  ?library:string list ->
  ?exclude:string list ->
  unit ->
  (plugin, string * Core_kernel.Error.t) Core_kernel.Result.t list

load () loads all plugins if they are not loaded yet.

Loads all plugins available in the system and returns a list of values in which each entry corresponds to a result of a loading attempt, which could be either a successfully loaded plugin or an error, in case if the attempt has failed.

The list of all plugins is list ?env ?provides ?library () which is furthermore refined by removing all plugins which names are specified in the exclude blacklist.

This function returns silently if Plugins.loaded is already decided. No matter the outcome, the Plugins.loaded future will be decided.

val events : event Bap_future.Std.stream

plugin subsystem event stream.

val loaded : unit Bap_future.Std.future

loaded occurs when all plugins are loaded

package bap-plugins