Literate Programming Projects

Literate programming is an interesting exercice. It forces programmers to think about how to present their code for other people to understand it. It poses several significant challenges, in particular in terms of code refactoring. If a given piece of code is too much entangled with proses explaining it, rewriting it becomes cumbersome.

That being said, literate programming is particularly well-suited for blog posts, since at the very least it provides the tool to enforce the code presented to readers is correct.

We use Emacs and org-mode to tangle the literate programming projects present in the posts/ directory of this website. This is done with the following emacs lisp script.

(cleopatra:configure) ; opinionated configuration provided by cleopatra

(org-babel-do-load-languages
 'org-babel-load-languages
 '((shell . t))) ; allow the execution of shell block code

 ;; scan the posts/ directory and tangled it into lp/
(setq org-publish-project-alist
      '(("lp"
         :base-directory "site/posts"
         :publishing-directory "lp"
         :recursive t
         :publishing-function cleopatra:tangle-publish)))

(org-publish-all)

Tangling literate programming is done in the prebuild phase of cleopatra.

literate-programming-prebuild :
        @cleopatra echo "Tangling" "literate programming project"
        @cleopatra exec -- cleopatra-run-elisp export-lp.el \
            >> build.log 2>&1

ARTIFACTS += lp/ site/posts/deps.svg

In the build phase, we actually try to compile the tangled projects. As of now, there is only one literate program: the Echo server implemented in Coq which demonstrates how coqffi can be used to implement realistic software projects.

COQFFI_ARCHIVE := site/files/coqffi-tutorial.tar.gz

coqffi-tutorial-build : literate-programming-prebuild
        @cleopatra echo "Building" "coqffi tutorial"
        @cd lp/coqffi-tutorial; dune build --display quiet
        @cleopatra echo "Archiving" "coqffi tutorial"
        @rm -f ${COQFFI_ARCHIVE}
        @tar --exclude="_build" -C lp/ -czvf ${COQFFI_ARCHIVE} coqffi-tutorial \
              2>&1 >> build.log

site/posts/CoqffiEcho.html : coqffi-tutorial-build
literate-programming-build : coqffi-tutorial-build

ARTIFACTS += ${COQFFI_ARCHIVE}