1.1--- a/readme.org	Sat Jun 22 23:52:20 2024 -0400
     1.2+++ b/readme.org	Sun Jun 23 00:48:02 2024 -0400
     1.3@@ -61,34 +61,44 @@
     1.4 | Mpd         | lib/aud/mpd            | https://vc.compiler.company/packy/mpd         |      |
     1.5 
     1.6 * Building
     1.7+The Core consists of two major system: the *lisp* system and the
     1.8+*rust* system. There is also an auxiliary *emacs* system containing a
     1.9+complete Emacs IDE configuration which serves as the base for user
    1.10+customizations.
    1.11+
    1.12 ** From Source
    1.13-*** Common Lisp
    1.14+*** Lisp
    1.15+The Lisp Core can be found under the =lisp= directory. It is the
    1.16+largest system, most actively developed, and is intended to cover the
    1.17+complete surface of the user-facing APIs contained in the core.
    1.18+
    1.19 Starting from a standard Common Lisp environment with at least
    1.20-Quicklisp installed, you can execute =./x.lisp= which will generate
    1.21-the core build tool binary - =./x=. This tool is a convenience for
    1.22-building and testing different parts of the core.
    1.23+[[https://www.quicklisp.org/beta/][Quicklisp]] installed, you can execute =./x.lisp build skel= to build
    1.24+the project compiler and =./x.lisp run skel= to run it. This tool is a
    1.25+convenience for building and testing different parts of the core from
    1.26+a minimal dependency set.
    1.27 
    1.28-#+name: x-save-self
    1.29+#+name: x-help
    1.30 #+begin_src shell :exports both :results output
    1.31 # bootstrap the core build tool
    1.32-./x.lisp
    1.33+./x.lisp --help
    1.34 #+end_src
    1.35 
    1.36-#+RESULTS: x-save-self
    1.37-: To load "rt":
    1.38-:   Load 1 ASDF system:
    1.39-:     rt
    1.40-: ; Loading "rt"
    1.41-: 
    1.42-: saving self to ./x
    1.43+#+RESULTS: x-help
    1.44+#+begin_example
    1.45+This is SBCL 2.4.5, an implementation of ANSI Common Lisp.
    1.46+More information about SBCL is available at <http://www.sbcl.org/>.
    1.47 
    1.48-#+begin_src shell :results output :exports both
    1.49-./x --help
    1.50-#+end_src
    1.51+SBCL is free software, provided as is, with absolutely no warranty.
    1.52+It is mostly in the public domain; some portions are provided under
    1.53+BSD-style licenses.  See the CREDITS and COPYING files in the
    1.54+distribution for more information.
    1.55+To load "rt":
    1.56+  Load 1 ASDF system:
    1.57+    rt
    1.58+; Loading "rt"
    1.59 
    1.60-#+RESULTS:
    1.61-#+begin_example
    1.62-x --- core build tool
    1.63+x.lisp --- core build tool
    1.64 x.lisp [CMD]
    1.65 CMDS:
    1.66 test
    1.67@@ -101,20 +111,26 @@
    1.68 install
    1.69 #+end_example
    1.70 
    1.71-Calling =x= with no arguments drops into a REPL:
    1.72-#+begin_src shell :results none :noeval t
    1.73-# start a repl
    1.74-./x
    1.75-#+end_src
    1.76-
    1.77 To test the lisp standard library:
    1.78-#+begin_src shell :results output :noeval t :exports both
    1.79+#+begin_src shell :results output :exports both
    1.80 # test systems
    1.81-./x test std
    1.82+./x.lisp test std
    1.83 #+end_src
    1.84 
    1.85 #+RESULTS:
    1.86 #+begin_example
    1.87+This is SBCL 2.4.5, an implementation of ANSI Common Lisp.
    1.88+More information about SBCL is available at <http://www.sbcl.org/>.
    1.89+
    1.90+SBCL is free software, provided as is, with absolutely no warranty.
    1.91+It is mostly in the public domain; some portions are provided under
    1.92+BSD-style licenses.  See the CREDITS and COPYING files in the
    1.93+distribution for more information.
    1.94+To load "rt":
    1.95+  Load 1 ASDF system:
    1.96+    rt
    1.97+; Loading "rt"
    1.98+
    1.99 To load "rt":
   1.100   Load 1 ASDF system:
   1.101     rt
   1.102@@ -143,18 +159,12 @@
   1.103 No tests failed.
   1.104 #+end_example
   1.105 
   1.106-To save the prelude core to =.stash/prelude.core=:
   1.107+To save the prelude to =.stash/prelude.core=:
   1.108 #+begin_src shell :results output :noeval t
   1.109 # save cores
   1.110 ./x save prelude
   1.111 #+end_src
   1.112 
   1.113-To build a CLI binary:
   1.114-#+begin_src shell :results none :noeval t
   1.115-# build binaries
   1.116-./x build skel
   1.117-#+end_src
   1.118-
   1.119 And to install binaries (defaults to =/usr/local/bin/=):
   1.120 #+begin_src shell :results none :noeval t
   1.121 # install binaries
   1.122@@ -162,15 +172,24 @@
   1.123 #+end_src
   1.124 
   1.125 *** Rust
   1.126+The Core Rust system can be found under the =rust= directory.
   1.127+
   1.128+A workspace is configured such that you can build all components with
   1.129+the following command (~NOTE~ - takes a long time):
   1.130 #+begin_src shell :exports both :results output
   1.131   cd rust && cargo build --release
   1.132 #+end_src
   1.133 
   1.134-* Binaries
   1.135+*** Emacs
   1.136+The core contains a collection of Emacs Lisp libraries under =emacs=
   1.137+which may be installed for the current user using the corresponding
   1.138+Makefile.
   1.139+
   1.140+* Programs
   1.141 This section lists all program binaries provided by the core.
   1.142 ** skel                                                                :lisp:
   1.143 #+begin_src shell :results output :exports both
   1.144-  ./x run skel --help
   1.145+  skel --help
   1.146 #+end_src
   1.147 
   1.148 #+RESULTS:
   1.149@@ -206,6 +225,17 @@
   1.150   make : build project targets
   1.151     -t/--target :  target to build
   1.152   run : run a script or command
   1.153+  compile : compile source code
   1.154+  build : build programs and libraries
   1.155+  dist : distribute build artifacts
   1.156+  install : install stuff
   1.157+  pack : pack stuff
   1.158+  unpack : unpack stuff
   1.159+  bundle : bundle source code
   1.160+  unbundle : unbundle source code
   1.161+  clean : clean up the project
   1.162+  test : run tests
   1.163+  bench : run benchmark
   1.164   status : print the vc status
   1.165   push : push the current project upstream
   1.166   pull : pull the current project from remote
   1.167@@ -216,7 +246,7 @@
   1.168 #+end_example
   1.169 ** organ                                                               :lisp:
   1.170 #+begin_src shell :results output :exports both
   1.171-./x run organ --help
   1.172+organ --help
   1.173 #+end_src
   1.174 
   1.175 #+RESULTS:
   1.176@@ -239,7 +269,7 @@
   1.177 
   1.178 ** packy                                                               :lisp:
   1.179 #+begin_src shell :results output :exports both
   1.180-./x run packy --help
   1.181+packy --help
   1.182 #+end_src
   1.183 
   1.184 #+RESULTS:
   1.185@@ -266,7 +296,7 @@
   1.186 
   1.187 ** rdb                                                                 :lisp:
   1.188 #+begin_src shell :results output :exports both
   1.189-./x run rdb --help
   1.190+rdb --help
   1.191 #+end_src
   1.192 
   1.193 #+RESULTS:
   1.194@@ -292,7 +322,7 @@
   1.195 
   1.196 ** homer                                                               :lisp:
   1.197 #+begin_src shell :results output :exports both
   1.198-./x run homer --help
   1.199+homer --help
   1.200 #+end_src
   1.201 
   1.202 #+RESULTS:
   1.203@@ -317,14 +347,14 @@
   1.204 
   1.205 ** COMMENT alik                                                        :rust:
   1.206 #+begin_src shell :results output :exports both
   1.207-cd rust && cargo run --bin alik -- --help
   1.208+alik --help
   1.209 #+end_src
   1.210 
   1.211 #+RESULTS:
   1.212 
   1.213 ** krypt                                                               :rust:
   1.214 #+begin_src shell :results output :exports both
   1.215-cd rust && cargo run --bin krypt -- --help
   1.216+krypt --help
   1.217 #+end_src
   1.218 
   1.219 #+RESULTS:
   1.220@@ -349,7 +379,7 @@
   1.221 
   1.222 ** mailman                                                             :rust:
   1.223 #+begin_src shell :results output :exports both
   1.224-cd rust && cargo run --bin mailman -- --help
   1.225+mailman --help
   1.226 #+end_src
   1.227 
   1.228 #+RESULTS:
   1.229@@ -373,6 +403,3 @@
   1.230   -V, --version      Print version
   1.231 #+end_example
   1.232 
   1.233-* Emacs
   1.234-The core contains some Emacs Lisp libraries under =emacs= which may be
   1.235-installed for the current user using the corresponding Makefile.