[Reproducible-commits] [reproducible-website] 25/55: Some more website tweaks
Chris Lamb
chris at chris-lamb.co.uk
Tue Aug 23 13:39:52 UTC 2016
This is an automated email from the git hooks/post-receive script.
lamby pushed a commit to branch master
in repository reproducible-website.
commit c49d9884387d4bbfad8c17ca7f61ecec1428b634
Author: Paul Gevers <elbrus at debian.org>
Date: Thu Nov 5 14:37:42 2015 +0100
Some more website tweaks
---
_docs/build_toolchain_from_source.md | 10 +++++-----
_docs/definition_strategies.md | 25 +++++++++++++------------
_docs/proprietary_os.md | 20 ++++++++++----------
_docs/recording.md | 21 +++++++++++----------
_docs/virtual_machine_drivers.md | 18 +++++++++---------
5 files changed, 48 insertions(+), 46 deletions(-)
diff --git a/_docs/build_toolchain_from_source.md b/_docs/build_toolchain_from_source.md
index 64a3b93..1a9384f 100644
--- a/_docs/build_toolchain_from_source.md
+++ b/_docs/build_toolchain_from_source.md
@@ -27,7 +27,7 @@ using a tag with a verified signature or a commit hash will work best.
The compilation itself can be driven by shell scripts or an extra target
in the project `Makefile`.
-Coreboot is a good example. The build documetation mandates to first run
+Coreboot is a good example. The build documentation mandates to first run
`make crossgcc` before building Coreboot itself.
Check-in everything
@@ -40,20 +40,20 @@ This is how several integrated operating systems like *BSD are
developed. “Building the world” will start by building the toolchain in
the version control system before building the rest of the system.
-It's also how it is done for Google's internal projects. They have
+Also Google's internal projects operate in this way. They have
released [Bazel](http://bazel.io/) which is based on their
-internal compilation tool. Bazel is designed to drive such large scale
+internal compilation tool. Bazel is designed to drive large scale
builds with speed and reproducibility in mind.
Outside of fully integrated operating systems or corporate environment,
it might be hard to push the idea of adding ten or more times the actual
-code base in toolchain…
+code base in the toolchain…
Ship the toolchain as a build product
-------------------------------------
As it might be hard to ask every user to spend time rebuilding a whole
-toolchain, OpenWrt gives a good example of a middle middle ground. An
+toolchain, OpenWrt gives a good example of a middle ground. An
“SDK” that can be downloaded alongside the system images which
contains everything that is needed to build—or rebuild—extra packages.
diff --git a/_docs/definition_strategies.md b/_docs/definition_strategies.md
index b184ac5..0c4bd20 100644
--- a/_docs/definition_strategies.md
+++ b/_docs/definition_strategies.md
@@ -4,39 +4,40 @@ layout: docs
permalink: /docs/definition-strategies/
---
-They are multiple ways to define the build environment in a way that it
+There are multiple ways to define the build environment in a way that it
can be distributed. The following methods are not exclusive and multiple
-aspects can be used for a single project. One can specify a reference
-Linux distribution and build a specific compiler version from source.
+aspects can be used for a single project.
Defining the build environment as part of the development process has a
very desirable aspect: changes in the build environment can be vetted
like any other changes. Updating to a new compiler version can be
-subject to reviews, automatic testing, and in case things
-break, rollback.
+subject to reviews, automatic testing, and—in case things
+break—rollback.
{% comment %}
XXX: maybe we want to add examples?
+Orig example in first paragraph One can specify a reference
+Linux distribution and build a specific compiler version from source.
{% endcomment %}
Build from source
-----------------
-One way to have users reproduce the tools used to perform the build
-is simply to have them start by building the right version of these
-tools from source.
+One simple way to have users reproduce the tools that are used to perform the
+build is making them start building the right version of these tools from
+source.
Using `make` or any other compilation driver, the required tools will be
downloaded, built, and locally installed before compiling the software.
Like any other [inputs from the network]({{ "/docs/volatile-inputs/" | prepend: site.baseurl }}),
-the content of the archive should be backed up and verified using
-cryptographic checksums.
+the content of the archive where the required source for the tools is stored
+should be backed up and verified using cryptographic checksums.
Reference distribution
----------------------
-Using a specific version of free software distribution is another viable
+Using a specific version of a free software distribution is another viable
option for a build environment.
Ideally, it should offer stable releases (like Debian, CentOS, or
@@ -62,4 +63,4 @@ trusted somehow. For example, it's currently not possible to install
Debian in a reproducible manner[^reproducible-install]. This makes it
harder to compare different installations.
-[^reproducible-install]: Some [preliminary work](https://wiki.debian.org/ReproducibleInstalls) has been done, mainly to identify the issues. Having byte-for-byte identical installations is a requirement to make *live* distributions build in a reproducible manner, so there is some interest by multiple parties in fixing the problem.
+[^reproducible-install]: Some [preliminary work](https://wiki.debian.org/ReproducibleInstalls) has been done, mainly to identify the issues. Having byte-for-byte identical installations is a requirement to make *live* distributions build in a reproducible manner, so there is interest by multiple parties in fixing the problem.
diff --git a/_docs/proprietary_os.md b/_docs/proprietary_os.md
index d048925..4e992b1 100644
--- a/_docs/proprietary_os.md
+++ b/_docs/proprietary_os.md
@@ -5,20 +5,20 @@ permalink: /docs/proprietary-os/
---
-It's hard to assess that proprietary operating systems have not been
-tampered with. They also require non-free compilation tools that can be
-hard to get for users.
+On proprietary operating systems, it is hard to determine if they are tampered
+with. Typically, they also require non-free compilation tools that can be hard
+to obtain for users.
The good news is that for some cases, we have free software tools which
are able to cross-compile software for proprietary operating systems
-from free operating systems. Both Bitcoin and Tor Browser have pioneered
-the technic to build their Windows and Mac OS X versions.
+on free operating systems. Both Bitcoin and Tor Browser have pioneered
+the technique to build their Windows and Mac OS X versions.
Windows
-------
For Windows, [ming-w64](http://mingw-w64.org/) will build Windows
-binaries from POSIX compatible operating systems.
+binaries on POSIX compatible operating systems.
[NSIS](http://nsis.sourceforge.net/) can be used to create integrated
installation package.
@@ -28,10 +28,10 @@ Both are readily available in several free software distributions.
Mac OS X
--------
-crosstool-ng [should work](https://bugs.torproject.org/9711#comment:73)
-to build software for Mac OS X. Sadly this seems to be require a
-non-redistributable part of the Apple SDK. It can extracted from XCode
-which can be downloaded at no charge.
+crosstool-ng [should work](https://bugs.torproject.org/9711#comment:73) to
+build software for Mac OS X. Sadly this seems to require a non-redistributable
+part of the Apple SDK. It can be extracted from XCode which can be downloaded
+at no charge.
Software from Mac OS X is often distributed as disk images (`.dmg`)
which can be created under GNU/Linux, but it seems to [require multiple
diff --git a/_docs/recording.md b/_docs/recording.md
index 7c9ba9e..633dca7 100644
--- a/_docs/recording.md
+++ b/_docs/recording.md
@@ -6,22 +6,23 @@ permalink: /docs/recording/
It is been customary in user facing software to provide a way for
developers investigating bugs to learn how the software has been
-built. The “about dialog” or output of `--version` would contain
+built. The “about dialog” or output of `--version` typically contains
information about the build environment.
In the context of reproducible builds, we either actively make aspects
of the build environment irrelevant to the build output, or ensure they
-are mandatory to rebuild the software exactly as it distributed.
+are mandatory to rebuild the software exactly as distributed.
-Any irrelevant information should not be recorded. This depends on what
-has been made [part of the build environment]({{ "/docs/perimeter/" | prepend: site.baseurl }}),
-but likely includes information such as date and time of the build,
-build system hostname, path, network configuration, CPU type, memory
-size, environment variables…
+All irrelevant information should not be recorded. What information is
+irrelevant depends on what defined to be
+[part of the build environment]({{ "/docs/perimeter/" | prepend: site.baseurl }}),
+but it likely includes information such as date and time of the build, build
+system hostname, path, network configuration, CPU type, memory size,
+environment variables…
The rest of the build environment should either be defined as part of
the development process or recorded during the build process.
-Anything recorded is best stored as a separate build product that can
-be easily ignored or distributed separately. This will help identify
-which variation is irrelevant to the software itself.
+Everything that is recorded is stored best as a separate build product that can
+be easily ignored or distributed separately. This will help identify which
+variation is irrelevant to the software itself.
diff --git a/_docs/virtual_machine_drivers.md b/_docs/virtual_machine_drivers.md
index fe644be..90683fd 100644
--- a/_docs/virtual_machine_drivers.md
+++ b/_docs/virtual_machine_drivers.md
@@ -9,8 +9,8 @@ system, forcing users to reinstall an entire computer just to reproduce
a build is a lot to ask.
Thankfully, nowadays we have virtual machine and containers which can
-give easy access to wide range of operating systems for a small
-overhead. Several tools have been designed to help driving virtual
+give easy access to a wide range of operating systems for little
+overhead. Several tools have been designed to help running virtual
machines and containers, some with the explicit goal of reproducible
builds in mind.
@@ -19,14 +19,14 @@ Gitian
[Gitian](https://gitian.org/) is the tool [used by
Bitcoin](https://github.com/bitcoin/bitcoin/blob/master/doc/gitian-building.md)
-and the Tor Browser. It either drives a Linux container using LXC, or a
+and the Tor Browser. It either runs in a Linux container using LXC, or in a
virtual machine using KVM.
Gitian takes
“[descriptors](https://github.com/bitcoin/bitcoin/blob/master/contrib/gitian-descriptors/)”
-as input which tells which base GNU/Linux distribution to use, which
-packages to install, which Git remotes must be fetched, any other input
-files, and a build script to be run with all of that. As explained
+as input which tell which base GNU/Linux distribution to use, which
+packages to install, which Git remotes to fetch, which other input
+files to use, and a build script to be run with all of that. As explained
earlier, using a virtual machine helps to get rid of several extra
variations that can happen from one system to the next. But this is
more complicated to setup for users.
@@ -46,7 +46,7 @@ in that environment which should be pretty much the same all the time.
To be sure that the base compiler is the same, one could use the fact
that Docker images can actually be addressed by a hash of their content.
-Another option is to build the Docker image itself in a reproducible
+Another option is to build the Docker image oneself in a reproducible
manner, something that can be done using
[Bazel](http://bazel.io/docs/be/docker.html).
@@ -54,7 +54,7 @@ Vagrant
-------
[Vagrant](https://www.vagrantup.com/) is another tool, written in Ruby,
-that can drive virtual machines with VirtualBox. It can also be used to
+that can run virtual machines with VirtualBox. It can also be used to
get a controlled build environment. The upside of Vagrant and VirtualBox
-is that they works on Mac OS X and Windows, and so this might help more
+is that they work on Mac OS X and Windows, and so this might help more
users to actually check that a build has not been tempered with.
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/reproducible/reproducible-website.git
More information about the Reproducible-commits
mailing list