/[gentoo]/xml/htdocs/doc/en/draft/bootstrapping-guide.xml
Gentoo

Diff of /xml/htdocs/doc/en/draft/bootstrapping-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.5 Revision 1.6
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2 2
3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bootstrapping-guide.xml,v 1.5 2006/01/05 19:09:34 swift Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/bootstrapping-guide.xml,v 1.6 2006/01/06 19:50:25 swift Exp $ -->
4 4
5<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 5<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
6 6
7<guide link="/doc/en/draft/bootstrapping-guide.xml" disclaimer="draft"> 7<guide link="/doc/en/draft/bootstrapping-guide.xml" disclaimer="draft">
8<title>Gentoo Bootstrapping Guide</title> 8<title>Gentoo Bootstrapping Guide</title>
48In computer theory, bootstrapping has several meanings. All of them boil down to 48In computer theory, bootstrapping has several meanings. All of them boil down to
49building more complex systems from simple ones. This document will discuss 49building more complex systems from simple ones. This document will discuss
50bootstrapping a toolchain: building a full cross-compilation environment able to 50bootstrapping a toolchain: building a full cross-compilation environment able to
51build software for the target system, followed by a rebuild of the system to the 51build software for the target system, followed by a rebuild of the system to the
52native environment. 52native environment.
53</p>
54
55<p>
56Sounds strange to you? Don't despair, we'll discuss all that in the rest of this
57document...
53</p> 58</p>
54 59
55</body> 60</body>
56</section> 61</section>
57<section> 62<section>
85 the <e>target</e> system is the system for which the software generates 90 the <e>target</e> system is the system for which the software generates
86 output (like the compiler) 91 output (like the compiler)
87 </li> 92 </li>
88</ul> 93</ul>
89 94
95<p>
96Each of those terms has a certain syntax used by the GNU compiler collection. It
97is therefore adviseable to consult the <uri
98link="http://gcc.gnu.org/onlinedocs">online GCC documentation</uri> for more
99information.
100</p>
101
90</body> 102</body>
91</section> 103</section>
92</chapter> 104</chapter>
93 105
94<chapter> 106<chapter>
226cross-compiling toolchain. The next step is to build the core system packages so 238cross-compiling toolchain. The next step is to build the core system packages so
227that you are able to boot into the minimal environment later on. 239that you are able to boot into the minimal environment later on.
228</p> 240</p>
229 241
230<p> 242<p>
231Our first task is to build a Linux kernel. 243Our first task is to build a Linux kernel:
232</p> 244</p>
233 245
234<pre caption="Building the Linux kernel"> 246<pre caption="Building the Linux kernel">
235$ <i>cd ~/cd/src/linux-*</i> 247$ <i>cd ~/cd/src/linux-*</i>
236$ <i>make menuconfig</i> 248$ <i>make menuconfig</i>
237$ <i>make dep boot CROSS_COMPILE=&lt;target&gt;</i> 249$ <i>make dep boot CROSS_COMPILE=&lt;target&gt;</i>
238</pre> 250</pre>
239 251
252<p>
253Next, build the core packages required to succesfully boot the system. The set
254of packages you'll need are:
255</p>
256
257<dl>
258 <dt><c>coreutils</c></dt>
259 <dd>Standard set of (POSIX) commands</dd>
260 <dt><c>diffutils</c></dt>
261 <dd>Tools for displaying the differences between files</dd>
262 <dt><c>grep</c></dt>
263 <dd>Text pattern searcher</dd>
264 <dt><c>sed</c></dt>
265 <dd>Streaming text editor</dd>
266 <dt><c>make</c></dt>
267 <dd>Makefile parser</dd>
268 <dt><c>tar</c></dt>
269 <dd>Tape Archive tool</dd>
270 <dt><c>gzip</c></dt>
271 <dd>Compression tool</dd>
272 <dt><c>util-linux</c></dt>
273 <dd>Linux utilities</dd>
274</dl>
275
276<p>
277All these tools should be fairly easy to build. Generally, you can set the
278following variables to declare your platform; the <c>configure</c> and
279<c>make</c> steps will then use those variables to make their platform-dependant
280decisions:
281</p>
282
283<pre caption="Setting platform environment variables">
284$ <i>export CC=</i><comment>your-platform</comment><i>-gcc</i>
285$ <i>export AR=</i><comment>your-platform</comment><i>-ar</i>
286$ <i>export RANLIB=</i><comment>your-platform</comment><i>-ranlib</i>
287$ <i>export LD=</i><comment>your-platform</comment><i>-ld</i>
288$ <i>export BUILD_CC=cc</i>
289$ <i>export HOST_CC=cc</i>
290$ <i>export CFLAGS=</i><comment>sane cflags</comment><i> -I~/cd/usr/include</i>
291</pre>
292
293<p>
294The build steps are then quite simple:
295</p>
296
297<pre caption="Build steps for the core packages">
298$ <i>./configure --prefix=/usr</i>
299$ <i>make</i>
300$ <i>make install prefix=~/cd/final</i>
301</pre>
302
303<p>
304The last thing you'll need is a statically linked version of a shell, for
305instance, <c>bash</c>:
306</p>
307
308<pre caption="Building a statically-linked bash">
309$ <comment>TODO</comment>
310</pre>
311
240</body> 312</body>
241</section> 313</section>
242<section> 314<section>
243<title>Bootstrapping the Toolchain</title> 315<title>Bootstrapping the Toolchain</title>
244<body> 316<body>
245 317
318<p>
319Now that you have build a minimal environment inside <path>~/cd</path>, we'll
320rebuild the toolchain so that it not only builds for the target platform (which
321it does already) but also builds <e>on</e> the target platform (it currently
322only works on the current system).
323</p>
324
325<p>
326First, we rebuild the <c>glibc</c> package:
327</p>
328
329<pre caption="Rebuilding glibc">
330$ <i>./configure --prefix=/usr --libdir=~/cd/usr/lib --build=${BUILD} \
331 --host=${TARGET} --with-headers=~/cd/usr/include --without-cvs \
332 --disable-profile --disable-debug --without-gd --enable-add-ons=nptl \
333 --with-tls --enable-kernel=2.6 --enable-shared</i>
334$ <i>make</i>
335$ <i>make install install_root=~/cd/final</i>
336</pre>
337
338<p>
339Next, we rebuild the <c>binutils</c> package:
340</p>
341
342<pre caption="Rebuilding binutils">
343$ <i>./configure --prefix=/usr --target=${TARGET} --with-sysroot=~/cd/final \
344 --libdir=~/cd/usr/lib --with-headers=~/cd/usr/include</i>
345$ <i>make all</i>
346$ <i>make install</i>
347</pre>
348
349<p>
350Finally, we rebuild the <c>gcc</c> package:
351</p>
352
353<pre caption="Rebuilding gcc">
354$ <i>./configure --prefix=/usr --target=${TARGET} --with-sysroot=~/cd/final \
355 --with-headers=~/cd/usr/include --enable-threads=posix \
356 --enable-languages=c,c++</i>
357$ <i>make</i>
358$ <i>make install</i>
359</pre>
360
361<p>
362Now the directory <path>~/cd/final</path> contains everything needed to
363continue.
364</p>
365
246</body> 366</body>
247</section>
248<section> 367</section>
249<title>Building the Core System Packages</title> 368<section>
369<title>Booting the System</title>
250<body> 370<body>
371
372<p>
373The next step is to try and boot the system. The easiest approach is to
374NFS-mount <path>~/cd/final</path> and boot the target platform using the kernel
375built at the beginning. Don't forget to set <c>init=/bin/sh</c> since the entire
376bootup sequence stuff (like <c>init</c>) isn't available yet.
377</p>
378
379<p>
380<brite>TODO</brite> inform how to boot from the CD and use an NFS-mounted root
381file system.
382</p>
251 383
252</body> 384</body>
253</section> 385</section>
254<section> 386<section>
255<title>Porting Portage</title> 387<title>Porting Portage</title>
256<body> 388<body>
257 389
390<p>
391To be able to use Portage, we need to be able to use Python. Download the
392sources in <path>~/cd/final/tmp</path> (so that it is available for the booted
393platform) and build it:
394</p>
395
396<pre caption="Building python">
397<comment>TODO</comment>
398</pre>
399
400<p>
401Next, download a Portage rescue set and install it. As Portage is a set of
402Python scripts with bash scripts, this should have no further requirements after
403installation:
404</p>
405
406<pre caption="Installing Portage">
407<comment>TODO</comment>
408</pre>
409
410<p>
411Once installed, try to run <c>emerge</c> and <c>ebuild</c> to find out if they
412appear to work:
413</p>
414
415<pre caption="Checking emerge">
416$ <i>emerge --info</i>
417</pre>
418
258</body> 419</body>
259</section> 420</section>
260<section> 421<section>
261<title>Creating a Stage1 Tarball</title> 422<title>Creating a Stage1 Tarball</title>
262<body> 423<body>
263 424
425<p>
426Booted in the platform and with a working Portage, you are now ready to create a
427stage1 tarball. Create a snapshot of your environment using <c>tar</c>:
428</p>
429
430<pre caption="Creating a stage1 tarball">
431<comment>TODO</comment>
432Don't forget to talk about unmasking all packages...
433</pre>
434
264</body> 435</body>
265</section> 436</section>
266<section> 437<section>
267<title>Creating a Bootable Environment</title> 438<title>Creating a Bootable Environment</title>
268<body> 439<body>
269 440
441<p>
442Next, to make sure that you'll always be able to boot the system (and help
443others as well), we'll create a bootable environment for the platform. Assuming
444that all platforms have a CD-ROM drive they can boot from, we'll focus on such
445environment.
446</p>
447
448<p>
449<brite>TODO</brite> talk about creating bootable CD.
450</p>
451
270</body> 452</body>
271</section> 453</section>
272<section> 454<section>
273<title>Finishing Off</title> 455<title>Finishing Off</title>
274<body> 456<body>
457
458<p>
459All set. Right? Nope, but almost :-)
460</p>
461
462<p>
463The most important step now is to inform the Gentoo community about what you've
464accomplished. Make sure you pay a visit at <c>#gentoo-dev</c> on
465<c>irc.freenode.net</c> and use our <uri link="http://forums.gentoo.org">Gentoo
466Forums</uri> to tell about the up and downfalls of your expedition. The most
467difficult steps are finished!
468</p>
275 469
276</body> 470</body>
277</section> 471</section>
278</chapter> 472</chapter>
279 473
345previously. 539previously.
346</p> 540</p>
347 541
348</body> 542</body>
349</section> 543</section>
544<section>
545<title>Creating a Fully Working Installation CD</title>
546<body>
547
548<p>
549If your entire installation has succeeded it is best to try and create an
550installation CD for your platform using <c>catalyst</c>. Not only will this
551require an additional profile (to support the new platform) but also some help
552from the Gentoo developers themselves. On the other hand, if you've succeeded in
553following all I've written until this part, you're probably already on your way
554to become a developer yourself :)
555</p>
556
557<p>
558The major benefit of using <c>catalyst</c> is that Gentoo is then able to create
559official support for the platform. Not only will there be a fully functional
560profile and keyword setting, but the core packages will be accepted for your
561platform, stages will be build and a working installation CD, just like those
562for the other architectures, will be available.
563</p>
564
565<p>
566<brite>TODO</brite> Talk about using <c>catalyst</c> to create all needed stuff.
567</p>
568
569</body>
570</section>
350</chapter> 571</chapter>
351 572
352<chapter> 573<chapter>
353<title>Frequently Asked Questions</title> 574<title>Frequently Asked Questions</title>
354<section> 575<section>

Legend:
Removed from v.1.5  
changed lines
  Added in v.1.6

  ViewVC Help
Powered by ViewVC 1.1.20