Remote Lisp images
==================

API reference
-------------

Remote Lisp images
~~~~~~~~~~~~~~~~~~

Function: ``EVAL-IN-GRANDCHILD``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(eval-in-grandchild prerequest request)``

Evaluate PREREQUEST and REQUEST, both readably printable Lisp forms, in a
grandchild process.  PREREQUEST and REQUEST must be evaluable using only
definitions established statically by your consfig, or in one of the ASDF
systems upon which your consfig depends.  Returns the stdout, stderr and exit
code of that process.

PREREQUEST will be evaluated before the grandchild calls fork(2) to establish
its own infrastructure for subsequent uses of this macro, and REQUEST after.
Thus, PREREQUEST must not start up any threads.

Simple error: ``WRONG-EXECUTION-CONTEXT-FOR-IMAGE-DUMP``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(wrong-execution-context-for-image-dump)``

Function: ``EVAL-IN-REINVOKED``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(eval-in-reinvoked prerequest request)``

In a grandchild process, evaluate PREREQUEST, dump an executable image, and
immediately reinvoke that image to evaluate REQUEST.  PREREQUEST and REQUEST
must be evaluable using only definitions established statically by your
consfig, or in one of the ASDF systems upon which your consfig depends.
Returns the stdout, stderr and exit code of that process.

Property: ``IMAGE-DUMPED``
^^^^^^^^^^^^^^^^^^^^^^^^^^

``(image-dumped &optional filename form always)``

Dump an executable image to FILENAME which will evaluate FORM, which must be
evaluable using only definitions established statically by your consfig, or in
one of the ASDF systems upon which your consfig depends.

If FILENAME is nil then use ~/.cache/consfigurator/images/latest, and if FORM
is nil then use one which will execute the current deployment.  Unless ALWAYS,
skip dumping an executable image when we can detect that the deployment is
already running from FILENAME.

When the Lisp implementation is SBCL, applying this property will fail unless
the same build of SBCL that's running is accessible via the filesystem.  A
common situation in which this problem arises is when Consfigurator has forked
into a chroot: unless the chroot has exactly the same operating system release
as the parent host and SBCL has already been installed within the chroot, the
requisite build of SBCL won't be accessible via the filesystem.

Similarly, the dumped image will not be reinvokable if any of the shared
libraries currently open are not accessible via the filesystem, which will
usually be the case after forking into a chroot.  See "Dumping and reinvoking
Lisp" in the "Pitfalls and limitations" section of the Consfigurator
manual.

In these situations you might like to quietly skip dumping an image.  For
example, if you're preparing a disk image, successfully dumping an image is
probably not needed for the image to be bootable.  After installing the disk
image and starting up the target machine, you can connect to it directly and
DEPLOY/HOSTDEPLOY all its properties again, at which point the image dump can
succeed.

To support this, when the current connection is a FORK-CONNECTION, and either
the Lisp implementation is SBCL and the same build of SBCL is not found to be
accessible via the filesytem, or some of the shared libraries currently open
are not accessible at their original paths, this property signals
WRONG-EXECUTION-CONTEXT-FOR-IMAGE-DUMP.  You can then quietly skip over this
property by applying it like this:

.. code-block:: none

  (eseqprops-until 'wrong-execution-context-for-image-dump
   (image-dumped)
   ;; ... properties depending on a successful image dump ...
   )

Function: ``ASDF-REQUIREMENTS-FOR-HOST-AND-FEATURES``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(asdf-requirements-for-host-and-features remote-lisp-features)``

Make an instance of ASDF-REQUIREMENTS for starting up a remote Lisp image in
which *FEATURES* has the value of REMOTE-LISP-FEATURES, based on the Lisp
systems required by the host currently being deployed.

Called by connection types which start up remote Lisp images.

Generic function: ``REQUEST-ASDF-REQUIREMENTS``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(request-asdf-requirements asdf-requirements)``

Request that all Lisp systems required to fulfill ASDF-REQUIREMENTS be
uploaded to the remote cache of the currently established connection.

Called by connection types which start up remote Lisp images.

Generic function: ``CONTINUE-DEPLOY*-PROGRAM``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(continue-deploy*-program remaining-connections asdf-requirements)``

Return a program to complete the work of an enclosing call to DEPLOY*.

Implementations of ESTABLISH-CONNECTION which start up remote Lisp images call
this function, instead of CONTINUE-DEPLOY*, and use the result to instruct the
newly started image.

Will query the remote cache for paths to Lisp systems, so a connection to the
host which will run the Lisp image must already be established.

The program returned is a single string consisting of a number of sexps
separated by newlines.  Each sexp must be evaluated by the remote Lisp image
before the following sexp is offered to its reader, on standard input.
