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.

Revisions

This revisions table has been automatically generated from the git history of this website repository, and the change descriptions may not always be as useful as they should.

You can consult the source of this file in its current version here.

2021-03-28 2021 Spring redesign 495f9db
2020-12-20 Provide some insight on how literate programming projects are built 9722f57
2020-12-14 Fine-grained dependency for literate programming build process c1b2d67
2020-12-14 Do not output when tangling coqffi tutorial 11157c8
2020-12-10 Fix the generation of coqffi-tutorial.tar.gz 0a530db
2020-12-10 Add a Series on coqffi, and the first literate program of this blog 2706544

Tangling §

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. 

;; opinionated configuration provided by cleopatra
(cleopatra:configure)

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

;; 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

Building §

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 _opam/init
	@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}