Project:Catalyst/FAQ
This article contains frequently asked questions (FAQs) relating to the Catalyst tool. It is not comprehensive list, but should help those who are interested in learning more.
Eventually a Catalyst guide will be written, but for now this will have to work. Post any unanswered questions on the associated discussion page.
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 system.
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 sub-architecture (ie. pentium4.) Then your stage2 will be built for the sub-architecture 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 sub-arches. How should I do this?
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 sub-architecture. 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 stage1.
I thought that Catalyst was able to build stages from scratch. If Catalyst builds stages from scratch, then why does it need a seed stage?
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 (stage3) 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 guide for Catalyst?
Currently, there is no official guide for Catalyst. If you are interested in writing one please do. It can be created your personal user space here on the Wiki and then moved to a more official location upon review by Catalyst developers.
The lack of an official guide does not mean that Catalyst is entirely undocumented. 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 or query Catalyst developers in #gentoo-releng (webchat).
Where do I put per-package use flags, mask settings, etc.?
Catalyst supports the configuration files in /etc/portage. Just add the following to the .spec file, and make sure that you use the same portage_confdir value for the seed stages as well:
example.spec.spec file exampleportage_confdir: /path/to/custom/etc/portage
Should I really build my own stage1 or just use one from a Gentoo mirror?
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.
This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: John P. Davis (author), Daniel Robbins ( Daniel Robbins (drobbins) ) (author), William Kilian (contributor), Chris Gianelloni (editor),
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.