From a342cf8a3602273751da751978f5120e234c10cb Mon Sep 17 00:00:00 2001 From: "Anthony G. Basile" Date: Sat, 2 Apr 2016 18:14:04 -0400 Subject: README.md: update --- README | 92 --------------------------------------------------------------- README.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 92 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 8bd1b7f..0000000 --- a/README +++ /dev/null @@ -1,92 +0,0 @@ -Description - -The Gentoo Reference System (GRS) Suite is a set of tools for building and -maintaining a well defined Gentoo system in which all choices in building the -system are predefined in configuration files housed on a central git -repository. All systems built according to a particular GRS spec should be -identical. As a "from source" distribution, Gentoo allows a large degree of -customization. The space of all possible packages and USE flags is vast, not to -speak of more radical choices such as different kernels (eg. Linux or FreeBSD), -executable formats (eg. ELF or Mach-O), different C Standard Libraries (eg. -glibc, uClibc or musl) and different providers of core userland utilities (eg. -busybox or coreutils). In contrast to other distributions where each instance -of an installed system is nearly identical to another, the large array of -choice in Gentoo means that any two systems are unlikely to be sufficiently -similar that executables or libraries from one will "just work" on the other, -even if the architecture and other hardware factors are the same; assuming, of -course, there is no conscious effort to build identical systems. This is where -the Gentoo Release System (GRS) Suite comes in. It does precisely this, namely, -it provides an automated method for repeatedly and predictably generating -identical Gentoo systems. - -GRS is designed to work roughly as follows: Periodic release tarballs are -generated which are "polished". For example, releases can provide -pre-configured display managers, windowing systems and desktop themes, even -user accounts and home directories. Installation should be as simple as -unpacking the release tarball on pre-formated partitions with minimal or no -further configuration. There is no need to build any packages or a kernel and -everything is ready to go out of the box. A release tarball can be downloaded -from some server or alternatively can be built locally. While these may not -initially be identical because they were build at different times, after -updating, both approaches should yield identical systems. - -Updating a GRS system can proceed by either building packages locally, or -downloading pre-built binpkgs. As long as one does not deviate from the GRS -defined set of USE flags, maskings and other configuration parameters, both -approaches should yield identical systems. A GRS system is always a Gentoo -system, so at any time, one can elect to part ways from GRS and venture out on -one's own! The GRS Suite provides a utilities to make sure that configurations -in /etc/portage are properly maintained in a manner consistent with GRS, but -emerge and other portage utilities will always work. Even if one does deviate -from the GRS specs, it should be possible to return to strict GRS using the -Suite's utilities, provided one has not deviated too far. - -GRS is provided by the app-portage/grs package. The same package is installed -on either a server responsible for building the release tarballs and binpkgs, -or on an actual GRS system. On the server, a daemon called grsrun will either -do a release run, in which case it builds the release tarballs, or it will do -an update run where it either builds or updates a bunch of extra binpkgs. For -example, for GRS = desktop-amd64-uclibc-hardened, the release run builds a -little under 900 packages and produces the polished release tarball, while the -update run builds/updates about 5700 packages. The first update run after a new -release is time consuming because some 5700 new packages must be built, but -subsequent update runs need only build packages which were bumped since the -last update run. - -On the client, a utility called grsup acts as a wrapper to emerge. grsup will -both manage the configuration files in /etc/portage as well as either builds or -download the binpkg from a PORTAGE_BINHOST. After the initial installation of a -GRS system, one need only run grsup to bring it up to date. While releases -tarballs will be pushed out periodically, these are not used to update an -existing GRS system, only to start new one. Rather, one GRS release should -smoothly update to the next; in other words, each GRS release is equivalent to -the previous release plus any updates since. The only reason to push out a new -release tarball is to avoid having to subsequently push out a large number of -updates for each new installation. - -CAVEAT: This is work in progress. A few of the above point are marginally -working or implemented. This warning will disappear after this whole project -moves past being experimental. - -Features: -* The GRS suite does not hard code any steps for the release or update runs. -Rather, a build script on the git repository describes the steps for building -each particular GRS system. This makes GRS runs highly flexible. One need only -transcribe the steps one would manually make in a chroot to build the system -into build script directives, and grsrun will automatically repeat them. -* It is possible to script a GRS system to do the equivalent of catalyst runs. -* The use of Linux cgroup make management easy. There is no need to trap or -propagate signals when writing the scripts that are to be run in the chroot. A -simple SIGTERM to grsrun will ensure that all children process no matter how -deep are properly terminated and that any bind-mounted filesystems are -unmounted. -* A GRS system acts as a "tinderbox lite" in that build failures are reported. -So as a GRS system evolves over time, as package are bumped, any breakages that -are introduced will be caught and reported. [TODO: get these reports -automatically into bugzilla.] - -Authors: -* Anthony G. Basile - -Homepage: -* https://wiki.gentoo.org/wiki/Project:RelEng_GRS diff --git a/README.md b/README.md new file mode 100644 index 0000000..db5edcb --- /dev/null +++ b/README.md @@ -0,0 +1,88 @@ +Description + +The Gentoo Reference System (GRS) Suite is a set of tools for building and +maintaining a well defined Gentoo system in which all choices in building the +system are predefined in configuration files housed on a central git +repository. All systems built according to a particular GRS spec should be +identical. As a "from source" distribution, Gentoo allows a large degree of +customization. The space of all possible packages and USE flags is vast, not to +speak of more radical choices such as different kernels (eg. Linux or FreeBSD), +executable formats (eg. ELF or Mach-O), different C Standard Libraries (eg. +glibc, uClibc or musl) and different providers of core userland utilities (eg. +busybox or coreutils). In contrast to other distributions where each instance +of an installed system is nearly identical to another, the large array of +choice in Gentoo means that any two systems are unlikely to be sufficiently +similar that executables or libraries from one will "just work" on the other, +even if the architecture and other hardware factors are the same; assuming, of +course, there is no conscious effort to build identical systems. This is where +the Gentoo Release System (GRS) Suite comes in. It does precisely this, namely, +it provides an automated method for repeatedly and predictably generating +identical Gentoo systems. + +GRS is designed to work roughly as follows: Periodic release tarballs are +generated which are "polished". For example, releases can provide +pre-configured display managers, windowing systems and desktop themes, even +user accounts and home directories. Installation should be as simple as +unpacking the release tarball on pre-formated partitions with minimal or no +further configuration. There is no need to build any packages or a kernel and +everything is ready to go out of the box. A release tarball can be downloaded +from some server or alternatively can be built locally. While these may not +initially be identical because they were build at different times, after +updating, both approaches should yield identical systems. + +Updating a GRS system can proceed by either building packages locally, or +downloading pre-built binpkgs. As long as one does not deviate from the GRS +defined set of USE flags, maskings and other configuration parameters, both +approaches should yield identical systems. A GRS system is always a Gentoo +system, so at any time, one can elect to part ways from GRS and venture out on +one's own! The GRS Suite provides a utilities to make sure that configurations +in /etc/portage are properly maintained in a manner consistent with GRS, but +emerge and other portage utilities will always work. Even if one does deviate +from the GRS specs, it should be possible to return to strict GRS using the +Suite's utilities, provided one has not deviated too far. + +GRS is provided by the app-portage/grs package. The same package is installed +on either a server responsible for building the release tarballs and binpkgs, +or on an actual GRS system. On the server, a daemon called grsrun will either +do a release run, in which case it builds the release tarballs, or it will do +an update run where it either builds or updates a bunch of extra binpkgs. For +example, for GRS = desktop-amd64-uclibc-hardened, the release run builds a +little under 900 packages and produces the polished release tarball, while the +update run builds/updates about 5700 packages. The first update run after a new +release is time consuming because some 5700 new packages must be built, but +subsequent update runs need only build packages which were bumped since the +last update run. + +On the client, a utility called grsup acts as a wrapper to emerge. grsup will +both manage the configuration files in /etc/portage as well as either builds or +download the binpkg from a PORTAGE_BINHOST. After the initial installation of a +GRS system, one need only run grsup to bring it up to date. While releases +tarballs will be pushed out periodically, these are not used to update an +existing GRS system, only to start new one. Rather, one GRS release should +smoothly update to the next; in other words, each GRS release is equivalent to +the previous release plus any updates since. The only reason to push out a new +release tarball is to avoid having to subsequently push out a large number of +updates for each new installation. + +Features: +* The GRS suite does not hard code any steps for the release or update runs. +Rather, a build script on the git repository describes the steps for building +each particular GRS system. This makes GRS runs highly flexible. One need only +transcribe the steps one would manually make in a chroot to build the system +into build script directives, and grsrun will automatically repeat them. +* It is possible to script a GRS system to do the equivalent of catalyst runs. +* The use of Linux cgroup make management easy. There is no need to trap or +propagate signals when writing the scripts that are to be run in the chroot. A +simple SIGTERM to grsrun will ensure that all children process no matter how +deep are properly terminated and that any bind-mounted filesystems are +unmounted. +* A GRS system acts as a "tinderbox lite" in that build failures are reported. +So as a GRS system evolves over time, as package are bumped, any breakages that +are introduced will be caught and reported. [TODO: get these reports +automatically into bugzilla.] + +Authors: +* Anthony G. Basile + +Homepage: +* https://wiki.gentoo.org/wiki/Project:RelEng_GRS -- cgit v1.2.3-65-gdbad