From f7ce63a2e4c452dacf688640f0810a4cfe888ed8 Mon Sep 17 00:00:00 2001 From: Ralph Ronnquist Date: Sun, 23 Apr 2023 15:32:15 +1000 Subject: [PATCH 1/1] editoral. expand and complete --- incore.lsp.8.adoc | 118 +++++++++++++++++++++++++++++++--------------- 1 file changed, 81 insertions(+), 37 deletions(-) diff --git a/incore.lsp.8.adoc b/incore.lsp.8.adoc index 90d2864..e7acf94 100644 --- a/incore.lsp.8.adoc +++ b/incore.lsp.8.adoc @@ -4,17 +4,18 @@ == NAME -incore.lsp - module for wrapping newlisp's load and read-file -functions to handle both in-core and external "ar" or "tar" archives -as local files. +incore.lsp - a newlisp module for application embedding. == SYNOPSIS -_embedding directive in Makefile_ +Use case: _normal module loading_:: + +(*load "incore.lsp"*) + +Use case: _as embedding directive in Makefile_:: -[pass] ---- -_binary_: _main.lsp_ _other.lsp*_ +_binary_: _main.lsp_ _other.lsp_* newlisp -x incore.lsp $@ chmod a+x $@ echo 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> $@ @@ -23,48 +24,91 @@ _binary_: _main.lsp_ _other.lsp*_ done >> $@ ---- +Use case: _indirectly with packnl_:: + +*packnl* *-w* _binary_ _main.lsp_ _member-option_* + + + == DESCRIPTION -*incore.lsp* is a newlisp module intended to be used for application -embedding into self-contained script collections. +*incore.lsp* is a newlisp module for application embedding into +self-contained script collections including both an in-core archive +and optionally external archives in _ar_ or _tar_ formats. + +The first use case illustrates loading the module in a running script. +When the module is loaded it installs an _archives_ hashtable and an +_archive_ context for handling an in-core archive, and then it wraps +newlisp's _load_, _read-file_ and _file?_ functions to first use the +_archives_ hashtable before looking at the external filesystem. + +The second use case shows an example of a _Makefile_ fragment that +makes an embedding with *incore.lsp* extended with an in-core archive +following the divide line of 40 "x" characters. The resulting _binary_ +will contain all the mentioned newlisp scripts ( _main.lsp_ and all +_other.lsp_) as an in-core archive appended to the embedding of +*incore.lsp*. As a result when the binary is executed the _main.lsp_ +script will be loaded and thus executed as the application script +while all _other.lsp_ scripts are availble to it for _load_ and +_read-file_. + +The third use case presents how the _packnl_ utility is used to achive +the same embedding as the second use case, though with the addition of +referring to scripts within _ar_ aor _tar_ archive files. + +=== incore.lsp API + +*core:core*:: + +This is a data reference functor that gets set up by reading +"/proc/self/exe". This is only useful for an embedded binary where it +will contain application's inc-core archive. Any other use case will +need to redefine *core:core* for its in-core archive, if any. -*incore.lsp* is the main scripting that locates application scripts -appended to the running binary and sets these up as in-core archive -files. It wraps the newlisp functions +load+, +read-file+ and +file?+ -so as to locate local files via the archives paths first. It will thus -locate any self-contained files first, before trying to find them as -external files. +(*archives* _FILENAME_ _ARCHIVE_):: -When the binary has files appended, the very first file is processed -as the application main script. +This is a hashtable mapping _FILENAME_ to containing _ARCHIVE_. The +_ARCHIVE_ argument is either a pathname for an external _ar_ or _tar_ +archive or a list of two numbers (offset and length) for an in-core +data slice. -=== newlisp API +(*archive* _ARCHIVE_):: -(*archives*):: +The _archive_ context is a namespace to for the functions implementing +archive access of files. The "default function" installs the members +of the given _ARCHIVE_ into the *archives* hashtable. -*archives* is a hashtable of known "local" files associated with -archiving details. These local files are associate with in-core access -details or with external archive pathname, which is an external -directory path, and +ar+ archive file (ending with ".a") or a +tar+ -archive file (detemined via the +file+ command). +*archive:main*:: -(*archive* _PATH_):: +This variable is assigned during module loading to identify the name +of the first in-core member. In the embedded use case this will be the +"main script" to load automatically. In that case the application will +exit after the main script has been loaded (unless it ends with _reset_ +function call). -*archive* is a context for the archive handling support functions, -including the "context function" to register archive accesible files -with the given _PATH_ as an external archive path. The given path is -processed and all content files are added to the *archives* hashtable -with the given access path. Note that the any current access -assignment will be overwritten. -+ -.Loading from known tar archive file. +(*archive:tar-able* _PATHNAME_):: + +This function uses the Unix _file_ command to recognize the given +_PATHNAME_ as naming a _tar_ file. (An _ar_ archive is recognized +simply by the _PATHNAME_ ending with ".a") + +(*archive:get-stdout* _COMMAND_):: + +This function executes the given shell _COMMAND_ and captures its +standard output into a newlisp binary data block. + +(*archive:get* _PATH_ _FILENAME_):: + +This function reads the _FILENAME_ from the _PATH_, which is a +directory, and _ar_ file or a _tar_ file. + +== EXAMPLE + +Note that *incore.lsp* is the embedding used by _packnl_. + +.Loading a file from an imagined compressed tar file. ==== ----- -(archive "/usr/share/myapp/utilities-version-2.5.tgz") +(archive "/usr/share/myapp/utilities-version-2.5.tgz") + (load "framework.lsp") ----- -This example illustrates how to make the files of a tar archive file -available for loading as if local files. ==== == SEE ALSO -- 2.39.2