1 files changed, 82 insertions, 0 deletions
diff --git a/site/posts/cleopatra/literate-programming.org b/site/posts/cleopatra/literate-programming.org
new file mode 100644
index 0000000..63e0b02
--- /dev/null
+++ b/site/posts/cleopatra/literate-programming.org
@@ -0,0 +1,82 @@
+#+TITLE: Literate Programming Projects
+
+#+SERIES: ../cleopatra.html
+#+SERIES_PREV: ./org.html
+#+SERIES_NEXT: ./theme.html
+
+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.
+
+#+BEGIN_EXPORT html
+<nav id="generate-toc"></nav>
+<div id="history">site/cleopatra/literate-programming.org</div>
+#+END_EXPORT
+
+* 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.
+
+#+BEGIN_SRC emacs-lisp :tangle export-lp.el
+;; 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)
+#+END_SRC
+
+Tangling literate programming is done in the =prebuild= phase of
+*~cleopatra~*.
+
+#+BEGIN_SRC makefile :tangle literate-programming.mk
+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
+#+END_SRC
+
+* Building
+
+In the =build= phase, we actually try to compile the tangled projects.
+As of now, there is only one literate program: [[../posts/CoqffiEcho.org][the Echo server
+implemented in Coq]] which demonstrates how ~coqffi~ can be used to
+implement realistic software projects.
+
+#+BEGIN_SRC makefile :tangle literate-programming.mk
+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}
+#+END_SRC