/[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.4 - (show annotations) (download) (as text)
Tue Apr 13 17:40:02 2004 UTC (10 years, 3 months ago) by plasmaroo
Branch: MAIN
Changes since 1.3: +20 -9 lines
File MIME type: application/xml
Added ppc64 to the list of supported architectures, --callback for newer
Genkernels and also <license/>.

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 <license/>
17
18 <version>1.0</version>
19 <date>February 15, 2003</date>
20
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 link="http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=9">
78 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 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 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 <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 <b>--<c>no-</c>clean</b>: This runs a <c>make clean</c> before compiling
207 your kernel. This causes all object files and dependencies to be removed.
208 </li>
209 <li>
210 <b>--<c>no-</c>mrproper</b>: This runs a <c>make mrproper</c> before
211 compiling your kernel. This causes all object files, dependencies <b>
212 and your configuration</b> to be removed.
213 </li>
214 </ul>
215
216 <ul>
217 <li>
218 <b>--kerneldir=<path>/path/to/sources</path></b>: This specifies an
219 alternative kernel source location, instead of the default location of
220 <path>/usr/src/linux</path>.
221 </li>
222 <li>
223 <b>--kernel-config=<path>/path/to/config-file</path></b>: This specifies an
224 alternative kernel configuration which would be used; rather than the
225 inpersistant <path>/path/to/sources/.config</path> which is used by
226 default.
227 </li>
228 </ul>
229
230 <ul>
231 <li>
232 <b>--<c>no-</c>bootsplash</b>: This adds <e>or does not add</e> bootsplash
233 support in the initrd which genkernel builds. Not all architectures
234 currently support bootsplash, and a kernel that supports bootsplash is
235 also required.
236 </li>
237 <li>
238 <b>--<c>no-</c>menuconfig</b>: This runs <e>or does not run</e> the kernel
239 menu-based configurator before building your kernel, after <c>make
240 oldconfig</c> has ran.
241 </li>
242 </ul>
243
244 <ul>
245 <li>
246 <b>--no-initrdmodules</b>: This doesn't copy any modules to the initrd
247 which genkernel creates.
248 </li>
249 <li>
250 <b>--<c>no-</c>install</b>: This installs <e>or does not install</e> your
251 kernel, modules, and initrd one the compilation has finished.
252 </li>
253 </ul>
254
255 </body>
256 </section>
257 <section>
258 <title>Genkernel miscellaenous flags</title>
259 <body>
260
261 <p>
262 Genkernel also supports some miscellaneous flags which do not fit into
263 the other two categories:
264 </p>
265
266 <ul>
267 <li>
268 <b>--arch-override=<c>someArch</c></b>: This flag can be used to override
269 what architecture genkernel thinks you're on, if the auto-detection
270 mechanism fails (please file a bug if it does!) or if you wish to
271 cross-compile a kernel.
272 </li>
273 </ul>
274
275 <ul>
276 <li>
277 <b>--busybox-config=<path>/path/to/busybox-config</path></b>: This
278 overrides the default busybox configuration with the specifid file
279 </li>
280 <li>
281 <b>--busybox-bin=<path>/path/to/busybox-binary.tar.bz2</path></b>: Using
282 this option means that a busybox binary would not be compiled, and the
283 specified tarball would be used. Note that busybox <e>must</e> be compiled
284 statically!
285 </li>
286 </ul>
287
288 <ul>
289 <li>
290 <b>--minkernpackage=<path>/output/to/yourkernel.tar.bz2</path></b>: This
291 flag outputs a tarball of the kernel, named as <path>kernel</path> and the
292 initrd named as <path>initrd</path> to the specified file. No path
293 information or modules will be includes in the tarball.
294 </li>
295 </ul>
296
297 </body>
298 </section>
299 <section>
300 <title>Running genkernel</title>
301 <body>
302
303 <p>
304 All that is needed to run genkernel is just genkernel with the
305 necessary flags as root. For example:
306 </p>
307
308 <pre caption="Running genkernel">
309 # genkernel --menuconfig --no-clean --no-install --bootsplash
310 <comment>(Would produce a kernel, asking you what how to configure it
311 to your desire, leaving alone any compiled object files, enabling
312 bootsplash support but not installing anything.)</comment>
313 </pre>
314
315 <p>
316 If you want genkernel to install your kernel as well, you must ensure
317 that your <path>/boot</path> partition is mounted - recent Genkernels
318 would automatically attempt to do this for you if MOUNTBOOT is set to
319 "yes" in <path>/etc/genkernel.conf</path>.
320 </p>
321
322 <pre caption="Mounting your /boot manually">
323 <comment>(If /boot is a valid entry in /etc/fstab:)</comment>
324 # mount /boot
325 <comment>(... otherwise for IDE disks:)</comment>
326 # mount /dev/hda1 /boot
327 <comment>(... and for SCSI disks:)</comment>
328 # mount /dev/sda1 /boot
329 </pre>
330
331 </body>
332 </section>
333 <section>
334 <title>Setting up genkernel to work with your bootloader</title>
335 <body>
336
337 <p>
338 To set up genkernel to work with your bootloader, three or four changes are
339 required to your bootloader configuration.
340 </p>
341
342 <ol>
343 <li>
344 Add <c>root=/dev/ram0</c> and <c>init=/linuxrc</c> to the
345 kernel parameters passed to the kernel image.
346 </li>
347 <li>
348 Add <c>real_root=/dev/hda3</c>, for example, to the kernel parameters
349 passed to the kernel image if <path>/dev/hda3</path> contains your root
350 partition.
351 </li>
352 <li>
353 If you are using bootsplash, add a suitable modeline such as
354 <c>vga=0x317</c> to the parameters passed to the kernel and also add
355 <c>splash=verbose</c> or <c>splash=silent</c> depending on the verboseness
356 you require from your bootsplash.
357 </li>
358 <li>
359 Add the initrd according to how your bootloader requires it: see the <uri
360 link="http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=9">Gentoo
361 Handbook</uri> for details on how you would do it for your bootloader.
362 </li>
363 </ol>
364
365 </body>
366 </section>
367 </chapter>
368
369 <chapter>
370 <title>Porting genkernel</title>
371 <section>
372 <title>Introduction</title>
373 <body>
374
375 <p>
376 Provided your architecture has all the required libraries and utilties
377 which genkernel requires, which includes but it not limited to a
378 working kernel for your architecture, working compiler suite, GNU
379 Make, and a working busybox distribution, you're all set to go!
380 </p>
381
382 <p>
383 For each architecture, genkernel uses
384 <path>/usr/share/genkernel/archName</path> for configuration files for
385 that architecture.
386 </p>
387
388 </body>
389 </section>
390 <section>
391 <title>How the system bootstrapping works</title>
392 <body>
393
394 <ol>
395 <li>
396 The bootloader loads the genkernel image, built to the specification of the
397 configuration files in the genkernel directories as well as the initrd
398 which is prepared by genkernel.
399 </li>
400 <li>
401 The kernel boots up, allocates a small amount of RAM in which busybox is
402 initialized, which probes the system with the modules in the modules_load
403 list for the architecture.
404 </li>
405 <li>
406 Once done, and providing that the <c>real_root</c> parameter which is the
407 root boot device as busybox sees things is found, the system is booted from
408 the device.
409 </li>
410 </ol>
411
412 </body>
413 </section>
414 <section>
415 <title>The configuration files</title>
416 <body>
417
418 <ul>
419 <li>
420 <path>busy-config</path>: This is the configuration which is used to build
421 busybox for your architecture.
422 </li>
423 <li>
424 <path>config.sh</path>: This is a shell script which sets various internal
425 genkernel variables. See one of the <path>config.sh</path> files for an
426 example.
427 </li>
428 <li>
429 <path>modules_load</path>: This is a file containing a space-delimited list
430 of modules which are loaded for SCSI, FireWire, ATARAID and PCMCIA support.
431 If none are available for your platform, leave the fields blank. See one of
432 the <path>modules_load</path> files for an example.
433 </li>
434 </ul>
435
436 <ul>
437 <li>
438 <path>kernel-config</path>: A default kernel configuration used for any
439 kernel version.
440 </li>
441 <li>
442 <path>kernel-config-2.4</path>: A default kernel configuration used for 2.4
443 series kernels.
444 </li>
445 <li>
446 <path>kernel-config-2.6</path>: A default kernel configuration used for 2.6
447 series kernels.
448 </li>
449 </ul>
450
451 </body>
452 </section>
453 </chapter>
454 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20