#+TITLE: cclsh
#+AUTHOR: Lukáš Hozda

A system shell running inside Common Lisp. Ordinary Unix commands and Common
Lisp forms share one live image, so the boundary between shell use and Lisp is
small and explicit.

The complete saved-image distribution targets CCL on Linux x86-64. The normal
source launcher also supports SBCL on macOS and Linux.

It is not a POSIX shell: command strings, scripts, pipelines and redirection use cclsh syntax.

* Try it

With Nix flakes enabled:

#+begin_src sh
nix run github:lambda-symbolics/cclsh -- --version
nix run github:lambda-symbolics/cclsh
#+end_src

Then type these lines inside cclsh:

#+begin_src text
$ pwd
$ (+ 1 2)
$ echo "Lisp result: " (+ 20 22)
$ help
#+end_src

The first line runs a normal command, the second evaluates Lisp, and the third
substitutes a Lisp result into a command.

* Install

The Nix flake is the recommended package:

#+begin_src sh
nix profile install github:lambda-symbolics/cclsh
cclsh --version
#+end_src

From a checkout, use =nix run .= or =nix profile install .#cclsh=.

Linux x86-64 release archives are also available on the
[[https://github.com/lambda-symbolics/cclsh/releases][GitHub Releases page]].
They include the matched CCL kernel, image and runtime, and do not require
Nix.

See [[file:docs/installation.org][Installing cclsh]] for Quicklisp state, CCL
and SBCL source launchers, local installation and the guarded shared
login-shell procedure.

* Shell and Lisp

A submitted line is interpreted by its shape:

- A line beginning with =(= is evaluated as Common Lisp in the =cclsh-user=
  package.
- Any other line starts in command mode and resolves a builtin or executable.
- Parenthesized Lisp inside a command is evaluated and substituted into its
  arguments.

Pipelines, sequencing and redirection are Lisp forms rather than sh operators:

#+begin_src lisp
(pipe (ls "-la") (grep "lisp"))
(pipe (make) (to "build.log"))
(capture (git "rev-parse" "--short" "HEAD"))
#+end_src

The same helpers are available to CCL programs after loading the =cclsh=
system. Commands can also be defined in Lisp with =defcommand= and used from
both command mode and Lisp.

* Highlights

- Clinedi line editing with history search, completion and highlighting
- foreground process groups, Ctrl-C handling and =jobs=/=fg=/=bg=/=disown=
- startup configuration in =~/.config/cclsh/startup.lisp=
- command strings, scripts, shebang scripts and piped input
- optional zoxide integration with =z= and =zi=
- optional experimental =cclsh-fast= prewarmed interactive launcher (CCL only)
- optional experimental =cclshd= shared-image terminal sessions (SBCL)

* Documentation

- [[file:docs/guide.org][User guide]]: syntax, substitution, pipelines, custom
  commands, job control, completion, configuration and scripting
- [[file:docs/installation.org][Installation]]: Nix, source builds and shared
  login-shell deployment
- [[file:docs/installation.org::*Experimental prewarmed launcher][Prewarmed launcher]]:
  opt-in daemon setup, fallback behavior and current limits
- [[file:docs/daemon.org][Shared SBCL daemon]]: setup, session state and shared-definition limits
- [[file:examples/startup.lisp][Example startup file]]
- [[file:docs/README.org][Documentation index]]

The built-in manual is available as =help= inside cclsh, or as =cclsh help=
from another shell. Use =cclsh help SECTION= for a specific topic.

* Development

Stock CCL 1.13 is sufficient for the full regression suite and unsaved REPL
development:

#+begin_src sh
scripts/check
#+end_src

SBCL runs the portable source launcher and its focused smoke suite:

#+begin_src sh
scripts/cclsh-sbcl
make sbcl-check
#+end_src

Standalone image builds require the downstream CCL changes documented in the
[[file:docs/installation.org][installation guide]].

* License

cclsh's original code and documentation are released under the ISC license.
See [[file:LICENSE][LICENSE]]. The CCL-derived patch mirrors under =patches/=
remain under the Apache License 2.0; see [[file:patches/LICENSE][their license]].