Attachment 234371 Details for Bug 318251 – porting-howto.xml

porting-howto.xml

porting-howto.xml (text/plain), 6.69 KB, created by nm (RETIRED) on 2010-06-07 08:52:56 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: nm (RETIRED)

Created: 2010-06-07 08:52:56 UTC

Size: 6.69 KB

patch

obsolete

><?xml version='1.0' encoding='UTF-8'?>
><!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
>
>
><guide>
><title>Porting Gentoo to a New Platform</title>
>
><author title="Author">
>  <mail link="vapier"/>
></author>
><author title="Editor">
>  <mail link="nightmorph"/>
></author>
>
><abstract>
>This document explains how to port Gentoo to new architectures and platforms.
></abstract>
>
>
>
><license/>
>
><version>1</version>
><date>2010-06-07</date>
>
><chapter>
><title>Introduction</title>
><section>
><body>
>
><p>
>As developers expand Gentoo to new architectures and platforms, they may find
>there isn't 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 straightforward for other
>arches/operating systems.
></p>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Getting the System Running</title>
><section>
><body>
>
><p>
>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 distro, etc...), or you can cross compile the entire system. The first
>route is the easiest, so we will cover that first. Simply boot up the system
>with the existing port and make sure it has all the important packages installed
>for development. A quick checklist:
></p>
>
><ul>
>  <li><c>binutils</c></li>
>  <li><c>gcc</c></li>
>  <li><c>glibc</c></li>
>  <li><c>python</c></li>
>  <li><c>rsync</c></li>
>  <li><c>wget</c></li>
>  <li><c>tar</c></li>
>  <li><c>gzip</c></li>
>  <li><c>bzip2</c></li>
>  <li><c>bash</c> (must be version 3 or newer)</li>
></ul>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Converting to Gentoo</title>
><section>
><body>
>
><p>
>Once you have these packages, you can easily install Portage. A script to do so
>can be found <uri
>link="http://dev.gentoo.org/~vapier/bootstrap-portage">here</uri>. Simply
>download it and run:
></p>
>
><pre caption="Bootstrapping Portage">
># <i>bash ./bootstrap-portage</i>
></pre>
>
><p>
>Then we need to create a profile for our new arch.
></p>
>
><pre caption="Creating a new profile">
># <i>mkdir -p /usr/local/portage/profiles/default/linux/sh</i>
># <i>cd /usr/local/portage/profiles/default/linux/sh</i>
># <i>echo '..' &gt; parent</i>
># <i>cat &lt;&lt; EOF &gt; make.defaults</i>
>ARCH="sh"
>ACCEPT_KEYWORDS="sh"
>GRP_STAGE23_USE="pam"
>EOF
># <i>cd /etc</i>
># <i>ln -s ../usr/local/portage/profiles/default/linux/sh make.profile</i>
># <i>"PORTDIR_OVERLAY=/usr/local/portage" >> make.conf</i>
></pre>
>
><p>
>Finally, sync up and we should have our Portage tree!
></p>
>
><pre caption="Syncing the Portage tree">
># <i>emerge --sync</i>
></pre>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Preparing a Seed for Catalyst</title>
><section>
><body>
>
><p>
>The next step is to prepare a seed for <uri
>link="/proj/en/releng/catalyst/index.xml">Catalyst</uri>, the tool used to
>create Gentoo releases. Since none of the ebuilds in Portage know about our new
>arch, we can cheat with <path>package.keywords</path> and using x86 as our
>reference arch.
></p>
>
><pre caption="Preparing keywords">
># <i>mkdir /etc/portage</i>
># <i>for p in $(env USE="-*" ACCEPT_KEYWORDS=x86 \
>	emerge system -qep --columns | awk '($1 ~ /ebuild/) {print $4}') ; do \
>	echo "${p} x86" >> package.keywords ; \
>done</i>
></pre>
>
><p>
>Then we simply emerge our system into a new root and create a seed tarball with
>the result:
></p>
>
><pre caption="Creating the seed tarball">
># <i>env ROOT=~/gentoo-seed/ USE="-*" emerge system</i>
># <i>tar jpcf ~/seed.tar.bz2 ~/gentoo-seed/</i>
></pre>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Preparing a Portage Snapshot for Catalyst</title>
><section>
><body>
>
><p>
>Now, take the list generated in package.keywords, and add the <c>sh</c> KEYWORD
>to them. If you use <c>ekeyword</c> from the <c>app-portage/gentoolkit-dev</c>
>package, things will go much faster. Once your Portage tree has been updated,
>create a <c>catalyst</c> snapshot:
></p>
>
><pre caption="Creating a Portage snapshot">
># <i>catalyst -C target=snapshot version_stamp=sh</i>
></pre>
>
><p>
>Before we can make stages with <c>catalyst</c>, we need to teach <c>catalyst</c>
>something about our new arch. Go into <path>/usr/lib/catalyst/arch/</path> and
>copy one of the small <path>.py</path> modules to <path>sh.py</path>. Then edit
>it to reflect the <c>sh</c> architecture. Finally, edit the
><path>generic_stage_target.py</path> file in
><path>/usr/lib/catalyst/modules/</path>. You just have to update the
><c>targetmap</c> and <c>machinemap</c> variables.
></p>
>
><p>
>Then try building a stage1 tarball with <c>catalyst</c> and the seed:
></p>
>
><pre caption="Building a stage1 tarball">
># <i>mkdir -p /var/tmp/catalyst/builds</i>
># <i>mv ~/seed.tar.bz2 /var/tmp/catalyst/builds/</i>
># <i>catalyst -C \
>	snapshot=sh version_stamp=sh \
>	subarch=sh profile=default/linux/sh \
>	rel_type=default target=stage1 \
>	source_subpath=seed</i>
></pre>
>
><p>
>If everything goes well, you should end up with a stage1 tarball from which you
>can then make stage2 and stage3 tarballs.
></p>
>
></body>
></section>
><section>
><title>Alternative: using the build-stages script</title>
><body>
>
><p>
>If you don't like the idea of running <c>catalyst</c> by hand, you can <uri
>link="http://dev.gentoo.org/~vapier/build-stages">grab the script</uri> that
>does the work for you. It will generate the Portage snapshot and stage[123]
>tarballs for you. Simply edit the settings at the top of the script (see above
>for the proper settings). You will still have to move the seed tarball to the
>catalyst directory.
></p>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Pushing Work into the Portage Tree</title>
><section>
><body>
>
><p>
>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).
></p>
>
></body>
></section>
><section>
><title>Create the profile</title>
><body>
>
><p>
>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 <path>/usr/portage/profiles/</path> subdirectory:
></p>
>
><ul>
>  <li>arch.list</li>
>  <li>profiles.desc</li>
></ul>
>
><p>
>You should declare the profile status in <path>profiles.desc</path> as "dev" for
>now (it'll keep people from yelling at you, trust me on this).
></p>
>
></body>
></section>
><section>
><title>Start committing KEYWORDS</title>
><body>
>
><p>
>At this point, you should be able to start updating ebuilds in the tree with the
>new KEYWORD.
></p>
>
></body>
></section>
></chapter>
></guide>
>

Actions: View

Attachments on bug 318251: 234371