added README

git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/catalyst/trunk@62 d1e1f19c-881f-0410-ab34-b69fee027534

1 files changed, 131 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 00000000..bd4c756d
--- /dev/null
+++ b/README
@@ -0,0 +1,131 @@
+catalyst is released under the GNU General Public License version 2,
+and is copyright Gentoo Technologies, Inc. Will be adding official
+COPYING file and source file preambles soon.
+
+How do I use this thing?
+========================
+
+Here's how you use catalyst. These instructions are for people using
+the cvs version of catalyst, not the to-be-created ebuild version.
+
+First, check out the gentoo/src/catalyst tree (which I'm guessing you
+have done.) Then, create an /etc/catalyst.conf file that looks like
+this:
+
+distdir="/mnt/misc/distfiles"
+options="ccache pkgcache"
+sharedir="/home/drobbins/cvs/gentoo/src/catalyst"
+
+The "sharedir" variable tells catalyst where to find its various
+plugins, and should point to the main catalyst directory that you
+checked out. the "options" variable is used to turn on .tbz2 package
+caching, which is off by default (you'll likely want it on, however.)
+Also, "distdir" is used here to tell catalyst where to look/store
+distfiles. The default is "/usr/portage/distfiles".
+
+Here are other variables you can set, and their default values.
+Please remember that *strings must be quoted*, as /etc/catalyst.conf
+uses python syntax:
+
+storedir	/var/tmp/catalyst		(where to build/write stuff)
+sharedir	/usr/share/catalyst		(where our plugins/scripts are)
+distdir		/usr/portage/distfiles		(where our distfiles are)
+portdir		/usr/portage			(where to grab snapshots from)
+options		ccache				what catalyst options are enabled
+
+You may also want to create a /usr/bin/catalyst symlink that points
+to the real location of your catalyst executable script.
+
+Creating a Portage tree snapshot
+================================
+
+First, make sure that your Portage tree is up-to-date as of 06 Nov 2003
+at the earliest, and that portage-2.0.49-r15 or 16 is unmasked for your
+specific build. These ebuilds (as of 06 Nov 2003) contain important fixes
+to allow catalyst to build properly. If you're not using the default-x86-1.4
+profile for building, please take a look at this profile and ensure that
+you are relatively in-sync with it. In particular, make sure that the
+GRP_STAGE23_USE variable is set in make.defaults, since catalyst uses
+this variable for building stage2 and stage3.
+
+Before building anything, you need to generate a snapshot of the portage
+tree that catalyst should use for building. To do this, ensure that your
+to-be-snapshotted portage tree is at /usr/portage, or set the "portdir"
+variable in /etc/catalyst.conf to point to the appropriate location, and
+then type:
+
+# catalyst target=snapshot version_stamp=20031102
+
+This will create the following file, assuming a /var/tmp/catalyst "storedir"
+setting:
+
+/var/tmp/catalyst/snapshots/portage-20031102.tar.bz2
+
+Grabbing a "seed" stage
+=======================
+
+Now, you need to grab a "seed" stage1, 2 or 3 tarball from somewhere to
+use to build other stages. Put the stage in /var/tmp/catalyst/builds/<profile>/;
+
+For example, if I have a stage3-pentium4-20031102.tar.bz2 file, I'd put it in:
+
+/var/tmp/catalyst/builds/default-x86-1.4/stage3-pentium4-20031102.tar.bz2
+
+...since that pentium4 stage was built using the "default-x86-1.4" profile.
+
+Building your first stage
+=========================
+
+Once you have your seed stage, you're now ready to build your first new stage.
+Here is a guideline for what components you'll need to build each type of stage:
+
+stage1 requires "generic" (ie. "x86" or "ppc") stage2 or 3
+
+stage2 requires "generic" stage1 (the only kind you should have :)
+
+stage3 requires stage2 of same type (ie. to build a "pentium3" stage3, you need
+a "pentium3" stage2, etc.)
+
+** Currently, only "stage1", "stage2" and "stage3" targets are supported. **
+
+Of course, to build each stage you will also need the Portage tree snapshot
+that you created above.
+
+To build a stage, type a command like this:
+
+# catalyst subarch=x86 version_stamp=20031102 target=stage2 rel_type=default rel_version=1.4 snapshot=20031102 source_subpath=default-x86-1.4/stage1-x86-20031102
+
+Wow -- that's a huge command! What does it mean? Let's look at the various arguments:
+
+cmdline arg			meaning
+-----------             	-------
+subarch=x86			build "generic" x86 stage (could also be "pentium3", "athlon-xp", "g4", etc.)
+version_stamp=20031102		give this stage being built a version stamp of "20031102"
+target=stage2			the type of stage we want to build is a stage2
+rel_type=default		use a "default-<mainarch>-??" profile (other possibilities: "hardened", etc.)
+rel_version=1.4			use a "??-<mainarch>-1.4" profile (note: mainarch is auto-determined from the subarch you provide)
+snapshot=20031102		use the Portage tree snapshot you created that has the "20031102" version_stamp
+source_subpath=default-x86-1.4/stage1-x86-20031102
+				To build our stage2, use a stage1 found at /var/tmp/catalyst/builds/ + this path. You are responsible
+				for ensuring that you choose an appopriate source stage for building your desired target stage.
+
+After you type this command, building should begin, and hopefully complete
+successfully, at which point the following tarball will be created:
+
+/var/tmp/catalyst/builds/default-x86-1.4/stage2-x86-20031102.tar.bz2
+
+The build directory used to build this stage can be found at:
+
+/var/tmp/catalyst/tmp/default-x86-1.4/stage2-x86-20031102/
+
+Building amd64 stages on x86
+============================
+
+Catalyst currently supports building x86 stages on 64-bit AMD64 systems. To do this,
+simply use as you would on x86, but ensure that the linux32 ebuild is emerged before
+starting. Catalyst will detect that you are building a 32-bit stage and will use the
+linux32 tool automatically when setting up chroots. Everything should work identically
+to if you were using a 32-bit system.
+
+Questions, bug reports:
+drobbins@gentoo.org