bootstrappable/pages/best-practises.skr

(post :title "Best Practises"
      (page
       (p [Are you developing or contributing to software that is affected by the bootstrapping problem?
           The following sections list best practises and practical examples that can help you pull yourself up by your own bootstraps,
           no matter if you are ,(anchor "a compiler writer" "#compiler"),
           ,(anchor "a build system developer" "#build-system"),
           or ,(anchor "a system distribution developer" "#distro").])

       `(div (@ (id "compiler")))
       (h2 [For compiler writers])

       (p [If you're working on a compiler that is written in a language other than the one it's compiling, you're all set!])
       (p [If your compiler is written in the language that it's compiling (“self-hosted”), it probably falls in one of the following categories.])

       (h3 [When an alternative implementation exists])
       (p [If other implementations of this programming language exist, please make sure your compiler can be built with one of these.
           Examples include:])

       (ul (li [The Go programming language has two implementations:
                ,(anchor "the reference implementation" "https://golang.org/") is self-hosted, and that in ,(anchor "GCC" "https://gcc.gnu.org") is written in C++.
                Furthermore, version 1.4 of the reference implementation was written in a different language and can be used to build version 1.5.])
           (li [Common Lisp has several implementations.
                Notably ,(anchor "GNU clisp" "http://www.clisp.org/") is written and C and can be used to build self-hosted implementations such as ,(anchor "SBCL" "http://www.sbcl.org/").]))

       (h3 [When there is only one implementation])
       (p [If your compiler targets a language for which no other implementation exists, then please consider maintaining a (minimal) implementation of the language written in a different language.
           Most likely this implementation exists, or existed at the point the programming language was created.
           Maintaining this alternate implementation has a cost;
           however, this cost should be minimal if this alternate implementation is used routinely to build the compiler, and if this implementation is kept simple—it does not need to be optimized.])
       (p [Examples include:])

       (ul (li [,(anchor "GNU Guile" "https://gnu.org/software/guile"),
                a Scheme implementation with a self-hosted compiler,
                relies on a ,(anchor "Scheme interpreter written in C" "http://git.savannah.gnu.org/cgit/guile.git/tree/libguile/eval.c") for bootstrapping purposes.]))
       (p [Please let us know if you’d like to add your compiler to this list!])


       `(div (@ (id "build-system")))
       (h2 [For build systems writers])

       (p [Build systems sometimes have chicken-and-egg problems: they may need a version of themselves to get built.
           If you are developing a build system, this can be avoided.
           We recommend that you provide an alternative way to build your build system.])
       (p [Examples include:])

       (ul (li [,(anchor "GNU Make" "https://gnu.org/software/make") does not require a ,(code "make") implementation.
                It can be built using a ,(anchor "shell script" "http://git.savannah.gnu.org/cgit/make.git/tree/build.template").])
           (li [,(anchor "Apache Ant" "http://ant.apache.org/") can bootstrap with a ,(anchor "shell script" "https://git-wip-us.apache.org/repos/asf?p=ant.git;a=blob;f=bootstrap.sh;h=60b6ece03ce78716bc036a44226f4934b541f326;hb=HEAD") that only relies on the Java compiler.])
           (li [,(anchor "Bazel" "https://bazel.build/") does not require Bazel to build itself but can be boostrapped with a ,(anchor "shell script" "https://github.com/bazelbuild/bazel/blob/master/compile.sh").])
           (li [,(anchor "Buck" "https://buckbuild.com/") does not require Buck to build itself.
                Instead, it can be built using ,(anchor "Ant" "https://github.com/facebook/buck/blob/master/build.xml").]))

       (p [Build systems are generally easier to safely bootstrap than a self-hosted compiler that may need a full language compiler of its language.
           A slow and inefficient build written in shell scripts or a different older build system (Ant, GNU Make) may suffice to generate a minimal version of the build system to bootstrap a complete version of it.])

       `(div (@ (id "distro")))
       (h2 [For distros])

       (p [It is unavoidable that distributions use some binaries as part of their bootstrap chain.
           However, distributions should endeavour to provide traceacibility and automated reproducibility for such binaries.
           This means that:])

       (ul (li [It should be clear where the binary came from and how it was produced.])
           (li [Users can reproduce the binary to verify that it has not been tampered with.]))

       (p [For example, a distribution might use a binary package of GCC to build GCC from source.
           This bootstrap binary is in most cases built from a previous revision of the distribution's GCC package.
           Thus, the distribution can label the binary with something like "this package was built by running <command> on revision <hash> of the distribution's package repository."
           A user can then easily reproduce the binary by fetching the specified sources and running the specified command.
           This build will in most cases depend on a previous generation of bootstrap binaries.
           Thus, we get a chain of verifiable bootstrap binaries stretching back in time.])

       (p [Bootstrap binaries may also come from upstream.
           This would typically be the case when a language is first added to a distribution.
           In this case, it may not be obvious how the binary can be reproduced, but the distribution should at least clearly label the provenance of the binary, e.g. ,(em "this binary was downloaded from https://upstream-compiler.example.org/upstream-compiler-20161211-x86_64-linux.tar.xz").]))

;;TODO: provide an example of how we do this / are going to do this in
;; Nixpkgs / Guix / ...?
;;http://git.savannah.gnu.org/cgit/guix.git/commit/?id=062134985802d85066418f6ee2f327122166a567
)