▼Xiden:   API Reference
►18 Plugins
On this page:
load-from-plugin
plugin-ref
18.1 Supported Bindings
catalog
string->source
get-extract-procedure
before-new-package
8.0
  top  ← prev  up  next → 

18 Plugins

 (require xiden/plugin) package: xiden

A plugin is a Racket module defined by a user. Plugins extend Xiden where it would otherwise have limited behavior. A plugin runs directly in Xiden’s runtime, with the same level of privilege as the OS-level user. This means that a plugin may freely reconfigure Xiden, if not outright harm a system.

procedure

(load-from-plugin key    
  fail-thunk    
  on-load-failure) → any
  key : symbol?
  fail-thunk : (-> any)
  on-load-failure : (-> exn:fail? any)
Evaluates as (dynamic-require (XIDEN_PLUGIN_MODULE) key fail-thunk).

If (XIDEN_PLUGIN_MODULE) fails to load, load-from-plugin returns the result of on-load-failure applied to the relevant exception.

procedure

(plugin-ref key default-value) → any/c

  key : symbol?
  default-value : any/c
Equivalent to (load-from-plugin key (const default-value) (const default-value)).

18.1 Supported Bindings

Xiden applies load-from-plugin internally to get references to user-defined extensions. The bindings defined below are not provided by Xiden, but are instead provided by a plugin to support the written behavior.

value

catalog : catalog?

A catalog used to resolve package queries.

Defaults to default-catalog.

procedure

(string->source user-string) → source?

  user-string : string?
Converts a string to a source.

When a user uses a plain string where a source is expected, then Xiden uses coerce-source to convert it to a source. By defining this, you control how strings map to byte sources.

Defaults to

(define (string->source s)
  (first-available-source
   (list (file-source s) (http-source s))
   null))

procedure

(get-extract-procedure path) → (-> input-port? void?)

  path : path-string?
Return a procedure used to extract files from the archive located at path, or #f if no such procedure is available.

Used by xiden/archive when it cannot extract files from path on its own.

procedure

(before-new-package original) → bare-racket-module?

  original : bare-racket-module?
A hook for returning a bare package definition to use for creating a package. original represents a package definition fetched from a source.

This procedure defaults to the identity function, which means no code is replaced. Otherwise, you may return an alternative definition to override original.

This procedure is useful for standardizing definitions, or for analyzing builds in a workspace. Define with care. This procedure can override every package definition, which can render a Xiden process inoperable or unsafe.

Take for example a function that returns the same static package definition, which has one dependency.

(define (before-new-package original)
  (struct-copy bare-racket-module original
               [code
                 '((input "pkgdef" (sources "https://example.com/other.rkt"))
                   (output "default"
                           pkgdef-input := (input-ref "pkgdef")
                           pkgdef-path := (resolve-input "pkgdef")
                           (install #f #f pkgdef-path)))]))

This creates builds that will not terminate. Even if Xiden downloads a new package definition from "https://example.com/other.rkt", it will only be replaced by another instance of the same data returned from before-new-package.

  top  ← prev  up  next →