aboutsummaryrefslogtreecommitdiff
path: root/README
blob: bd4c756d162afa9777da8e96bc9116ee3222cacd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
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