build: Generate gcc-mesboot-graph from .dot.
[mes.git] / doc / mes.texi
index d25a040f0aa1e8d22acc6a8ba0187c0b176e3e7f..c2ec05bfeb3c2b4f99f8c84eecdd115cb6b68d80 100644 (file)
@@ -25,6 +25,9 @@ Documentation License''.
 
 @dircategory Bootstrapping
 @direntry
+* Mes: (mes).       A system bootstrap worthy of GNU.
+
+
 * mes: (mes)Invoking mes.       Running Mes, a minimalist Guile lookalike.
 * mescc: (mes)Invoking MesCC.   Running the MesCC bootstrap compiler.
 @end direntry
@@ -57,6 +60,7 @@ Scheme interpreter and C compiler written for bootstrapping the GNU system.
 * Bootstrapping::               Would you strap my boots?
 * Contributing::                Your help needed!
 * Acknowledgments::             Thanks!
+* Resources::
 * GNU Free Documentation License::  The license of this manual.
 * Concept Index::               Concepts.
 * Programming Index::           Data types, functions, and variables.
@@ -112,9 +116,9 @@ These were “Maxwell’s Equations of Software!”
 @end quotation
 
 Mes@footnote{``Mes'' is an acronym for the Maxwell Equations of
-Software.} consists of a mutual self-hosting Scheme interpreter
-prototype written in C and a Nyacc-based (see @pxref{NYACC User's
-Guide,,, nyacc-ug, NYACC User's Guide}) C compiler written in Scheme.
+Software.} consists of a mutual self-hosting Scheme interpreter written
+in C and a Nyacc-based (see @pxref{NYACC User's Guide,,, nyacc-ug, NYACC
+User's Guide}) C compiler written in Scheme.
 
 The Scheme interpreter @file{mes.c} is about 5000LOC of restricted C and
 intended to be bootstrappable using a very simple C compiler.
@@ -122,19 +126,39 @@ intended to be bootstrappable using a very simple C compiler.
 @section Software Freedom
 @cindex purpose
 The four essential Freedoms of Software are at the core of our GNU
-community.  Quoting the first freedom from
-@url{https://www.gnu.org/philosophy/free-sw.html}
+community.  Quoting the GNU philosophy@footnote{The four essential
+freedoms @url{https://www.gnu.org/philosophy/free-sw.html}}
 
 @quotation
-The freedom to study how the program works, and change it so it does
-your computing as you wish (freedom 1).  Access to the source code is a
-precondition for this.
+A program is free software if the program's users have the four
+essential freedoms:
+
+@enumerate 0
+@item
+    The freedom to run the program as you wish, for any purpose (freedom 0).
+
+@item
+    The freedom to study how the program works, and change it so it does
+    your computing as you wish (freedom 1). Access to the source code is
+    a precondition for this.
+
+@item
+    The freedom to redistribute copies so you can help others (freedom
+    2).
+
+@item
+    The freedom to distribute copies of your modified versions to others
+    (freedom 3). By doing this you can give the whole community a chance
+    to benefit from your changes. Access to the source code is a
+    precondition for this.
+@end enumerate
 @end quotation
 
 So we have access to the software, we have studied it, possibly modified
 it, we built it and we installed it on a computer or some device.  How
 can we trust that when we run the program we are indeed running the
-untainted product of the source code that we studied?
+untainted product of the source code that we studied?  Unless we are
+certain of this we cannot really enjoy freedom 1.
 
 @menu
 * Reproducible Builds::         Reproducibility and free software.
@@ -146,8 +170,8 @@ untainted product of the source code that we studied?
 @section Reproducible Builds
 
 The current Reproducible Builds effort incubated in the Debian
-project@footnote{http://debian.org} and was organized by Lunar.  Quoting
-the @url{https://reproducible-builds.org/} website
+project@footnote{@url{http://debian.org, The Debian Project}} and was organized by Lunar.  Quoting
+the Reproducible Builds website@footnote{@url{https://reproducible-builds.org/,Reproducible Builds}}
 
 @quotation
 A build is reproducible if given the same source code, build environment
@@ -172,7 +196,7 @@ largely because failing that precondition makes justifable trust in
 binaries provided suspect at best and downright dangerous in reality.
 
 It becomes clear that a bit-by-bit reproducible build of all our
-sofwares is essential if we value our Freedom #1.
+sofwares is essential if we value our Freedom 1.
 
 @subsection An Old Idea
 
@@ -180,7 +204,7 @@ The idea of reproducible builds is not very new.  It was implemented for
 GNU tools in the early 1990s (which we learned, much later in 2017).  In
 the Debian world it was mentioned first in 2000 and then more explicitly
 in 2007 on
-debian-devel@footnote{@url{https://lists.debian.org/debian-devel/2007/09/msg00746.html}}
+debian-devel@footnote{@url{https://lists.debian.org/debian-devel/2007/09/msg00746.html,Martin Uecker on debian-devel on bit-reproducibility}}
 
 @quotation
 I think it would be really cool if the Debian policy required that
@@ -196,8 +220,8 @@ Software distributions that take reproducible builds seriously are
 currently shipping well over 90% reproducible packages.
 
 That a package builds bit-by-bit reproducibly however is not enough to
-guarantee Freedom #1.  There is another factor that is often overlooked:
-opaque ascii or binary @emph{seeds} that are injected dnuring build
+guarantee Freedom 1.  There is another factor that is often overlooked:
+opaque ascii or binary @emph{seeds} that are injected during build
 time.  Yes, a package may build reproduciblly from all inspectable
 sourcess...but what functionality is programmed in the opaque seed?
 
@@ -242,10 +266,10 @@ $ du -schx *
 
 There is an obvious solution: we cannot allow any binary seeds in our
 software stack.  Not even in the bootstrap binaries.  Maybe that is a
-bit too strong: want to have the absolute minimum of binary seeds and
-all binary seeds need to be inspectable and need to be reviewed.
+bit too strong: we want to have the absolute minimum of binary seeds and
+all binary seeds need to be inspectable and must be reviewed.
 
-@subsection The Magical Self Hosting Hex Assembler
+@subsection The Magical Self-Hosting Hex Assembler
 
 June 2016 I learnt about
 @url{https://github.com/oriansj/stage0/,Stage0}.  Jeremiah Orians
@@ -280,7 +304,7 @@ powers of LISP?
 Mes is a Scheme@footnote{Scheme is a modern LISP} interpreter that will
 be indirectly bootstrapped from @file{hex0} and that wields the magical
 powers of LISP to close the bootstrap gap, asserting we can enjoy
-software Freedom #1.
+software Freedom 1.
 
 @c *********************************************************************
 @node Installation
@@ -398,7 +422,8 @@ build-aux/check-mescc.sh
 Run a single MesCC test
 
 @example
-CC=gcc CC32=i686-unknown-linux-gnu-gcc MES=guile build-aux/test.sh
+CC=gcc CC32=i686-unknown-linux-gnu-gcc MES=guile \
+  build-aux/test.sh scaffold/tests/00-exit-0
 @end example
 
 @node Bootstrapping
@@ -416,7 +441,7 @@ all from source code.  In addition to the carefully signed source code
 of all the programs (the `milk') an opaque binary seed (the `yogurt') is
 injected as an essential dependency.
 
-Why would this a problem, I hear you ask?  This is how it is done, we
+Why would this be a problem, I hear you ask?  This is how it is done, we
 always did it this way, everyone does it like this!  Indeed, a popular
 way of handling the bootstrapping issue is by ignoring it.
 
@@ -424,7 +449,7 @@ way of handling the bootstrapping issue is by ignoring it.
 Your compiler becoming self-hosting@dots{}a language creator's wet
 dream.
 
-@author Paul Hoogendijk
+@author PFH
 @end quotation
 
 It seems that writing a self-hosting compiler is considered to be a
@@ -449,7 +474,7 @@ responsibility.
 @section The Mes Bootstrap Process
 
 The Mes full source bootstrap process@footnote{TBH, the current state of
-affairs demands to label this the reduced binary seed bootstrap} is
+affairs demands to label this a `reduced binary seed bootstrap'} is
 currently being developed in GuixSD@footnote{See
 @file{gnu/packages/mes.scm} in the @var{wip-bootstrap} branch in Guix
 git
@@ -476,6 +501,18 @@ binutils-source + binutils0 + gcc + glibc => binutils
 gcc-source + binutils + gcc-core + glibc => gcc
 @end verbatim
 
+@c This graph is generated from wip-bootstrap, doing:
+
+@c sed -i s,package-with-bootstrap-guile,identity, gnu/packages/{commencement,mes}.scm
+
+@c ~/src/guix-bootstrap/pre-inst-env guix graph gcc-mesboot > doc/images/gcc-mesboot-graph.dot
+@c dot -T png doc/images/gcc-mesboot-graph.dot > doc/images/gcc-mesboot-graph.png
+
+Here's a generated dependency diagram to give you impression, it is not
+complete or correct.
+
+@image{images/gcc-mesboot-graph,2in,,Reference graph of the gcc-mesboot}
+
 Work is ongoing to remove these binary seeds that were intentionally
 injected by our own doing as temporary shortcut
 @example
@@ -770,8 +807,7 @@ guix environment -l guix.scm
 Finally, you have to invoke @code{make check} to run tests
 (@pxref{Running the Test Suites}).  If anything fails, take a look at
 installation instructions (@pxref{Installation}) or send a message to
-@email{janneke@@gnu.org, janneke} or to the @email{guix-devel@@gnu.org}
-mailing list.
+the @email{guix-devel@@gnu.org} mailing list.
 
 @node Running Mes From the Source Tree
 @section Running Mes From the Source Tree
@@ -837,8 +873,7 @@ Additionally, in Mes we prefer to format @code{if} statements like this
 Development is done using the Git distributed version control system.
 Thus, access to the repository is not strictly necessary.  We welcome
 contributions in the form of patches as produced by @code{git
-format-patch} sent to @email{janneke@@gnu.org, janneke} or to the
-@email{guix-devel@@gnu.org} mailing list.
+format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
 
 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
 standards, GNU Coding Standards}); you can check the commit history for
@@ -862,9 +897,13 @@ honesty with a more helpful and more blunt reminder of a mantra of Free
 Software:
 
 @quotation
+@table @strong
+@item Q:
 When@dots{}?
 
+@item A:
 @dots{}sooner if you help.
+@end table
 
 @author Eric Raymond
 @end quotation
@@ -881,12 +920,46 @@ Join us on @code{#bootstrappable} on the Freenode IRC network or on
 
 We would like to thank the following people for their help: Jeremiah
 Orians, pdewacht, rain1, Ricardo Wurmus, Rutger van Beusekom.
-
+w
 We also thank Ludovic Courtès for creating GuixSD and making the
 bootstrap problem so painfully visible, John McCarthy for creating
-LISP-1.5 and Alan Kay for their observation that Page 13
+LISP-1.5 and Alan Kay for their inspiring comment on
 @url{https://queue.acm.org/detail.cfm?id=1039523, Page 13}.
 
+@c *********************************************************************
+@node Resources
+@chapter Resources
+
+@itemize
+
+@item
+@url{https://bootstrappable.org, Bootstrappable Builds} Minimize the
+amount and size of opaque binary seeds we need to swallow.
+
+@item
+@url{https://reproducible-builds.org, Reproducible Builds}
+Provide a verifiable path from source code to binary.
+
+@item
+@url{https://gitlab.com/oriansj/stage0, Stage0}
+If we want, it could all start with a ~500 byte self-hosting hex
+assembler.
+
+@item
+@url{https://bootstrapping.miraheze.org, Bootstrapping wiki} An amazing
+collection of small/bootstrappable compilers, operating systems,
+anything you need.
+
+@item
+@url{irc.freenode.net, #bootstrappable} The bootstrapping community home
+at the freenode IRC network.
+
+@item
+@file{guix-devel@@gnu.org} The Guix mailing list, where it all started.
+@url{https://lists.gnu.org/archive/html/guix-devel/, guix-devel archives}.
+
+@end itemize
+
 @c *********************************************************************
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License