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