a4943c1db1
* doc/mes.texi: Remarks from Rutger.
984 lines
30 KiB
Plaintext
984 lines
30 KiB
Plaintext
\input texinfo
|
||
@c -*- mode: texinfo; -*-
|
||
|
||
@c %**start of header
|
||
@setfilename mes.info
|
||
@documentencoding UTF-8
|
||
@settitle Mes Reference Manual
|
||
@c %**end of header
|
||
|
||
@include version.texi
|
||
|
||
@c Identifier of the OpenPGP key used to sign tarballs and such.
|
||
@set OPENPGP-SIGNING-KEY-ID 1A858392E331EAFDB8C27FFBF3C1A0D9C1D65273
|
||
|
||
@copying
|
||
Copyright @copyright{} 2018 Jan (janneke) Nieuwenhuizen@*
|
||
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
any later version published by the Free Software Foundation; with no
|
||
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
||
copy of the license is included in the section entitled ``GNU Free
|
||
Documentation License''.
|
||
@end copying
|
||
|
||
@dircategory Bootstrapping
|
||
@direntry
|
||
* Mes: (mes). A system bootstrap worthy of GNU.
|
||
|
||
|
||
* mes: (mes)Invoking mes. Running Mes, a minimalist Guile lookalike.
|
||
* mescc: (mes)Invoking MesCC. Running the MesCC bootstrap compiler.
|
||
@end direntry
|
||
|
||
@titlepage
|
||
@title Mes Reference Manual
|
||
@subtitle Full Source Bootstrapping of the GNU GuixSD Operating System
|
||
@author Jan (janneke) Nieuwenhuizen
|
||
|
||
@page
|
||
@vskip 0pt plus 1filll
|
||
Edition @value{EDITION} @*
|
||
@value{UPDATED} @*
|
||
|
||
@insertcopying
|
||
@end titlepage
|
||
|
||
@contents
|
||
|
||
@c *********************************************************************
|
||
@node Top
|
||
@top Mes
|
||
|
||
This document describes Mes version @value{VERSION}, a bootstrappable
|
||
Scheme interpreter and C compiler written for bootstrapping the GNU system.
|
||
|
||
@menu
|
||
* Introduction:: What is Mes about?
|
||
* Installation:: Installing Mes.
|
||
* Bootstrapping:: Would you strap my boots?
|
||
* Contributing:: Your help needed!
|
||
* Acknowledgments:: Thanks!
|
||
* Resources::
|
||
* GNU Free Documentation License:: The license of this manual.
|
||
* Concept Index:: Concepts.
|
||
* Programming Index:: Data types, functions, and variables.
|
||
|
||
@detailmenu
|
||
--- The Detailed Node Listing ---
|
||
|
||
Software Freedom
|
||
|
||
* Reproducible Builds:: Reproducibility and free software.
|
||
* Bootstrappable Builds:: The freedom to build a software without binary seed.
|
||
* Full Source Bootstrap:: Software dependencies worthy of GNU.
|
||
|
||
Installation
|
||
|
||
* Regular Requirements:: Software needed to build and run Mes.
|
||
* Bootstrap Requirements:: Software needed to bootstrap Mes.
|
||
* Running the Test Suites:: Testing Mes.
|
||
|
||
Bootstrapping
|
||
|
||
* The Mes Bootstrap Process:: How Mes will make you yogurt from pure milk.
|
||
* Invoking Mes:: Running Mes, a minimalist Guile lookalike.
|
||
* Invoking MesCC:: Running the MesCC bootstrap compiler.
|
||
|
||
Invoking Mes
|
||
|
||
* Environment Variables:: If the bits won't change, change their habitat.
|
||
|
||
Invoking MesCC
|
||
|
||
* MesCC Environment Variables:: There's no NIX like POSIX.
|
||
|
||
Contributing
|
||
|
||
* Building from Git:: The latest and greatest.
|
||
* Running Mes From the Source Tree:: Hacker tricks.
|
||
* The Perfect Setup:: The right tools.
|
||
* Coding Style:: Hygiene of the contributor.
|
||
* Submitting Patches:: Share your work.
|
||
|
||
@end detailmenu
|
||
@end menu
|
||
|
||
@c *********************************************************************
|
||
@node Introduction
|
||
@chapter Introduction
|
||
|
||
@quotation
|
||
These were “Maxwell’s Equations of Software!”
|
||
|
||
@author Alan Kay
|
||
@end quotation
|
||
|
||
Mes@footnote{``Mes'' is an acronym for the Maxwell Equations of
|
||
Software.} consists of a mutual self-hosting Scheme interpreter written
|
||
in C and a Nyacc-based (see @pxref{NYACC User's Guide,,, nyacc-ug, NYACC
|
||
User's Guide}) C compiler written in Scheme.
|
||
|
||
The Scheme interpreter @file{mes.c} is about 5000LOC of restricted C and
|
||
intended to be bootstrappable using a very simple C compiler.
|
||
|
||
@section Software Freedom
|
||
@cindex purpose
|
||
The four essential Freedoms of Software are at the core of our GNU
|
||
community. Quoting the GNU philosophy@footnote{The four essential
|
||
freedoms @url{https://www.gnu.org/philosophy/free-sw.html}}
|
||
|
||
@quotation
|
||
A program is free software if the program's users have the four
|
||
essential freedoms:
|
||
|
||
@enumerate 0
|
||
@item
|
||
The freedom to run the program as you wish, for any purpose (freedom 0).
|
||
|
||
@item
|
||
The freedom to study how the program works, and change it so it does
|
||
your computing as you wish (freedom 1). Access to the source code is
|
||
a precondition for this.
|
||
|
||
@item
|
||
The freedom to redistribute copies so you can help others (freedom
|
||
2).
|
||
|
||
@item
|
||
The freedom to distribute copies of your modified versions to others
|
||
(freedom 3). By doing this you can give the whole community a chance
|
||
to benefit from your changes. Access to the source code is a
|
||
precondition for this.
|
||
@end enumerate
|
||
@end quotation
|
||
|
||
So we have access to the software, we have studied it, possibly modified
|
||
it, we built it and we installed it on a computer or some device. How
|
||
can we trust that when we run the program we are indeed running the
|
||
untainted product of the source code that we studied? Unless we are
|
||
certain of this we cannot really enjoy freedom 1.
|
||
|
||
@menu
|
||
* Reproducible Builds:: Reproducibility and free software.
|
||
* Bootstrappable Builds:: The freedom to build a software without binary seed.
|
||
* Full Source Bootstrap:: Software dependencies worthy of GNU.
|
||
@end menu
|
||
|
||
@node Reproducible Builds
|
||
@section Reproducible Builds
|
||
|
||
The current Reproducible Builds effort incubated in the Debian
|
||
project@footnote{@url{http://debian.org, The Debian Project}} and was organized by Lunar. Quoting
|
||
the Reproducible Builds website@footnote{@url{https://reproducible-builds.org/,Reproducible Builds}}
|
||
|
||
@quotation
|
||
A build is reproducible if given the same source code, build environment
|
||
and build instructions, any party can recreate bit-by-bit identical
|
||
copies of all specified artifacts.
|
||
@end quotation
|
||
|
||
@subsection Can we trust our freedom?
|
||
|
||
Now consider the opposite, that a second build of a piece of source code
|
||
produces a different binary program. Upon further investigation we
|
||
might find that the only difference is a timestamp that was embedded in
|
||
the binary, or perhaps the name of the directory it was built in. Such
|
||
investigations can be nontrivial and are highly unpractical. And what
|
||
if the binary difference is not so trivial, cannot be easily accounted
|
||
for?
|
||
|
||
A piece of software that cannot be built bit-by-bit reproducible is
|
||
probably not a good community member in the world of software freedom.
|
||
We think the importance of reproducibility should not be underestimated
|
||
largely because failing that precondition makes justifable trust in
|
||
binaries provided suspect at best and downright dangerous in reality.
|
||
|
||
It becomes clear that a bit-by-bit reproducible build of all our
|
||
sofwares is essential if we value our Freedom 1.
|
||
|
||
@subsection An Old Idea
|
||
|
||
The idea of reproducible builds is not very new. It was implemented for
|
||
GNU tools in the early 1990s (which we learned, much later in 2017). In
|
||
the Debian world it was mentioned first in 2000 and then more explicitly
|
||
in 2007 on
|
||
debian-devel@footnote{@url{https://lists.debian.org/debian-devel/2007/09/msg00746.html,Martin Uecker on debian-devel on bit-reproducibility}}
|
||
|
||
@quotation
|
||
I think it would be really cool if the Debian policy required that
|
||
packages could be rebuild bit-identical from source.
|
||
|
||
@author Martin Uecker
|
||
@end quotation
|
||
|
||
@node Bootstrappable Builds
|
||
@section Bootstrappable Builds
|
||
|
||
Software distributions that take reproducible builds seriously are
|
||
currently shipping well over 90% reproducible packages.
|
||
|
||
That a package builds bit-by-bit reproducibly however is not enough to
|
||
guarantee Freedom 1. There is another factor that is often overlooked:
|
||
opaque ascii or binary @emph{seeds} that are injected during build
|
||
time. Yes, a package may build reproduciblly from all inspectable
|
||
sourcess...but what functionality is programmed in the opaque seed?
|
||
|
||
@subsection Bootstrap Binaries
|
||
Possibly one of the most harmless, but certainly by far the biggest
|
||
binary seed that all software distributions inject are the so called
|
||
@emph{bootstrap binaries}. Bootstrap binaries are the initial binary
|
||
seeds that are used to start building the distribution.
|
||
|
||
The GNU GuixSD operating system has a relatively small closure of
|
||
bootstrap binaries: GNU binutils, GNU gcc, GNU Libc, GNU Guile, and
|
||
``Static binaries'' (think: bash, coreutils, diffutils, findutils,
|
||
gawk, grep, gzip, make, sed, tar)
|
||
|
||
@example
|
||
$ du -schx $(readlink $(guix build bootstrap-tarballs)/*)
|
||
2.1M /gnu/store/9623n4bq6iq5c8cwwdq99qb7d0xj93ym-binutils-static-stripped-tarball-2.28.1/binutils-static-stripped-2.28.1-x86_64-linux.tar.xz
|
||
18M /gnu/store/437xwygmmwwpkddcyy1qvjcv4hak89pb-gcc-stripped-tarball-5.5.0/gcc-stripped-5.5.0-x86_64-linux.tar.xz
|
||
1.8M /gnu/store/55ccx18a0d1x5y6a575jf1yr0ywizvdg-glibc-stripped-tarball-2.26.105-g0890d5379c/glibc-stripped-2.26.105-g0890d5379c-x86_64-linux.tar.xz
|
||
5.7M /gnu/store/bqf0ajclbvnbm0a46819f30804y3ilx0-guile-static-stripped-tarball-2.2.3/guile-static-stripped-2.2.3-x86_64-linux.tar.xz
|
||
5.8M /gnu/store/j8yzjmh9sy4gbdfwjrhw46zca43aah6x-static-binaries-tarball-0/static-binaries-0-x86_64-linux.tar.xz
|
||
33M total
|
||
@end example
|
||
|
||
only a 33MB download that unpacks to 252BM of opaque binaries, that we
|
||
most probably have the source of, shall we review these together? ;-)
|
||
|
||
@example
|
||
$ for i in $(readlink $(guix build bootstrap-tarballs)/*);\
|
||
do sudo tar xf $i; done
|
||
$ du -schx *
|
||
130M bin
|
||
13M include
|
||
54M lib
|
||
51M libexec
|
||
5.2M share
|
||
252M total
|
||
@end example
|
||
|
||
@node Full Source Bootstrap
|
||
@section Full Source Bootstrap
|
||
|
||
There is an obvious solution: we cannot allow any binary seeds in our
|
||
software stack. Not even in the bootstrap binaries. Maybe that is a
|
||
bit too strong: we want to have the absolute minimum of binary seeds and
|
||
all binary seeds need to be inspectable and must be reviewed.
|
||
|
||
@subsection The Magical Self-Hosting Hex Assembler
|
||
|
||
June 2016 I learnt about
|
||
@url{https://github.com/oriansj/stage0/,Stage0}. Jeremiah Orians
|
||
created `hex0' a ~500 byte self-hosting hex assembler. The source code
|
||
is well documented and the binary is the exact mirror of the source
|
||
code. I was inspired: what if we could bootstrap a whole GNU
|
||
distribution from source, using only an initial 500 byte binary seed?
|
||
|
||
@subsection LISP as Maxwell's Equations of Software
|
||
|
||
As fate would have it, I stumbled upon this
|
||
@url{https://queue.acm.org/detail.cfm?id=1039523, interview with Alan
|
||
Kay}, where he shares a revelation he had when reading John McCarthy's
|
||
@url{http://www.softwarepreservation.org/projects/LISP/book/LISP%25201.5%2520Programmers%2520Manual.pdf,
|
||
LISP-1.5} manual:
|
||
|
||
@quotation
|
||
that was the big revelation to me @dots{} when I finally understood that
|
||
the half page of code on the bottom of page 13 of the Lisp 1.5 manual
|
||
was Lisp in itself. These were “Maxwell’s Equations of Software!” This
|
||
is the whole world of programming in a few lines that I can put my hand
|
||
over.
|
||
|
||
@author Alan Kay
|
||
@end quotation
|
||
|
||
Our starting point is @file{hex0}, a 500 byte hex assembler and we need
|
||
to somehow close the gap to building the bootstrap binaries, esp. GNU
|
||
Gcc and GNU Libc. What better way to do that than by leveraging the
|
||
powers of LISP?
|
||
|
||
Mes is a Scheme@footnote{Scheme is a modern LISP} interpreter that will
|
||
be indirectly bootstrapped from @file{hex0} and that wields the magical
|
||
powers of LISP to close the bootstrap gap, asserting we can enjoy
|
||
software Freedom 1.
|
||
|
||
@c *********************************************************************
|
||
@node Installation
|
||
@chapter Installation
|
||
|
||
@cindex installing Mes
|
||
Mes is available for download from
|
||
@url{http://gitlab.com/janneke/mes/}. This section describes the
|
||
software requirements of Mes, as well as how to install it and get ready
|
||
to use it.
|
||
|
||
|
||
@menu
|
||
* Regular Requirements:: Software needed to build and run Mes.
|
||
* Bootstrap Requirements:: Software needed to bootstrap Mes.
|
||
* Running the Test Suites:: Testing Mes.
|
||
@end menu
|
||
|
||
@node Regular Requirements
|
||
@section Regular Requirements
|
||
|
||
This section lists requirements when building Mes from source. The
|
||
build procedure for Mes is the same as for other GNU software, and is
|
||
not covered here. Please see the files @file{README} and @file{INSTALL}
|
||
in the Mes source tree for additional details.
|
||
|
||
Mes depends on the following packages:
|
||
|
||
@itemize
|
||
@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.13 or
|
||
later, including 2.2.x;
|
||
@item @url{http://www.gnu.org/software/make/, GNU Make}.
|
||
@item @url{https://savannah.gnu.org/projects/nyacc/, NYACC}, currently only the patched
|
||
version 0.80.42 from @url{http://gitlab.com/janneke/nyacc/, patched
|
||
NYACC} is known to work.
|
||
@item @url{http://gcc.gnu.org, GCC's gcc}, version 3.0.0 or later.
|
||
@end itemize
|
||
|
||
The following dependencies are optional:
|
||
|
||
@itemize
|
||
@item
|
||
Installing @url{https://github.com/oriansj/mescc-tools/, mescc-tools},
|
||
version 0.5 or later, will allow you to have MesCC assemble and link.
|
||
@end itemize
|
||
|
||
@cindex Guile, compatibility
|
||
Mes is compatible with GNU Guile, so it is possible to share the same
|
||
Scheme code between both. Of course, Mes only supports the minimal
|
||
subset of R5RS and Guile extensions to run MesCC.
|
||
|
||
@node Bootstrap Requirements
|
||
@section Bootstrap Requirements
|
||
|
||
This section lists requirements when building Mes as a bootstrap
|
||
package. The bootstrap build procedure for Mes is similar to building
|
||
GNU software and goes like this
|
||
|
||
@example
|
||
export prefix=/usr/local # for example
|
||
export MES_SEED=../mes # for example
|
||
# optionally set some other environment variables
|
||
sh build.sh
|
||
sh check.sh
|
||
sh install.sh
|
||
@end example
|
||
|
||
See @file{build.sh} for inspiration on what environment variables to
|
||
set.
|
||
|
||
Bootstrapping Mes depends on the following packages:
|
||
|
||
@itemize
|
||
@item a POSIX-compatible shell
|
||
@item @url{https://github.com/oriansj/mescc-tools/, mescc-tools}, version 0.5 or later.
|
||
@item @url{http://gitlab.com/janneke/mes-seed/, mes-seed}, version 0.16 or later.
|
||
@end itemize
|
||
|
||
@node Running the Test Suites
|
||
@section Running the Test Suites
|
||
|
||
@cindex test suites
|
||
After a successful @command{configure} and @code{make} run, it is a good
|
||
idea to run the test suites.
|
||
|
||
@example
|
||
make check
|
||
@end example
|
||
|
||
Run Mes Scheme language semantics tests (@file{scaffold/boot}) only
|
||
|
||
@example
|
||
build-aux/check-boot.sh
|
||
@end example
|
||
|
||
Run a single Mes boot test
|
||
|
||
@example
|
||
MES_BOOT=scaffold/boot/00-zero.scm src/mes
|
||
@end example
|
||
|
||
Run a single Mes Scheme test
|
||
|
||
@example
|
||
tests/boot.test
|
||
tests/boot.test-guile
|
||
@end example
|
||
|
||
Run MesCC tests only
|
||
|
||
@example
|
||
build-aux/check-mescc.sh
|
||
@end example
|
||
|
||
Run a single MesCC test
|
||
|
||
@example
|
||
CC=gcc CC32=i686-unknown-linux-gnu-gcc MES=guile \
|
||
build-aux/test.sh scaffold/tests/00-exit-0
|
||
@end example
|
||
|
||
@node Bootstrapping
|
||
@chapter Bootstrapping
|
||
|
||
@quotation
|
||
Recipe for yogurt: Add yogurt to milk.
|
||
|
||
@author Anonymous
|
||
@end quotation
|
||
|
||
The bootstrap problem we have set out to solve is that none of our
|
||
modern software distributions, and GuixSD in particular, can be created
|
||
all from source code. In addition to the carefully signed source code
|
||
of all the programs (the `milk') an opaque binary seed (the `yogurt') is
|
||
injected as an essential dependency.
|
||
|
||
Why would this be a problem, I hear you ask? This is how it is done, we
|
||
always did it this way, everyone does it like this! Indeed, a popular
|
||
way of handling the bootstrapping issue is by ignoring it.
|
||
|
||
@quotation
|
||
Your compiler becoming self-hosting@dots{}a language creator's wet
|
||
dream.
|
||
|
||
@author PFH
|
||
@end quotation
|
||
|
||
It seems that writing a self-hosting compiler is considered to be a
|
||
language creator's ultimate goal. It means that their language and
|
||
compiler have become powerful enough to not depend on a pre-exising
|
||
language that possibly is---but certainly was until now---more
|
||
powerful; it feels like passing the rite to adulthood.
|
||
|
||
When you see the irony, you grasp what our bootstrapping effort means in
|
||
practice. Creating bootstrappable software is not hard; actually most
|
||
softwares' first releases are bootstrappable. The problem of
|
||
bootstrapping is not a technical one, it is a lack of awareness and
|
||
responsibility.
|
||
|
||
@menu
|
||
* The Mes Bootstrap Process:: How Mes will make you yogurt from pure milk.
|
||
* Invoking Mes:: Running Mes, a minimalist Guile lookalike.
|
||
* Invoking MesCC:: Running the MesCC bootstrap compiler.
|
||
@end menu
|
||
|
||
@node The Mes Bootstrap Process
|
||
@section The Mes Bootstrap Process
|
||
|
||
The Mes full source bootstrap process@footnote{TBH, the current state of
|
||
affairs demands to label this a `reduced binary seed bootstrap'} is
|
||
currently being developed in GuixSD@footnote{See
|
||
@file{gnu/packages/mes.scm} in the @var{wip-bootstrap} branch in Guix
|
||
git
|
||
@url{http://git.savannah.gnu.org/cgit/guix.git/tree/gnu/packages/mes.scm?h=wip-bootstrap}}.
|
||
In it's intiial form it is only available for x86-linux.
|
||
|
||
Currently, it goes like this:
|
||
|
||
@verbatim
|
||
mescc-tools-source + mescc-tools-seed => mescc-tools
|
||
|
||
mes-source + mescc-tools + mescc-seed => mes
|
||
|
||
tcc-source + mes + tinycc-seed => tcc
|
||
|
||
binutils-source + mes + tcc => binutils0
|
||
|
||
gcc-source + tcc + binutils0 => gcc-core
|
||
|
||
glibc-source + kernel-headers-source + binutils0 + gcc => glibc
|
||
|
||
binutils-source + binutils0 + gcc + glibc => binutils
|
||
|
||
gcc-source + binutils + gcc-core + glibc => gcc
|
||
@end verbatim
|
||
|
||
@c FIXME: ./pre-inst-env guix graph --type=references gcc-mesboot@4.1.0
|
||
@c | dot -T png > gcc-mesboot-4.1.0.png
|
||
|
||
@c Using anything else (e.g. --type=package, --type=bag) produces an
|
||
@c unreadable image with *many* duplicates.
|
||
|
||
Here's a generated dependency diagram to give you impression, it is
|
||
not complete or correct.
|
||
|
||
@image{images/gcc-mesboot-graph,2in,,Reference graph of the gcc-mesboot}
|
||
|
||
Work is ongoing to remove these binary seeds that were intentionally
|
||
injected by our own doing as temporary shortcut
|
||
@example
|
||
mescc-tools-seed, mes-seed, tinycc-seed
|
||
@end example
|
||
|
||
These additional non-bootstrapped dependencies (i.e., binary seeds) are
|
||
taken for granted
|
||
|
||
@example
|
||
BOOTSTRAP-GUILE, flex, bash,
|
||
bzip2, coreutils, diffutils, gawk, grep, gzip, make, sed, tar
|
||
@end example
|
||
|
||
Although we think these are less essential and thus less interesting
|
||
than the GNU toolchain triplet that we focussed on initially, our next
|
||
priority is to eleminate these one by one.
|
||
|
||
@node Invoking Mes
|
||
@section Invoking Mes
|
||
|
||
@cindex repl
|
||
The @command{mes} command is the Scheme interpreter whose prime
|
||
directive is to run the @command{MesCC} program.
|
||
|
||
For convenience and testing purposes, @command{mes} tries to mimic
|
||
Guile.
|
||
|
||
@example
|
||
mes @var{option}@dots{} @file{FILE}@dots{}
|
||
@end example
|
||
|
||
The @var{option}s can be among the following:
|
||
|
||
@table @code
|
||
|
||
@item -s @var{script} @var{arg}@dots{}
|
||
@cindex script mode
|
||
By default, Mes will read a file named on the command line as a script.
|
||
Any command-line arguments @var{arg}@dots{} following @var{script}
|
||
become the script's arguments; the @code{command-line} function returns
|
||
a list of strings of the form @code{(@var{script} @var{arg}@dots{})}.
|
||
|
||
Scripts are read and evaluated as Scheme source code just as the
|
||
@code{load} function would. After loading @var{script}, Mes exits.
|
||
|
||
@item -c @var{expr} @var{arg}@dots{}
|
||
@cindex evaluate expression, command-line argument
|
||
Evaluate @var{expr} as Scheme code, and then exit. Any command-line
|
||
arguments @var{arg}@dots{}) following @var{expr} become command-line
|
||
arguments; the @code{command-line} function returns a list of strings of
|
||
the form @code{(@var{guile} @var{arg}@dots{})}, where @var{mes} is the
|
||
path of the Mes executable.
|
||
|
||
@item -- @var{arg}@dots{}
|
||
Run interactively, prompting the user for expressions and evaluating
|
||
them. Any command-line arguments @var{arg}@dots{} following the
|
||
@option{--} become command-line arguments for the interactive session;
|
||
the @code{command-line} function returns a list of strings of the form
|
||
@code{(@var{guile} @var{arg}@dots{})}, where @var{mes} is the path of the
|
||
Mes executable.
|
||
|
||
@item -L,--load-path=@var{directory}
|
||
Add @var{directory} to the front of Mes module load path. The given
|
||
directories are searched in the order given on the command line and
|
||
before any directories in the @env{GUILE_LOAD_PATH} environment
|
||
variable.
|
||
|
||
@item -C,--compiled-path=@var{directory}
|
||
Accepted and ignored for Guile compatibility.
|
||
|
||
@item ---dump
|
||
dump binary program to stdout
|
||
|
||
@item -l @var{file}
|
||
Load Scheme source code from @var{file}, and continue processing the
|
||
command line.
|
||
|
||
@item -e,--main=@var{function}
|
||
Make @var{function} the @dfn{entry point} of the script. After loading
|
||
the script file (with @option{-s}) or evaluating the expression (with
|
||
@option{-c}), apply @var{function} to a list containing the program name
|
||
and the command-line arguments---the list provided by the
|
||
@code{command-line} function.
|
||
|
||
@item -h@r{, }--help
|
||
Display help on invoking Mes, and then exit.
|
||
|
||
@item ---load
|
||
load binary program [module/mes/boot-0.32-mo]
|
||
|
||
@item -v@r{, }--version
|
||
Display the current version of Mes, and then exit.
|
||
|
||
@end table
|
||
|
||
@menu
|
||
* Environment Variables:: If the bits won't change, change their habitat.
|
||
@end menu
|
||
|
||
@node Environment Variables
|
||
@subsection Environment Variables
|
||
@cindex environment variables
|
||
@cindex shell
|
||
@cindex initialization
|
||
|
||
@c Hmm, I expected this paragraph in the Guix manual?
|
||
Here are the environment variables (see @pxref{Environment Variables,,,
|
||
guile, Guile Reference}) that affect the run-time behavior of
|
||
Mes:
|
||
|
||
@table @env
|
||
@item MES_BOOT
|
||
@vindex MES_BOOT
|
||
|
||
Set @env{MES_BOOT} to change the initial Scheme program that Mes runs.
|
||
|
||
@item MES_ARENA
|
||
@vindex MES_ARENA
|
||
|
||
The initial size of the arena @pxref{5.3,,, sicp, SICP} in cells. Default: 20,000.
|
||
|
||
@item MES_MAX_ARENA
|
||
@vindex MES_MAX_ARENA
|
||
|
||
The maximum size of the arena in cells. Default: 100,000,000.
|
||
|
||
@item MES_DEBUG
|
||
@vindex MES_DEBUG
|
||
|
||
@enumerate
|
||
@item
|
||
Informational:
|
||
@itemize
|
||
@item MODULEDIR
|
||
@item included SCM modules and sources
|
||
@item result of program
|
||
@item gc stats at exit
|
||
@end itemize
|
||
@item
|
||
opened files
|
||
|
||
@item
|
||
runtime gc stats
|
||
|
||
@item
|
||
detailed info
|
||
@itemize
|
||
@item parsed, expanded program
|
||
@item list of builtins
|
||
@item list of symbol
|
||
@item opened input strings
|
||
@item gc details
|
||
@end itemize
|
||
|
||
@item
|
||
usage of opened input strings
|
||
@end enumerate
|
||
|
||
|
||
@item GUILE_LOAD_PATH
|
||
@vindex GUILE_LOAD_PATH
|
||
This variable may be used to augment the path that is searched for
|
||
Scheme files when loading. Its value should be a colon-separated list
|
||
of directories. If it contains the special path component @code{...}
|
||
(ellipsis), then the default path is put in place of the ellipsis,
|
||
otherwise the default path is placed at the end. The result is stored
|
||
in @code{%load-path}.
|
||
|
||
Mes uses @var{@strong{GUILE}_LOAD_PATH} for compatibility with Guile.
|
||
|
||
@end table
|
||
|
||
@node Invoking MesCC
|
||
@section Invoking MesCC
|
||
|
||
@example
|
||
mescc @var{option}@dots{} @file{FILE}@dots{}
|
||
@end example
|
||
|
||
The @var{option}s can be among the following:
|
||
|
||
@table @code
|
||
|
||
@item -c
|
||
@cindex compile
|
||
preprocess, compile and assemble only; do not link
|
||
|
||
@item -D @var{DEFINE}[=@var{VALUE}]
|
||
@cindex define DEFINE [VALUE=1]
|
||
|
||
@item -E
|
||
preprocess only; do not compile, assemble or link
|
||
|
||
@item -g
|
||
add @command{blood-elf} debug info
|
||
|
||
This enables GDB setting breakpoints on function names, and to have the
|
||
GDB backtrace command to show the function call stack.
|
||
|
||
@item -h, --help
|
||
display this help and exit
|
||
|
||
@item -I DIR
|
||
append DIR to include path
|
||
|
||
@item -L DIR
|
||
append DIR to library path
|
||
|
||
@item -l LIBNAME
|
||
link with LIBNAME
|
||
|
||
@item -o FILE
|
||
write output to FILE
|
||
|
||
@item -S
|
||
preprocess and compile only; do not assemble or link
|
||
|
||
@item -v, --version
|
||
display version and exit
|
||
|
||
@item -w,--write=TYPE
|
||
dump Nyacc AST using TYPE @{pretty-print,write@}
|
||
|
||
@end table
|
||
|
||
@menu
|
||
* MesCC Environment Variables:: There's no NIX like POSIX.
|
||
@end menu
|
||
|
||
@node MesCC Environment Variables
|
||
@subsection MesCC Environment Variables
|
||
|
||
@table @env
|
||
@item MES
|
||
@vindex MES
|
||
|
||
Setting @env{MES} to a mes-compatible Scheme will run MesCC using that
|
||
@example
|
||
MES=guile mescc -c scaffold/main.c
|
||
@end example
|
||
|
||
See, now Guile has become compatible with Mes, instead of the other way
|
||
around ;-)
|
||
|
||
@item C_INCLUDE_PATH
|
||
@vindex C_INCLUDE_PATH
|
||
|
||
@item LIBRARY_PATH
|
||
@vindex LIBRARY_PATH
|
||
|
||
@item NYACC_DEBUG
|
||
@vindex NYACC_DEBUG
|
||
|
||
Setting @env{NYACC_DEBUG} makes nyacc print names of function
|
||
during the parsing phase.
|
||
|
||
@end table
|
||
|
||
|
||
@c *********************************************************************
|
||
@node Contributing
|
||
@chapter Contributing
|
||
|
||
@menu
|
||
* Building from Git:: The latest and greatest.
|
||
* Running Mes From the Source Tree:: Hacker tricks.
|
||
* The Perfect Setup:: The right tools.
|
||
* Coding Style:: Hygiene of the contributor.
|
||
* Submitting Patches:: Share your work.
|
||
@end menu
|
||
|
||
@node Building from Git
|
||
@section Building from Git
|
||
|
||
If you want to hack Mes itself, it is recommended to use the latest
|
||
version from the Git repository:
|
||
|
||
@example
|
||
git clone https://gitlab.com/janneke/mes.git
|
||
@end example
|
||
|
||
The easiest way to set up a development environment for Mes is, of
|
||
course, by using Guix! The following command starts a new shell where
|
||
all the dependencies and appropriate environment variables are set up to
|
||
hack on Mes:
|
||
|
||
@example
|
||
guix environment -l guix.scm
|
||
@end example
|
||
|
||
Finally, you have to invoke @code{make check} to run tests
|
||
(@pxref{Running the Test Suites}). If anything fails, take a look at
|
||
installation instructions (@pxref{Installation}) or send a message to
|
||
the @email{guix-devel@@gnu.org} mailing list.
|
||
|
||
@node Running Mes From the Source Tree
|
||
@section Running Mes From the Source Tree
|
||
|
||
Running Mes from the source tree is supported out of the box. This has
|
||
been accomplished by using some magic and heuristics. These should be
|
||
removed and if necessary replaced by a @file{./pre-inst-env} trick.
|
||
|
||
@node The Perfect Setup
|
||
@section The Perfect Setup
|
||
|
||
The Perfect Setup to hack on Mes is basically the perfect setup used
|
||
for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
|
||
Manual}). First, you need more than an editor, you need
|
||
@url{http://www.gnu.org/software/emacs, Emacs}, empowered by the
|
||
wonderful @url{http://nongnu.org/geiser/, Geiser}.
|
||
|
||
Geiser allows for interactive and incremental development from within
|
||
Emacs: code compilation and evaluation from within buffers, access to
|
||
on-line documentation (docstrings), context-sensitive completion,
|
||
@kbd{M-.} to jump to an object definition, a REPL to try out your code,
|
||
and more (@pxref{Introduction,,, geiser, Geiser User Manual}).
|
||
|
||
@node Coding Style
|
||
@section Coding Style
|
||
|
||
In general our code follows the GNU Coding Standards (@pxref{Top,,,
|
||
standards, GNU Coding Standards}). However, they do not say much about
|
||
Scheme, so here are some additional rules.
|
||
|
||
@subsection Programming Paradigm
|
||
|
||
Scheme code in Mes is written in a purely functional style.
|
||
|
||
@subsection Formatting Code
|
||
|
||
@cindex formatting code
|
||
@cindex coding style
|
||
When writing Scheme code, we follow common wisdom among Scheme
|
||
programmers. In general, we follow the
|
||
@url{http://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
|
||
Style Rules}. This document happens to describe the conventions mostly
|
||
used in Guile’s code too. It is very thoughtful and well written, so
|
||
please do read it.
|
||
|
||
@cindex indentation, of code
|
||
@cindex formatting, of code
|
||
If you do not use Emacs, please make sure to let your editor knows these
|
||
rules.
|
||
|
||
Additionally, in Mes we prefer to format @code{if} statements like this
|
||
@example
|
||
(if foo? trivial-then
|
||
(let ((bar (the-longer @dots{})))
|
||
more-complicated
|
||
@dots{}
|
||
else))
|
||
@end example
|
||
|
||
@node Submitting Patches
|
||
@section Submitting Patches
|
||
|
||
Development is done using the Git distributed version control system.
|
||
Thus, access to the repository is not strictly necessary. We welcome
|
||
contributions in the form of patches as produced by @code{git
|
||
format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
|
||
|
||
Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
|
||
standards, GNU Coding Standards}); you can check the commit history for
|
||
examples.
|
||
|
||
@subsection Reporting Bugs
|
||
|
||
Encountering a problem or bug can be very frustrating for you as a user
|
||
or potential contributor. For us as Mes maintainers, the preferred bug
|
||
report includes a beautiful and tested patch that we can integrate
|
||
without any effort.
|
||
|
||
However, please don't let our preference stop you from reporting a bug.
|
||
There's one thing @emph{much} worse for us than getting a bug report
|
||
without a patch: Reading a complaint or rant online about your pain and
|
||
how our work sucks, without having heard directly what you experienced.
|
||
|
||
So if you report a problem, will it be fixed? And @strong{when}? The
|
||
most honest answer is: It depends. Let's curry that informationless
|
||
honesty with a more helpful and more blunt reminder of a mantra of Free
|
||
Software:
|
||
|
||
@quotation
|
||
@table @strong
|
||
@item Q:
|
||
When@dots{}?
|
||
|
||
@item A:
|
||
@dots{}sooner if you help.
|
||
@end table
|
||
|
||
@author Eric Raymond
|
||
@end quotation
|
||
|
||
@cindex contact, irc, mailing list
|
||
@cindex bug, bug report, reporting a bug
|
||
Join us on @code{#bootstrappable} on the Freenode IRC network or on
|
||
@file{guix-devel@@gnu.org} to share your experience---good or bad.
|
||
|
||
|
||
@c *********************************************************************
|
||
@node Acknowledgments
|
||
@chapter Acknowledgments
|
||
|
||
We would like to thank the following people for their help: Jeremiah
|
||
Orians, pdewacht, rain1, Ricardo Wurmus, Rutger van Beusekom.
|
||
w
|
||
We also thank Ludovic Courtès for creating GuixSD and making the
|
||
bootstrap problem so painfully visible, John McCarthy for creating
|
||
LISP-1.5 and Alan Kay for their inspiring comment on
|
||
@url{https://queue.acm.org/detail.cfm?id=1039523, Page 13}.
|
||
|
||
@c *********************************************************************
|
||
@node Resources
|
||
@chapter Resources
|
||
|
||
@itemize
|
||
|
||
@item
|
||
@url{https://bootstrappable.org, Bootstrappable Builds} Minimize the
|
||
amount and size of opaque binary seeds we need to swallow.
|
||
|
||
@item
|
||
@url{https://reproducible-builds.org, Reproducible Builds}
|
||
Provide a verifiable path from source code to binary.
|
||
|
||
@item
|
||
@url{https://gitlab.com/oriansj/stage0, Stage0}
|
||
If we want, it could all start with a ~500 byte self-hosting hex
|
||
assembler.
|
||
|
||
@item
|
||
@url{https://bootstrapping.miraheze.org, Bootstrapping wiki} An amazing
|
||
collection of small/bootstrappable compilers, operating systems,
|
||
anything you need.
|
||
|
||
@item
|
||
@url{irc.freenode.net, #bootstrappable} The bootstrapping community home
|
||
at the freenode IRC network.
|
||
|
||
@item
|
||
@file{guix-devel@@gnu.org} The Guix mailing list, where it all started.
|
||
@url{https://lists.gnu.org/archive/html/guix-devel/, guix-devel archives}.
|
||
|
||
@end itemize
|
||
|
||
@c *********************************************************************
|
||
@node GNU Free Documentation License
|
||
@appendix GNU Free Documentation License
|
||
@cindex license, GNU Free Documentation License
|
||
@include fdl-1.3.texi
|
||
|
||
@c *********************************************************************
|
||
@node Concept Index
|
||
@unnumbered Concept Index
|
||
@printindex cp
|
||
|
||
@node Programming Index
|
||
@unnumbered Programming Index
|
||
@syncodeindex tp fn
|
||
@syncodeindex vr fn
|
||
@printindex fn
|
||
|
||
@bye
|
||
|
||
@c Local Variables:
|
||
@c ispell-local-dictionary: "american";
|
||
@c End:
|