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}