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