/[gentoo]/xml/htdocs/doc/en/genkernel.xml
Gentoo

Contents of /xml/htdocs/doc/en/genkernel.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.6 - (hide annotations) (download) (as text)
Thu Apr 22 17:14:01 2004 UTC (10 years, 5 months ago) by plasmaroo
Branch: MAIN
Changes since 1.5: +3 -3 lines
File MIME type: application/xml
Added a missing "all"...

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3    
4     <guide link="/doc/en/xml-guide.xml">
5     <title>Gentoo Linux Genkernel Guide</title>
6    
7     <author title="Author">
8     <mail link="plasmaroo@gentoo.org">Tim Yamin</mail>
9     </author>
10    
11     <abstract>
12     This guide intends to provide a reference of all the functions
13     provided by Genkernel.
14     </abstract>
15    
16 plasmaroo 1.4 <license/>
17    
18 plasmaroo 1.6 <version>1.0.0.1</version>
19     <date>April 22, 2003</date>
20 swift 1.1
21     <chapter>
22     <title>Introduction</title>
23     <section>
24     <title>Introduction</title>
25     <body>
26    
27     <p>
28     Genkernel is designed to allow users who are not previously used to
29     compiling a kernel to use a similar setup to that one that is used on
30     the Gentoo LiveCDs which auto-detects your hardware.
31     </p>
32    
33     <p>
34     Some users may also be interested in using genkernel for hardware
35     which requires initialization and a working kernel before it can be
36     booted. Because genkernel also automatically compiles your kernel modules,
37     thus allowing hardware which needs to be loaded with module parameters
38     to be used.
39     </p>
40    
41     </body>
42     </section>
43     <section>
44     <title>Is genkernel for me?</title>
45     <body>
46    
47     <p>
48     Genkernel is often a good choice to those who are unused to compiling
49     their own kernel or those who are not certain about their hardware
50     configurations.
51     </p>
52    
53     <p>
54     Because genkernel is designed to use a generic configuration, it
55     should be able to support all of your hardware - however, because all
56     the drivers and modules have to be compiled as well, compiling a
57     kernel by yourself is often much faster provided you know what you need.
58     </p>
59    
60     <p>
61     Genkernel does not however, currently support booting the sytem from
62     LVM2/EVMS2 partitions. Users are recommended to use a manually compiled
63     kernel for the time being.
64     </p>
65    
66     </body>
67     </section>
68     <section>
69     <title>Getting genkernel</title>
70     <body>
71    
72     <p>
73     You can obtain genkernel by simply running <c>emerge genkernel</c>. Don't
74     forget to use the <c>-k</c> flag for emerge if you are using binary packages,
75     i.e. GRP. Due to the GRP packages having an older version of genkernel, the
76     flags are different. As a result, you should consult the <uri
77 neysx 1.2 link="http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=9">
78 swift 1.1 Gentoo Handbook</uri> and <path>genkernel --help</path>.
79     </p>
80    
81     </body>
82     </section>
83     <section>
84     <title>Supported platforms</title>
85     <body>
86    
87     <p>
88 plasmaroo 1.4 As of genkernel 3.0.2; the following platforms should be
89     supported: alpha, amd64, parisc, parisc64, ppc, ppc64, sparc, sparc64, and x86. If
90 swift 1.1 you believe that there is a bug with the support code, and not with
91     genkernel, please file a bug at the <uri
92     link="http://bugs.gentoo.org">Gentoo Bugzilla.</uri>
93     </p>
94    
95     </body>
96     </section>
97     </chapter>
98    
99     <chapter>
100     <title>Genkernel usage</title>
101     <section>
102     <title>Introduction</title>
103     <body>
104    
105     <p>
106     Genkernel is designed to work in three modes:
107     </p>
108    
109     <ul>
110     <li>"all" mode: this builds the kernel and the initrd</li>
111     <li>"kernel" mode: this only builds the kernel image</li>
112     <li>"initrd" mode: this only builds the initrd</li>
113     </ul>
114    
115     <p>
116     Most users will only want the "all" mode, which runs the "kernel" mode
117     and the "initrd" mode for you. <b>Note</b> that the "kernel" and "initrd"
118     modes are currently just aliases for the "all" mode, so they will
119     currently give you no special effect.
120     </p>
121    
122     <p>
123     Although genkernel is mainly a command to make your life easier when
124     you need to compile a kernel, genkernel is also packed full of
125     different flags which allow you to customize how your kernel is
126     compiled or configured.
127     </p>
128    
129     </body>
130     </section>
131     <section>
132     <title>Genkernel compiler flags</title>
133     <body>
134    
135     <p>
136     Genkernel supports the following flags which are passed to the
137     relevant applications when your kernel is assembled:
138     </p>
139    
140     <ul>
141     <li>
142     <b>--kernel-as=<c>someAssembler</c></b>: This specifies an assembler which
143     would be used for compiling your kernel.
144     </li>
145     <li>
146     <b>--kernel-cc=<c>someCompiler</c></b>: This specifies a compiler which
147     would be used for compiling your kernel.
148     </li>
149     <li>
150     <b>--kernel-ld=<c>someLinker</c></b>: This specifies a linker which would
151     be used for compiling your kernel.
152     </li>
153     <li>
154     <b>--kernel-make=<c>someMake</c></b>: This specifies an alternate GNU Make
155     which would be used for compiling your kernel.
156     </li>
157     </ul>
158    
159     <ul>
160     <li>
161     <b>--utils-as=<c>someAssembler</c></b>: This specifies an assembler which
162     would be used for compiling the support utilities.
163     </li>
164     <li>
165     <b>--utils-cc=<c>someCompiler</c></b>: This specifies a compiler which
166     would be used for compiling the support utilities.
167     </li>
168     <li>
169     <b>--utils-ld=<c>someLinker</c></b>: This specifies a linker which would be
170     used for compiling the support utilities.
171     </li>
172     <li>
173     <b>--utils-make=<c>someMake</c></b>: This specifies an alternate GNU Make
174     which would be used for compiling the support utilities.
175     </li>
176     </ul>
177    
178     <ul>
179     <li>
180     <b>--makeopts=<c>-jJobs</c></b>: This specifies the flags which would be
181     passed to GNU Make when the kernel and utilities are being compiled.
182     </li>
183     </ul>
184    
185     </body>
186     </section>
187     <section>
188     <title>Genkernel kernel flags</title>
189     <body>
190    
191     <p>
192     Genkernel supports the following flags, some of which have
193     <c>--<b>no-</b>option</c> equivalents that influence
194     kernel compilation:
195     </p>
196    
197     <ul>
198     <li>
199 plasmaroo 1.4 <b>--callback="echo Hello"</b>: This routine calls the specified
200     arguments after the kernel and the relevant modules have been built; but
201     before the initrd has been built. This is useful where you might want
202     external modules installed to the initrd by emerging the relevant item
203     using the callback and then redefinining a Genkernel module group.
204     </li>
205     <li>
206 plasmaroo 1.5 <b>--<c>no-</c>clean</b>: This runs <e>or does not
207     run</e> <c>make clean</c> before compiling your kernel. This
208     causes all object files and dependencies to be removed.
209 swift 1.1 </li>
210     <li>
211 plasmaroo 1.5 <b>--<c>no-</c>mrproper</b>: This runs <e>or does not
212     run</e> <c>make mrproper</c> before compiling your kernel. This
213     causes all object files, dependencies <b> and your
214     configuration</b> to be removed.
215 swift 1.1 </li>
216     </ul>
217    
218     <ul>
219     <li>
220     <b>--kerneldir=<path>/path/to/sources</path></b>: This specifies an
221     alternative kernel source location, instead of the default location of
222     <path>/usr/src/linux</path>.
223     </li>
224     <li>
225     <b>--kernel-config=<path>/path/to/config-file</path></b>: This specifies an
226     alternative kernel configuration which would be used; rather than the
227     inpersistant <path>/path/to/sources/.config</path> which is used by
228     default.
229     </li>
230     </ul>
231    
232     <ul>
233     <li>
234     <b>--<c>no-</c>bootsplash</b>: This adds <e>or does not add</e> bootsplash
235     support in the initrd which genkernel builds. Not all architectures
236     currently support bootsplash, and a kernel that supports bootsplash is
237     also required.
238     </li>
239     <li>
240     <b>--<c>no-</c>menuconfig</b>: This runs <e>or does not run</e> the kernel
241     menu-based configurator before building your kernel, after <c>make
242     oldconfig</c> has ran.
243     </li>
244     </ul>
245    
246     <ul>
247     <li>
248     <b>--no-initrdmodules</b>: This doesn't copy any modules to the initrd
249     which genkernel creates.
250     </li>
251     <li>
252 cam 1.3 <b>--<c>no-</c>install</b>: This installs <e>or does not install</e> your
253 swift 1.1 kernel, modules, and initrd one the compilation has finished.
254     </li>
255     </ul>
256    
257     </body>
258     </section>
259     <section>
260     <title>Genkernel miscellaenous flags</title>
261     <body>
262    
263     <p>
264     Genkernel also supports some miscellaneous flags which do not fit into
265     the other two categories:
266     </p>
267    
268     <ul>
269     <li>
270     <b>--arch-override=<c>someArch</c></b>: This flag can be used to override
271     what architecture genkernel thinks you're on, if the auto-detection
272     mechanism fails (please file a bug if it does!) or if you wish to
273     cross-compile a kernel.
274     </li>
275     </ul>
276    
277     <ul>
278     <li>
279     <b>--busybox-config=<path>/path/to/busybox-config</path></b>: This
280     overrides the default busybox configuration with the specifid file
281     </li>
282     <li>
283     <b>--busybox-bin=<path>/path/to/busybox-binary.tar.bz2</path></b>: Using
284     this option means that a busybox binary would not be compiled, and the
285     specified tarball would be used. Note that busybox <e>must</e> be compiled
286     statically!
287     </li>
288     </ul>
289    
290     <ul>
291     <li>
292     <b>--minkernpackage=<path>/output/to/yourkernel.tar.bz2</path></b>: This
293     flag outputs a tarball of the kernel, named as <path>kernel</path> and the
294     initrd named as <path>initrd</path> to the specified file. No path
295     information or modules will be includes in the tarball.
296     </li>
297     </ul>
298    
299     </body>
300     </section>
301     <section>
302     <title>Running genkernel</title>
303     <body>
304    
305     <p>
306     All that is needed to run genkernel is just genkernel with the
307     necessary flags as root. For example:
308     </p>
309    
310     <pre caption="Running genkernel">
311 plasmaroo 1.6 # genkernel --menuconfig --no-clean --no-install --bootsplash all
312 swift 1.1 <comment>(Would produce a kernel, asking you what how to configure it
313     to your desire, leaving alone any compiled object files, enabling
314     bootsplash support but not installing anything.)</comment>
315     </pre>
316    
317     <p>
318     If you want genkernel to install your kernel as well, you must ensure
319 plasmaroo 1.4 that your <path>/boot</path> partition is mounted - recent Genkernels
320     would automatically attempt to do this for you if MOUNTBOOT is set to
321     "yes" in <path>/etc/genkernel.conf</path>.
322 swift 1.1 </p>
323    
324 plasmaroo 1.4 <pre caption="Mounting your /boot manually">
325 swift 1.1 <comment>(If /boot is a valid entry in /etc/fstab:)</comment>
326     # mount /boot
327     <comment>(... otherwise for IDE disks:)</comment>
328     # mount /dev/hda1 /boot
329     <comment>(... and for SCSI disks:)</comment>
330     # mount /dev/sda1 /boot
331     </pre>
332    
333     </body>
334     </section>
335     <section>
336     <title>Setting up genkernel to work with your bootloader</title>
337     <body>
338    
339     <p>
340     To set up genkernel to work with your bootloader, three or four changes are
341     required to your bootloader configuration.
342     </p>
343    
344     <ol>
345     <li>
346     Add <c>root=/dev/ram0</c> and <c>init=/linuxrc</c> to the
347     kernel parameters passed to the kernel image.
348     </li>
349     <li>
350     Add <c>real_root=/dev/hda3</c>, for example, to the kernel parameters
351     passed to the kernel image if <path>/dev/hda3</path> contains your root
352     partition.
353     </li>
354     <li>
355     If you are using bootsplash, add a suitable modeline such as
356     <c>vga=0x317</c> to the parameters passed to the kernel and also add
357     <c>splash=verbose</c> or <c>splash=silent</c> depending on the verboseness
358     you require from your bootsplash.
359     </li>
360     <li>
361     Add the initrd according to how your bootloader requires it: see the <uri
362 neysx 1.2 link="http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=9">Gentoo
363 swift 1.1 Handbook</uri> for details on how you would do it for your bootloader.
364     </li>
365     </ol>
366    
367     </body>
368     </section>
369     </chapter>
370    
371     <chapter>
372     <title>Porting genkernel</title>
373     <section>
374     <title>Introduction</title>
375     <body>
376    
377     <p>
378     Provided your architecture has all the required libraries and utilties
379     which genkernel requires, which includes but it not limited to a
380     working kernel for your architecture, working compiler suite, GNU
381     Make, and a working busybox distribution, you're all set to go!
382     </p>
383    
384     <p>
385     For each architecture, genkernel uses
386     <path>/usr/share/genkernel/archName</path> for configuration files for
387     that architecture.
388     </p>
389    
390     </body>
391     </section>
392     <section>
393     <title>How the system bootstrapping works</title>
394     <body>
395    
396     <ol>
397     <li>
398     The bootloader loads the genkernel image, built to the specification of the
399     configuration files in the genkernel directories as well as the initrd
400     which is prepared by genkernel.
401     </li>
402     <li>
403     The kernel boots up, allocates a small amount of RAM in which busybox is
404     initialized, which probes the system with the modules in the modules_load
405     list for the architecture.
406     </li>
407     <li>
408     Once done, and providing that the <c>real_root</c> parameter which is the
409     root boot device as busybox sees things is found, the system is booted from
410     the device.
411     </li>
412     </ol>
413    
414     </body>
415     </section>
416     <section>
417     <title>The configuration files</title>
418     <body>
419    
420     <ul>
421     <li>
422     <path>busy-config</path>: This is the configuration which is used to build
423     busybox for your architecture.
424     </li>
425     <li>
426     <path>config.sh</path>: This is a shell script which sets various internal
427     genkernel variables. See one of the <path>config.sh</path> files for an
428     example.
429     </li>
430     <li>
431     <path>modules_load</path>: This is a file containing a space-delimited list
432     of modules which are loaded for SCSI, FireWire, ATARAID and PCMCIA support.
433     If none are available for your platform, leave the fields blank. See one of
434     the <path>modules_load</path> files for an example.
435     </li>
436     </ul>
437    
438     <ul>
439     <li>
440     <path>kernel-config</path>: A default kernel configuration used for any
441     kernel version.
442     </li>
443     <li>
444     <path>kernel-config-2.4</path>: A default kernel configuration used for 2.4
445     series kernels.
446     </li>
447     <li>
448     <path>kernel-config-2.6</path>: A default kernel configuration used for 2.6
449     series kernels.
450     </li>
451     </ul>
452    
453     </body>
454     </section>
455     </chapter>
456     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20