= incore.lsp(8)
:doctype: manpage
:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}

== 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.

== SYNOPSIS

_embedding directive in Makefile_

[pass]
----
_binary_: _main.lsp_ _other.lsp*_
	newlisp -x incore.lsp $@
	chmod a+x $@
	echo 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> $@
	for F in $^ ; do \
	    echo "$$F\n$$(stat -c %s $$F)" ; cat $$F ; \
	done >> $@
----

== DESCRIPTION

*incore.lsp* is a newlisp module intended to be used for application
embedding into self-contained script collections.

*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.

When the binary has files appended, the very first file is processed
as the application main script.

=== newlisp API

(*archives*)::

*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* _PATH_)::

*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 "/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

*newlisp*, *ar*, *tar*, *packnl*

== AUTHOR

Ralph Ronnquist <ralph.ronnwuidt@gmail.com>