From Gentoo Wiki
Jump to: navigation, search

Porting Gentoo to new architectures/platforms/etc...


As developers expand Gentoo to new architectures and platforms, they may find there is not any real collection of knowledge which explains all the little details of Portage and moving a platform into the experimental release stage. This document aims to address that. Here we port Gentoo Linux to the SuperH (sh) architecture, but the details should be pretty straight forward for other architectures and operating systems.

Getting the system running

This is the hardest step by far (really!). There are two ways to get going. You can start with an existing Linux port out there (Debian, RedHat, some random hobbyist distribution, etc...), or you can cross compile the entire system. The first route is the easiest, so we will only cover that in this guide. Simply boot up the system with the existing port and make sure it has all the important packages installed for development. A quick checklist (with recommended minimum versions):

  • binutils (2.20)
  • gcc (4.4)
  • glibc (2.11)
  • python (2.7)
  • rsync
  • wget
  • tar
  • gzip
  • bzip2
  • bash (must be 2.05b or newer, ver 3 is best, accessible as /bin/bash)

Converting to Gentoo

Once you have these packages, you can easily install Portage. This script has been written to do the task. Simply download it and run:

root #sh ./bootstrap-portage

todo: move this file to the portage tree and parse the portage ebuild ...

We now need to make a profile for the new architecture. To do so, we first create a local ebuild repository (overlay) with the new profile, then active the both the repository and the profile:

root #mkdir -p /usr/local/portage/profiles/default/linux/sh
root #cd /usr/local/portage/profiles/default/linux/sh
root #echo '..' > parent
root #cat << EOF > make.defaults
root #mkdir -p /etc/portage
root #cd /etc/portage
root #echo "PORTDIR_OVERLAY=/usr/local/portage" >> make.conf
root #ln -sfT ../usr/local/portage/profiles/default/linux/sh make.profile
If you decide to use a newer version of Portage than provided by the bootstrap script, additional steps may be necessary to set up the local ebuild repository and the profile. See the Profile and Ebuild repository wiki pages for more information.

Finally, sync up and we should have our Portage tree!

root #emerge --sync

Preparing a seed for Catalyst

Since none of the ebuilds in Portage know about our new arch, we can cheat with package.keywords and using x86 as the reference architecture:

root #mkdir -p /etc/portage
root #cd /etc/portage
root #printf '%s x86\n' $(USE="-*" ACCEPT_KEYWORDS=x86 emerge @system -qep --cols | awk '{print $2}') >> package.keywords

Then we simply emerge the system into a new root and create a seed tarball with the result:

root #env ROOT=~/gentoo-seed/ USE="-*" emerge @system
root #tar jpcf ~/seed.tar.bz2 ~/gentoo-seed/

Preparing a Portage snapshot for Catalyst

Now we need to add the sh KEYWORD to all ebuilds in the system set. To do so, one can use ekeyword command from app-portage/gentoolkit to automatically update the ebuilds and their manifests:

The following command modifies the ebuilds in-place. Use ekeyword -n instead of ekeyword -m for a dry-run.
root #ekeyword -m $(ACCEPT_KEYWORDS="x86" USE="-*" emerge @system -qep --cols | awk '{print $2, $3}' | sed -e 's_^\([^ /]*\)/\([^ ]*\) \(.*\)$_sh /usr/portage/\1/\2/\2-\3.ebuild_' | sort -u | tr '\n' ' ')
As of December 8, 2018, ekeyword can only handle arches from the official portage repository ('gentoo'). Hence, if using an entirely new arch not yet supported by Gentoo, you might have to add the arch to /usr/portage/profiles/arch.list as a workaround. See bug #672728 for details.

Once the Portage tree has been updated, create a Catalyst snapshot:

root #catalyst -C target=snapshot version_stamp=sh

Before we can make stages with catalyst, we need to teach it something about our new arch. Go into /usr/lib/catalyst/arch/ and copy one of the small *.py modules to sh.py. Then edit it to reflect the sh architecture. Finally edit the generic_stage_target.py file in /usr/lib/catalyst/modules/. You just have to update the targetmap and machinemap variables.

Then try building a stage1 with catalyst and the seed.

root #mkdir -p /var/tmp/catalyst/builds
root #mv ~/seed.tar.bz2 /var/tmp/catalyst/builds/
root #catalyst -C \
  snapshot=sh version_stamp=sh \
  subarch=sh profile=default/linux/sh \
  rel_type=default target=stage1 \

If everything goes well, you should end up with a stage1 tarball which you can then make a stage2 and a stage3 from.


If you don't like the idea of running catalyst by hand (i know, it sucks), you can grab this script which will generate the Portage snapshot and stage[123] files for you. Simply edit the settings at the top of the script (see above for proper settings). You will still have to move the seed tarball to the Catalyst dir.

Pushing work into the Portage tree

If we don't want all this work to be for nothing, we have to share it :). Here's what needs to be updated so you don't start committing half broken work (and making other developers very angry).

Create the profiles

Our first profile was just a 'make it work' solution. Now you have to create a much more complete one. After you've committed the profile, update the following files in the profiles/ subdir:

  • arch.list
  • profiles.desc

You should declare the profile status in profiles.desc as exp for now (it'll keep people from yelling at you, trust me on this).

Start committing KEYWORDS

At this point, you should be able to start updating ebuilds in the tree with the new KEYWORD.