# Gentoo Production Buildhoster - Usage Notes
# Copyright (c) 2005 Mike Green <mikey at badpenguins dot com>
# Released under the GNU GPLv2

bin/buildhost:

Usage:
  buildhost [ action buildhost_name ] | buildhost_name

  buildhost_name
     Refers to the corresponding spec file without specifying the extension.
     For example:
     buildhost mybuildhost
     Will chroot into the buildhost generated from mybuildhost.spec.

Actions:

  buildhost_name
    With only the buildhost_name argument buildhost will prepare the buildhost
    chroot environment and enter it.  Note that the buildhost must have
    previously been created via the buildhost --create buildhost_name command.
    The buildhost environment will be prepared by bind mounting the needed
    resources (PORTDIR, DISTFILES, PORTDIR_OVERLAY(s), /dev, /proc), and
    creating config files (make.conf, locale.gen, /etc/portage/*,
     /root/.bashrc).  Any changes to the spec file will be detected and the
    config files will be regenerated.

  --create buildhost_name
    Create a buildhost from the settings in the corresponding spec file.
    This action involves verifying the settings in the spec file, extracting
    the stage tarball, creating make.conf, creating the portage config
    files and creating any other needed config files (locale.gen).

  --help
    You are looking at it.

  --list
    List all currenly installed buildhosts.

  --refresh buildhost_name [ emerge options ]
    "Refresh" buildhost_name. Any packages defined by build_package: tags
    will be emerged in the order that they appearance in the spec file, each
    package will be updated via emerge -u, an emerge -Du world will run,
    and finally an emerge -DuN world will be performed.  Standard
    emerge options can also be passed through to the emerges, -pv or -f
    for example.  Note that the refresh-buildhost script can be manually run
    within the chroot environment at any time.

  --refresh-all [ emerge options ]
    "Refresh" (as descibed above) every buildhost present.

  --refresh-digests
    For every overlay present on the box, generate any missing digests for
    all ebuilds.

  --snapshot buildhost_name
    Generate a tarball of the specified buildhost.  The resulting tarball
    will be created in the BUILDHOST_STAGES directory and will be named:

    buildhost_name-snapshot_name.tar.bz2

    This action will unmount any currently mounted resources within the
    chroot environment.  There is no locking, so it is up to the user to
    determine if any other processes are currently running within the
    buildhost!

  --stage3 buildhost_name
    Run a custom bootstrap script and perform an emerge -e system on
    the buildhost.  The customized bootstrap script is:

    /usr/lib/buildhoster/scripts/buildhost-bootstrap.sh

    Note that the buildhost-bootstrap.sh script can be manually run at
    any time within the buildhost chroot and is also functional in a
    standalone environment.

  --unmount buildhost_name
    Unmount all bind mounted resources within buildhost_name.

    Perform this action before rm -r'ing any buildhosts, or you may end
    up deleting the parent host's /dev, /proc, portage tree, overlays,
    and distfiles!!!!

  --unmount-all
    Unmount (as descibed above) all bind mounted resources within ALL
    buildhosts currently installed on the box.

bin/refresh-overlays:

Looks in BUILDHOST_OVERLAY_CACHE and creates snapshots of any overlays
present.  The snapshots will be placed in the BUILDHOST_OVERLAYS
directory and will be named `basename OVERLAY`.tar.bz2.  For example if you
have a /var/buildhoster/overlays/myoverlay overlay, it will be named
myoverlay.tar.bz2.  It will overwrite any existing snapshot.

docs/gentoo-buildhoster-x.x.x.ebuild:

An ebuild to install gentoo-buildhoster.  Stick it in an overlay, generate the
digest with ebuild gentoo-buildhoster-x.x.x.ebuild, emerge gentoo-buildhoster.

docs/readme.txt:

You are looking at it ;)

docs/sample-tutorial.txt:

A tutorial that includes a sample spec, a sample overlay, etc...

etc/buildhoster.conf:

The gentoo-buildhoster configuration file.  Mostly it defines directory
locations used by gentoo-buildhoster.  The config file itself is will
commented.

lib/buildhoster-functions.sh:

Common functions used by the various commands in bin.  Very simply written to
encourage customization.

samples/specs:

Sample buildhost spec file for a stage3 that is optimized for a pentium3 and
using portage-20070326.tar.bz2 for the portage snapshot.

samples/overlays/sample-overlay:

A sample overlay containing a host configuration file package
(sampleweb-configs), a metapackage that contains the list of packages
needed for the sample web server (metapackages-web-server), and a sample kernel
package (poweredge-sc420).  Refer to docs/sample-tutorial.txt for details on
how to use these samples.

scripts/buildhost-bootstrap.sh:

The bootstrap script used by buildhost-stage3 to create a stage3 buildhost
from a stage1 tarball.  Handles CHOST/toolchain updates from any stage1 or
stage3.  Can also be used standalone.

scripts/refresh-buildhost [extra emerge options]:

A script that is copied over to the buildhost usr/local/bin directory and used
to build any packages defined by build_package: in the buildhost spec file.
For each package defined by build_package, var/lib/portage/world will be
checked, if the package has not been installed it will be emerged.  For each
of those packages an upgrade will be attempted, finally an emerge -Du world
will be performed.  This is mainly useful in situations where packages need
to be emerged in a certain order to prevent blockage stupidity.