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