From a4770c1eed69dcf25e212097ba055d07b5fe5c77 Mon Sep 17 00:00:00 2001 From: Jan Nieuwenhuizen Date: Wed, 27 Jun 2018 13:42:47 +0200 Subject: [PATCH] doc: Initial version. * doc/mes.texi: New file. * doc/fdl-1.3.texi: New file. * AUTHORS: Mention it. * GNUmakefile (doc, info, install-info): New targets. * install.sh: Install info if available. * guix: (mes): Add texinfo to native-inputs. * configure: Check for makeinfo. --- .dir-locals.el | 6 +- .gitignore | 2 + AUTHORS | 3 + BOOTSTRAP | 2 +- GNUmakefile | 25 +- configure | 3 + doc/GNU-EVAL-APPLY | 135 +++++++ doc/fdl-1.3.texi | 505 +++++++++++++++++++++++++ doc/mes.texi | 911 +++++++++++++++++++++++++++++++++++++++++++++ guix.scm | 5 +- install.sh | 7 + 11 files changed, 1600 insertions(+), 4 deletions(-) create mode 100644 doc/GNU-EVAL-APPLY create mode 100644 doc/fdl-1.3.texi create mode 100644 doc/mes.texi diff --git a/.dir-locals.el b/.dir-locals.el index 76ab5369..dc0c15d5 100644 --- a/.dir-locals.el +++ b/.dir-locals.el @@ -34,6 +34,8 @@ (exports (matches-in-string "^[+] export \\(.*\\)" output))) (mapcar (lambda (line) (apply #'setenv (split-string line "="))) exports ))) )))) + (makefile-mode + (indent-tabs-mode . t)) (scheme-mode . ((geiser-active-implementations . (guile)) @@ -46,4 +48,6 @@ (lambda (dir) (add-to-list 'geiser-guile-load-path dir)) (mapcar #'prefix-dir-locals-dir - '("scripts" "guile")))))))) + '("scripts" "guile"))))))) + (texinfo-mode . ((indent-tabs-mode . nil) + (fill-column . 72)))) diff --git a/.gitignore b/.gitignore index cdf7b840..852e4209 100644 --- a/.gitignore +++ b/.gitignore @@ -52,6 +52,8 @@ ? ?.mes \#*# +/doc/mes.info +/doc/version.texi /doc/fosdem/fosdem.aux /doc/fosdem/fosdem.log /doc/fosdem/fosdem.nav diff --git a/AUTHORS b/AUTHORS index 3224703a..d2e9281d 100644 --- a/AUTHORS +++ b/AUTHORS @@ -57,3 +57,6 @@ module/srfi/srfi-26.scm Sxml bits from Guile module/sxml/xpath.scm + +GNU FDL in texinfo from GNU +doc/fdl-1.3.texi diff --git a/BOOTSTRAP b/BOOTSTRAP index 57299ee1..04716f8e 100644 --- a/BOOTSTRAP +++ b/BOOTSTRAP @@ -51,7 +51,7 @@ about the bootstrap binaries and compilers? *** The current way out: Ignore the problem - ``recipe for yoghurt: add yoghurt to milk'' + ``recipe for yogurt: add yogurt to milk'' *** New solution: Full source bootstrapping path diff --git a/GNUmakefile b/GNUmakefile index eb2d1afc..1ecbb6a0 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -1,3 +1,5 @@ +.PHONY: doc + GUILE:=guile GUILE_FLAGS:=--no-auto-compile -L . -L guile -C . -C guile @@ -11,7 +13,9 @@ PHONY_TARGETS:= all all-go check clean clean-go default help install default: all -all: +all: build doc + +build: ./build.sh cc: @@ -59,6 +63,22 @@ seed: all-go mes-gcc mes-tcc $(MESCC_TOOLS_SEED)/libs cd $(MESCC_TOOLS_SEED) && MES_PREFIX=$(PWD) ./bootstrap.sh +doc/version.texi: doc/mes.texi GNUmakefile + (set `LANG= date -r $< +'%d %B %Y'`;\ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > $@ + +doc: info + +info: doc/mes.info + +doc/mes.info: doc/mes.texi doc/version.texi GNUmakefile + $(MAKEINFO) -o $@ -I doc $< + +install-info: info + define HELP_TOP Usage: make [OPTION]... [TARGET]... @@ -66,13 +86,16 @@ Targets: all update everything all-go update .go files cc update src/mes.gcc-out + doc update documentation mes-gcc update src/mes.mes-gcc-out mes-tcc update src/mes.mes-tcc-out mes update src/mes check run unit tests clean run git clean -dfx clean-go clean .go files + info update info documentation install install in $(PREFIX) + install-info install info docs in $(PREFIX)/share/info seed update mes-seed in $(MES_SEED) endef export HELP_TOP diff --git a/configure b/configure index d7a1b274..bd312107 100755 --- a/configure +++ b/configure @@ -247,6 +247,7 @@ Some influential environment variables: (if (member ARCH '("i686" "arm")) (string-append BUILD_TRIPLET "-" CC) "i686-unknown-linux-gnu-gcc"))) (TCC (or (getenv "TCC") "tcc")) + (MAKEINFO (or (getenv "MAKEINFO") "makeinfo")) (GUILE_TOOLS (or (getenv "GUILE_TOOLS") "guile-tools")) (BLOOD_ELF (or (getenv "BLOOD_ELF") "blood-elf")) (HEX2 (or (getenv "HEX2") "hex2")) @@ -287,6 +288,8 @@ Some influential environment variables: (set! TCC #f)) (set! make? (check-version "make" '(4 0) #:optional? #t)) (check-version "perl" '(5)) + (if (not (check-version "makeinfo" '(6) #:optional? #t)) + (set! MAKEINFO #f)) (when (pair? required) (stderr "\nMissing dependencies [~a], run\n\n" ((->string ", ") required)) diff --git a/doc/GNU-EVAL-APPLY b/doc/GNU-EVAL-APPLY new file mode 100644 index 00000000..fbee8489 --- /dev/null +++ b/doc/GNU-EVAL-APPLY @@ -0,0 +1,135 @@ +* General Information +** Do you agree to follow GNU policies? + +Yes, of course. + +** Package name and version: + +Mes 0.16 + +** Author Full Name : + +Jan (janneke) Nieuwenhuizen + +** URL to package home page (if any): https://gitlab.com/janneke/mes + +I'm happy to move to savannah when Mes becomes a GNU package. + +** URL to source tarball: + +https://gitlab.com/janneke/mes/-/archive/v0.16/mes-0.16.tar.gz + +or: git clone https://gitlab.com/janneke/mes + +** Brief description of the package: + +Mes aims to help create full source bootstrapping for GuixSD as part of +the bootstrappable builds effort (See https://bootstrappable.org/). + +It currently consists of a mutual self-hosting Scheme interpreter +prototype written in C and a Nyacc-based C compiler written in Scheme. +This C prototype is being simplified to be transpiled by M2-Planet. + +Mes+MesCC can compile an only lighty patched TinyCC that is +self-hosting. Using this tcc and the Mes C library we now have a +reduced-binary-seed bootstrap for the gnutools triplet: glibc-2.2.5, +binutils-2.20.1, gcc-4.1.0. + +* Code +** Dependencies: + +Mes can be built as a regular package, or as part of the full source +(currently: reduced binary seed) bootstrap process. + +*** Regular build + + - https://github.com/mescc-tools, 0.5 is known to work. + - https://savannah.gnu.org/projects/nyacc, 0.80.42 is known to work. + - GNU Gcc, 4.9.3 is known to work. + - GNU Guile, version 2.0.12 or is know to work. + - SH, /bin/sh, GNU Bash 4.3 is known to work. + - GNU coreutils + - sed, GNU sed 4.2 is known to work. + - git, 2.10 is known to work. + - Perl, 5.22 is known to work. + +*** Bootstrap build + + - https://github.com/oriansj/mescc-tools, 0.5 is known to work. + - https://savannah.gnu.org/projects/nyacc, 0.80.42 is known to work. + - https://gitlab.com/janneke/mes-seed, 0.16 is known to work. + +** Configuration, building, installation: + +*** Guix build, install + + guix build mes, guix package --install mes + +*** Regular build + + ./configure; make; make check; make install + +*** Bootstrap build + + + sh build.sh + sh check.sh + sh install.sh + +** Documentation: + +Mes does not yet have any documentation other than AUTHORS, HACKING, +INSTALL, NEWS, README. When it does, it will be in Texinfo: I live in +Emacs. I have initiated the GNU LilyPond documentation and website, +which are written in texinfo. + +** Internationalization: + +Mes does not have Internationalization. As it's an early bootstrap +package, it's unsure if it will ever get that. I do have experience +with adding Internationalization to GNU LilyPond. + +** Accessibility: + +None. + +** Security: + +Mes will be used as a critical link in our GNU bootstrapping chain. +It is essential for Mes to get a proper review before it is put in +place. + +* Licensing: + +GNU GPL 3, or later. + +* Similar free software projects: + +There are similarities with GNU Guile and to a lesser extent also with +MIT/GNU Scheme and SCM; in fact Mes' scheme tries to be compatible with +Guile Scheme. GNU Guile is about 30x faster than Mes. + +The main difference is that mes.c is ~5,000LOC of very simple C and can +can be bootstrapped almost entirely from source, without any binary +seed. Currently, it needs a ~1MB ASSCI seed. + +Guile is ~100,000LOC of full-blown C, not counting its dependencies +such as libgc. + +Another difference with regular Scheme implementations, is that Mes does +not strive for RXRS compliance, instead it strives for minimalism and +Guile compatibility. + +If in doubt, please contact the GuixSD or Guile maintainers. + +* Any other information, comments, or questions: + +I am an original author of GNU LilyPond and current GuixSD developer. I +have regular discussions about Mes and GuixSD with GuixSD and Guile +maintainers. + +Mes currently targets only x86-linux, I would like some help to look at +other architectures and esp. at targeting the Hurd. + +Greetings, +janneke diff --git a/doc/fdl-1.3.texi b/doc/fdl-1.3.texi new file mode 100644 index 00000000..cb71f05a --- /dev/null +++ b/doc/fdl-1.3.texi @@ -0,0 +1,505 @@ +@c The GNU Free Documentation License. +@center Version 1.3, 3 November 2008 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +@uref{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, La@TeX{} input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or PDF produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The ``publisher'' means any person or entity that distributes copies +of the Document to the public. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +@item +RELICENSING + +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the +site means any set of copyrightable works thus published on the MMC +site. + +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +``Incorporate'' means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is ``eligible for relicensing'' if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + 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 group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.''@: line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: diff --git a/doc/mes.texi b/doc/mes.texi new file mode 100644 index 00000000..413e39f1 --- /dev/null +++ b/doc/mes.texi @@ -0,0 +1,911 @@ +\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)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! +* 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 +prototype 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 first freedom from +@url{https://www.gnu.org/philosophy/free-sw.html} + +@quotation +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. +@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? + +@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{http://debian.org} and was organized by Lunar. Quoting +the @url{https://reproducible-builds.org/} website + +@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}} + +@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 dnuring 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: want to have the absolute minimum of binary seeds and +all binary seeds need to be inspectable and need to 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 +@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 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 Paul Hoogendijk +@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 the 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 + +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 +@email{janneke@@gnu.org, janneke} or 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 @email{janneke@@gnu.org, janneke} or to the +@email{guix-devel@@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 +When@dots{}? + +@dots{}sooner if you help. + +@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. + +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 observation that Page 13 +@url{https://queue.acm.org/detail.cfm?id=1039523, Page 13}. + +@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: diff --git a/guix.scm b/guix.scm index 30002ff3..8b4ab924 100644 --- a/guix.scm +++ b/guix.scm @@ -53,6 +53,7 @@ (gnu packages mes) (gnu packages package-management) (gnu packages perl) + (gnu packages texinfo) ((guix build utils) #:select (with-directory-excursion)) (guix build-system gnu) (guix build-system trivial) @@ -153,7 +154,9 @@ hex2 linker.") `(("i686-linux-binutils" ,(cross-binutils triplet)) ("i686-linux-gcc" ,(cross-gcc triplet))) '()) - ("perl" ,perl))) ;build-aux/gitlog-to-changelog + ("help2man" ,help2man) + ("perl" ,perl) ; build-aux/gitlog-to-changelog + ("texinfo" ,texinfo))) (arguments `(#:phases (modify-phases %standard-phases diff --git a/install.sh b/install.sh index 112807bc..84aa3f4e 100755 --- a/install.sh +++ b/install.sh @@ -1,6 +1,7 @@ #! /bin/sh set -e +set -o pipefail export PREFIX SHELL=${SHELL-$(command -v sh)} @@ -56,3 +57,9 @@ sed \ -e "s,^#! /bin/sh,#! $SHELL," \ scripts/diff.scm > $PREFIX/bin/diff.scm chmod -w+x $PREFIX/bin/diff.scm + +if [ -f doc/mes.info ]; then + mkdir -p $PREFIX/share/info + install-info --info-dir=$PREFIX/share/info doc/mes.info + tar -cf- doc/mes.info* | tar -xf- --strip-components=1 -C $PREFIX/share/info +fi