#lisp-template

An opinionated template for kickstarting new Common Lisp projects with quickproject.

#The Opinions

When starting most any programming project, many things are needed:

• A good utility library (or two): we use alexandria and serapeum
• A language enhancement (or two): we use iterate and sometimes trivial-pln or fset
• A library for generating docs: we use mgl-pax
• A library for writing tests: we use try

(Perhaps dubiously, I lean on the transitive dependency on alexandria and only load serapeum and a local-nickname for its bundle package.)

Once these basic ingredients are provided we need ways to use them such as:

• Run tests in CI on every commit: we do this through builds.sr.ht and our .build.yml
• Run tests locally before commit: we do this through an included (but optional) pre-commit hook
• Run tests locally from the CLI: we do this via a good old Makefile and make test
  • Sure, I prefer running my tests in emacs but to each their own.
• Generate the READMEs: we do this via mgl-pax and make docs
  • See src/docs.lisp and run make docs to sample the output
  • The mgl-pax tutorial may also be helpful
  • The pre-commit hook can do this every commit if you like, just uncomment # make docs
• Generate a site of HTML documentation: we do this via mgl-pax and make site
• Deliver an executable: we provide this via make app

Finally there are some things that are very specific to my taste:

• Tracking notes and TODOs: we added JOURNAL.org and TODO.org files for this purpose
  • If they are not to your liking, please simply delete them from your clone of the project template.

Perhaps at some point I will write more on why I have converged on this set of preferences. I would also like to add a deploy command for pushing the site to pages.sr.ht but haven't yet gotten around to it.

#Install

Clone this repo to your local machine and add the helper script to your path:

git clone https://git.sr.ht/~kingcons/lisp-template ~/.lisp-template
echo '\n# lisp-template helper' >> ~/.zshrc # (or ~/.bashrc as appropriate)
echo 'export PATH="$HOME/.lisp-template/bin:$PATH"' >> ~/.zshrc

Then define a new-project function in your lisp init-file (such as ~/.sbclrc) to leverage the template. Make sure to modify the default values to your liking! :)

NOTE: We rely on mgl-pax for generating the README and try for tests. If you want to change those things, you will need to dive deeper into modifying the template. But please, hack the template up all you like.

(defun new-project (name &key
                           (srht-user "kingcons")
                           (projects-dir "projects")
                           (author "Brit Butler")
                           (license "MIT")
                           (include-copyright nil)
                           (depends-on '(:serapeum
                                         :iterate
                                         :mgl-pax
                                         :swank))
                           (template-directory "~/.lisp-template/template/"))
  (unless (find-package :quickproject)
    (ql:quickload :quickproject)) ; Quickproject transitively loads cl-fad
  (let* ((builder (find-symbol "MAKE-PROJECT" "QUICKPROJECT"))
         (dir-ify (find-symbol "PATHNAME-AS-DIRECTORY" "CL-FAD"))
         (ql-path (merge-pathnames name (first ql:*local-project-directories*)))
         (pathname (funcall (find-symbol "MERGE-PATHNAMES-AS-DIRECTORY" "CL-FAD")
                            (user-homedir-pathname)
                            (funcall dir-ify projects-dir)
                            (funcall dir-ify name))))
    (push (lambda () (list :srht-user srht-user))
          (symbol-value (find-symbol "*TEMPLATE-PARAMETER-FUNCTIONS*" :quickproject)))
    (funcall builder pathname
             :author author
             :license license
             :include-copyright include-copyright
             :depends-on depends-on
             :template-directory template-directory)
    (uiop:run-program (list "ln" "-sf" (namestring pathname) (namestring ql-path)))))

#Usage

Either call from the REPL or use the command line helper if the default args are sufficient. (Currently the CLI script doesn't support specifying alternative options.)

Note that the COPYING file in the template is an MIT license so change its contents if needed.

lisp-project my-project
cd ~/projects/my-project
git init
sh bin/install-hooks
git add .
git commit -m "Initial commit"

Afterwards, you can simply dive into your project and start hacking while using make as you please. Note that there are Makefile targets for:

• app - to compile a binary in the projects bin folder
• docs - to generate a README from the docs file using MGL-PAX
• repl - to spawn a repl you can slime-connect to
• site - to generate the documentation as a webpage, handy with Sourcehut pages and .build.yml
• test - to invoke the test suite

Finally, the Makefile defaults to SBCL but also works with Clozure and should be easy to extend. To use it with an alternate lisp, simply pass the command for your lisp to make:

make test LISP=ccl