/[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.8 - (show annotations) (download) (as text)
Fri Aug 6 22:09:59 2004 UTC (9 years, 8 months ago) by neysx
Branch: MAIN
Changes since 1.7: +6 -5 lines
File MIME type: application/xml
Fixed links/a typo/date

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

  ViewVC Help
Powered by ViewVC 1.1.20