This file documents how barclamps are packaged for installation
and distribution.

All barclamps that the Crowbar build process creates are packaged into 
tarballs with the following layout:

  <barclamp name>/ is the name of the barclamp 
    crowbar.yml contains required barclamp metadata.  More detailed information
                on what this file contains can be found in:
                /opt/dell/barclamp_model on a freshly installed admin node.
    sha1sums contains SHA1 checksums of everything in the barclamp tarball.
             barclamp_install.rb uses this information to ensure that
             the tarball was not corrupted and that it will not overwrite local
             changes when installing a different barclamp revision.
    bin/ contains binaries for /opt/dell/bin.
         These are installed by barclamp_install.rb.
    chef/ contains chef cookbooks, roles, and data bags.
          See the barclamp model for more information on these directories. 
    smoketest/ contains scripts for the smoketest framework.
               See crowbar/test_framework/README.testing for more info.
    cache/ contains the files and packages required by this barclamp
      files/ contains raw files that the barclamp needs.
             Examples are things like .ami files, raw source packages, etc.
             Files and paths under this directory will be merged into
             /tftpboot/files, and will wind up being served from
             http://<admin ip>:8091/files/
	     As a special case, the install process will unpack the .rpm
             files from anything that looks like an Oracle java install
	     package and place them into
	     /tftpboot/<os-token>/crowbar-extra/oracle-java
      gems/ contains gems that the barclamp requires.
            Any gems will be symlinked into /tftpboot/gemsite/gems.
            The install process on the admin node arranges for 
            /tftpboot/gemsite to be served as a Rubygems repository through
	    http://<admin ip>:3001/, and all nodes are configured to use
	    that URL as their primary Gem repository.
      <os-token>/ is a name like ubuntu-10.10, centos-5.7, etc.
                  Ideally, there will be one of these for each OS the barclamp
		  supports.  
        pkgs/ contains all the <os-token> packages that the barclamp needs.
	      /tftpboot/<os-token>/crowbar-extra/<barclamp name> will be a 
	      symlink to this directory, so this directory should follow the
	      layout conventions appropriate for whatever package manager
	      is used by <os-token>.  Any packages in this directory will be
	      installable on all the nodes.

Creating a barclamp tarball:

   The crowbar repository has a package_barclamp.sh script to help automate
the process of creating a barclamp tarball.  That script makes the following
assumptions:
  1: The barclamp you wish to create is checked out under the Crowbar git
     repository at barclamps/<barclamp name>.
  2: The packages, files, and gems that your barclamp needs are present in the
     crowbar build cache and were fetched by the build process.

The package_barclamp.sh script takes the following options:
  * --destdir <directory>
    If this option is present, package_barclamp will save the barclamp tarballs
    it creates in <directory>.  If it is not present, it will save them in the 
    current directory.
  * --os <os-token>
    If this option is present, package_barclamp will only stage OS specific
    packages for <os-token> along with the OS-independent files and gems. If
    it is not present, package_barclamps.sh will try to package all the OS
    specific packages it finds in the build cache.
  * <barclamp names>
    The names of the barclamps you want to package.

Installing a barclamp:

   Once you have a Crowbar admin node up and running, you can install new
or updated barclamps using barclamp_install.rb.

barclamp_install.rb can install multiple barclamps from multiple different
sources at the same time, and it always installs barclamps in priority
order as defined in the crowbar.yml for each barclamp. barclamp_install.rb
knows about 3 types of sources:
  * A path to a barclamp tarball.
    If you pass a path to a barclamp tarball, barclamp_install.rb will
    extract the tarball into a temporary directory and verify that the
    previous install (if any) is pristine before continuing.
  * A path to a directory containing a valid crowbar.yml.
    If you pass a directory outside of /opt/dell/barclamps, barclamp_install.rb
    will check to see if the current install is pristine before allowing the
    install to continue.
  * The name of a barclamp already installed in /opt/dell/barclamps.
    If this is the case, barclamp_install.rb will assume that you are
    reuploading an already installed barclamp, and will not check for 
    pristineness.

You can override the pristineness check in any of the above install methods
by passing the --force switch to barclamp_install.rb.  After the pristineness
check passes (or is overridden), the installer will copy the updated barclamp
contents into /opt/dell/barclamps/<barclamp name>, merge the newer crowbar
framework bits, update the chef components, and add new files and symlinks
(as appropriate) to the cache directories.

Once the new barclamp is installed, you will have to manually update the
metadata for the gem and OS package repositories -- barclamp_install.rb is
not smart enough to do it for you.  The steps for that are:
  * find -L /tftpboot -type l -print0 |xargs -0 rm
    This will delete any dangling symlinks that may be laying around.
  * cd /tftpboot/gemsite; gem generate_index
    This will recreate the metadata that gem uses to install the gems.
  * cd /tftpboot/<os-token>/crowbar-extra
    <os-token> is the OS you want to regenerate the package metadata for.
    On RPM based distros, run:
    # createrepo -d -q .
    # knife ssh 'node:*' yum clean expire-cache
    On .deb based distros, run:
    # dpkg-scanpackages . |gzip -9 >Packages.gz
    # knife ssh 'node:*' apt-get update