README.adoc

   1 = The packnl Project
   2 :author: Ralph Ronnquist
   3 :revdate: Sun, 30 Apr 2023 23:56:02 +1000
   4
   5 *packnl* is a tool for "packing" a newlisp application into an
   6 executable by using the embedding feature of newlisp. Such a packed
   7 binary will have +incore.lsp+ as its embedded script, and then it is
   8 extended with the application files in a "simple archive" format. In
   9 short, the executable is a newlisp interpreter packed together with
  10 the application scripts into a single binary file.
  11
  12 The packed appplication uses the first application file as its "main
  13 script", which is loaded and executed automatically. Other application
  14 files are available for the +load+, +read-file+ and +file?+ functions.
  15
  16 == Usage Examples
  17
  18 .Writing a packed binary
  19 ====
  20 ----
  21     packnl -w binary ( file | -a name | -A name | -C path )*
  22 ----
  23 This commandline form is used for preparing a binary with the given
  24 files. The nominated files will be appended to the binary in the given
  25 order.
  26
  27 * The *-a* option is used for registering the members of an +ar+ style
  28 archive to subseqently be selectively nominated for inclusion into the
  29 binary.
  30
  31 * The *-A* option is used for including all members of an +ar+ style
  32 archive.
  33
  34 * The *-C* option is used for changing (input) directory as given.
  35 ====
  36
  37 .Listing a packed binary
  38 ====
  39 ----
  40     packnl -t binary
  41 ----
  42 This commandline form is used for reviewing a packed binary as a list
  43 of its included members.
  44 ====
  45
  46 .Unpack a packed binary
  47 ====
  48 ----
  49     packnl -u binary directory
  50 ----
  51 This commandline form is used for unpacking a packed binary into a
  52 given target directory.
  53 ====
  54
  55 == Packed Binary Format
  56
  57 A packed binary is essentially a concatenation of an embedded newlisp
  58 executable (together with its embedded script) and an archive file in
  59 "ar" format. The latter is a concatenation of the files included where
  60 each has a 2-line preamble consisting of the pathname in one line,
  61 then the content byte size as a 10-base number in ascii. Please review
  62 the Makefile which creates *packnl* as a conformant packed binary
  63 using plain *sh* commands.
  64