doc: Migration to Libera Chat.
[mes.git] / doc / mes.texi
1 \input texinfo
2 @c -*- mode: texinfo; -*-
3
4 @c %**start of header
5 @setfilename mes.info
6 @documentencoding UTF-8
7 @settitle GNU Mes Reference Manual
8 @c %**end of header
9
10 @include version.texi
11
12 @c Identifier of the OpenPGP key used to sign tarballs and such.
13 @set OPENPGP-SIGNING-KEY-ID 1A858392E331EAFDB8C27FFBF3C1A0D9C1D65273
14
15 @copying
16 Copyright @copyright{} 2018,2019,2020,2021 Jan (janneke) Nieuwenhuizen@*
17
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU Free Documentation License, Version 1.3 or
20 any later version published by the Free Software Foundation; with no
21 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
22 copy of the license is included in the section entitled ``GNU Free
23 Documentation License''.
24 @end copying
25
26 @dircategory Bootstrapping
27 @direntry
28 * Mes: (mes).       A system bootstrap worthy of GNU.
29
30
31 * mes: (mes)Invoking mes.       Running Mes, a minimalist Guile lookalike.
32 * mescc: (mes)Invoking mescc.   Running the MesCC bootstrap compiler.
33 @end direntry
34
35 @titlepage
36 @title GNU Mes Reference Manual
37 @subtitle Full Source Bootstrapping for the GNU system
38 @author Jan (janneke) Nieuwenhuizen
39
40 @page
41 @vskip 0pt plus 1filll
42 Edition @value{EDITION} @*
43 @value{UPDATED} @*
44
45 @insertcopying
46 @end titlepage
47
48 @contents
49
50 @c *********************************************************************
51 @node Top, Introduction, (dir), (dir)
52 @top GNU Mes
53
54 This document describes GNU Mes version @value{VERSION}, a bootstrappable
55 Scheme interpreter and C compiler written for bootstrapping the GNU system.
56
57 @menu
58 * Introduction::                What is Mes about?
59 * Installation::                Installing Mes.
60 * Bootstrapping::               Would you strap my boots?
61 * Contributing::                Your help needed!
62 * Acknowledgments::             Thanks!
63 * Resources::
64 * GNU Free Documentation License::  The license of this manual.
65 * Concept Index::               Concepts.
66 * Programming Index::           Data types, functions, and variables.
67
68 @detailmenu
69  --- The Detailed Node Listing ---
70
71 Software Freedom
72
73 * Reproducible Builds::         Reproducibility and free software.
74 * Bootstrappable Builds::       The freedom to build a software without binary seed.
75 * Full Source Bootstrap::       Software dependencies worthy of GNU.
76 * LISP as Maxwell's Equations of Software::  Auditable elegance.
77
78 Installation
79
80 * Regular Requirements::        Software needed to build and run Mes.
81 * Bootstrap Requirements::      Software needed to bootstrap Mes.
82 * Running the Test Suites::     Testing Mes.
83
84 Bootstrapping
85
86 * The Mes Bootstrap Process::   How Mes will make you yogurt from pure milk.
87 * Invoking mes::                Running Mes, a minimalist Guile lookalike.
88 * Invoking mescc::              Running the MesCC bootstrap compiler.
89 * Invoking mesar::
90
91 Invoking mes
92
93 * Environment Variables::       If the bits won't change, change their habitat.
94
95 Invoking mescc
96
97 * MesCC Environment Variables::  There's no NIX like POSIX.
98
99 Contributing
100
101 * Building from Git::           The latest and greatest.
102 * Running Mes From the Source Tree::  Hacker tricks.
103 * Porting GNU Mes::             Teach Mes about your platform.
104 * The Perfect Setup::           The right tools.
105 * Coding Style::                Hygiene of the contributor.
106 * Submitting Patches::          Share your work.
107
108 @end detailmenu
109 @end menu
110
111 @c *********************************************************************
112 @node Introduction, Installation, Top, Top
113 @chapter Introduction
114
115 @quotation
116 These were “Maxwell’s Equations of Software!”
117
118 @author Alan Kay
119 @end quotation
120
121 The purpose of GNU Mes@footnote{``Mes'' is an acronym for the Maxwell
122 Equations of Software.} is to help create a computer operating system
123 that we can trust.
124
125 Mes consists of a mutual self-hosting Scheme interpreter written in C
126 and a Nyacc-based (see @pxref{NYACC User's Guide,,, nyacc-ug, NYACC
127 User's Guide}) C compiler written in Scheme.  The Scheme interpreter
128 @file{mes.c} is about 5,000LOC of restricted C, to be compiled with
129 M2-Planet@footnote{See @url{https://github.com/oriansj/m2-planet}}, a
130 very simple C compiler.
131
132 If we want to trust our computers to do what we instructed them to do
133 then we need to be able to inspect all instructions---all
134 softwares---that we have given it to run.
135
136 @section Software Freedom
137 @cindex purpose
138 The four essential Freedoms of Software are at the core of our GNU
139 community.  Quoting the GNU philosophy@footnote{The four essential
140 freedoms @url{https://www.gnu.org/philosophy/free-sw.html}}
141
142 @quotation
143 A program is free software if the program's users have the four
144 essential freedoms:
145
146 @enumerate 0
147 @item
148     The freedom to run the program as you wish, for any purpose (freedom 0).
149
150 @item
151     The freedom to study how the program works, and change it so it does
152     your computing as you wish (freedom 1). Access to the source code is
153     a precondition for this.
154
155 @item
156     The freedom to redistribute copies so you can help others (freedom
157     2).
158
159 @item
160     The freedom to distribute copies of your modified versions to others
161     (freedom 3). By doing this you can give the whole community a chance
162     to benefit from your changes. Access to the source code is a
163     precondition for this.
164 @end enumerate
165 @end quotation
166
167 A computer operating system that respects the user's freedom is one
168 essential ingredient for building a reliable, trustable computing
169 system.  There are about a dozen general purpose operating systems that
170 can be trusted in this way, see
171 @url{https://www.gnu.org/distros/free-distros.html, Free Distributions}.
172 For all softwares on such a system we have the full source code and
173 build recipes available.
174
175 @c The Free System Distribution Guidelines (GNU FSDG)@footnote{Examples of
176 @c free operating systems are GNU Guix, GNU Parabola and Trisquel, see
177 @c https://www.gnu.org/distros/free-system-distribution-guidelines.html}
178 @c can serve as help to create such a system
179
180 So we have access to all the software, we have studied it, possibly
181 modified it, then we built it and we installed it on a computer or some
182 device or appliance.  How can we trust that when we run the program we
183 are indeed running the untainted product of the source code that we
184 studied?  Unless we are certain of this we cannot really enjoy
185 Freedom 1.
186
187 @menu
188 * Reproducible Builds::         Reproducibility and free software.
189 * Bootstrappable Builds::       The freedom to build a software without binary seed.
190 * Full Source Bootstrap::       Software dependencies worthy of GNU.
191 * LISP as Maxwell's Equations of Software::  Auditable elegance.
192 @end menu
193
194 @node Reproducible Builds, Bootstrappable Builds, Introduction, Introduction
195 @section Reproducible Builds
196
197 The current Reproducible Builds effort incubated in the Debian
198 project@footnote{@url{http://debian.org, The Debian Project}} and was
199 organized by Lunar.  Quoting the Reproducible Builds
200 website@footnote{@url{https://reproducible-builds.org/,Reproducible
201 Builds}}
202
203 @quotation
204 A build is reproducible if given the same source code, build environment
205 and build instructions, any party can recreate bit-by-bit identical
206 copies of all specified artifacts.
207 @end quotation
208
209 @subsection Can we trust our freedom?
210
211 Now consider the opposite, that a second build of a piece of source code
212 produces a different binary program.  Upon further investigation we
213 might find that the only difference is probably harmless: a timestamp
214 that was embedded in the binary, or perhaps the name of the user that
215 built it or directory it was built in.  Such investigations can be
216 nontrivial and are highly unpractical.  And what if the binary
217 difference is not so trivial, cannot be easily accounted for?
218
219 A piece of software that cannot be built bit-by-bit reproducible is
220 probably not a good community member in the world of software freedom.
221 We think the importance of reproducibility should not be underestimated
222 largely because failing that precondition makes justifable trust in
223 binaries provided suspect at best and downright dangerous in reality.
224
225 It becomes clear that a bit-by-bit reproducible build of all our
226 sofwares is essential if we value our Freedom 1.
227
228 @subsection An Old Idea
229
230 The idea of reproducible builds is not very new.  It was implemented for
231 GNU tools in the early 1990s (which we learned, much later in 2017).  In
232 the Debian world it was mentioned first in 2000 and then more explicitly
233 in 2007 on
234 debian-devel@footnote{@url{https://lists.debian.org/debian-devel/2007/09/msg00746.html,Martin Uecker on debian-devel on bit-reproducibility}}
235
236 @quotation
237 I think it would be really cool if the Debian policy required that
238 packages could be rebuild bit-identical from source.
239
240 @author Martin Uecker
241 @end quotation
242
243 @node Bootstrappable Builds, Full Source Bootstrap, Reproducible Builds, Introduction
244 @section Bootstrappable Builds
245
246 Software distributions that take reproducible builds seriously are
247 currently shipping well over 90% reproducible packages.
248
249 That a package builds bit-by-bit reproducibly however is not enough to
250 guarantee Freedom 1.  There is another factor that is often overlooked:
251 opaque ascii or binary @emph{seeds} that are injected during build
252 time.  Yes, a package may build reproduciblly from all inspectable
253 sourcess...but what functionality is programmed in the opaque seed?
254
255 @subsection Bootstrap Binary Seed
256 Possibly one of the most harmless, but certainly by far the biggest
257 binary seed that all software distributions inject are the so called
258 @emph{bootstrap binary seed}.  Bootstrap binaries are the initial binary
259 seeds that are used to start building the distribution.
260
261 The GNU Guix operating system, version 1.0 had a relatively small
262 closure of bootstrap binary seed: GNU binutils, GNU gcc, GNU Libc, GNU
263 Guile, and ``Static binaries'' (think: bash, bzip2, coreutils, gawk,
264 grep, gzip, patch, sed, tar, xz).
265
266 @example
267 $ du -schx $(readlink $(guix build bootstrap-tarballs)/*)
268 2.1M    /gnu/store/9623n4bq6iq5c8cwwdq99qb7d0xj93ym-binutils-static-stripped-tarball-2.28.1/binutils-static-stripped-2.28.1-x86_64-linux.tar.xz
269 18M     /gnu/store/437xwygmmwwpkddcyy1qvjcv4hak89pb-gcc-stripped-tarball-5.5.0/gcc-stripped-5.5.0-x86_64-linux.tar.xz
270 1.8M    /gnu/store/55ccx18a0d1x5y6a575jf1yr0ywizvdg-glibc-stripped-tarball-2.26.105-g0890d5379c/glibc-stripped-2.26.105-g0890d5379c-x86_64-linux.tar.xz
271 5.7M    /gnu/store/bqf0ajclbvnbm0a46819f30804y3ilx0-guile-static-stripped-tarball-2.2.3/guile-static-stripped-2.2.3-x86_64-linux.tar.xz
272 5.8M    /gnu/store/j8yzjmh9sy4gbdfwjrhw46zca43aah6x-static-binaries-tarball-0/static-binaries-0-x86_64-linux.tar.xz
273 33M     total
274 @end example
275
276 only a 33MB download that unpacks to a 252MB @emph{seed} of opaque
277 binary code.
278
279 @example
280 $ for i in $(readlink $(guix build bootstrap-tarballs)/*);\
281   do sudo tar xf $i; done
282 $ du -schx *
283 130M    bin
284 13M     include
285 54M     lib
286 51M     libexec
287 5.2M    share
288 252M    total
289 @end example
290
291 During the Guix 1.1 development series we managed to create the first
292 reduction by 50% of the Guix @emph{bootstrap binary seed}@footnote{See
293 @url{https://guix.gnu.org/blog/2019/guix-reduces-bootstrap-seed-by-50/}}.
294 This was a very important step because the ~250MB @emph{seed} of binary
295 code was practically non-auditable, which makes it hard to establish
296 what source code produced them.
297
298 @node Full Source Bootstrap,  , Bootstrappable Builds, Introduction
299 @section  Full Source Bootstrap
300
301 There is an obvious solution: we cannot allow any binary seeds in our
302 software stack.  Not even in the bootstrap binary seed.  Maybe that is a
303 bit too strong: we want to have the absolute minimum of binary seeds and
304 all binary seeds need to be inspectable and must be reviewed.  How big
305 would the absolute minimal set be?
306
307 @subsection The Magical Self-Hosting Hex Assembler
308
309 June 2016 I learnt about
310 @url{https://github.com/oriansj/stage0/,Stage0}.  Jeremiah Orians
311 created @file{hex0} a ~500 byte self-hosting hex assembler.  The source
312 code is well documented and the binary is the exact mirror of the source
313 code.  I was inspired.
314
315 Here is an example of what the @file{hex0} program looks like; the start
316 of the @var{hex} function
317
318 @example
319 00000060: 4883 f830 7c6f 4883 f83a 7c5a 4883 f841  H..0|oH..:|ZH..A
320 @dots{}
321 000000d0: 48c7 c0ff ffff ffc3 0000 0000 0000 0000  H...............
322 000000e0: 4883 e830 c300 0000 0000 0000 0000 0000  H..0............
323 @end example
324
325 All computer programs look like this: an opaque list of computer codes.
326 The initial programs that we take for granted---the bootstrap binary
327 seed---are about 250MB of such numbers: think 250,000 pages full of
328 numbers.
329
330 Most computers work pretty well so apparently there is not a pressing
331 need to inspect and study all of these codes.  At the same time it is
332 tricky to fully trust@footnote{ Ken Thompson's 1984 Turing award
333 acceptance speech
334 @url{http://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf,
335 Reflections on Trusting Tust}.} a computer that was bootstrapped in this
336 way.
337
338 Here is what the source code of the @file{hex0} assembler looks like
339
340 @example
341 ## function: hex
342 48 83 f8 30                # cmp $0x30,%rax
343 7c 6f                      # jl 6000f3 <ascii_other>
344 48 83 f8 3a                # cmp $0x3a,%rax
345 7c 5a                      # jl 6000e4 <ascii_num>
346 48 83 f8 41                # cmp $0x41,%rax
347 @dots{}
348 ## function: ascii_other
349 48 c7 c0 ff ff ff ff       # mov $0xffffffffffffffff,%rax
350 c3                         # ret
351 @dots{}
352 ## function: ascii_num
353 48 83 e8 30                # sub $0x30,%rax
354 c3                         # ret
355 @end example
356
357 While it may be hard to understand what this piece of the program does,
358 it should be possible for anyone to verify that the computer codes above
359 correspond to the source code with comments.
360
361 One step beyond these annotated codes is Assembly language.  To write a
362 program in Assembly, you only need to provide the instructions; the
363 codes are computed by the @file{assembler} program.
364
365 @example
366 hex:
367         # deal all ascii less than 0
368         cmp $48, %rax
369         jl ascii_other
370         # deal with 0-9
371         cmp $58, %rax
372         jl ascii_num
373 @dots{}
374 ascii_other:
375         mov $-1, %rax
376         ret
377 ascii_num:
378         sub $48, %rax
379         ret
380 @end example
381
382 More readable still, a similar program text in the C programming language.
383
384 @example
385 int
386 hex (int c)
387 @{
388   if (c >= '0' && c <= '9')
389     return c - 48;
390 @dots{}
391 @}
392 @end example
393
394 What if we could bootstrap our entire system from only this one
395 @file{hex0} assembler binary seed?  We would only ever need to inspect
396 these 500 bytes of computer codes.  Every@footnote{Some program
397 languages have become very hard or practically impossible to bootstrap.
398 Instead of depending on a simple language such as C, they depend on a
399 recent version of itself, or on other binary or ASCII seeds, on other
400 recent programs written in that language, or even on manual
401 intervention.  Programs written in a language that cannot be
402 bootstrapped can still run on our systems, but cannot enjoy any of the
403 trust we intend to create.} later program is written in a more friendly
404 programming language: Assembly, C, @dots{}  Scheme.
405
406 Inspecting all these programs is a lot of work, but it can certainly be
407 done.  We might be able to create a fully inspectable path from almost
408 nothing to all of the programs that our computer runs.  Something that
409 seemed to be an impossible dream is suddenly starting to look like
410 ``just a couple years of work''.
411
412 @node LISP as Maxwell's Equations of Software
413 @section LISP as Maxwell's Equations of Software
414
415 As fate would have it, I stumbled upon this
416 @url{https://queue.acm.org/detail.cfm?id=1039523, interview with Alan
417 Kay}, where he shares a revelation he had when reading John McCarthy's
418 @url{http://www.softwarepreservation.org/projects/LISP/book/LISP%201.5%20Programmers%20Manual.pdf,
419 LISP-1.5} manual:
420
421 @quotation
422 that was the big revelation to me @dots{} when I finally understood that
423 the half page of code on the bottom of page 13 of the Lisp 1.5 manual
424 was Lisp in itself.  These were “Maxwell’s Equations of Software!”  This
425 is the whole world of programming in a few lines that I can put my hand
426 over.
427
428 @author Alan Kay
429 @end quotation
430
431 Our starting point is @file{hex0}, a 500 byte hex assembler and we need
432 to somehow close the gap to building the bootstrap binary seed, esp. GNU
433 Gcc and the GNU C Library.  What better way to do that than by
434 leveraging the powers of LISP?
435
436 GNU Mes is a Scheme@footnote{Scheme is a modern LISP} interpreter that
437 will be indirectly bootstrapped from @file{hex0} and that wields the
438 magical powers of LISP to close the bootstrap gap, asserting we can
439 enjoy software Freedom 1.
440
441 @subsection Auditable Elegance
442
443 @code{eval} and @code{apply} are mutual recursing functions that---using
444 a few helper functions---describe the core of the universe of computing.
445
446 @lisp
447 (define (apply fn x a)
448   (cond
449    ((atom fn)
450     (cond
451      ((eq fn CAR)  (caar x))
452      ((eq fn CDR)  (cdar x))
453      ((eq fn CONS) (cons (car x) (cadr x)))
454      ((eq fn ATOM) (atom (car x)))
455      ((eq fn EQ)   (eq (car x) (cadr x)))
456      (#t           (apply (eval fn a) x a))))
457    ((eq (car fn) LAMBDA)
458                    (eval (caddr fn) (pairlis (cadr fn) x a)))
459    ((eq (car fn) LABEL)
460                    (apply (caddr fn) x
461                           (cons (cons (cadr fn) (caddr fn)) a)))))
462 @end lisp
463
464 @lisp
465 (define (eval e a)
466   (cond
467    ((atom e) (cdr (assoc e a)))
468    ((atom (car e))
469     (cond ((eq (car e) QUOTE) (cadr e))
470           ((eq (car e) COND)  (evcon (cdr e) a))
471           (#t                 (apply (car e) (evlis (cdr e) a) a))))
472    (#t       (apply (car e) (evlis (cdr e) a) a))))
473 @end lisp
474
475 It will be a big day when our computers are fully bootstrapped from
476 source.  It would be nice if that source code were readable, auditable
477 and elegant.  To be honest, the elegance displayed above that we
478 achieved at the very start of the Mes project is currently hard to find.
479 It is our sincerest hope to bring back this level of quality and
480 elegance..
481
482 @c *********************************************************************
483 @node Installation, Bootstrapping, Introduction, Top
484 @chapter Installation
485
486 @cindex installing Mes
487 Mes is available for download from its website at
488 @url{https://www.gnu.org/pub/gnu/mes/}.  This section describes the
489 software requirements of Mes, as well as how to install it and get ready
490 to use it.
491
492
493 @menu
494 * Regular Requirements::        Software needed to build and run Mes.
495 * Bootstrap Requirements::      Software needed to bootstrap Mes.
496 * Running the Test Suites::     Testing Mes.
497 @end menu
498
499 @node Regular Requirements, Bootstrap Requirements, Installation, Installation
500 @section Regular Requirements
501
502 This section lists requirements when building Mes from source.  The
503 build procedure for Mes is the same as for other GNU software, and is
504 not covered here.  Please see the files @file{README} and @file{INSTALL}
505 in the Mes source tree for additional details.
506
507 GNU Mes depends on the following packages:
508
509 @itemize
510 @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.13 or
511 later, including 2.2.x and 3.0.x,
512 @item @url{http://www.gnu.org/software/make/, GNU Make}.
513 @item @url{https://savannah.gnu.org/projects/nyacc/, NYACC}, version 1.00.2,
514 @item @url{http://gcc.gnu.org, GCC's gcc}, version 2.95.3 or later, including 10.2.0,
515 @item @url{https://savannah.gnu.org/projects/mescc-tools/, mescc-tools}, version 0.7.0 or later,
516 @end itemize
517
518 @cindex Guile, compatibility
519 Mes is compatible with GNU Guile, so it is possible to share the same
520 Scheme code between both.  Currently Mes only supports the minimal
521 subset of R5RS and Guile extensions to run MesCC.
522
523 @node Bootstrap Requirements, Running the Test Suites, Regular Requirements, Installation
524 @section Bootstrap Requirements
525
526 This section lists requirements when building Mes as a bootstrap
527 package.  The bootstrap build procedure for Mes is similar to building
528 GNU software and goes like this
529
530 @example
531 sh configure.sh --prefix=/your/prefix/here
532 sh bootstrap.sh
533 sh check.sh
534 sh install.sh
535 @end example
536
537 See @file{configure.sh} and @file{bootstrap.sh} for inspiration on what
538 environment variables to set.
539
540 Bootstrapping Mes depends on the following packages:
541
542 @itemize
543 @item a POSIX-compatible shell
544 @item @url{https://github.com/oriansj/mescc-tools/, mescc-tools}, version 0.6.1 or later.
545 @item @url{https://savannah.gnu.org/projects/nyacc/, NYACC}, 0.93.0 or later, including 0.99.0.
546 @end itemize
547
548 @node Running the Test Suites,  , Bootstrap Requirements, Installation
549 @section Running the Test Suites
550
551 @cindex test suites
552 After a successful @command{configure} and @code{make} run, it is a good
553 idea to run the test suites.
554
555 @example
556 make check
557 @end example
558
559 Run Mes Scheme language semantics tests (@file{scaffold/boot}) only
560
561 @example
562 build-aux/check-boot.sh
563 @end example
564
565 Run a single Mes boot test
566
567 @example
568 MES_BOOT=scaffold/boot/00-zero.scm bin/mes
569 @end example
570
571 Run a single Mes Scheme test
572
573 @example
574 ./pre-inst-env tests/boot.test
575 MES=guile ./pre-inst-env tests/boot.test
576 @end example
577
578 Run MesCC tests only
579
580 @example
581 build-aux/check-mescc.sh
582 @end example
583
584 Run a single MesCC test
585
586 @example
587 CC=gcc CC32=i686-unknown-linux-gnu-gcc MES=guile \
588   build-aux/test.sh scaffold/tests/00-exit-0
589 @end example
590
591 @node Bootstrapping, Contributing, Installation, Top
592 @chapter Bootstrapping
593
594 @quotation
595 Recipe for yogurt: Add yogurt to milk.
596
597 @author Anonymous
598 @end quotation
599
600 The bootstrap problem we have set out to solve is that none of our
601 modern software distributions, and Guix in particular, can be created
602 all from source code.  In addition to the carefully signed source code
603 of all the programs (the `milk') an opaque binary seed (the `yogurt') is
604 injected as an essential dependency.
605
606 Why would this be a problem, I hear you ask?  This is how it is done, we
607 always did it this way, everyone does it like this!  Indeed, a popular
608 way of handling the bootstrapping issue is by ignoring it.
609
610 @quotation
611 Your compiler becoming self-hosting@dots{}a language creator's wet
612 dream.
613
614 @author PFH
615 @end quotation
616
617 It seems that writing a self-hosting compiler is considered to be a
618 language creator's ultimate goal.  It means that their language and
619 compiler have become powerful enough to not depend on a pre-exising
620 language that possibly is---but certainly was until now---more
621 powerful; it feels like passing the rite to adulthood.
622
623 When you see the irony, you grasp what our bootstrapping effort means in
624 practice.  Creating bootstrappable software is not hard; actually most
625 softwares' first releases are bootstrappable.  The problem of
626 bootstrapping is not a technical one, it is a lack of awareness and
627 responsibility.
628
629 @menu
630 * The Mes Bootstrap Process::   How Mes will make you yogurt from pure milk.
631 * Invoking mes::                Running Mes, a minimalist Guile lookalike.
632 * Invoking mescc::              Running the MesCC bootstrap compiler.
633 * Invoking mesar::
634 @end menu
635
636 @node The Mes Bootstrap Process, Invoking mes, Bootstrapping, Bootstrapping
637 @section The Mes Bootstrap Process
638
639 The Reduced Binary Seed bootstrap currently adopted by Guix@footnote{See
640 @file{gnu/packages/commencement.scm} in the @var{master} branch in Guix
641 git
642 @url{http://git.savannah.gnu.org/cgit/guix.git/tree/gnu/packages/commencement.scm}}.
643 In its intiial form it is only available for x86-linux arm armhf-linux.
644
645 Currently, it goes like this:
646
647 @verbatim
648                          gcc-mesboot (4.9.4)
649                                 ^
650                                 |
651                         glibc-mesboot (2.16.0)
652                                 ^
653                                 |
654                          gcc-mesboot1 (4.7.4)
655                                 ^
656                                 |
657                         binutils-mesboot (2.20.1a)
658                                 ^
659                                 |
660                          gcc-mesboot0 (2.95.3)
661                                 ^
662                                 |
663                          glibc-mesboot0 (2.2.5)
664                                 ^
665                                 |
666                         gcc-core-mesboot (2.95.3)
667                                 ^
668                                 |
669     make-mesboot0, diffutils-mesboot, binutils-mesboot0 (2.20.1a)
670                                 ^
671                                 |
672                             tcc-boot
673                                 ^
674                                 |
675                             tcc-boot0
676                                 ^
677                                 |
678                             mes-boot
679                                 ^
680                                 |
681                                 *
682               bootstrap-mescc-tools, bootstrap-mes (~10MB)
683       bootstrap-bash, bootstrap-coreutils&co, bootstrap-guile (~120MB)
684 @end verbatim
685
686 @c This graph is generated from wip-bootstrap, doing:
687
688 @c ~/src/guix/core-updates/pre-inst-env guix graph --type=bag -e '(@@ (gnu packages commencement) gcc-mesboot)' > doc/images/gcc-mesboot-graph.dot
689 @c dot -T png doc/images/gcc-mesboot-graph.dot > doc/images/gcc-mesboot-graph.png
690
691 Here's a generated dependency diagram to for the final bootstrap gcc
692 that builds the rest of Guix.
693
694 @image{images/gcc-mesboot-graph,2in,,Reference graph of the gcc-mesboot}
695
696 Work is ongoing to remove these binary seeds that were intentionally
697 injected by our own doing as temporary shortcut
698 @example
699 bootstrap-mescc-tools (seed), bootstrap-mes (seed)
700 @end example
701
702 For now, these additional non-bootstrapped dependencies (i.e., binary
703 seeds) are taken for granted
704
705 @example
706 bootstrap-guile, bash, bzip2, coreutils, gawk, grep, gzip, patch, sed,
707 tar, xz
708 @end example
709
710 Although we think these are less essential and thus less interesting
711 than the GNU toolchain triplet that we focussed on initially, our next
712 priority is to eleminate these one by one.
713
714 @node Invoking mes, Invoking mescc, The Mes Bootstrap Process, Bootstrapping
715 @section Invoking mes
716
717 @cindex repl
718 The @command{mes} command is the Scheme interpreter whose prime
719 directive is to run the @command{MesCC} program.
720
721 For convenience and testing purposes, @command{mes} tries to mimic
722 guile.
723
724 @example
725 mes @var{option}@dots{} @file{FILE}@dots{}
726 @end example
727
728 The @var{option}s can be among the following:
729
730 @table @code
731
732 @item -s @var{script} @var{arg}@dots{}
733 @cindex script mode
734 By default, mes will read a file named on the command line as a script.
735 Any command-line arguments @var{arg}@dots{} following @var{script}
736 become the script's arguments; the @code{command-line} function returns
737 a list of strings of the form @code{(@var{script} @var{arg}@dots{})}.
738
739 Scripts are read and evaluated as Scheme source code just as the
740 @code{load} function would.  After loading @var{script}, mes exits.
741
742 @item -c @var{expr} @var{arg}@dots{}
743 @cindex evaluate expression, command-line argument
744 Evaluate @var{expr} as Scheme code, and then exit.  Any command-line
745 arguments @var{arg}@dots{}) following @var{expr} become command-line
746 arguments; the @code{command-line} function returns a list of strings of
747 the form @code{(@var{guile} @var{arg}@dots{})}, where @var{mes} is the
748 path of the mes executable.
749
750 @item -- @var{arg}@dots{}
751 Run interactively, prompting the user for expressions and evaluating
752 them.  Any command-line arguments @var{arg}@dots{} following the
753 @option{--} become command-line arguments for the interactive session;
754 the @code{command-line} function returns a list of strings of the form
755 @code{(@var{guile} @var{arg}@dots{})}, where @var{mes} is the path of the
756 mes executable.
757
758 @item -L,--load-path=@var{directory}
759 Add @var{directory} to the front of Mes module load path.  The given
760 directories are searched in the order given on the command line and
761 before any directories in the @env{GUILE_LOAD_PATH} environment
762 variable.
763
764 @item -C,--compiled-path=@var{directory}
765 Accepted and ignored for Guile compatibility.
766
767 @item -l @var{file}
768 Load Scheme source code from @var{file}, and continue processing the
769 command line.
770
771 @item -e,--main=@var{function}
772 Make @var{function} the @dfn{entry point} of the script.  After loading
773 the script file (with @option{-s}) or evaluating the expression (with
774 @option{-c}), apply @var{function} to a list containing the program name
775 and the command-line arguments---the list provided by the
776 @code{command-line} function.
777
778 @item -h@r{, }--help
779 Display help on invoking mes, and then exit.
780
781 @item -v@r{, }--version
782 Display the current version of mes%, and then exit.
783
784 @end table
785
786 @menu
787 * Environment Variables::       If the bits won't change, change their habitat.
788 @end menu
789
790 @node Environment Variables,  , Invoking mes, Invoking mes
791 @subsection Environment Variables
792 @cindex environment variables
793 @cindex shell
794 @cindex initialization
795
796 @c Hmm, I expected this paragraph in the Guix manual?
797 Here are the environment variables (see @pxref{Environment Variables,,,
798 guile, Guile Reference}) that affect the run-time behavior of
799 mes:
800
801 @table @env
802 @item MES_BOOT
803 @vindex MES_BOOT
804
805 Set @env{MES_BOOT} to change the initial Scheme program that mes runs.
806
807 @item MES_ARENA
808 @vindex MES_ARENA
809
810 The initial size of the arena @pxref{5.3,,, sicp, SICP} in cells.  Default: 20,000.
811
812 @item MES_MAX_ARENA
813 @vindex MES_MAX_ARENA
814
815 The maximum size of the arena in cells.  Default: 100,000,000.
816
817 @item MES_MAX_STRING
818 @vindex MES_MAX_STRING
819
820 The maximum size of a string.  Default: 524,288.
821
822 @item MES_DEBUG
823 @vindex MES_DEBUG
824
825 @enumerate
826 @item
827   Informational:
828 @itemize
829 @item MODULEDIR
830 @item included SCM modules and sources
831 @item result of program
832 @item gc stats at exit
833 @end itemize
834 @item
835 opened files
836
837 @item
838 runtime gc stats
839
840 @item
841 detailed info
842 @itemize
843 @item parsed, expanded program
844 @item list of builtins
845 @item list of symbol
846 @item opened input strings
847 @item gc details
848 @end itemize
849
850 @item
851 usage of opened input strings
852 @end enumerate
853
854
855 @item GUILE_LOAD_PATH
856 @vindex GUILE_LOAD_PATH
857 This variable may be used to augment the path that is searched for
858 Scheme files when loading.  Its value should be a colon-separated list
859 of directories.  If it contains the special path component @code{...}
860 (ellipsis), then the default path is put in place of the ellipsis,
861 otherwise the default path is placed at the end.  The result is stored
862 in @code{%load-path}.
863
864 Mes uses @var{@strong{GUILE}_LOAD_PATH} for compatibility with Guile.
865
866 @end table
867
868 @node Invoking mescc, Invoking mesar, Invoking mes, Bootstrapping
869 @section Invoking mescc
870
871 @example
872 mescc @var{option}@dots{} @file{FILE}@dots{}
873 @end example
874
875 The @var{option}s can be among the following:
876
877 @table @code
878
879 @item --align=@var{symbol}
880 align @var{symbol}, the default is @code{functions}; other valid values
881 are: @code{globals}.
882
883 @item --base-address=ADRRESS
884 use BaseAddress ADDRESS [0x1000000]
885
886 @item -c
887 @cindex compile
888 preprocess, compile and assemble only; do not link
889
890 @item -D @var{DEFINE}[=@var{VALUE}]
891 @cindex define DEFINE [VALUE=1]
892
893 @item -dumpmachine
894 @cindex arch
895 @cindex architecture
896 @cindex machine
897 display the compiler's target processor
898
899 @item -E
900 preprocess only; do not compile, assemble or link
901
902 @item -g
903 add @command{blood-elf} debug info
904
905 This enables GDB setting breakpoints on function names, and to have the
906 GDB backtrace command to show the function call stack.
907
908 @item -h, --help
909 display this help and exit
910
911 @item -I DIR
912 append DIR to include path
913
914 @item -L DIR
915 append DIR to library path
916
917 @item -l LIBNAME
918 link with LIBNAME
919
920 @item -m BITS
921 compile for BITS bits [32]
922
923 @item -O LEVEL
924 use optimizing LEVEL
925
926 @item -o FILE
927 write output to FILE
928
929 @item -S
930 preprocess and compile only; do not assemble or link
931
932 @item --std=STANDARD
933 assume that the input sources are for STANDARD
934
935 @item -V,--version
936 display version and exit
937
938 @item -w,--write=TYPE
939 dump Nyacc AST using TYPE @{pretty-print,write@}
940
941 @item -x LANGUAGE
942 specify LANGUAGE of the following input files
943
944 @end table
945
946 @menu
947 * MesCC Environment Variables::  There's no NIX like POSIX.
948 @end menu
949
950 @node MesCC Environment Variables,  , Invoking mescc, Invoking mescc
951 @subsection MesCC Environment Variables
952
953 @table @env
954 @item MES
955 @vindex MES
956
957 Setting @env{MES} to a mes-compatible Scheme will run mescc using that
958 @example
959 MES=guile mescc -c scaffold/main.c
960 @end example
961
962 See, now Guile has become compatible with Mes, instead of the other way
963 around ;-)
964
965 @item C_INCLUDE_PATH
966 @vindex C_INCLUDE_PATH
967
968 @item LIBRARY_PATH
969 @vindex LIBRARY_PATH
970
971 @item NYACC_DEBUG
972 @vindex NYACC_DEBUG
973
974 Setting @env{NYACC_DEBUG} makes nyacc print names of function
975 during the parsing phase.
976
977 @end table
978
979 @node Invoking mesar,  , Invoking mescc, Bootstrapping
980 @section Invoking mesar
981
982 @example
983 mesar @var{option}@dots{} @var{command} @file{ARCHIVE-FILE} @file{FILE}@dots{}
984 @end example
985
986 The @var{command} is ignored for compatibility with @file{ar}
987
988 @example
989   r[ab][f][u]  - replace existing or insert new file(s) into the archive
990   [c]          - do not warn if the library had to be created
991   [D]          - use zero for timestamps and uids/gids (default)
992 @end example
993
994 and assumed to be @var{crD}.
995
996 The @var{option}s can be among the following:
997
998 @table @code
999
1000 @item -h, --help
1001 display this help and exit
1002
1003 @item -V,--version
1004 display version and exit
1005
1006 @end table
1007
1008 @c *********************************************************************
1009 @node Contributing, Acknowledgments, Bootstrapping, Top
1010 @chapter Contributing
1011
1012 @menu
1013 * Building from Git::           The latest and greatest.
1014 * Running Mes From the Source Tree::  Hacker tricks.
1015 * Porting GNU Mes::             Teach Mes about your platform.
1016 * The Perfect Setup::           The right tools.
1017 * Coding Style::                Hygiene of the contributor.
1018 * Submitting Patches::          Share your work.
1019 @end menu
1020
1021 @node Building from Git, Running Mes From the Source Tree, Contributing, Contributing
1022 @section Building from Git
1023
1024 If you want to hack GNU Mes itself, it is recommended to use the latest
1025 version from the Git repository:
1026
1027 @example
1028 git clone git://git.savannah.gnu.org/mes.git
1029 @end example
1030
1031 The easiest way to set up a development environment for Mes is, of
1032 course, by using Guix!  The following command starts a new shell where
1033 all the dependencies and appropriate environment variables are set up to
1034 hack on Mes:
1035
1036 @example
1037 guix environment -l .guix.scm
1038 @end example
1039
1040 Finally, you have to invoke @code{make check} to run tests
1041 (@pxref{Running the Test Suites}).  If anything fails, take a look at
1042 installation instructions (@pxref{Installation}) or send a message to
1043 the @email{bug-mes@@gnu.org} mailing list.
1044
1045 @node Running Mes From the Source Tree, Porting GNU Mes, Building from Git, Contributing
1046 @section Running Mes From the Source Tree
1047
1048 First, you need to have an environment with all the dependencies
1049 available (@pxref{Building from Git}), and then simply prefix each
1050 command by @command{./pre-inst-env} (the @file{pre-inst-env} script
1051 lives in the top build tree of Mes).
1052
1053 @node Porting GNU Mes, The Perfect Setup, Running Mes From the Source Tree, Contributing
1054 @section Porting GNU Mes
1055
1056 Mes is supported for x86-linux and armhf-linux.  A 64 bit (x86_64-linux)
1057 is almost done, only a few bugs remain.  The Guix bootstrap for
1058 x86_64-linux uses mes for x86-lunix and that is not expected to change.
1059 Likewise, aarch64-linux uses mes for armhf-linux.
1060
1061 A port to GNU/Hurd (x86-gnu) is underway.
1062
1063 Initial scaffold, built by @file{build-aux/build-scaffold.sh}:
1064 @example
1065   @file{lib/linux/x86-mes-gcc/exit-42.S}
1066   @file{lib/linux/x86-mes/elf32-0exit-42.hex2}
1067   @file{lib/linux/x86-mes/elf32-body-exit-42.hex2}
1068
1069   @file{lib/linux/x86-mes-gcc/hello-mes.S}
1070   @file{lib/linux/x86-mes/elf32-0hello-mes.hex2}
1071   @file{lib/linux/x86-mes/elf32-body-hello-mes.hex2}
1072 @end example
1073
1074 Porting MesCC:
1075 @example
1076   @file{lib/x86-mes/x86.M1}
1077
1078   @file{module/mescc/mescc.scm}
1079   @file{module/mescc/i386/as.scm}
1080   @file{module/mescc/i386/info.scm}
1081
1082   @file{mes/module/mescc/i386/as.mes}
1083   @file{mes/module/mescc/i386/info.mes}
1084 @end example
1085
1086 @node The Perfect Setup, Coding Style, Porting GNU Mes, Contributing
1087 @section The Perfect Setup
1088
1089 The Perfect Setup to hack on Mes is basically the perfect setup used
1090 for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
1091 Manual}).  First, you need more than an editor, you need
1092 @url{http://www.gnu.org/software/emacs, Emacs}, empowered by the
1093 wonderful @url{http://nongnu.org/geiser/, Geiser}.
1094
1095 Geiser allows for interactive and incremental development from within
1096 Emacs: code compilation and evaluation from within buffers, access to
1097 on-line documentation (docstrings), context-sensitive completion,
1098 @kbd{M-.} to jump to an object definition, a REPL to try out your code,
1099 and more (@pxref{Introduction,,, geiser, Geiser User Manual}).
1100
1101 @node Coding Style, Submitting Patches, The Perfect Setup, Contributing
1102 @section Coding Style
1103
1104 In general our code follows the GNU Coding Standards (@pxref{Top,,,
1105 standards, GNU Coding Standards}).  However, they do not say much about
1106 Scheme, so here are some additional rules.
1107
1108 @subsection Programming Paradigm
1109
1110 Scheme code in Mes is written in a purely functional style.
1111
1112 @subsection Formatting Code
1113
1114 @cindex formatting code
1115 @cindex coding style
1116 When writing Scheme code, we follow common wisdom among Scheme
1117 programmers.  In general, we follow the
1118 @url{http://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
1119 Style Rules}.  This document happens to describe the conventions mostly
1120 used in Guile’s code too.  It is very thoughtful and well written, so
1121 please do read it.
1122
1123 @cindex indentation, of code
1124 @cindex formatting, of code
1125 If you do not use Emacs, please make sure to let your editor knows these
1126 rules.
1127
1128 Additionally, in Mes we prefer to format @code{if} statements like this
1129 @example
1130 (if foo? trivial-then
1131     (let ((bar (the-longer @dots{})))
1132       more-complicated
1133       @dots{}
1134       else))
1135 @end example
1136
1137 @node Submitting Patches,  , Coding Style, Contributing
1138 @section Submitting Patches
1139
1140 Development is done using the Git distributed version control system.
1141 Thus, access to the repository is not strictly necessary.  We welcome
1142 contributions in the form of patches as produced by @code{git
1143 format-patch} sent to the @email{bug-mes@@gnu.org} mailing list.
1144
1145 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
1146 standards, GNU Coding Standards}); you can check the commit history for
1147 examples.
1148
1149 @subsection Reporting Bugs
1150
1151 Encountering a problem or bug can be very frustrating for you as a user
1152 or potential contributor.  For us as Mes maintainers, the preferred bug
1153 report includes a beautiful and tested patch that we can integrate
1154 without any effort.
1155
1156 However, please don't let our preference stop you from reporting a bug.
1157 There's one thing @emph{much} worse for us than getting a bug report
1158 without a patch: Reading a complaint or rant online about your
1159 frustrations and how our work sucks, without having heard directly what
1160 you experienced.
1161
1162 So if you report a problem, will it be fixed?  And @strong{when}?  The
1163 most honest answer is: It depends.  Let's curry that informationless
1164 honesty with a more helpful and more blunt reminder of a mantra of free
1165 software:
1166
1167 @quotation
1168 @table @strong
1169 @item Q:
1170 When will it be finished?
1171
1172 @item A:
1173 It will be ready sooner if you help.
1174 @end table
1175
1176 @author Richard Stallman
1177 @end quotation
1178
1179 @cindex contact, irc, mailing list
1180 Join us on @code{#bootstrappable} on the Libera Chat IRC network or on
1181 @email{bug-mes@@gnu.org} to share your experience---good or bad.
1182
1183 @cindex bug, bug report, reporting a bug
1184 Please send bug reports with full details to @email{bug-mes@@gnu.org}.
1185
1186 @c *********************************************************************
1187 @node Acknowledgments, Resources, Contributing, Top
1188 @chapter Acknowledgments
1189
1190 We would like to thank the following people for their help: Jeremiah
1191 Orians, Peter de Wachter, rain1, Ricardo Wurmus, Rutger van Beusekom.
1192
1193 We also thank Ludovic Courtès for creating GNU Guix and making the
1194 bootstrap problem so painfully visible, John McCarthy for creating
1195 LISP-1.5 and Alan Kay for their inspiring comment on
1196 @url{https://queue.acm.org/detail.cfm?id=1039523, Page 13}.
1197
1198 @c *********************************************************************
1199 @node Resources, GNU Free Documentation License, Acknowledgments, Top
1200 @chapter Resources
1201
1202 @itemize
1203
1204 @item
1205 @url{https://bootstrappable.org, Bootstrappable Builds} Minimize the
1206 amount and size of opaque binary seeds we need to swallow.
1207
1208 @item
1209 @url{https://reproducible-builds.org, Reproducible Builds}
1210 Provide a verifiable path from source code to binary.
1211
1212 @item
1213 @url{https://gitlab.com/oriansj/stage0, Stage0}
1214 If we want, it could all start with a ~500 byte self-hosting hex
1215 assembler.
1216
1217 @item
1218 @url{https://bootstrapping.miraheze.org, Bootstrapping wiki} An amazing
1219 collection of small/bootstrappable compilers, operating systems,
1220 anything you need.
1221
1222 @item
1223 @url{irc.libera.chat, #bootstrappable} The bootstrapping community home
1224 at the Libera Chat IRC network.
1225
1226 @item
1227 @file{guix-devel@@gnu.org} The Guix mailing list, where it all started.
1228 @url{https://lists.gnu.org/archive/html/guix-devel/, guix-devel archives}.
1229
1230 @end itemize
1231
1232 @c *********************************************************************
1233 @node GNU Free Documentation License, Concept Index, Resources, Top
1234 @appendix GNU Free Documentation License
1235 @cindex license, GNU Free Documentation License
1236 @include fdl-1.3.texi
1237
1238 @c *********************************************************************
1239 @node Concept Index, Programming Index, GNU Free Documentation License, Top
1240 @unnumbered Concept Index
1241 @printindex cp
1242
1243 @node Programming Index,  , Concept Index, Top
1244 @unnumbered Programming Index
1245 @syncodeindex tp fn
1246 @syncodeindex vr fn
1247 @printindex fn
1248
1249 @bye
1250
1251 @c Local Variables:
1252 @c ispell-local-dictionary: "american";
1253 @c End: