1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
#+BEGIN_EXPORT html
<h1>Bootstrapping an Extensible Toolchain</h1>
#+END_EXPORT
A literate program is a particular type of software program where the sentence
/“the code is the documentation”/ is actually the expected result, rather than
an admission of failure. That is, the same source files are used to generate the
program *and* the documentation.
That being said, *~cleopatra~* is a toolchain to build a website before being a
literate program, and one of its objective is to be /part of this very website
it is used to generate/. To acheive this, *~cleopatra~* has been written as a
collection of org files which can be either “tangled” using [[https://orgmode.org/worg/org-contrib/babel/][Babel]] or “exported”
as a HTML document. Tangling here refers to extracted marked code blocks into
files.
The page you are currently reading is *~cleopatra~* entry point. Its primilarly
purpose is to introduce two Makefiles: ~Makefile~ and ~bootstrap.mk~.
* The Root of Generation
~Makefile~ serves two purposes: it initiates a few global variables, and it
provides a rule to generate ~bootstrap.mk~. At this point, some readers may
wonder /why/ we need ~Makefile~ in this context, and the motivation behind this
choice is really reminescent of a boot sequence. The rationale is that we need a
“starting point” for *~cleopatra~*. The toolchain cannot live solely inside
org-files, otherwise there would not have any code to execute the first time we
tried to generate the website. We need an initial Makefile, one that has little
chance to change, so that we can almost consider it read-only. Contrary to the
other Makefiles that we will generate, this one will not be deleted by ~make
clean~.
This is similar to your computer: it requires a firmware to boot, whose purpose
—in a nutshell— is to find and load an operating system.
Modifying the content of ~Makefile~ in this document /will/ modify
~Makefile~. This means one can easily put *~cleopatra~* into an inconsistent
state, which would prevent further generation. This is why the generated
~Makefile~ should be versioned, so that you can use
#+BEGIN_SRC shell
git restore Makefile
#+END_SRC
before fixing your error.
#+BEGIN_SRC makefile :tangle (concat (getenv "ROOT") "/Makefile") :noweb tangle
ROOT := $(shell pwd)
CLEODIR := site/posts/meta
GENFILES := scripts/tangle-org.el bootstrap.mk
EMACS := ROOT="${ROOT}" emacs
#+END_SRC
#+BEGIN_SRC makefile :tangle (concat (getenv "ROOT") "/Makefile") :noweb tangle
default: build
include bootstrap.mk
Makefile bootstrap.mk scripts/tangle-org.el \
&: ${CLEODIR}/Bootstrap.org
@echo " tangle $<"
@${EMACS} $< --batch \
--eval "(require 'org)" \
--eval "(setq org-src-preserve-indentation t)" \
--eval "(org-babel-tangle)" 2>/dev/null
#+END_SRC
* Bootstrapping
#+NAME: tangle-org
#+BEGIN_SRC emacs-lisp :tangle (concat (getenv "ROOT") "/scripts/tangle-org.el")
(require 'org)
(setq org-src-preserve-indentation t)
(org-babel-tangle)
#+END_SRC
#+BEGIN_SRC makefile :tangle (concat (getenv "ROOT") "/bootstrap.mk")
GENSASS :=
CONTENTS :=
GENFILES += org.mk scripts/export-org.el coq.mk \
sass.mk ${SASS} templates/main.html \
soupault.conf
include org.mk coq.mk sass.mk
TANGLEARGS := --batch \
--load="${ROOT}/scripts/tangle-org.el" \
2>/dev/null
build : ${CONTENTS} ${GENFILES}
@echo " run soupault"
@soupault
@echo " update .gitignore"
@scripts/update-gitignore.sh ${CONTENTS} ${GENFILES} ${GENSASS}
clean :
@echo " remove generated files"
@rm -rf ${CONTENTS} ${GENFILES} build/
force : clean build
soupault.conf : ${CLEODIR}/Soupault.org
@echo " tangle $<"
@${EMACS} $< ${TANGLEARGS}
org.mk scripts/export-org.el site/style/org.sass \
coq.mk site/style/coq.sass \
&: ${CLEODIR}/Contents.org
@echo " tangle $<"
@${EMACS} $< ${TANGLEARGS}
sass.mk ${SASS} templates/main.html \
&: ${CLEODIR}/Theme.org
@echo " tangle $<"
@${EMACS} $< ${TANGLEARGS}
.PHONY: clean build force default
#+END_SRC
# Local Variables:
# org-src-preserve-indentation: t
# End:
|