EncapPackages: Beginning of some dir structure changes

git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@2074 ce84e21b-d406-0410-9b95-82705330c041

1 files changed, 177 insertions, 0 deletions

diff --git a/encap/HOWTO b/encap/HOWTO
new file mode 100644
index 000000000..488639c7f
--- /dev/null
+++ b/encap/HOWTO
@@ -0,0 +1,177 @@
+= Encap based bootstrap for bcfg2 and complete bcfg2 client toolchain =
+
+This bootstrap code is a method for getting bcfg2 (as a client),
+including all dependencies, up and running on a new platform as
+quickly as possible (from source).
+
+The latest version of this document is always available from:
+ * http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/encap/README
+
+For a more general overview of what this is, see:
+ * http://trac.mcs.anl.gov/projects/bcfg2/wiki/EncapPackages
+
+You can view this document with glorious Trac Wiki formatting at:
+ * http://trac.mcs.anl.gov/projects/bcfg2/wiki/EncapHowto
+   (Although that version may be out of date)
+
+You can obtain the latest version of the code from bcfg2 svn:
+ * `svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2/encap`
+
+Or browse the latest version on the web via:
+ * http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/encap
+
+Using the encap package manager it automatically downloads, builds and
+creates encap packages for bcfg2 and dependencies to `/usr/local/encap`, and
+installs symbolic links to these packages from `/usr/local` (the usual encap
+thing). 
+
+It attempts to be as self contained as possible; everything gets linked to
+under `/usr/local/lib/bcfg2`, except for bcfg2 itself and some dependent
+software, which is prefixed by `b2-` (`b2-openssl`, `b2-python` etc.).  
+
+To run the bcfg2 server, you also need to install gamin, which
+supports a subset of the platforms bcfg2 client will work on, including
+GNU/Linux and FreeBSD.
+
+When using this packaging, `/etc/bcfg2.conf` is instead
+`/usr/local/etc/bcfg2.conf`.
+
+This should be considered an alpha version. Everything compiles and seems to
+work, but it has not yet been tested with a working bcfg2 repository.
+
+== Building and installing everything ==
+ 1. Make sure all of the Prerequisites (see below) are installed.
+ 1. The build user needs write access to the encap source and build 
+    directories. By default, these are `/usr/local/encap` and 
+    `/usr/local/src`. If you like to live dangerously, you can also just do 
+    the builds as `root`.
+ 1. Run `make`. This will kick off and background the entire build process. 
+    Make output will be redirected to `make.log`, and package build output 
+    will go to individual log files.
+ 1. If everything goes well, try running "`bcfg2-repo-validate`". This should 
+    not generate a python traceback :-)
+ 1. You now have *-encap-*.tar.gz encap packages you can distribute to other 
+    machines. If you don't like the OS name encap uses automatically (esp. 
+    on GNU/Linux these can be too generic), do `make rename OS=somestring`.
+
+== Prerequisites ==
+ * GNU gcc and GNU g++
+   * If you are using the gcc distributed with Solaris/x86 10, you need to 
+     install the gcc bugfix at http://www.openssl.org/~appro/values.c by 
+     running "ksh -f values.c" as root (or openssl will segfault)
+ * GNU make (make sure "gmake" links to GNU make on non-GNU platforms)
+ * /usr/local/man should be a directory, not a symbolic link
+ * epkg (the encap package manager)
+   * Canonical website is http://www.encap.org/epkg
+   * Mirror of epkg binaries is available at http://www.dclark.us/mirror/
+   * If built from source, first need all recommended libraries from web page
+
+You will need binaries of the GNU tools. For GNU and BSD based operating 
+systems, you should be able to get these via the operating system's package 
+system. For commercial operating systems, these can be obtained from:
+
+ AIX::
+ * UCLA's Public Domain Software Library for AIX at 
+   http://aixpdslib.seas.ucla.edu/aixpdslib.html 
+   (These are trivial to convert into encap packages)
+ * Bull AIX Freeware at http://www.bullfreeware.com/
+
+ Solaris::
+ * Freeware for Solaris at http://www.sunfreeware.com/
+ * Community Software for Solaris at http://www.blastwave.org/packages.php
+
+== Supported Platforms == 
+Below is a table of platforms that have been successfully bootstrapped using
+this code.
+
+|| OS        || Vendor || Version || Arch  || GCC   || By || With VERSION   ||
+|| AIX       || IBM    || 5.3     || POWER || 4.1.0 || dc || 0.7/0.8.2      ||
+|| GNU/Linux || Debian || Sarge   || i386  || 3.3.5 || dc || 0.7/0.8.2      ||
+|| GNU/Linux || Debian || Sid     || i386  || 4.1.2 || dc || 0.8/0.8.2      ||
+|| Solaris   || Sun    || 10      || Sparc || 3.4.3 || dc || 0.7/0.8.2      ||
+|| Solaris   || Sun    || 10      || i386  || 3.4.3 || dc || 0.7/0.8.2      ||
+
+dc: "Daniel Clark" <mailto:dclark@member.fsf.org>
+
+If you bootstrap a platform not listed above, please add a comment to:
+ * http://trac.mcs.anl.gov/projects/bcfg2/ticket/74
+so that platform can be added to the list. 
+
+If you modified any of the files in this package to be able to bootstrap the
+new platform, please include either diffs or a tarball of your modified
+version in a new ticket so your changes can be incorporated into a new
+release. 
+
+Any other notes, such as where you got the GNU binaries or any issues people
+should be aware of, would also be appreciated. 
+
+You may want to scan all of the bootstrapped binaries and libraries with
+`ldd` (or equivalent) to make sure there are no dependencies on libraries
+other than those included with the base operating system and the libraries
+built as part of the bootstrap process. 
+
+On non-GNU operating systems, libgcc and libstdc++ are a run-time
+requirement. These libraries are usually distributed with gcc/g++, so the
+bootstrap system attempts to create encap packages containing those
+libraries by copying them from the build machine. To test that this worked,
+you'll want to either temporarily remove gcc/g++ from the build machine and
+make sure everything still works, or install the bcfg2-*.tar.gz encap
+packages on a "clean" machine (without a gcc/g++ install) and test on that 
+machine.
+
+Note that the doc for the encap profile format is in "man 5 encap_profile".
+
+== Release Notes ==
+ 0.1::
+ * Initial Released Version
+ * Work needs to be done to minimize size of distribution. In 0.1
+   libraries and binaries are not stripped, and there is a lot of
+   pruning that can be done of individual packages.
+
+ 0.2::
+ * Updated bcfg2 to 0.8.2pre7
+ * Updated README to point to mcs.anl.gov resources
+
+ 0.3::
+ * Updated bcfg2 to 0.8.2pre10
+
+ 0.4::
+ * Versions before this version won't work without manually fixing paths
+ * Added patches so paths actually exist, specifically:
+   * bcfg2.conf default location is /usr/local/etc
+   * epkg/encap paths changed to encap default /usr/local paths
+   * schema prefix patch (changeset 1953) applied
+   * default schema prefix changed to /usr/local/lib/bcfg2
+ * Added mirror of all packages downloaded by the profiles at 
+   http://www.pobox.com/users/dclark/mirror and made mirror default for
+   those downloads
+   * Set up automatic hourly mirror of bcfg2 ftp site *.tar.gz files
+   * Mirror of other packages is manual (but deps shouldn't change often)
+
+ 0.5::
+ * Removed external download of patches as that was not working consistently;
+   replaced with patches inline the bcfg2 encap profile (.ep file)
+ * Added GNU patch dependency, both for bcfg2 patches and call from Cfg.py
+ * Fixed bcfg-repo-validate so it can find xmllint (as b2-xmllint)
+ 
+ 0.6::
+ * Updated bcfg2 to 0.8.2 (released version)
+ * Removed r1953 patch from bcfg2 profile, since that is included in 0.8.2
+ * Added alpha version warning
+
+ 0.7::
+ * Added Solaris support
+
+ 0.8::
+ * Added python code to fix paths; removed inline patch & GNU patch dependency
+   * Path change happens as part of install, logged to postinstall.log
+ * Changed prefix from b2 to b2- to disambiguate from system commands  
+ * Fixes to make man pages easier to access
+ * Install tools as b2-example-tools-*
+ * Added some auxiliary tools under tools/ directory
+   * daemontools - cross-platform alternative to init scripts/cron
+   * ostiary - simple/secure daemon for kicking off a local script
+   * epkg Makefile - to build epkg when prebuilt binaries aren't available
+
+== Documentation Version ==
+$Id$