README.adoc

   1 The packnl Project
   2 ==================
   3
   4 *packnl* is a tool for "packing" a newlisp application into an
   5 executable by using the embedding feature of newlisp. Such a packed
   6 binary will have +incore.lsp+ as its embedded script, and then it is
   7 extended with the application files in a "simple archive" format. In
   8 short, the executable is a newlisp interpreter packed together with
   9 the application scripts into a single binary file.
  10
  11 The packed appplication uses the first application file as its "main
  12 script", which is loaded and executed automatically. Other application
  13 files are available for the +load+, +read-file+ and +file?+ functions.
  14
  15 Usage Examples
  16 --------------
  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
  58 A packed binary is essentially a concatenation of an embedded newlisp
  59 executable (together with its embedded script) and an archive file in
  60 "ar" format. The latter is a concatenation of the files included where
  61 each has a 2-line preamble consisting of the pathname in one line,
  62 then the content byte size as a 10-base number in ascii. Please review
  63 the Makefile which creates *packnl* as a conformant packed binary
  64 using plain *sh* commands.
  65