mescc: Mes C Library: Fix qsort to support duplicate entries.
[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 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 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 GNU 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%201.5%20Programmers%20Manual.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 GNU Mes is a Scheme@footnote{Scheme is a modern LISP} interpreter that
305 will be indirectly bootstrapped from @file{hex0} and that wields the
306 magical powers of LISP to close the bootstrap gap, asserting we can
307 enjoy software Freedom 1.
308
309 @c *********************************************************************
310 @node Installation
311 @chapter Installation
312
313 @cindex installing Mes
314 Mes is available for download from its website at
315 @url{http://www.gnu.org/pub/gnu/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 GNU 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.17 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 This graph is generated from wip-bootstrap, doing:
505
506 @c sed -i s,package-with-bootstrap-guile,identity, gnu/packages/{commencement,mes}.scm
507
508 @c ~/src/guix-bootstrap/pre-inst-env guix graph gcc-mesboot > doc/images/gcc-mesboot-graph.dot
509 @c dot -T png doc/images/gcc-mesboot-graph.dot > doc/images/gcc-mesboot-graph.png
510
511 Here's a generated dependency diagram to give you impression, it is not
512 complete or correct.
513
514 @image{images/gcc-mesboot-graph,2in,,Reference graph of the gcc-mesboot}
515
516 Work is ongoing to remove these binary seeds that were intentionally
517 injected by our own doing as temporary shortcut
518 @example
519 mescc-tools-seed, mes-seed, tinycc-seed
520 @end example
521
522 These additional non-bootstrapped dependencies (i.e., binary seeds) are
523 taken for granted
524
525 @example
526 BOOTSTRAP-GUILE, flex, bash,
527 bzip2, coreutils, diffutils, gawk, grep, gzip, make, sed, tar
528 @end example
529
530 Although we think these are less essential and thus less interesting
531 than the GNU toolchain triplet that we focussed on initially, our next
532 priority is to eleminate these one by one.
533
534 @node Invoking Mes
535 @section Invoking Mes
536
537 @cindex repl
538 The @command{mes} command is the Scheme interpreter whose prime
539 directive is to run the @command{MesCC} program.
540
541 For convenience and testing purposes, @command{mes} tries to mimic
542 Guile.
543
544 @example
545 mes @var{option}@dots{} @file{FILE}@dots{}
546 @end example
547
548 The @var{option}s can be among the following:
549
550 @table @code
551
552 @item -s @var{script} @var{arg}@dots{}
553 @cindex script mode
554 By default, Mes will read a file named on the command line as a script.
555 Any command-line arguments @var{arg}@dots{} following @var{script}
556 become the script's arguments; the @code{command-line} function returns
557 a list of strings of the form @code{(@var{script} @var{arg}@dots{})}.
558
559 Scripts are read and evaluated as Scheme source code just as the
560 @code{load} function would.  After loading @var{script}, Mes exits.
561
562 @item -c @var{expr} @var{arg}@dots{}
563 @cindex evaluate expression, command-line argument
564 Evaluate @var{expr} as Scheme code, and then exit.  Any command-line
565 arguments @var{arg}@dots{}) following @var{expr} become command-line
566 arguments; the @code{command-line} function returns a list of strings of
567 the form @code{(@var{guile} @var{arg}@dots{})}, where @var{mes} is the
568 path of the Mes executable.
569
570 @item -- @var{arg}@dots{}
571 Run interactively, prompting the user for expressions and evaluating
572 them.  Any command-line arguments @var{arg}@dots{} following the
573 @option{--} become command-line arguments for the interactive session;
574 the @code{command-line} function returns a list of strings of the form
575 @code{(@var{guile} @var{arg}@dots{})}, where @var{mes} is the path of the
576 Mes executable.
577
578 @item -L,--load-path=@var{directory}
579 Add @var{directory} to the front of Mes module load path.  The given
580 directories are searched in the order given on the command line and
581 before any directories in the @env{GUILE_LOAD_PATH} environment
582 variable.
583
584 @item -C,--compiled-path=@var{directory}
585 Accepted and ignored for Guile compatibility.
586
587 @item ---dump
588 dump binary program to stdout
589
590 @item -l @var{file}
591 Load Scheme source code from @var{file}, and continue processing the
592 command line.
593
594 @item -e,--main=@var{function}
595 Make @var{function} the @dfn{entry point} of the script.  After loading
596 the script file (with @option{-s}) or evaluating the expression (with
597 @option{-c}), apply @var{function} to a list containing the program name
598 and the command-line arguments---the list provided by the
599 @code{command-line} function.
600
601 @item -h@r{, }--help
602 Display help on invoking Mes, and then exit.
603
604 @item ---load
605 load binary program [module/mes/boot-0.32-mo]
606
607 @item -v@r{, }--version
608 Display the current version of Mes, and then exit.
609
610 @end table
611
612 @menu
613 * Environment Variables::       If the bits won't change, change their habitat.
614 @end menu
615
616 @node Environment Variables
617 @subsection Environment Variables
618 @cindex environment variables
619 @cindex shell
620 @cindex initialization
621
622 @c Hmm, I expected this paragraph in the Guix manual?
623 Here are the environment variables (see @pxref{Environment Variables,,,
624 guile, Guile Reference}) that affect the run-time behavior of
625 Mes:
626
627 @table @env
628 @item MES_BOOT
629 @vindex MES_BOOT
630
631 Set @env{MES_BOOT} to change the initial Scheme program that Mes runs.
632
633 @item MES_ARENA
634 @vindex MES_ARENA
635
636 The initial size of the arena @pxref{5.3,,, sicp, SICP} in cells.  Default: 20,000.
637
638 @item MES_MAX_ARENA
639 @vindex MES_MAX_ARENA
640
641 The maximum size of the arena in cells.  Default: 100,000,000.
642
643 @item MES_DEBUG
644 @vindex MES_DEBUG
645
646 @enumerate
647 @item
648   Informational:
649 @itemize
650 @item MODULEDIR
651 @item included SCM modules and sources
652 @item result of program
653 @item gc stats at exit
654 @end itemize
655 @item
656 opened files
657
658 @item
659 runtime gc stats
660
661 @item
662 detailed info
663 @itemize
664 @item parsed, expanded program
665 @item list of builtins
666 @item list of symbol
667 @item opened input strings
668 @item gc details
669 @end itemize
670
671 @item
672 usage of opened input strings
673 @end enumerate
674
675
676 @item GUILE_LOAD_PATH
677 @vindex GUILE_LOAD_PATH
678 This variable may be used to augment the path that is searched for
679 Scheme files when loading.  Its value should be a colon-separated list
680 of directories.  If it contains the special path component @code{...}
681 (ellipsis), then the default path is put in place of the ellipsis,
682 otherwise the default path is placed at the end.  The result is stored
683 in @code{%load-path}.
684
685 Mes uses @var{@strong{GUILE}_LOAD_PATH} for compatibility with Guile.
686
687 @end table
688
689 @node Invoking MesCC
690 @section Invoking MesCC
691
692 @example
693 mescc @var{option}@dots{} @file{FILE}@dots{}
694 @end example
695
696 The @var{option}s can be among the following:
697
698 @table @code
699
700 @item -c
701 @cindex compile
702 preprocess, compile and assemble only; do not link
703
704 @item -D @var{DEFINE}[=@var{VALUE}]
705 @cindex define DEFINE [VALUE=1]
706
707 @item -E
708 preprocess only; do not compile, assemble or link
709
710 @item -g
711 add @command{blood-elf} debug info
712
713 This enables GDB setting breakpoints on function names, and to have the
714 GDB backtrace command to show the function call stack.
715
716 @item -h, --help
717 display this help and exit
718
719 @item -I DIR
720 append DIR to include path
721
722 @item -L DIR
723 append DIR to library path
724
725 @item -l LIBNAME
726 link with LIBNAME
727
728 @item -o FILE
729 write output to FILE
730
731 @item -S
732 preprocess and compile only; do not assemble or link
733
734 @item -v, --version
735 display version and exit
736
737 @item -w,--write=TYPE
738 dump Nyacc AST using TYPE @{pretty-print,write@}
739
740 @end table
741
742 @menu
743 * MesCC Environment Variables::  There's no NIX like POSIX.
744 @end menu
745
746 @node MesCC Environment Variables
747 @subsection MesCC Environment Variables
748
749 @table @env
750 @item MES
751 @vindex MES
752
753 Setting @env{MES} to a mes-compatible Scheme will run MesCC using that
754 @example
755 MES=guile mescc -c scaffold/main.c
756 @end example
757
758 See, now Guile has become compatible with Mes, instead of the other way
759 around ;-)
760
761 @item C_INCLUDE_PATH
762 @vindex C_INCLUDE_PATH
763
764 @item LIBRARY_PATH
765 @vindex LIBRARY_PATH
766
767 @item NYACC_DEBUG
768 @vindex NYACC_DEBUG
769
770 Setting @env{NYACC_DEBUG} makes nyacc print names of function
771 during the parsing phase.
772
773 @end table
774
775
776 @c *********************************************************************
777 @node Contributing
778 @chapter Contributing
779
780 @menu
781 * Building from Git::           The latest and greatest.
782 * Running Mes From the Source Tree::  Hacker tricks.
783 * The Perfect Setup::           The right tools.
784 * Coding Style::                Hygiene of the contributor.
785 * Submitting Patches::          Share your work.
786 @end menu
787
788 @node Building from Git
789 @section Building from Git
790
791 If you want to hack GNU Mes itself, it is recommended to use the latest
792 version from the Git repository:
793
794 @example
795 git clone git://git.savannah.gnu.org/mes.git
796 @end example
797
798 The easiest way to set up a development environment for Mes is, of
799 course, by using Guix!  The following command starts a new shell where
800 all the dependencies and appropriate environment variables are set up to
801 hack on Mes:
802
803 @example
804 guix environment -l guix.scm
805 @end example
806
807 Finally, you have to invoke @code{make check} to run tests
808 (@pxref{Running the Test Suites}).  If anything fails, take a look at
809 installation instructions (@pxref{Installation}) or send a message to
810 the @email{bug-mes@@gnu.org} mailing list.
811
812 @node Running Mes From the Source Tree
813 @section Running Mes From the Source Tree
814
815 First, you need to have an environment with all the dependencies
816 available (@pxref{Building from Git}), and then simply prefix each
817 command by @command{./pre-inst-env} (the @file{pre-inst-env} script
818 lives in the top build tree of Mes).
819
820 @node The Perfect Setup
821 @section The Perfect Setup
822
823 The Perfect Setup to hack on Mes is basically the perfect setup used
824 for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
825 Manual}).  First, you need more than an editor, you need
826 @url{http://www.gnu.org/software/emacs, Emacs}, empowered by the
827 wonderful @url{http://nongnu.org/geiser/, Geiser}.
828
829 Geiser allows for interactive and incremental development from within
830 Emacs: code compilation and evaluation from within buffers, access to
831 on-line documentation (docstrings), context-sensitive completion,
832 @kbd{M-.} to jump to an object definition, a REPL to try out your code,
833 and more (@pxref{Introduction,,, geiser, Geiser User Manual}).
834
835 @node Coding Style
836 @section Coding Style
837
838 In general our code follows the GNU Coding Standards (@pxref{Top,,,
839 standards, GNU Coding Standards}).  However, they do not say much about
840 Scheme, so here are some additional rules.
841
842 @subsection Programming Paradigm
843
844 Scheme code in Mes is written in a purely functional style.
845
846 @subsection Formatting Code
847
848 @cindex formatting code
849 @cindex coding style
850 When writing Scheme code, we follow common wisdom among Scheme
851 programmers.  In general, we follow the
852 @url{http://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
853 Style Rules}.  This document happens to describe the conventions mostly
854 used in Guile’s code too.  It is very thoughtful and well written, so
855 please do read it.
856
857 @cindex indentation, of code
858 @cindex formatting, of code
859 If you do not use Emacs, please make sure to let your editor knows these
860 rules.
861
862 Additionally, in Mes we prefer to format @code{if} statements like this
863 @example
864 (if foo? trivial-then
865     (let ((bar (the-longer @dots{})))
866       more-complicated
867       @dots{}
868       else))
869 @end example
870
871 @node Submitting Patches
872 @section Submitting Patches
873
874 Development is done using the Git distributed version control system.
875 Thus, access to the repository is not strictly necessary.  We welcome
876 contributions in the form of patches as produced by @code{git
877 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
878
879 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
880 standards, GNU Coding Standards}); you can check the commit history for
881 examples.
882
883 @subsection Reporting Bugs
884
885 Encountering a problem or bug can be very frustrating for you as a user
886 or potential contributor.  For us as Mes maintainers, the preferred bug
887 report includes a beautiful and tested patch that we can integrate
888 without any effort.
889
890 However, please don't let our preference stop you from reporting a bug.
891 There's one thing @emph{much} worse for us than getting a bug report
892 without a patch: Reading a complaint or rant online about your pain and
893 how our work sucks, without having heard directly what you experienced.
894
895 So if you report a problem, will it be fixed?  And @strong{when}?  The
896 most honest answer is: It depends.  Let's curry that informationless
897 honesty with a more helpful and more blunt reminder of a mantra of Free
898 Software:
899
900 @quotation
901 @table @strong
902 @item Q:
903 When@dots{}?
904
905 @item A:
906 @dots{}sooner if you help.
907 @end table
908
909 @author Eric Raymond
910 @end quotation
911
912 @cindex contact, irc, mailing list
913 Join us on @code{#bootstrappable} on the Freenode IRC network or on
914 @email{guix-devel@@gnu.org} to share your experience---good or bad.
915
916 @cindex bug, bug report, reporting a bug
917 Please send bug reports with full details to @email{bug-mes@@gnu.org}.
918
919 @c *********************************************************************
920 @node Acknowledgments
921 @chapter Acknowledgments
922
923 We would like to thank the following people for their help: Jeremiah
924 Orians, pdewacht, rain1, Ricardo Wurmus, Rutger van Beusekom.
925 w
926 We also thank Ludovic Courtès for creating GuixSD and making the
927 bootstrap problem so painfully visible, John McCarthy for creating
928 LISP-1.5 and Alan Kay for their inspiring comment on
929 @url{https://queue.acm.org/detail.cfm?id=1039523, Page 13}.
930
931 @c *********************************************************************
932 @node Resources
933 @chapter Resources
934
935 @itemize
936
937 @item
938 @url{https://bootstrappable.org, Bootstrappable Builds} Minimize the
939 amount and size of opaque binary seeds we need to swallow.
940
941 @item
942 @url{https://reproducible-builds.org, Reproducible Builds}
943 Provide a verifiable path from source code to binary.
944
945 @item
946 @url{https://gitlab.com/oriansj/stage0, Stage0}
947 If we want, it could all start with a ~500 byte self-hosting hex
948 assembler.
949
950 @item
951 @url{https://bootstrapping.miraheze.org, Bootstrapping wiki} An amazing
952 collection of small/bootstrappable compilers, operating systems,
953 anything you need.
954
955 @item
956 @url{irc.freenode.net, #bootstrappable} The bootstrapping community home
957 at the freenode IRC network.
958
959 @item
960 @file{guix-devel@@gnu.org} The Guix mailing list, where it all started.
961 @url{https://lists.gnu.org/archive/html/guix-devel/, guix-devel archives}.
962
963 @end itemize
964
965 @c *********************************************************************
966 @node GNU Free Documentation License
967 @appendix GNU Free Documentation License
968 @cindex license, GNU Free Documentation License
969 @include fdl-1.3.texi
970
971 @c *********************************************************************
972 @node Concept Index
973 @unnumbered Concept Index
974 @printindex cp
975
976 @node Programming Index
977 @unnumbered Programming Index
978 @syncodeindex tp fn
979 @syncodeindex vr fn
980 @printindex fn
981
982 @bye
983
984 @c Local Variables:
985 @c ispell-local-dictionary: "american";
986 @c End: