DevelopmentInstructions

''If you were looking for information on the test suite, it's been moved [[Tests|here]]''

= Overview =

The BCCD-NG environment is stored entirely in a Subversion repository on hopper. Read-write access is provided over ssh, at
  svn+ssh://bccd-ng.cluster.earlham.edu/cluster/svnroot/bccd-ng/

Development branches are under

  svn+ssh://bccd-ng.cluster.earlham.edu/cluster/svnroot/bccd-ng/branches

with the common branch name being ''your-name''-devel.

The BCCDv3 ISO is assembled in a single pass in the <code>[https://cluster.earlham.edu/trac/bccd-ng/browser/trunk/bin/build_livecd.pl#L1 bin/build_livecd.pl]</code> script. It is composed of a series of tests from the Bccd.pm perl module, found in <code>[https://cluster.earlham.edu/trac/bccd-ng/browser/trunk/trees/usr/local/lib/site_perl/Bccd.pm#L1 trees/usr/local/lib/site_perl/Bccd.pm]</code>. Tests take different numbers of arguments, so look at the signature of the specific test subroutine to figure that out. Keep in mind that every run_test call will have at least four arguments: the name of the test, the success return code the test should expect (which is left blank in nearly all cases for a safe default), the message the test should print out, and the first (and maybe only) argument for the test.

For historical reasons, the liberation script is at <tt>packages/liberate.pl</tt>. This probably should be moved to a more sensible location in the future. The script has the same layout as the build_livecd.pl script. Remember that the liberation should assume no network connectivity, so all files should be fetched in the ISO build. Files that are specific to the liberation can be stored in <tt>/root/liberate</tt>, which is reference by the <tt>$LIBFETCH</tt> variable.

For more information on specific tests, see the POD documentation within Bccd.pm.

= Getting started =

== Creating a new SVN branch ==

The best way to get started is to make your own SVN branch. To do that, enter a directory on your current system where you want a local check out, and issue a command like this:

   svn cp svn+ssh://bccd-ng.cluster.earlham.edu/cluster/svnroot/bccd-ng/trunk/ \
      svn+ssh://bccd-ng.cluster.earlham.edu/cluster/svnroot/bccd-ng/branches/your-branch-here

You can then checkout or update that branch. To checkout your newly created branch, issue a command like:

   svn co svn+ssh://bccd-ng.cluster.earlham.edu/cluster/svnroot/bccd-ng/branches/your-branch-here

You will now want to get setup in [[Jenkins]].

== Directory structure ==

* <code>bin</code> - Contains executables responsible for maintenance of the BCCD itself, for instance building the ISO image and copying it to a USB stick.
* <code>packages</code> - Contains files that must be downloaded in a specific order from <code>build_livecd.pl</code>.
* <code>trees</code> - Every subdirectory of <code>trees</code> is downloaded in a single transaction, so this is where you should be files that don't need to be downloaded in a specific order. 
** <code>trees/bin</code> - Binaries that should end up in /bin on the BCCD, the default location for the <code>bccd-*</code> commands.
** <code>trees/arch/''arch''</code> - Contains architecture-specific files
** <code>trees/KNOPPIX</code> - Contains files that will end up in the BCCD outside the KNOPPIX singularity (i.e. in the ISO itself)

== Recipes ==

# Add or modify a file in ~bccd
## All files should be in in <code>packages/etc/skel</code> to support [https://cluster.earlham.edu/trac/bccd-ng/ticket/692 multiple users].
## Modify or add the file in skel, and commit the change. All the files will be pulled down automatically.
# Change a file in /etc
## Add the file to <code>packages/etc</code>.
## The placement of files in /etc comes with many dependencies (when a package gets installed, whether a service gets started automatically, etc.). For this reason, you'll have to add a [[DevelopmentInstructions#Running_tests|''test'']] to fetch the file out of WebDAV, and optionally other tests to change its ownership and permissions. There are several for loops in <code>build_livecd.pl</code> that you might be able to take advantage of, if your file has similar dependencies as the other files in that loop.
# Add a [[DevelopmentInstructions#Environment_management|module]]
## "Master" module files are stored in <code>trees/usr/local/Modules/3.2.6/modulefiles</code>. You will probably never have to touch these unless you need to add another module repository.
## "Software" module files are stored in <code>trees/usr/local/etc/modules</code>, and <code>trees/usr/local/etc/modules-remote</code> (if you're using remote modules).
## Since modules are stored in a subdirectory of tree (<code>trees/usr</code>), all files are fetched at once and you don't have to add a separate test.

== Commits etiquette ==

Follow two rules when you commit:

# Always reference a ticket number in the commit message, e.g. <pre>adding libnet-ip for dhcp dialog script (#358)</pre>
# Always test your changes before merging from your branch into trunk.

= Build process =

See [[Build Process]]

= Build requirements =

The following 

* Perl modules
** WWW::Mechanize (libtest-www-mechanize-perl)
** Term::ReadKey (libterm-readkey-perl)
** Readonly (libreadonly-perl)
** UI::Dialog (libui-dialog-perl)
** NetAddr::IP (libnetaddr-ip-perl)
** Net::DHCP::Packet (libnet-dhcp-perl)
** Net::CIDR (libnet-cidr-perl)
** YAML (libnet-yaml-perl)
** (File::Temp)
* debootstrap
* subversion
* genisoimage
* lsof
* bzip2
* psmisc (for killall)
* syslinux-common (for ppmtolss16)
* netpbm (for pngtopnm)
* liblzma-dev (for custom squashfs-tools)
* liblzo2-dev (for custom squashfs-tools)
* squashfs-tools (custom)
** Download squashfs-tools 4.2 from [http://squashfs.sourceforge.net/ SourceForge]
** After unpacking, enter the squashfs-tools directory. Set the following variables in the Makefile:
*** XZ_SUPPORT = 1
*** LZO_SUPPORT = 1
*** LZMA_XZ_SUPPORT = 1
*** LZMA_DIR=/usr
** Type <code>make install</code> to install the squashfs tools in /usr/local/bin

Note: Some default versions of the File::Temp Perl module are bugged and do not contain the newdir method. To circumvent this issue, install File::Temp using cpan.

Then proceed to setup [[Jenkins]]

= Stages =

The BCCD has a number of different configurations, called stages. Applications need to know this so they can react appropriately. The current stage is stored in <code>/etc/bccd-stage</code>. The current stages are these:

* '''BUILD'''     - Only during the initial build of the ISO image
* '''LIVE'''      - True for systems running off a live media (CD, USB, etc.)
* '''LIBERATED''' - True for the liberated head node

A proposed addition is:

* '''DISKLESS'''  - True for diskless nodes running off a liberated head node

= Troubleshooting =

== bccd-report ==

<code>/bin/bccd-report</code> is a script that end users may run to gather all information that might be useful in debugging a problem. This script will generate ~bccd/bccd-report.tar.bz2, which maybe transported to another system and emailed to the list manually. The list of gathered information is in [https://cluster.earlham.edu/trac/bccd-ng/ticket/696 #696].

It is designed to have as few dependencies as possible, so that even a seriously impaired system may still generate useful information.

The end user documentation is at [[UserInstructions#Supplying information to developers|the user instructions page]].

== Regenerating live squashfs ==

Often it's desirable to generate just the squashfs filesystem, located in the BCCD ISO image at <code>live/filesystem.squashfs</code>. The most common reason would be to test a feature without having to wait for an entire ISO build. These are the steps necessary to do this on a Debian-type system:

<ol>
 <li>Make sure you have the squashfs-tools package installed.</li>
 <li>Fetch the <code>extract_squashfs</code> script from [https://cluster.earlham.edu/trac/bccd-ng/browser/trunk/bin/extract_squashfs SVN].</li>
 <li>Extract the ISO image and containing squashfs to separate directories: <code>sudo ./extract_squashfs -i <i>/path/to/bccd.iso</i></code></li>
 <li>This command will print out two paths - one with "ISO" and one with "SQUASHFS". Take note of both and be sure to clean them up when you are done.</li>
 <li>Make edits in the SQUASHFS directory as needed.</li>
 <ul>
  <li>Generate a new SQUASHFS, stick it on an existing USB stick: <code>sudo mksquashfs /tmp/squashfs.5ETepz /mnt/usb0/live/filesystem.squashfs -comp xz</code></li>
  <li>Generate a new SQUASHFS (see above), but instead stick it in the ISO image directory at <code>live/filesystem.squashfs</code>. Then re-generate the ISO image: <code>genisoimage -pad -l -r -J -v -V BCCDv3-<i>some-svn-rev</i> -no-emul-boot -boot-load-size   4 -boot-info-table -b boot/isolinux/isolinux.bin -c boot/isolinux/boot.cat -hide-   rr-moved -o <i>/path/to/bccd.iso</i> <i>/path/to/ISO_DIR</i></code>
 </ul>
</ol>

== Debugging early boot process ==

Problems early on in the boot process can be difficult to diagnose. It is useful to understand the Linux boot process to know where to begin debugging:

# The BIOS (or equivalent like EFI) detects boot devices and assembles them into a list based on some internal heuristic (typically user-specifiable in the BIOS configuration)
# For each boot device from the list, the BIOS will attempt to find a boot code in the first sector of the device. The first device that has this code will have it loaded into memory and executed.
# In the case of BCCD, this boot code (whether from a CD, USB stick, or hard drive) will point at the boot loader (isolinux in the case of CD, syslinux in the case of USB sticks, and GRUB in the case of hard drives).
# The boot loader contains information on where to find the Linux kernel. Additional information is passed as options to the kernel command line, such as the location of the initial RAM disk (initrd), but is not interpreted by the boot loader itself. If found, the boot loader will load the kernel into memory and execute it.
## isolinux assumes that it will be placed within a [http://en.wikipedia.org/wiki/ISO_9660 ISO9660 filesystem] in the directory <code>/boot/isolinux</code>. It will look for a <code>isolinux.cfg</code> file within that directory, and all paths in that file are relative to <code>/boot/isolinux</code>.
## syslinux assumes that it will be placed with a [http://en.wikipedia.org/wiki/File_Allocation_Table VFAT filesystem] in the root directory. It looks for a <code>syslinux.cfg</code> file, and all paths in that file are relative to <code>/</code>.
## syslinux 4.05 is known to work for BCCD; if you get problems finding the root filesystem or the BCCD splash screen, you should downgrade.
# The kernel will spawn a single process called "swapper", which will initialize critical OS functions like memory management, process scheduling, and hardware detection. Hardware with support built directly into the kernel (as opposed to a loadable module) will be detected during this step.
# Once swapper is done bringing the system to a minimally-usable state, it will try to find the initrd specified in the initrd= option in the boot configuration file (isolinux.cfg, syslinux.cfg, etc.) in the same filesystem as the boot loader and kernel. This file is either a gzip'd [http://en.wikipedia.org/wiki/Ext2 ext2 filesystem] image or a gzip'd [http://en.wikipedia.org/wiki/Cpio cpio archive]. It will uncompress and copy the contents of the initrd into a RAM disk, and look for the executable specified by the init= command line option from the boot loader. swapper will fork a process called "init" which will execute the init executable. In practice this is a shell script, but it can be any valid executable.
# The init process will configure hardware devices whose modules are not built directly into the kernel, and also perform other tasks that need to be done before the main OS boots. In the case of BCCD, this includes configuring networking for diskless nodes, and configuring the aufs union filesystem for live and diskless nodes. As a final task, it will mount the actual root filesystem. How it finds the root filesystem depends on the mode:
## For live systems, it will be detected by mounting every available disk device, and looking for the file specified by the BOOT_IMAGE kernel command line argument (KNOPPIX by default). The first device containing that file is assumed to be the root filesystem.
## For liberated systems, it will be specified by the root= kernel command line argument.
## For diskless systems, it will be specified by a combination of root=/dev/nfs and nfsroot= being set to the IP address and directory that should be mounted. There is additional logic within the init script to setup the aufs mounts.
# When init completes, it will execute a function called pivot_root that will change the root filesystem pointer from the RAM disk to the newly-mounted root filesystem, and then execute <code>/sbin/init</code> within the context of the new root filesystem. At this point RAM disk is destroyed, and the OS completes booting (mounting other filesystems, starting services, networking, etc.).

=== Debugging problems with the boot code ===

If you don't even see the boot loader screen (isolinux, syslinux, grub), you should check:

* That the devices are detected in the BIOS configuration.
* That the devices actually have boot code on them. (insert examples of running utilities manually)

=== Debugging problems with the boot filesystem ===

If you see the boot loader, but get some problem immediately after it tries executing the kernel (before the penguins appear):

* Make sure the kernel is in the location specified by the boot loader. (insert configuration docs here)
* Make sure that the boot filesystem is mountable by inserting the media in a booted system and mounting it.

=== Debugging problems with the kernel boot process ===

If you get problems with the kernel (after the penguins appear):

<ul>
 <li>Remove the <code>quiet</code> option from the kernel boot options, and set <code>loglevel</code> to 7. This will allow you to see the kernel output as it boots.</li>
 <ul>
  <li>For CD images, you must [[DevelopmentInstructions#Rebuilds|rebuild the ISO image]] with a new <code>/boot/isolinux/isolinux.cfg</code></li>
  <li>For USB sticks, insert it into another system and edit the <code>syslinux.cfg</code> file in the root of the boot filesystem.</li>
  <li>For liberated systems, you can simply hit "e" when grub appears, and edit the command line interactively.</li>
 </ul>
 <li>If you're really stuck, you can try inserting debug statements into the init script in the initrd.</li>
 <ul>
  <li>For live booting off a CD (follow all steps for CD booting, only steps marked <b>USB</b> for USB sticks):</li>
  <ol>
   <li>Mount the ISO image over the loop back interface: <code>mount -o loop,ro <i>/path/to/bccd.iso</i> /mnt/loop0</code></li>
   <li>Make a temporary directory to hold the ISO image: <code>mkdir -p /tmp/bccd</code></li>
   <li>Copy the ISO image into the temp directory: <code>rsync -av /mnt/loop0/ /tmp/bccd/</code></li>
   <li><b>USB</b> Uncompress the initrd: <code>gunzip /tmp/bccd/boot/isolinux/minirt.gz</code></li>
   <li><b>USB</b> Mount it over the loop back interface: <code>mount -o loop /tmp/bccd/boot/isolinux/minirt /mnt/loop1</code></li>
   <li><b>USB</b> Insert debug statements into the init script, <code>/mnt/loop1/linuxrc</code>. This might be echo'ing variables, or you can get a full shell by sticking <code>/bbin/sh</code> wherever you want</li>
   <li><b>USB</b> Unmount the initrd: <code>umount /mnt/loop1</code></li>
   <li><b>USB</b> Recompress initrd: <code>gzip /tmp/bccd/boot/isolinux/minirt</code></li>
   <li>[[DevelopmentInstructions#Rebuilds|Rebuild the ISO image]]</li>
  </ol>
  <li><b>NOTE</b> - The live CD uses the busybox shell, which contains a number of programs in a single executable image. There are two different ways of accessing these programs:
  <ul>
   <li>By linking directory entries to busybox (for instance, <code>ls -> busybox</code>), such that ARGV[0] will be set to the program name.</li>
   <li>By calling busybox directly, and supplying the program name as ARGV[1] (for instance, <code>/bbin/busybox ls</code>)</li>
  </ul>
 </ul>
</ul>

=== systemd ===

See [[Systemd]]

=== Downgrading syslinux ===

# Fetch syslinux 4.05: <code>curl -k -O https://cluster.earlham.edu/bccd-ng/syslinux/syslinux-common_4.05+dfsg-6+deb7u1_all.deb -O https://cluster.earlham.edu/bccd-ng/syslinux/syslinux_4.05+dfsg-6+deb7u1_amd64.deb</code>
# Install: <code>dpkg -i syslinux-common_4.05+dfsg-6+deb7u1_all.deb syslinux_4.05+dfsg-6+deb7u1_amd64.deb</code>
# Prevent future upgrades from touching syslinux: <code>apt-mark hold syslinux syslinux-common</code>

= Advanced =
''If you were looking for information on the test suite, it's been moved [[Tests|here]]''

== Subversion Best Practices ==

See [[Subversion Best Practices]] for more information on how to use [http://subversion.apache.org/ Subversion] effectively for BCCD development.

== build_livecd.pl and the Bccd.pm Perl module ==

=== Common variables ===

* <tt>$project</tt>: Use wherever you would use the project name.
* <tt>$websvn</tt>: Use wherever you need to point into the branch's subversion repository.
* <tt>$builddir</tt>: The full, un-chroot'd path to the temporary build directory.
* <tt>$software</tt>: Software directory within the build directory.
* <tt>$projdir</tt>: The common directory for diskless node information.
* <tt>$newhome</tt>: The home directory of the bccd user.
* <tt>$checkin</tt>: The directory where nodes checkin to the master node.
* <tt>$libfetch</tt>: The directory where files used only after liberation are placed.
* <tt>$test_name</tt>: The name of the test. Only used if you're updating the test database.
* <tt>$stage</tt>: The name of the current stage. Will be BUILD for the build.
* <tt>$svnrev</tt>: The subversion revision that the script is building against.
* <tt>$tmpdir</tt>: The temporary directory for the build.
* <tt>$packages</tt>: List of packages to install with <tt>apt-get</tt>.

=== Common operations ===

The following are a list of operations that are common to the `build_livecd.pl` script. They are somewhat ordered, in that if you can get by with an earlier operation, you should.

==== Debian CLI ====

This should always be preferred to any of the other options. Use `apt-get`, `debootstrap`, `debconf`, etc. wherever possible, called from the system test in Bccd.pm. This might look like

<pre>
$Bccd->run_test(
                "system",
                "",
                "Running apt-get install."
                "apt-get install $packages"
                );
</pre>

==== Changing files ====

If you have to, change only part of the file using sed or perl regexen, Again, you can call these from the system tests in Bccd.pm. This might look like

<pre>
$Bccd->run_test(
                "system",
                "",
                "Changing interface in networking."
                "sed -e 's/ifconfig eth0/ifconfig eth1/g' < \ 
$libdir/$projdir/etc/init.d/networking > $libdir/etc/init.d/networking"
                );
</pre>

==== Entire file ====

You can store an entire file in subversion. Fetch it using the <tt>revfetch</tt> test, which takes the URL to the file, the subversion revison, and where you want to squirt the file in the build. This might look like

<pre>
$Bccd->run_test(
              "revfetch",
              "",
              "Fetched checkin cron.",
              $svnrev,
              "$websvn/packages/etc/cron.d/node-checkin",
              "$builddir/etc/cron.d/node-checkin"
              );
</pre>

==== Entire tree ====

Use this only if you are fetching a directory tree and not overwriting existing files. There are too many dependency problems involved with overwriting existing files in the build. chdir using the <tt>chdir</tt> test to the base directory of the destination directory tree. Then use the <tt>recrevfetch</tt> test, which takes a subversion revision, and a repository URL. This might look like

<pre>
$Bccd->run_test(
              "chdir",
              "",
              "cd $builddir",
              "$builddir"
              );

$Bccd->run_test(
              "recrevfetch",
              "",
              "Fetched bin tools.",
              $svnrev,
              "$websvn/packages/bin/"
              );
</pre>

==== Tar balls ====

The BCCD-NG development originally used tar balls to distribute changes. This is deprecated for a number of reasons, but where it's still working I haven't touched it. Do what I say and not what I do, and use the options above.

==== Init scripts ====

Init scripts are a SysV-based system's way of starting a service at a particular time. Init scripts in the BCCD are located either in <code>packages/etc/init.d</code> or <code>trees/etc/init.d</code>. Remember that files in <code>packages</code> need to be pulled down individually, while files in <code>trees</code> are pulled down en masse. Most init scripts need <code>update-rc.d</code> run, so most should end up in <code>packages</code>. Here's a step-by-step procedure for adding one:

<ol>
 <li>Add your init script to <code>packages/etc/init.d</code> in your SVN branch.</li>
 <li>Annotate the LSB block appropriately. For instance, below is the LSB block for <code>packages/etc/init.d/networking</code>. This makes sure that local filesystems are mounted (important for diskless nodes), and that the mountkernfs and bccd-nics init script have already run. It also says that, if available, ifupdown should be run before networking starts, and after it stops. See [http://wiki.debian.org/LSBInitScripts the Debian wiki] for details on how LSB works in Debian.
<pre>
### BEGIN INIT INFO
# Provides:          networking
# Required-Start:    mountkernfs $local_fs bccd-nics
# Required-Stop:     $local_fs
# Should-Start:      ifupdown
# Should-Stop:       ifupdown
# Default-Start:     2 5
# Default-Stop:      0 1 6
# Short-Description: Raise network interfaces.
### END INIT INFO
</pre></li>
 <li>In <code>bin/build_livecd.pl</code>, add a test to remove the init script's stop and start links. This is necessary so that they can be re-created with the proper dependency information. There are for-loops in build_livecd.pl, but a singleton test would look like this:
<pre>
    $Bccd->run_test(
        "system",
        "",
        "Disabled $script.",
        "/usr/sbin/chroot $BUILDDIR /usr/sbin/update-rc.d -f some-script remove",
        );
</pre></li>
 <li>In <code>bin/build_livecd.pl</code>, add a test to re-addthe init script's stop and start links based on the new dependency information. There are for-loops in build_livecd.pl, but a singleton test would look like this:
<pre>
    $Bccd->run_test(
        "system",
        "",
        "Disabled $script.",
        "/usr/sbin/chroot $BUILDDIR /usr/sbin/update-rc.d -f some-script defaults",
        );
</pre></li>
 <li>Commit everything to SVN.</li>
 <li>[[#Building_the_BCCD_ISO|Rebuild the ISO.]]</li>
</ol>

== Building the BCCD ISO ==

Changes should always be tested before being committed to trunk. This can be done on any Debian system with a checkout of the subversion repository.

# cd into <tt>branches/livecd-devel/bin/</tt>.
# <code>script -fc "sudo perl build_livecd.pl --arch i386 --suite squeeze --outiso /tmp/test-$(whoami).iso --websvn (your branch in the web repository) " /tmp/build-script-$(whoami).log</code>
#* Your branch should look something like this: 
#** <nowiki>http://bccd-ng.cluster.earlham.edu/svn/bccd-ng/branches/(branch name)</nowiki>
# You can view the output of the test in <code>/tmp/build-script-(your username).log</code>.
#* try <code> grep '^not ok' /tmp/build-script-$(whoami).log</code>
#* If you have problems add <code>--debug --nocleanup</code> to the build_livecd.pl command line and append <code>&> build-stderr-stdout.log</code> to the command line.

== Automated builds ==

After you get all the prerequisites setup and do a manual build, you can setup automated builds. First fetch auto_build_wrapper.sh from the bin directory of a branch or trunk.

   wget http://bccd-ng.cluster.earlham.edu/svn/bccd-ng/trunk/bin/auto_build_wrapper.sh && chmod +x auto_build_wrapper.sh

Then create configuration file that looks like this:

   ARCH=amd64
   DBUSER=dc_tester
   WEBSVN="http://bccd-ng.cluster.earlham.edu/svn/bccd-ng/"
   BRANCH="${WEBSVN}/trunk/"
   BINDIR="/bin/"
   BLDCD="build_livecd.pl"
   PATH=$PATH:/sbin:/usr/sbin
   OUTBASE=/cluster/bccd-ng/stable
   OUTISO=$OUTBASE/bccd_latest.${ARCH}.iso
   TEMPISO=$(mktemp ${OUTISO}.XXXXXXXX)

Then setup a cron job that looks like this:

   34 20 * * * /root/auto_build_wrapper.sh -c /root/auto_build_wrapper.i386.conf

== Committing changes to trunk ==
# You'll need a working copy of trunk for this. If you haven't already, go to a folder and run <tt> svn co svn+ssh://leemasa@cluster.earlham.edu/cluster/svnroot/bccd-ng/trunk</tt>
#* Get comfortable, this will take a while.
#* If you have a working copy of trunk, make sure it's up-to-date with <tt> svn up </tt>.
# get into the root of your trunk directory
# Run <tt>svn merge --dry-run -r rev1:rev2  (your development working directory) .</tt>. rev1 is the last commit into the trunk, which you can see with <tt>svn log | less</tt>. rev2 is the new revision that you just committed to livecd-devel. Make sure the files being updated are the files you want updated. Look for any files with a "C" by them. You will have to merge those files by hand in the next step.
# <tt>svn merge -r rev1:rev2 svn+ssh://bccd-ng.cluster.earlham.edu/cluster/svnroot/bccd-ng/branches/livecd-devel/ .</tt>. Merge any conflicted files by hand, then run <tt>svn resolved filename</tt>. After everything is OK, run <tt>svn commit</tt> in the trunk directory, and commit your changes. Make sure that build_livecd.pl still has its websvn variable pointing into trunk and not livecd-devel.

== Adding packages ==

See [[Reprepro]] for details on how the BCCD package repository works.

See [[Fpm]] for details on how to build custom packages for BCCD.

=== Via aptitude ===

aptitude is easy if there is an existing deb package in the tree on a0. Simply add it to the YAML configuration file <code>bin/packages.conf</code>. Most packages should be added to BASE. EXTRA is for packages that might become optional in the future, and AMD64 is for packages that should only be installed on AMD64 (rather than i386) builds.

=== Via svn ===

This option involves adding a "tree" to the subversion repository that contains the software built. Follow these steps to do it:

# From the live CD or liberation (liberation is recommended for disk space reasons), build and install the software into a subdirectory of /cluster/software.
# Make a symlink from ''software-xx.yy.zz'' to ''software'', where xx.yy.zz is a version number.
# tar up ''software-xx.yy.zz'' and ''software'', and move the tar ball to a host with a local subversion checkout.
# cd into the development branch, and then to <code>trees/software/cluster/software</code>.
# un-tar the tar ball.
# Run <code>svn add software*</code>.
# Remove the keywords property (this can cause binaries to become corrupted): <code>find ''dir'' -type f ! -regex '.*\/\.svn\/.*' -print0|xargs -0 svn pd svn:keywords</code>
# Commit the changes.
# [[DevelopmentInstructions#Testing_changes|Build a test ISO]] and test the new software.
# Merge the changes into the trunk.
# Document the process of building the package in the [[Software Build Documentation]] page.

== Local builds ==
=== Using a local package mirror ===

By default, the build process uses the package mirror located at http://debmirror.cluster.earlham.edu/apt/mirror/bccd-ng/debian/. The script will allow the use of a local debmirror. Supply the hostname to the local repository using the <tt>--debmirror</tt> option. Don't supply the full URL; the rest of the URL will be constructed later in the script.

=== Using a local Subversion mirror ===

The build script fetches files out of Subversion using WebDAV at http://bccd-ng.cluster.earlham/svn/bccd-ng/branch-name, where branch-name would be trunch or branches/livecd-devel. You can supply an alternative WebDAV URL with <tt>--websvn</tt>.
== Editing the splash screen ==
See the isolinux instructions for changing a boot screen: http://www.sweb.cz/Frantisek.Rysanek/splash/isolinux-splash-HOWTO.html

== Kernel updates ==

See [[Kernel updates]].

== Environment management ==

As mentioned in [[UserInstructions#Environmentmanagement|the user manual]], the BCCD uses [http://modules.sourceforge.net Modules] to manage a user's environment (variables, aliases, etc.). This provides a Tcl-based framework to manage a user's environment as software packages are added and deleted. Every package installed in <tt>/bccd/software</tt> should get a module directory in <tt>/usr/local/etc/modules</tt>, with every version of the package as a separate file in the directory. Every module file is  a Tcl script invoked by the <tt>modules</tt> command. For example, OpenMPI version 1.4.0 has this file in <tt>/usr/local/etc/modules/openmpi/1.4.0</tt> ([http://cluster.earlham.edu/trac/bccd-ng/browser/trunk/trees/usr/local/etc/modules/openmpi/1.4.0#L1 source]):

<pre>
#%Module1.0#####################################################################

prereq          modules
conflict	lam
conflict	mpich2
set             MOD_OPENMPI              $env(BCCD_SW)/openmpi
set      MOD_OPENMPI_VERSION      1.4.0
set      MOD_OPENMPI_DIR          $MOD_OPENMPI-$MOD_OPENMPI_VERSION
module-whatis "OPENMPI"

prepend-path    PATH                $MOD_OPENMPI_DIR/bin/
prepend-path    LD_LIBRARY_PATH     $MOD_OPENMPI_DIR/lib/
prepend-path    MANPATH             $MOD_OPENMPI_DIR/share/man/
prepend-path    -d " " LDFLAGS      -L$MOD_OPENMPI_DIR/lib/
prepend-path    -d " " CPPFLAGS     -I$MOD_OPENMPI_DIR/include/

if { [catch { exec /bin/bccd-snarfhosts $env(HOME)/machines openmpi} msg] } {
	puts "bccd-snarfhosts failed: $::errorInfo"
}
</pre>

* The first line is a magic number to identify this as a modules file.
* <tt>prereq modules</tt> will cause an error to be printed if the main BCCD modules file (called <tt>modules</tt>) isn't loaded first.
* The <tt>conflict</tt> lines make sure other MPI implementations aren't loaded at the same time this module is loaded, since the binary names conflict.
* The next three lines set internal Tcl variables that are scoped only within this file. These are not environment variables.
* <tt>module-whatis "OPENMPI"</tt> is just a free-form identification for what this module provides.
* Optional <tt>setenv</tt> lines will set user environment variables to whatever values are provided in the third field (e.g., <tt>setenv VARIABLE "value"</tt>)
* The <tt>prepend-path</tt> lines ensure that OpenMPI's files are found properly in a user's search paths. The <tt>-d " "</tt> changes the delimiter from the default of <tt>:</tt>, since <tt>LDFLAGS</tt> and <tt>CPPFLAGS</tt> are both space-delimited.
* The MPI modules automatically run <tt>bccd-snarfhosts</tt> when loaded to ensure the correct version of the machines file is in the user's home directory.

These module files should be placed in <tt>trees/usr/local/etc/modules/''software-name''/''version''</tt>, which is part of the <tt>MODULEPATH</tt> search path. <tt>module load</tt> will load the lexigraphically last software version by default, but you can override this behavior by symlinking the version you want to be default to <tt>default</tt>.

See the [[Fpm]] page for details on building .deb packages to install into Modules.

See the [[Software Build]] page for build information for these software packages.

== USB automounting ==

The BCCD uses udev to detect when USB storage devices are plugged in, and mounts them automatically. The udev setup is in [http://trac.cluster.earlham.edu/bccd-ng/browser/trunk/packages/etc/udev/rules.d/99-automount_usb.rules], and the script that the rule file calls is in [http://trac.cluster.earlham.edu/bccd-ng/browser/trunk/trees/bin/bccd-usbwall].

== SNMP ==

BCCD uses SNMP to gather information from other BCCD nodes. Its unique IANA private enterprise number is 40551.

== Licensing & copyright ==

=== SVN properties ===

'''Todo''' - Document how to do this in ~/.subversion/config

* Set Id: <code>svn propset svn:keywords Id ''file''</code>
* Set Copyright: <code>svn propset Copyright 'Copyright (C) ''YYYY'' Andrew Fitz Gibbon, Paul Gray, Kevin Hunter, Dave Joiner, Sam Leeman-Munk, Tom Murphy, Charlie Peck, Skylar Thompson, & Aaron Weeden' ''file''</code>
* Set License: <code>svn propset License -F ''/path/to/COPYING'' ''file''</code>

=== In every file ===

Put this at the top of every file, in whatever comment blocks make sense:

   $Id$
   
   This file is part of BCCD, an open-source live CD for computational science
   education.
   
   Copyright (C) 2010 Andrew Fitz Gibbon, Sam Leeman-Munk, Charlie Peck,
      Skylar Thompson, & Aaron Weeden
   
   This program is free software: you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.
   
   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.
   
   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.