This is a not comprehensive list of FAQ about Catalyst.
Frequently Asked Questions
Frequently Asked Questions
How do I build a stage2 and stage3 tarball for a non-generic CPU type,
such as pentium4?
First, make sure that your hardware is capable of building such a stage. If
you want to build a pentium4 stage, you will need to build on a Pentium
4 or AMD64/Opteron system (or better). You cannot build a pentium4 stage
on an Athlon XP system, as Athlon XP CPUs do not support SSE2 instructions, and
SSE2 instructions will be enabled for pentium4 stages. Likewise, if you
want to build a g4 stage, you will need to do this on a PowerPC G4 or G5
Once you've made sure that you're building on the right hardware, simply follow
the steps above, but for building the stage2, simply change the subarch
setting to a valid non-generic subarchitecture (ie. pentium4.) Then your
stage2 will be built for the subarchitecture that you specify. Then, use this
stage2 as the "seed" stage to build your stage3. Of course, you will also want
to modify the subarch setting in your stage3 spec to match what you used
in your stage2 spec.
I want to build a bunch of stages for various subarches. How should I
First, build a generic stage1. Then use this stage1 to build a specialized
stage2 and stage3. Use the stage1 again to build another specialized stage2 and
stage3. You do not need to re-build the stage1 -- all your specialized stage2's
and stage3's can use the same "seed" stage1.
Can I build a stage1 for a non-generic CPU type?
This is a very bad idea, as users expect stage1's to work on any type of
subarchitecture. This way, they can use the stage1 on any system without
worries. You should be sure to not "pollute" your stage1 with non-generic
CPU-specific code. Always use a "generic" stage3 as a seed to build a new
I thought that catalyst was able to build stages "from scratch." If
catalyst builds stages from scratch, then why does it need a "seed
Good question. As you know, a stage2 and stage3 are dependent on previous
stages for building, which is expected and made clear by their name (ie. a
"stage2" implies that there was a "stage1".) However, catalyst does need a
seed stage for building a stage1, so in regards to building a stage1 it's worth
looking into why this is necessary. When building a stage1, catalyst uses the
seed stage3 to set up a chroot environment. Inside the chroot environment, the
new stage1 is built by setting the ROOT environment variable to
/tmp/stage1root. This instructs the package manager to merge all
new packages not to the current filesystem, but to the filesystem in
/tmp/stage1root. Catalyst then tars up /tmp/stage1root
and it becomes the target stage1. What this means is that when catalyst builds
a stage1, the stage1 itself does not inherit any binaries or libraries from the
seed that is used. The seed that is used does impact the target stage1
somewhat -- the Linux headers on the seed are used for building the stage1's
glibc, and the compilers on the seed are used to compile all the programs on
the stage1. The seed stage is used to isolate the stage1 build process from
your local system, and also allows for x86 stage1's to be built on amd64
systems, for example.
Is there an official HOWTO for Catalyst?
Currently, there is no official HOWTO. If you are interested in writing one,
though, please file a bug with the HOWTO attached to it. The lack of an
official HOWTO does not mean that catalyst is completely undocumented, though.
When catalyst is emerged, a well commented set of example spec files are
installed to /usr/share/doc/catalyst-$version/examples.
If you still have questions after reading through the examples, feel
free to subscribe to the gentoo-catalyst mailing list.
Where do I put per-package use flags, mask settings, etc.?
Catalyst supports the configuration files in /etc/portage. Just add the
following to your spec file, and make sure that you use the same
portage_confdir setting for your seed stages as well:
Should I really build my own stage1 or just use one from a Gentoo
It is best practice to always build your own stages if you are not using
the same snapshot that was used to build the last release. The state of the tree
is very much dependent on itself. If you have a stage1 from 3 months ago, it is
very likely that you will run into problems with blockers and other changes in
the tree that will cause you build or compatibility problems.
How do I keep my GRP/stages/LiveCD packages updated?
Catalyst uses Portage for all of the building work, so all that you have to do
is regenerate your Portage snapshot and rebuild your GRP/stages/LiveCD. Portage
will follow all of its normal rules for deciding which packages to update.
Does Catalyst use any special USE flag syntax?
No, catalyst's USE flag syntax is exactly the same as portage's.
Does Catalyst support crosscompiling?
No, at the moment it does not.