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

== NAME

incore.lsp - a newlisp module for application embedding.

== SYNOPSIS

Use case: _normal module loading_::

(*load "incore.lsp"*)

Use case: _as embedding directive in Makefile_::

----
_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 >> $@
----

Use case: _indirectly with packnl_::

*packnl* *-w* _binary_ _main.lsp_ _member-option_* +


== DESCRIPTION

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

(*archives* _FILENAME_ _ARCHIVE_)::

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.

(*archive* _ARCHIVE_)::

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.

*archive:main*::

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: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") +
(load "framework.lsp")
====

== SEE ALSO

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

== AUTHOR

Ralph Ronnquist <ralph.ronnwuidt@gmail.com>