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