SOJRN: Declarative, Transactional Config/Dotfile Deployment in CL

A Lisp-native dotfile/config deployment tool for keeping your Common Lisp tooling consistent across Linux and Windows. Declarative source-to-target config mapping (add-config) with symlink/copy specs, backed by a cl-dbi-tracked SQL persistence layer, plus a GTK4 GUI frontend. Unlike a pure stateless symlink-farm tool, it tracks what’s been deployed where, over time, in an actual database rather than just inferring state from the filesystem each run.

PS: I am building this for my own use and my own amusement — not a bid for The One True Config/Dotfile Tool. Feel free to poke around, steal ideas, or use it yourself if it looks fun.

Build, Testing, & Configuration

Dependencies (see Guix manifest.scm for reference). Note these are generic library dependencies; Linux users can install them via their distro’s package manager:

• SBCL
• ocicl
• sqlite (libsqlite3)
• gtk
• pango
• cairo
• gdk-pixbuf
• graphene
• libffi
• pkg-config
• gcc-toolchain
• libfixposix

ocicl is a modern approach for Common Lisp Systems Management. It even supports vendored sources, which this project currently needs, i.e. cl-cffi-gtk4 and cl-cffi-gdk-pixbuf, all other CL dependencies are handled by ocicl.

Build & Test

First install sbcl and run bootstrap.lisp, which setup up a symlink for the specially configured sbcl configuration file (.sbclrc) tailored for this project. Next install ocicl. Vendoring of cl-cffi-gtk4 and cl-cffi-gdk-pixbuf are handled in bootstrap.lisp. The sojrn system load/build is supported by :sojrn-package-inferred-system class which sets up the CFFI environment setting LD_LIBRARY_PATH for both Linux and Windows. This is implmented in the ASDF system extension :sojrn-asdf-system.

The document generation system automates api listing listing functions and their associated docstrings. More to come on more comprehensive documentation generation.

The executable build system is handled by the subsystem :sojrn/executable and whose inner workings are implmented in our ASDF extension system :sojrn-asdf-system class :sojrn-exec-system.

;; Build System
(asdf:load-system :sojrn)

;; Test System
(asdf:test-system :sojrn-tests)

;; Generate Documentation (WIP)
(asdf:load-system :sojrn-docs)

;; Create Executable (WIP)
(asdf:make :sojrn/executable)

;; Build Libraries/Extensions (WIP)
(asdf:load-system :sojrn/libraries)

Configuration Manager

The config-manager declaratively maps source files to deployment targets via add-config — manager, name, source, target, plus a :spec (symlink or copy) and :type. It validates the source exists before accepting the entry, warning rather than failing if it doesn’t. database.lisp backs it with a cl-dbi database, so deployment state is tracked over time rather than re-inferred from the filesystem each run. startup.lisp holds the actual per-machine declarations — the manager itself is generic, startup.lisp establishes the policy.

First edit/modify *config-spec* to your specific dotfile/config specifications and then deploy (the default manager instance is defined in *config-mgr*):

;; Apply your own config specification
#+(or)
(setf *config-spec*
'(("Your SBCL Config"
   "path/to/source/.sbclrc.lisp" "~/.sbclrc"
   :spec :symlink :type :file)))

;; Defaults

;; cd to ~/Work/sojrn/ (or location of this repo)
(asdf:load-system :sojrn)
;; First visualize your deployment plan
(sojrn:outline sojrn:*config-mgr*)
;; Deploy!
(sojrn:deploy sojrn:*config-mgr*)

GTK4 UI (WIP)

Currently working on establishing a gtk4 frontend using cl-cffi-gtk4.

Note: ocicl will install most of the dependencies, however, currently cl-cffi-gtk4 is not building upstream, so it needs to be vendored in ocicl/ manually along with cl-cffi-gdk-pixbuf.

Then you can run the currently simple UI as follows:

;; Re-run to finish building successfully
(asdf:load-system :sojrn)
(sojrn:main)

Play & Learn

As a fun exercise of incorporating a library, I adapted the SDRAW and DTRACE tools from the book Common Lisp: A Gentle Introduction to Symbolic Computation. This is staged in the system/library learn-cl. For example, you can run the sdraw learning tool (a cons cell visual aid) in this project as follows:

(sojrn:sdraw '(This (is a (test!))))

;; =>
;; [*|*]--->[*|*]--->NIL
;;  |        |
;;  v        v
;; THIS     [*|*]--->[*|*]--->[*|*]--->NIL
;;           |        |        |
;;           v        v        v
;;           IS       A       [*|*]--->NIL
;;                             |
;;                             v
;;                            TEST!

Roadmap

• [X] Build configuration manager system
• [X] Incorporate config-manager persistence via sqlite
• [X] Begin Scaffolding GTK4 UI System
• [X] Build a documentation system
• [ ] Extend Configuration Manager to build/deploy external systems
• [ ] Build a GTK4 GUI config system inspector
• [ ] Build a CLI executable for deployment system (?)
• [ ] Build a CL ASDF package-inferred-system scaffolding tool (?)

References:

• ocicl — Common Lisp system manager used throughout this project.
• cl-cffi-gtk4 and its sibling libraries:
  • cl-cffi-gdk-pixbuf
  • cl-cffi-glib,
  • cl-cffi-cairo,
  • cl-cffi-pango,
  • cl-cffi-graphene,
• FiveAM — the testing framework backing sojrn-tests.
• 3bmd — Markdown rendering used by sojrn-docs’s generator.
• Common Lisp: A Gentle Introduction to Symbolic Computation
  • source for the sdraw=/=dtrace learning tools in learn-cl.
• GNU Guix - The system this project was develop on — the environment manifest.scm targets.

License

Licensed under the Apache-2.0, fork it, sell it, build an empire on it, just don’t sue me over patents and leave the copyright notice where you found it!

See LICENSE for the full text.