source: trunk/debathena/NOTES @ 22729

This hierarchy contains Debian/Ubuntu-specific materials, also known
as "Debathena".  The contents are:

* debathena - Debathena-specific software packages such as PAM and NSS
  modules.

* config - Packages for configuring native system software in a manner
  appropriate for Athena.

* meta - Packages which contain nothing but dependencies on other
  packages and serve as an installation convenience.

* scripts - Build scripts and supporting materials.

Debathena is a SIPB project, and its infrastructure and procedures
will need to be adapted for Athena 10.  For the moment this file will
document the Debathena procedures as they are, not as they will be.
The current procedures do not even use this svn repository yet.

Debian software used by Debathena:

  * schroot - Used to manage build chroot environments for each
    Debian/Ubuntu version.  We use the lvm-snapshot schroot type,
    which allows rapid construction of ephemeral copies of template
    "source" chroots, so that every binary package build is done in a
    clean environment.

  * debuild - Used to create Debian source packages from package
    source directories.

  * sbuild - Used to build binary packages from source packages inside
    schroot environments.

  * equivs - Used to create packages which only contain dependency
    information.  Somewhat of a dirty hack, since it doesn't keep
    proper changelogs, but it reduces overhead.

  * CDBS (Common Debian Build System) - Referenced by debian/rules
    files in packages.  Contains standard build rules to cut down on
    per-package boilerplate.

  * reprepro - Used to upload packages into the apt repositories.

  * approx - Used to create a local cache of Debian packages on the
    build server.  This cache is referenced by the build chroots for
    improved performance.

Procedures used by Debathena for handling day-to-day package changes
for regular packages:

  * To prepare a change to a regular package, the contents are edited
    directly in the /mit/debathena/packages subdir.

  * To record the prepared change in the changelog:
    (From inside the package source directory)
    dadch

  * To build and deploy the changed package for all environments:
    (From inside the package source directory, on debuild.mit.edu)
    debuild -S
    cd ..
    da sbuildhack <filename>.dsc

  * Generally the package is tested by manually installing it on test
    machines with dpkg -i.

  * To deploy the package to the repository:
    (From the package source parent directory, on debuild.mit.edu as
    the debuild user)
    daupload-release <filename>_source.changes

  * If the package is architecture-independent, the -A option is
    passed to da and daupload-release.

For an equivs-built package, the process is simpler since there is no
source package and only one binary package:

  * To prepare a change to the control file, the contents are edited
    directly in the /mit/debathena/packages subdir.

  * To build the binary package:
    (From the package directory, on debuild.mit.edu)
    equivs-build --full <filename>.equivs

  * To deploy the package to the repository:
    daequivsupload <filename>.changes

Adding a new distribution:

  <not yet written>

Setting up a build server:
(Adapted for Athena 10)

  1. The build server must be installed with free space in an LVM
     volume group.  The build chroots consume 2GB each.

  1. Install debathena-standard as per the the instructions in
     http://debathena.mit.edu/install.

  2. Install the packages listed in
     scripts/build-server/packages (using "aptitude install")

  3. Install debathena-login, debathena-ssh-server, and
     debathena-build-depends (using "aptitude install").

     (Depending on how recently debathena-build-depends was rebuilt,
     additional packages might need to be installed to satisfy the
     build-depends of newer packages.  This can be taken care of later
     when an error occurs building a source package.)

  4. Edit /etc/security/access.conf and add a first line:
     -:ALL EXCEPT root <developer usernames>:ALL

  5. Edit /etc/group and add the developers to the sbuild group.

  6. Create /etc/passwd entries for each developer with "hesinfo
     username passwd >> /etc/passwd" and then run pwconv.

     (This is not necessary for the login system on the main root
     environment, but is for the chroot environments.)

  7. Append to /etc/approx.conf the contents of
     scripts/build-server/approx.conf.tail

  8. For each supported dist and arch (see scripts/all-schroots) run:

       VG=/dev/blah scripts/build-server/make-chroot dist arch

     substituting the name of the volume group for blah.

     Example: VG=/dev/dink scripts/build-server/make-chroot gutsy i386

Removing a build chroot on the build server:

  1. Run VG=/dev/blah scripts/clean-schroots to make sure that the
     build chroot is not mounted, substituting the name of the volume
     group for blah.

  2. Edit /etc/schroot/schroot.conf and delete the section
     corresponding to the chroot.

  3. Run lvchange -an blah/chrootname
     substituting the name of the volume group for blah and the chroot
     name for chroot.  Example: lvchange -an dink/gutsy-i386-sbuild

  4. Run lvremove -an blah/chrootname