00INSTALL

INSTALLING cl-launch
====================

If you're going to build things that depend on cl-launch using ASDF or XCVB,
you need to install cl-launch.

However, even without installation, cl-launch will work happily as a
standalone script that drives the building of simple executables or
ones that use ASDF.


Simple installation
-------------------

If you want to install cl-launch at its default location in ``/usr/local``,
just you::

	sudo make install

If instead you want it in ``/usr``, do::

	sudo make install PREFIX=/usr

A list of variables you may want to modify or override is
at the beginning of the ``Makefile``.

Wherever you install cl-launch, we recommend you have a symlink
from /usr/bin/cl to wherever you installed cl-launch, so that
everyone may be able rely on that location for scripts that start with:
	#!/usr/bin/cl


Advanced installation
---------------------

You can decide separately where the binary will be using ``INSTALL_BIN``
(to override the default of ``$PREFIX/bin``)
and where the Lisp source code will go using ``INSTALL_SOURCE``
(to override the default of ``$PREFIX/share/common-lisp/source/cl-launch``)
with a symlink to the asd file going in ``INSTALL_SYSTEMS``
(to override the default of ``$PREFIX/share/common-lisp/systems``).


Update and reinstallation
-------------------------

Personally, I have a ``./reinstall`` script that does::

	make install_system PREFIX=$HOME/.local

and if not for a judicious symlink
from ``$HOME/bin/cl-launch`` to my checkout,
it would also do::

	make install_binary PREFIX=$HOME


Configuration
-------------

Of course you should adjust your ``PATH`` and your ``CL_SOURCE_REGISTRY``
coherently with where you install cl-launch.


Faking the installation
-----------------------

If you just want to see what cl-launch will create
without installing it to the final destination,
you can install to a fake destination::

	mkdir -p build/bin build/systems build/source
	make install INSTALL_BIN=${PWD}/build/bin INSTALL_SOURCE=${PWD}/build/source INSTALL_SYSTEMS=${PWD}/build/systems


Using it
--------

Get short help with
	cl-launch --help

Get long help with
	cl-launch --more-help | ${PAGER:-less}

Here are three examples:

1- Running code directly from the command line:
	cl -sp lisp-stripper "(count-lisp-loc \"asdf.lisp\")"

2- Defining a script that counts lines of Lisp code a la wc :

#!/usr/bin/cl -sp lisp-stripper -E main
(defun main (argv)
  (if argv
      (map () 'print-loc-count argv)
      (print-loc-count *standard-input*)))

3- Comparing how the many implementations evaluate a same form:

for l in sbcl ccl clisp cmucl ecl abcl scl allegro lispworks gcl xcl ; do
   cl-launch -l $l -i '(format t "'$l': ~S~%" `#5(1 ,@`(2 3)))' \
   2>&1 | grep "^$l:" # LW, GCL are verbose
done

More examples in XCVB and Exscribe source code.