pkgs/development/lisp-modules-new-obsolete/doc/api.md

   1 ## The API
   2
   3 This page documents the Nix API of nix-cl.
   4
   5 ## Overview
   6
   7 The core API functions are `build-asdf-system` and
   8 `lispWithPackagesInternal`.
   9
  10 They are considered more low-level that the rest of the API, which
  11 builds on top of them to provide a more convenient interface with sane
  12 defaults.
  13
  14 The higher-level API provides a lot of pre-configured packages,
  15 including all of Quicklisp, and consists of the functions:
  16
  17 - `lispPackagesFor`
  18 - `lispWithPackages`
  19
  20 Finally, there are functions that provide pre-defined Lisps, for
  21 people who don't need to customize that:
  22
  23 - `abclPackages`, `eclPackages`, `cclPackages`, `claspPackages`, `sbclPackages`
  24 - `abclWithPackages`, `eclWithPackages`, `cclWithPackages`, `claspWithPackages`, `sbclWithPackages`
  25
  26 The following is an attempt to document all of this.
  27
  28 ## Packaging systems - `build-asdf-system`
  29
  30 Packages are declared using `build-asdf-system`. This function takes
  31 the following arguments and returns a `derivation`.
  32
  33 #### Required arguments
  34
  35 ##### `pname`
  36 Name of the package/library
  37
  38 ##### `version`
  39 Version of the package/library
  40
  41 ##### `src`
  42 Source of the package/library (`fetchzip`, `fetchgit`, `fetchhg` etc.)
  43
  44 ##### `lisp`
  45 This command must load the provided file (`$buildScript`) then exit
  46 immediately. For example, SBCL's --script flag does just that.
  47
  48 #### Optional arguments
  49
  50 ##### `patches ? []`
  51
  52 Patches to apply to the source code before compiling it. This is a
  53 list of files.
  54
  55 ##### `nativeLibs ? []`
  56
  57 Native libraries, will be appended to the library
  58 path. (`pkgs.openssl` etc.)
  59
  60 ##### `javaLibs ? []`
  61
  62 Java libraries for ABCL, will be appended to the class path.
  63
  64 ##### `lispLibs ? []`
  65
  66 Lisp dependencies These must themselves be packages built with
  67 `build-asdf-system`
  68
  69 ##### `systems ? [ pname ]`
  70
  71 Some libraries have multiple systems under one project, for example,
  72 [cffi] has `cffi-grovel`, `cffi-toolchain` etc.  By default, only the
  73 `pname` system is build.
  74
  75 `.asd's` not listed in `systems` are removed before saving the library
  76 to the Nix store. This prevents ASDF from referring to uncompiled
  77 systems on run time.
  78
  79 Also useful when the `pname` is different than the system name, such
  80 as when using [reverse domain naming]. (see `jzon` ->
  81 `com.inuoe.jzon`)
  82
  83 [cffi]: https://cffi.common-lisp.dev/
  84 [reverse domain naming]: https://en.wikipedia.org/wiki/Reverse_domain_name_notation
  85
  86 ##### `asds ? systems`
  87
  88 The .asd files that this package provides. By default, same as
  89 `systems`.
  90
  91 #### Return value
  92
  93 A `derivation` that, when built, contains the sources and pre-compiled
  94 FASL files (Lisp implementation dependent) alongside any other
  95 artifacts generated during compilation.
  96
  97 #### Example
  98
  99 [bordeaux-threads.nix] contains a simple example of packaging
 100 `alexandria` and `bordeaux-threads`.
 101
 102 [bordeaux-threads.nix]: /examples/bordeaux-threads.nix
 103
 104 ## Building a Lisp with packages: `lispWithPackagesInternal`
 105
 106 Generators of Lisps configured to be able to `asdf:load-system`
 107 pre-compiled libraries on run-time are built with
 108 `lispWithPackagesInternal`.
 109
 110 #### Required Arguments
 111
 112 ##### `clpkgs`
 113
 114 An attribute set of `derivation`s returned by `build-asdf-system`
 115
 116 #### Return value
 117
 118 `lispWithPackagesInternal` returns a function that takes one argument:
 119 a function `(lambda (clpkgs) packages)`, that, given a set of
 120 packages, returns a list of package `derivation`s to be included in
 121 the closure.
 122
 123 #### Example
 124
 125 The [sbcl-with-bt.nix] example creates a runnable Lisp where the
 126 `bordeaux-threads` defined in the previous section is precompiled and
 127 loadable via `asdf:load-system`:
 128
 129 [sbcl-with-bt.nix]: /examples/sbcl-with-bt.nix
 130
 131 ## Reusing pre-packaged Lisp libraries: `lispPackagesFor`
 132
 133 `lispPackagesFor` is a higher level version of
 134 `lispPackagesForInternal`: it only takes one argument - a Lisp command
 135 to use for compiling packages. It then provides a bunch of ready to
 136 use packages.
 137
 138 #### Required Arguments
 139
 140 ##### `lisp`
 141
 142 The Lisp command to use in calls to `build-asdf-system` while building
 143 the library-provided Lisp package declarations.
 144
 145 #### Return value
 146
 147 A set of packages built with `build-asdf-system`.
 148
 149 #### Example
 150
 151 The [abcl-package-set.nix] example generates a set of thousands of packages for ABCL.
 152
 153 [abcl-package-set.nix]: /examples/abcl-package-set.nix
 154
 155 ## Reusing pre-packaged Lisp libraries, part 2: `lispWithPackages`
 156
 157 This is simply a helper function to avoid having to call
 158 `lispPackagesFor` if all you want is a Lisp-with-packages wrapper.
 159
 160 #### Required Arguments
 161
 162 ##### `lisp`
 163
 164 The Lisp command to pass to `lispPackagesFor` in order for it to
 165 generate a package set. That set is then passed to
 166 `lispWithPackagesInternal`.
 167
 168 #### Return value
 169
 170 A Lisp-with-packages function (see sections above).
 171
 172 #### Example
 173
 174 The [abcl-with-packages.nix] example creates an `abclWithPackages` function.
 175
 176 [abcl-with-packages.nix]: /examples/abcl-with-packages.nix
 177
 178 ## Using the default Lisp implementations
 179
 180 This is the easiest way to get going with `nix-cl` in general. Choose
 181 the CL implementation of interest and a set of libraries, and get a
 182 lisp-with-packages wrapper with those libraries pre-compiled.
 183
 184 #### `abclPackages`, `eclPackages`, `cclPackages`, `claspPackages`, `sbclPackages`
 185
 186 Ready to use package sets.
 187
 188 #### `abclWithPackages`, `eclWithPackages`, `cclWithPackages`, `claspWithPackages`, `sbclWithPackages`
 189
 190 Ready to use wrapper generators.
 191
 192 #### Example
 193
 194 For example, to open a shell with SBCL + hunchentoot + sqlite in PATH:
 195 ```
 196 nix-shell -p 'with import ./. {}; sbclWithPackages (ps: [ ps.hunchentoot ps.sqlite ])'
 197 ```