commit: 85b44d605e6a85095a16f81b5eee9c380567acae Author: Anthony G. Basile <blueness <AT> gentoo <DOT> org> AuthorDate: Tue Aug 4 19:35:22 2015 +0000 Commit: Anthony G. Basile <blueness <AT> gentoo <DOT> org> CommitDate: Tue Aug 4 19:35:22 2015 +0000 URL: https://gitweb.gentoo.org/proj/grss.git/commit/?id=85b44d60
README: bring in line with wiki page. README | 171 +++++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 87 insertions(+), 84 deletions(-) diff --git a/README b/README index 626f80d..8bd1b7f 100644 --- a/README +++ b/README @@ -1,89 +1,92 @@ - -What is this? - -The Gentoo Reference System (GRS) Suite is a set of utilities for producing and -maintaining identical Gentoo systems from a series of configuration files housed -on a central git repository. 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. Gentoo -on FreeBSD), different C Standard Libraries (eg. glibc, uClibc or musl) and different -providers of core userland utilities (eg. busybox vs. 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 -Gentoo 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 predicably 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 preconfigured display -managers, windowing systems, 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 may -not 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 localy, or downloading -prebuilt 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 in a -manner consistant with GRS, but emerge and other portage utilities will always work. -Even if one does deviate from the GRS defined parameters, it should be possible to -return to strict GRS using the GRS utilities, provided one has not deviated too far. - -GRS is provided by app-portage/grs. 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,x -while the update builds/updates about 5700 packages. he first update run after a -new release is very time consuimgin becuase 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 update 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 download 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. - +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 repo describes the steps for building each - particular GRS system. This makes GRS runs highly flexible. One need only - transcribe the steps one would manually take in a chroot in build the system - into the build script, and grsrun will automatically repeat them. - - * It is possible to script a GRS system to do the equivalent of catalyst runs. - [TODO: there is still one more build script directive required here, pivot_chroot.] - - * 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 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. - +* 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 <[email protected].> - +* Anthony G. Basile <[email protected].> +Homepage: +* https://wiki.gentoo.org/wiki/Project:RelEng_GRS
