Deployments
===========

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

Deployments
~~~~~~~~~~~

Function: ``AT-END``
^^^^^^^^^^^^^^^^^^^^

``(at-end function)``

Request that FUNCTION be called at the end of the current (sub)deployment.
Called by property :APPLY and :UNAPPLY subroutines.  FUNCTION will be passed a
single argument representing whether or not the deployment made a change.

Properties which call this are responsible for ensuring that the I/O performed
by FUNCTION is compatible with the connection type.  This amounts to the
following requirement: if FUNCTION performs I/O beyond what :POSIX property
:APPLY subroutines are permitted to perform, the property calling AT-END to
register FUNCTION must be declared to be a :LISP property.

Function: ``CONSFIGURE``
^^^^^^^^^^^^^^^^^^^^^^^^

``(consfigure propspec-expression &key collect-at-end)``

Immediately preprocess and apply PROPSPEC-EXPRESSION in the context of the
current target host and connection.  This function is provided for use by
specialised property combinators.  It should not be used in property
definitions nor in consfigs (except via the UNAPPLY macro).

The :HOSTATTRS subroutines of properties applied by PROPSPEC-EXPRESSION will
be executed, but any new hostattrs they push will be discarded.  Thus either
PROPSPEC-EXPRESSION should not apply any properties whose :HOSTATTRS
subroutines push new hostattrs, or the caller should seperately arrange for
those subroutines to be executed in a context in which newly pushed hostattrs
will not be discarded.

Function: ``DEPLOY*``
^^^^^^^^^^^^^^^^^^^^^

``(deploy* connections host &optional additional-properties)``

Execute the deployment which is defined by the pair (CONNECTIONS . HOST),
except possibly with the property application specification
ADDITIONAL-PROPERTIES also applied to HOST.

This is the entry point to Consfigurator's primary loop.  Typically users use
DEPLOY, DEPLOY-THESE, and the function definitions established by DEFDEPLOY,
DEFDEPLOY-THESE, etc., rather than calling this function directly.  However,
code which programmatically constructs deployments will need to call this.

Function: ``DEPLOY-THESE*``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(deploy-these* connections host properties)``

Like DEPLOY*, but replace the properties of HOST with PROPERTIES.

HOST has all its usual static informational attributes, as set by its usual
properties, plus any set by PROPERTIES.  Static informational attributes set
by PROPERTIES can override the host's usual static informational attributes,
in the same way that later entries in the list of properties specified in
DEFHOST forms can override earlier entries (see DEFHOST's docstring).

Function: ``CONTINUE-DEPLOY*``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(continue-deploy* connection remaining-connections)``

Complete the work of an enclosing call to DEPLOY* or DEPLOY-THESE*.

Used by implementations of ESTABLISH-CONNECTION which need to do something
like fork(2) and then return to Consfigurator's primary loop in the child.

Macro: ``DEPLOY``
^^^^^^^^^^^^^^^^^

``(deploy connections host &body additional-properties)``

Establish CONNECTIONS to HOST, and apply each of the host's usual
properties, followed by specified by ADDITIONAL-PROPERTIES, an unevaluated
property application specification.

CONNECTION is a keyword identifying a connection type, a list beginning with
such a keyword and followed by keyword arguments required to establish the
connection, or a list of such lists.

Then HOST has all its usual static informational attributes, plus any set by
ADDITIONAL-PROPERTIES.  Static informational attributes set by
ADDITIONAL-PROPERTIES can override the host's usual static informational
attributes, in the same way that later entries in the list of properties
specified in DEFHOST forms can override earlier entries (see DEFHOST's
docstring).

The evaluation of ADDITIONAL-PROPERTIES to produce a property application
specification may retrieve existing hostattrs, but should not set any new
ones (not to be confused with how the :HOSTATTRS subroutines of properties in
ADDITIONAL-PROPERTIES may set additional hostattrs).

Macro: ``DEPLOY-THESE``
^^^^^^^^^^^^^^^^^^^^^^^

``(deploy-these connections host &body properties)``

Like DEPLOY, except apply each of the properties specified by PROPERTIES,
and not the host's usual properties, unless they also appear in PROPERTIES.
PROPERTIES is an unevaluated property application specification.

This function is useful to apply one or two properties to a host right now,
e.g. at the REPL when when testing new property definitions.  If HOST is
usually deployed using a Lisp-type connection, and the property you are testing
is :POSIX, you might use a connection type like :SSH so that you can quickly
alternate between redefining your work-in-progress property and seeing what
happens when you apply it to HOST.

HOST has all its usual static informational attributes, as set by its usual
properties, plus any set by PROPERTIES.  Static informational attributes set
by PROPERTIES can override the host's usual static informational attributes,
in the same way that later entries in the list of properties specified in
DEFHOST forms can override earlier entries (see DEFHOST's docstring).

The evaluation of PROPERTIES to produce a property application specification
may retrieve existing hostattrs, but should not set any new ones (not to be
confused with how the :HOSTATTRS subroutines of properties in PROPERTIES may
set additional hostattrs).

Macro: ``DEFDEPLOY``
^^^^^^^^^^^^^^^^^^^^

``(defdeploy name connections &body additional-properties)``

Define a function which does (DEPLOY CONNECTIONS HOST ADDITIONAL-PROPERTIES).
You can then eval (NAME) to execute this deployment.

Macro: ``DEFDEPLOY-THESE``
^^^^^^^^^^^^^^^^^^^^^^^^^^

``(defdeploy-these name connections &body properties)``

Define a function which does (DEPLOY-THESE CONNECTIONS HOST PROPERTIES).
You can then eval (NAME) to execute this deployment.

Function: ``HOSTDEPLOY*``
^^^^^^^^^^^^^^^^^^^^^^^^^

``(hostdeploy* host &optional additional-properties)``

Like DEPLOY*, but use the host's default deployment.

Function: ``HOSTDEPLOY-THESE*``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(hostdeploy-these* host properties)``

Like DEPLOY-THESE*, but use the host's default deployment.

Macro: ``HOSTDEPLOY``
^^^^^^^^^^^^^^^^^^^^^

``(hostdeploy host &body additional-properties)``

Like DEPLOY, but use the host's default deployment.

Macro: ``HOSTDEPLOY-THESE``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(hostdeploy-these host &body properties)``

Like DEPLOY-THESE, but use the host's default deployment.

Macro: ``LOCALSUDO``
^^^^^^^^^^^^^^^^^^^^

``(localsudo &rest properties)``

Deploy PROPERTIES to localhost using a :SUDO connection.

It is assumed that on this system the shell command 'hostname -f' will return
the full hostname, and that sudo is configured to ask for a password.  Useful
for testing properties at the REPL.  See also LOCALSUDON and EVALS.

Macro: ``LOCALSUDON``
^^^^^^^^^^^^^^^^^^^^^

``(localsudon &rest properties)``

Deploy PROPERTIES to localhost using a :SUDO connection.

This is like LOCALSUDO except that it assumes sudo is configured *not* to ask
for a password.

Macro: ``LOCALHD``
^^^^^^^^^^^^^^^^^^

``(localhd &rest properties)``

Deploy PROPERTIES to localhost using HOSTDEPLOY-THESE*.

It is assumed that on this system the shell command 'hostname -f' will return
the full hostname.  Useful for testing properties at the REPL.  See also
EVALS.

Property: ``DEPLOYS``
^^^^^^^^^^^^^^^^^^^^^

``(deploys connections host &optional additional-properties)``

Execute the deployment which is defined by the pair (CONNECTIONS . HOST),
except possibly with the property application specification
ADDITIONAL-PROPERTIES also applied to HOST, like DEPLOY.

Useful to have one host act a controller, applying properties to other hosts.
Also useful to set up VMs, chroots, disk images etc. on localhost.

Property: ``DEPLOYS-THESE``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

``(deploys-these connections host properties)``

Like DEPLOYS, except apply to HOST each of the properties specified by
PROPERTIES, and not the host's usual properties, unless they also appear in
PROPERTIES, like DEPLOY-THESE.

Property: ``EVALS``
^^^^^^^^^^^^^^^^^^^

``(evals &rest forms)``

Property which just evaluates each of FORMS using EVAL.  Only for testing
newly defined functions and programmatic applications of properties at the
REPL with DEPLOY-THESE/HOSTDEPLOY-THESE -- do not add to hosts.

For example, to sudo to root to test your new function which needs root
privileges to do anything at all,

.. code-block:: none

  (deploy-these :sudo laptop.example.com (evals '(my-new-function)))

where laptop.example.com is your laptop.

Note that while this property is declared to be :POSIX for flexibility,
whether it is actually :POSIX depends on what input and output FORMS perform.
