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 reading
  63 "/proc/self/exe". This is only useful for an embedded binary where it
  64 will contain application's inc-core archive. Any other use case will
  65 need to redefine *core:core* for its in-core archive, if any.
  66
  67 (*archives* _FILENAME_ _ARCHIVE_)::
  68
  69 This is a hashtable mapping _FILENAME_ to containing _ARCHIVE_. The
  70 _ARCHIVE_ argument is either a pathname for an external _ar_ or _tar_
  71 archive or a list of two numbers (offset and length) for an in-core
  72 data slice.
  73
  74 (*archive* _ARCHIVE_)::
  75
  76 The _archive_ context is a namespace to for the functions implementing
  77 archive access of files. The "default function" installs the members
  78 of the given _ARCHIVE_ into the *archives* hashtable.
  79
  80 *archive:main*::
  81
  82 This variable is assigned during module loading to identify the name
  83 of the first in-core member. In the embedded use case this will be the
  84 "main script" to load automatically. In that case the application will
  85 exit after the main script has been loaded (unless it ends with _reset_
  86 function call).
  87
  88 (*archive:tar-able* _PATHNAME_)::
  89
  90 This function uses the Unix _file_ command to recognize the given
  91 _PATHNAME_ as naming a _tar_ file. (An _ar_ archive is recognized
  92 simply by the _PATHNAME_ ending with ".a")
  93
  94 (*archive:get-stdout* _COMMAND_)::
  95
  96 This function executes the given shell _COMMAND_ and captures its
  97 standard output into a newlisp binary data block.
  98
  99 (*archive:get* _PATH_ _FILENAME_)::
 100
 101 This function reads the _FILENAME_ from the _PATH_, which is a
 102 directory, and _ar_ file or a _tar_ file.
 103
 104 == EXAMPLE
 105
 106 Note that *incore.lsp* is the embedding used by _packnl_.
 107
 108 .Loading a file from an imagined compressed tar file.
 109 ====
 110 (archive "/usr/share/myapp/utilities-version-2.5.tgz") +
 111 (load "framework.lsp")
 112 ====
 113
 114 == SEE ALSO
 115
 116 *newlisp*, *ar*, *tar*, *packnl*
 117
 118 == AUTHOR
 119
 120 Ralph Ronnquist <ralph.ronnwuidt@gmail.com>