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}