incore.lsp.8.adoc

   1 = incore.lsp(8)
   2 :doctype: manpage
   3 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
   4
   5 == NAME
   6
   7 incore.lsp - a newlisp module for application embedding.
   8
   9 == SYNOPSIS
  10
  11 Use case: _normal module loading_::
  12
  13 (*load "incore.lsp"*)
  14
  15 Use case: _as embedding directive in Makefile_::
  16
  17 ----
  18 _binary_: _main.lsp_ _other.lsp_*
  19         newlisp -x incore.lsp $@
  20         chmod a+x $@
  21         echo 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> $@
  22         for F in $^ ; do \
  23             echo "$$F\n$$(stat -c %s $$F)" ; cat $$F ; \
  24         done >> $@
  25 ----
  26
  27 Use case: _indirectly with packnl_::
  28
  29 *packnl* *-w* _binary_ _main.lsp_ _member-option_* +
  30
  31
  32 == DESCRIPTION
  33
  34 *incore.lsp* is a newlisp module for application embedding into
  35 self-contained script collections including both an in-core archive
  36 and optionally external archives in _ar_ or _tar_ formats.
  37
  38 The first use case illustrates loading the module in a running script.
  39 When the module is loaded it installs an _archives_ hashtable and an
  40 _archive_ context for handling an in-core archive, and then it wraps
  41 newlisp's _load_, _read-file_ and _file?_ functions to first use the
  42 _archives_ hashtable before looking at the external filesystem.
  43
  44 The second use case shows an example of a _Makefile_ fragment that
  45 makes an embedding with *incore.lsp* extended with an in-core archive
  46 following the divide line of 40 "x" characters. The resulting _binary_
  47 will contain all the mentioned newlisp scripts ( _main.lsp_ and all
  48 _other.lsp_) as an in-core archive appended to the embedding of
  49 *incore.lsp*. As a result when the binary is executed the _main.lsp_
  50 script will be loaded and thus executed as the application script
  51 while all _other.lsp_ scripts are availble to it for _load_ and
  52 _read-file_.
  53
  54 The third use case presents how the _packnl_ utility is used to achive
  55 the same embedding as the second use case, though with the addition of
  56 referring to scripts within _ar_ aor _tar_ archive files.
  57
  58 === incore.lsp API
  59
  60 *core:core*::
  61
  62 This is a data reference functor that gets set up by re-reading the
  63 executable as data block. This is only useful for an embedded binary
  64 where it will contain application's in-core archive. Any other use
  65 case will need to redefine *core:core* for its in-core archive
  66 if any.
  67
  68 (*archives* _FILENAME_ _ARCHIVE_)::
  69
  70 This is a hashtable mapping _FILENAME_ to containing _ARCHIVE_. The
  71 _ARCHIVE_ argument is either a pathname for an external _ar_ or _tar_
  72 archive or a list of two numbers (offset and length) for an in-core
  73 data slice.
  74
  75 (*archive* _ARCHIVE_)::
  76
  77 The _archive_ context is a namespace to for the functions implementing
  78 archive access of files. The "default function" installs the members
  79 of the given _ARCHIVE_ into the *archives* hashtable.
  80
  81 *archive:main*::
  82
  83 This variable is assigned during module loading to identify the name
  84 of the first in-core member. In the embedded use case this will be the
  85 "main script" to load automatically. In that case the application will
  86 exit after the main script has been loaded (unless it ends with _reset_
  87 function call).
  88
  89 (*archive:tar-able* _PATHNAME_)::
  90
  91 This function uses the Unix _file_ command to recognize the given
  92 _PATHNAME_ as naming a _tar_ file. (An _ar_ archive is recognized
  93 simply by the _PATHNAME_ ending with ".a")
  94
  95 (*archive:get-stdout* _COMMAND_)::
  96
  97 This function executes the given shell _COMMAND_ and captures its
  98 standard output into a newlisp binary data block.
  99
 100 (*archive:get* _PATH_ _FILENAME_)::
 101
 102 This function reads the _FILENAME_ from the _PATH_, which is a
 103 directory, and _ar_ file or a _tar_ file.
 104
 105 == EXAMPLE
 106
 107 Note that *incore.lsp* is the embedding used by _packnl_.
 108
 109 .Loading a file from an imagined compressed tar file.
 110 ====
 111 (archive "/usr/share/myapp/utilities-version-2.5.tgz") +
 112 (load "framework.lsp")
 113 ====
 114
 115 == SEE ALSO
 116
 117 *newlisp*, *ar*, *tar*, *packnl*
 118
 119 == AUTHOR
 120
 121 Ralph Ronnquist <ralph.ronnwuidt@gmail.com>