From 4c1d7997f82bf9800cc3c0a055b3a63aded74d8e Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Mon, 6 Dec 2010 13:21:54 +0100 Subject: [PATCH] Migrate man page to asciidoc, add Makefile, add .gitignore --- .gitignore | 2 + Makefile | 8 + doc/asciidoc.conf | 3 + doc/genkernel.8.txt | 361 ++++++++++++++++++++++++++++++++++++++++++++ genkernel.8 | 329 ---------------------------------------- 5 files changed, 374 insertions(+), 329 deletions(-) create mode 100644 .gitignore create mode 100644 Makefile create mode 100644 doc/asciidoc.conf create mode 100644 doc/genkernel.8.txt delete mode 100644 genkernel.8 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..643cdcc --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +/genkernel.8 + diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..ec7e55c --- /dev/null +++ b/Makefile @@ -0,0 +1,8 @@ +PACKAGE_VERSION = `/bin/fgrep GK_V= genkernel | sed "s/.*GK_V='\([^']\+\)'/\1/"` + +genkernel.8: doc/genkernel.8.txt doc/asciidoc.conf Makefile + a2x --conf-file=doc/asciidoc.conf --attribute="genkernelversion=$(PACKAGE_VERSION)" \ + --format=manpage -D . "$<" + +clean: + rm -f genkernel.8 diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf new file mode 100644 index 0000000..5835345 --- /dev/null +++ b/doc/asciidoc.conf @@ -0,0 +1,3 @@ +# +# asciidoc.conf for genkernel's man page +# diff --git a/doc/genkernel.8.txt b/doc/genkernel.8.txt new file mode 100644 index 0000000..c6867a7 --- /dev/null +++ b/doc/genkernel.8.txt @@ -0,0 +1,361 @@ +GENKERNEL(8) +============ +:man source: genkernel {genkernelversion} +:man manual: genkernel {genkernelversion} + + +NAME +---- +genkernel - the Gentoo Linux automatic kernel compiler. + + +SYNOPSIS +-------- +*genkernel* [options...] action + + +INTRODUCTION +------------ +Genkernel is designed to allow users who are not previously used to +compiling a kernel to use a similar setup to that one that is used on +the Gentoo LiveCDs which auto-detects your hardware. + +Some users may also be interested in using genkernel for hardware which +requires initialization and a working kernel before it can be booted +because genkernel also automatically compiles your kernel modules, +allowing hardware which needs to be loaded with module parameters to be +used. + + +USAGE +----- +All that is needed to run genkernel is just `genkernel` with an +action and any flags you might need: + +------------------------------------------ +# genkernel --menuconfig --no-clean --no-install all +------------------------------------------ + +This would produce a kernel, asking you what how to configure it to +your desire, leaving alone any existing compiled object files, but not +installing anything. + + +ACTIONS +------- +An action tells genkernel what you want it to do - the following +actions are supported: + +*all*:: + Build all steps - the kernel, modules, and the ramdisk. +*bzImage*:: + Build only the kernel. +*kernel*:: + Build only the kernel and the modules. +*initramfs*:: + Build only the ramdisk. + + +OPTIONS +------- +Genkernel supports the following options which alter its behaviour. +Certain options have *--no-* variants which do the opposite thing. +You can specify your options in any order. + + +DEBUGGING OPTIONS +~~~~~~~~~~~~~~~~~ +*--loglevel*=<0-5>:: + This controls the out verbosity level of genkernel output - if + this is set to 0, minimal debugging is done; if this is set to 5 + as much output as possible is given. + +*--logfile*=:: + This outputs debugging data to the file . By default + this is '/var/log/genkernel.log'. + +*--*[*no-*]*color*:: + Turns on, or off, output in color using escape sequences. + + +KERNEL CONFIGURATION +~~~~~~~~~~~~~~~~~~~~ +*--*[*no-*]*menuconfig*:: + Runs, or does not run "make menuconfig" after running "make oldconfig". + +*--*[*no-*]*save-config*:: + Saves, or does not save the kernel configuration to '/etc/kernels' + if the kernel is successfully compiled. + +*--gconfig*:: + Run "make gconfig" after "make oldconfig". + +*--xconfig*:: + Run "make xconfig" after "make oldconfig". + + +KERNEL COMPILATION +~~~~~~~~~~~~~~~~~~ +*--*[*no-*]*clean*:: + Runs, or does not run, "make clean" before compilation - this + erases any compiled object files in the kernel source tree but + does not have an impact on the kernel configuration. Specifying + *--no-clean* implies *--no-mrproper*. + +*--*[*no-*]*mrproper*:: + Runs, or does not run, "make mrproper" before compilation - this + erases both any compiled object files in the kernel source tree + as well as the kernel configuration. + +*--*[*no-*]*install*:: + Installs, or does not install the kernel to '/boot' after building. + The default is *--install*. If MOUNTBOOT is set in + '/etc/genkernel.conf' then '/boot' will be automatically mounted if + it is not already mounted before the ramdisk and kernel images + are copied over. + +*--*[*no-*]*symlink*:: + Manages, or does not manage, symlinks in '/boot' like the manual + kernel "make install" process does. A kernel (or, depending on + options, kernelz) symlink will link to the most recently built + kernel image and a kernel.old (or kernelz.old) symlink will link + to the second most recently built image, if one exists. Similar + symlinks (both * and *.old) are managed for initramfs and System.map. + The corresponding work products (i.e., the actual kernel + and initamfs images, and System.map) are also managed accordingly. + NOTE: Specifying *--symlink* does nothing unless + *--install* is also specified. + +*--no-ramdisk-modules*:: + Don't copy any modules to the ramdisk. + +*--oldconfig*:: + Implies *--no-clean*, and thus *--no-mrproper*, running a "make oldconfig". + +*--callback*=<...>:: + Run the specified arguments in the current environment after the + kernel and modules have been compiled. + + +KERNEL LOCATIONS +~~~~~~~~~~~~~~~~ +*--kerneldir*=:: + This specifies the location of the kernel sources; the default + is '/usr/src/linux'. + +*--kernel-config*=:: + This specifies a kernel configuration file to use for compilation; + by default genkernel uses the config from the previous + build of the same kernel version or a default kernel config if + there isn't a previous config. + + +LOW-LEVEL COMPILATION OPTIONS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +*--kernel-cc*=:: + Compiler to use for the kernel compilation (e.g. distcc). + +*--kernel-as*=:: + Assembler to use for the kernel compilation. + +*--kernel-ld*=:: + Linker to use for the kernel compilation. + +*--kernel-make*=:: + GNU Make to use for the kernel compilation. + +*--utils-cc*=:: + Compiler to use for utilities. + +*--utils-as*=:: + Assembler to use for utilities. + +*--utils-ld*=:: + Linker to use for utilities. + +*--utils-make*=:: + GNU Make to use for utilities. + +*--makeopts*=:: + GNU Make options such as -j2, etc. + + +INITIALIZATION +~~~~~~~~~~~~~~ +*--*[*no-*]*splash*=:: + If the extra argument is specified, splash is forced using + rather than the default theme specified in your splash + configuration. If *--no-splash* is specified, then splash is disabled. + +*--splash-res*=:: + Optionally select splash resolutions to include. + +*--do-keymap-auto*:: + Force keymap selection at boot. + +*--dmraid*:: + Add DMRAID support. + +*--evms*:: + Add in EVMS support from static binaries if they exist on the + system: you should run "emerge evms" first. + +*--lvm*:: + Add in LVM support from static binaries if they exist on the + system, or compile static LVM binaries if static ones do not + exist. + +*--luks*:: + Add in Luks support from static binaries if they exist on the + system. + +*--static*:: + This builds a monolithic kernel without any modules on any + initial ramdisks. + +*--linuxrc*=:: + Use for the linuxrc instead of the genkernel linuxrc. + + +INTERNALS +~~~~~~~~~ +*--arch-override*=:: + Force the architecture settings described by the profile + instead of autodetecting the running architecture. + +*--tempdir*=:: + Sets genkernel's temporary working directory to . + + +OUTPUT SETTINGS +~~~~~~~~~~~~~~~ +*--kernname*=<...>:: + Tag the kernel and initrd with a name, if not defined this + option defaults to genkernel + +*--minkernpackage*=:: + File to output a .tar.bz2'd kernel and initrd: no modules outside + of the initrd will be included... + +*--modulespackage*=:: + File to output a .tar.bz2'd modules after the callbacks have run + +*--kerncache*=:: + File to output a .tar.bz2'd kernel, contents of '/lib/modules/' + and the kernel config. NOTE: This is created before the callbacks + are run. + +*--no-kernel-sources*=:: + This option is only valid if kerncache is defined If there is a + valid kerncache no checks will be made against a kernel source + tree. + +*--initramfs-overlay*=:: + Directory structure to include in the initramfs, only available + on 2.6 kernels + + +RAMDISK OPTIONS +--------------- +The following options can be passed as kernel parameters from the bootloader, +which the ramdisk scripts would recognize. + +*real_root*=<...>:: + Specifies the device node of the root filesystem to mount. + +*crypt_root*=<...>:: + This specifies the device encrypted by Luks, which contains the + root filesystem to mount. + +*crypt_swap*=<...>:: + This specifies the swap device encrypted by Luks. + +*root_key*=<...>:: + In case your root is encrypted with a key, you can use a device + like a usb pen to store the key. This value should be the key + path relative to the mount point. + +*root_keydev*=<...>:: + If necessary provide the name of the device that carries the + root_key. If unset while using root_key, it will automatically + look for the device in every boot. + +*swap_key*=<...>:: + Same as root_key for swap. + +*swap_keydev*=<...>:: + Same as root_keydev for swap. + +*crypt_silent*:: + Set this to silent all the output related to the cryptographic + software, and in case your encrypted device isn't open with the + key, it opens a shell in the initrd quietly. + +*dodmraid*=<...>:: + Passes arguments to dmraid on bootup. + +*real_init*=<...>:: + Passes arguments to init on bootup. + +*scandelay*=<...>:: + Pauses for 10 seconds before running devfsd if no argument is + specified; otherwise pauses for the number of specified seconds. + +*ip*=<...>:: + Normally used to tell the kernel that it should start a network + interface. If present, the initrd will try to mount a livecd + over NFS. + +*nfsroot*=<...>:: + If present, the initrd will try to mount a livecd from that + location. Otherwise the location will be deduced from the DCHP + request (option root-path) + +*doevms*:: + Activate EVMS volumes on bootup + +*dolvm*:: + Activate LVM volumes on bootup + +*doscsi*:: + Activate SCSI devices on bootup, necessary when SCSI support is + compiled as modules and you're using SCSI or SATA devices. + + +NETBOOTING +---------- +The initrd scripts have limited support for network booting. This is +activated if the *ip*=<...> kernel parameter was given. Please refer to +the genkernel guide at 'http://www.gentoo.org/doc/en/genkernel.xml' for +more information. + +The initrd scripts will extract any *.tar.gz files found in the '/add' +directory of the livecd into the root filesystem during boot. This way +it is easy to extend a netbooted LiveCD i.e. add custom tools, or other +kernel modules. + + +REPORTING BUGS +-------------- +If you believe you have found a bug in the genkernel scripts, then +please file a bug on the Gentoo Linux Bugzilla: 'http://bugs.gentoo.org', +assigning your bug to genkernel@gentoo.org. We cannot assist you with +kernel compilation failures unless they are caused by a genkernel bug. + +Kernel issues for Gentoo-supported kernels, including compilation failures +should go to 'http://bugs.gentoo.org' and should be assigned to kernel@gentoo.org. +Please check if an existing bug documents the same +issue before opening a new bug. Issues for kernel sources not supported +by Gentoo should go to their relevant authors. + + +AUTHORS +------- +- Tim Yamin +- Eric Edgar +- NFS Support by Thomas Seiler + + +SEE ALSO +-------- +/etc/genkernel.conf - genkernel configuration file diff --git a/genkernel.8 b/genkernel.8 deleted file mode 100644 index e0c3ad1..0000000 --- a/genkernel.8 +++ /dev/null @@ -1,329 +0,0 @@ -.TH GENKERNEL "8" "June 2006" "genkernel 3.3" "Gentoo Linux" -.SH NAME -genkernel \- the Gentoo Linux automatic kernel compiler. -.SH SYNOPSIS -\fBgenkernel\fR \fI[options...] action\fR -.SH INTRODUCTION -Genkernel is designed to allow users who are not previously used to -compiling a kernel to use a similar setup to that one that is used on -the Gentoo LiveCDs which auto-detects your hardware. -.PP -Some users may also be interested in using genkernel for hardware -which requires initialization and a working kernel before it can be -booted because genkernel also automatically compiles your kernel -modules, allowing hardware which needs to be loaded with module -parameters to be used. -.SH USAGE -All that is needed to run genkernel is just ``genkernel'' with an action -and any flags you might need: -.PP -# genkernel --menuconfig --no-clean --no-install all -.PP -This would produce a kernel, asking you what how to configure it -to your desire, leaving alone any existing compiled object files, but not -installing anything. -.SH ACTIONS -An action tells genkernel what you want it to do - the following -actions are supported: -.PP -.I \fBall\fR -.RS -Build all steps - the kernel, modules, and the ramdisk. -.RE -.I \fBbzImage\fR -.RS -Build only the kernel. -.RE -.I \fBkernel\fR -.RS -Build only the kernel and the modules. -.RE -.I \fBinitramfs\fR -.RS -Build only the ramdisk. -.RE -.SH OPTIONS -Genkernel supports the following options which alter its -behaviour. Certain options have ``\fB--no-\fR'' variants which -do the opposite thing. You can specify your options in any order. -.PP -.BR Debugging \ Options -.TP -\fB\-\-loglevel=\fR<0-5> -This controls the out verbosity level of genkernel output - if this is set -to 0, minimal debugging is done; if this is set to 5 as much output as -possible is given. -.TP -\fB\-\-logfile=\fR -This outputs debugging data to the file . By default this is -.I /var/log/genkernel.log\fR. -.TP -\fB\-\-\fR[no\-]\fBcolor\fR -Turns on, or off, output in color using escape sequences. -.PP -.BR Kernel \ Configuration -.TP -\fB\-\-\fR[no\-]\fBmenuconfig\fR -Runs, or does not run "make menuconfig" after running "make oldconfig". -.TP -\fB\-\-\fR[no\-]\fBsave\-config\fR -Saves, or does not save the kernel configuration to -.I /etc/kernels -if the kernel is successfully compiled. -.TP -\fB\-\-gconfig\fR -Run "make gconfig" after "make oldconfig". -.TP -\fB\-\-xconfig\fR -Run "make xconfig" after "make oldconfig". -.PP -.BR Kernel \ Compilation -.TP -\fB\-\-\fR[no\-]\fBclean\fR -Runs, or does not run, "make clean" before compilation - this erases any -compiled object files in the kernel source tree but does not have an impact -on the kernel configuration. Specifying \fB\-\-no\-clean\fR implies -\fB\-\-no\-mrproper\fR. -.TP -\fB\-\-\fR[no\-]\fBmrproper\fR -Runs, or does not run, "make mrproper" before compilation - this erases both -any compiled object files in the kernel source tree as well as the kernel -configuration. -.TP -\fB\-\-\fR[no\-]\fBinstall\fR -Installs, or does not install the kernel to -.I /boot -after building. The default is --install. If MOUNTBOOT is set in -.I /etc/genkernel.conf -then -.I /boot -will be automatically mounted if it is -not already mounted before the ramdisk and kernel images are copied over. -.TP -\fB\-\-\fR[no\-]\fBsymlink\fR -Manages, or does not manage, symlinks in -.I /boot -like the manual kernel "make install" process does. A -.I kernel -(or, depending on options, -.I kernelz\fR) -symlink will link to the most recently built kernel image and a -.I kernel.old -(or -.I kernelz.old\fR) -symlink will link to the second most recently built image, if one exists. -Similar symlinks (both * and *.old) are managed for -.I initramfs\fR -and -.I System.map\f. -The corresponding work products (i.e., the actual kernel and initamfs images, -and System.map) are also managed accordingly. NOTE: Specifying --symlink -does nothing unless --install is also specified. -.TP -\fB\-\-no\-ramdisk\-modules\fR -Don't copy any modules to the ramdisk. -.TP -\fB\-\-oldconfig\fR -Implies \fB\-\-no\-clean\fR, and thus \fB\-\-no\-mrproper\fR, running a -"make oldconfig". -.TP -\fB\-\-callback=\fR<...> -Run the specified arguments in the current environment after the kernel and -modules have been compiled. -.PP -.BR Kernel \ Locations -.TP -\fB\-\-kerneldir=\fR -This specifies the location of the kernel sources; the default is -/usr/src/linux. -.TP -\fB\-\-kernel\-config=\fR -This specifies a kernel configuration file to use for compilation; by -default genkernel uses the config from the previous build of the same kernel -version or a default kernel config if there isn't a previous config. -.PP -.BR Low-Level \ Compilation \ Options -.TP -\fB\-\-kernel\-cc=\fR -Compiler to use for the kernel compilation (e.g. distcc). -.TP -\fB\-\-kernel\-as=\fR -Assembler to use for the kernel compilation. -.TP -\fB\-\-kernel\-ld=\fR -Linker to use for the kernel compilation. -.TP -\fB\-\-kernel\-make=\fR -GNU Make to use for the kernel compilation. -.TP -\fB\-\-utils\-cc=\fR -Compiler to use for utilities. -.TP -\fB\-\-utils\-as=\fR -Assembler to use for utilities. -.TP -\fB\-\-utils\-ld=\fR -Linker to use for utilities. -.TP -\fB\-\-utils\-make=\fR -GNU Make to use for utilities. -.TP -\fB\-\-makeopts=\fR -GNU Make options such as \fB\-j2\fR, etc. -.PP -.BR Initialization -.TP -\fB\-\-\fR[no\-]\fBsplash=\fR -If the extra argument is specified, splash is forced using -rather than the default theme specified in your splash -configuration. If \fB\-\-no-splash\fR is specified, then -splash is disabled. -.TP -\fB\-\-splash-res=\fR -Optionally select splash resolutions to include. -.TP -\fB\-\-do\-keymap\-auto\fR -Force keymap selection at boot. -.TP -\fB\-\-dmraid\fR -Add DMRAID support. -.TP -\fB\-\-evms\fR -Add in EVMS support from static binaries if they exist on the system: -you should run "emerge evms" first. -.TP -\fB\-\-lvm\fR -.RS -Add in LVM support from static binaries if they exist on the system, -or compile static LVM binaries if static ones do not exist. -.RE -.TP -\fB\-\-luks\fR -.RS -Add in Luks support from static binaries if they exist on the -system. -.RE -.TP -\fB\-\-static\fR -This builds a monolithic kernel without any modules on any initial ramdisks. -.TP -\fB\-\-linuxrc=\fR -Use for the linuxrc instead of the genkernel linuxrc. -.PP -.BR Internals -.TP -\fB\-\-arch\-override=\fR -Force the architecture settings described by the profile -instead of autodetecting the running architecture. -.TP -\fB\-\-tempdir=\fR -Sets genkernel's temporary working directory to . -.PP -.BR Output \ Settings -.TP -\fB\-\-kernname=\fR<...> -Tag the kernel and initrd with a name, if not defined this option defaults to genkernel -.TP -\fB\-\-minkernpackage=\fR -File to output a .tar.bz2'd kernel and initrd: no modules outside of the -initrd will be included... -.TP -\fB\-\-modulespackage=\fR -File to output a .tar.bz2'd modules after the callbacks have run -.TP -\fB\-\-kerncache=\fR -File to output a .tar.bz2'd kernel, contents of /lib/modules/ and the kernel config. -\fBNOTE\fR: This is created before the callbacks are run. -.TP -\fB\-\-no\-kernel\-sources=\fR -This option is only valid if kerncache is defined -If there is a valid kerncache no checks will be made -against a kernel source tree. -.TP -\fB\-\-initramfs\-overlay=\fR -Directory structure to include in the initramfs, -only available on 2.6 kernels -.SH RAMDISK OPTIONS -The following options can be passed as kernel parameters from the -bootloader, which the ramdisk scripts would recognize. -.TP -\fBreal_root=\fR<...> -Specifies the device node of the root filesystem to mount. -.TP -\fBcrypt_root=\fR<...> -This specifies the device encrypted by Luks, which contains the root -filesystem to mount. -.TP -\fBcrypt_swap=\fR<...> -This specifies the swap device encrypted by Luks. -.TP -\fBroot_key=\fR<...> -In case your root is encrypted with a key, you can use a device like a usb pen to store the key. -This value should be the key path relative to the mount point. -.TP -\fBroot_keydev=\fR<...> -If necessary provide the name of the device that carries the root_key. -If unset while using root_key, it will automatically look for the device in every boot. -.TP -\fBswap_key=\fR<...> -Same as root_key for swap. -.TP -\fBswap_keydev=\fR<...> -Same as root_keydev for swap. -.TP -\fBcrypt_silent\fR -Set this to silent all the output related to the cryptographic software, and in case your encrypted device isn't open with the key, it opens a shell in the initrd quietly. -.TP -\fBdodmraid=\fR<...> -Passes arguments to dmraid on bootup. -.TP -\fBreal_init=\fR<...> -Passes arguments to init on bootup. -.TP -\fBscandelay=\fR<...> -Pauses for 10 seconds before running devfsd if no argument is specified; -otherwise pauses for the number of specified seconds. -.TP -\fBip=\fR<...> -Normally used to tell the kernel that it should start a network interface. If present, the initrd will try to mount a livecd over NFS. -.TP -\fBnfsroot=\fR<...> -If present, the initrd will try to mount a livecd from that location. Otherwise the location will be deduced from the DCHP request (option root\-path) -.TP -\fBdoevms\fR -Activate EVMS volumes on bootup -.TP -\fBdolvm\fR -Activate LVM volumes on bootup -.TP -\fBdoscsi\fR -Activate SCSI devices on bootup, necessary when SCSI support is compiled as modules and you're using SCSI or SATA devices. - -.SH NETBOOTING -The initrd scripts have limited support for network booting. -This is activated if the ip=<...> kernel parameter was given. Please refer to the genkernel guide at http://www.gentoo.org/doc/en/genkernel.xml for more information. - -The initrd scripts will extract any *.tar.gz files found in the \fB/add\fR directory of the livecd into the root filesystem during boot. This way it is easy to extend a netbooted LiveCD i.e. add custom tools, or other kernel modules. -.SH REPORTING BUGS -If you believe you have found a bug in the genkernel scripts, then please -file a bug on the Gentoo Linux Bugzilla: -.I http://bugs.gentoo.org\fR, -assigning your bug to genkernel@gentoo.org. We cannot assist you -with kernel compilation failures unless they are caused by a genkernel -bug. -.PP -Kernel issues for Gentoo-supported kernels, including compilation -failures should go to -.I http://bugs.gentoo.org -and should be assigned to kernel@gentoo.org. Please check if an -existing bug documents the same issue before opening a new bug. Issues -for kernel sources not supported by Gentoo should go to their relevant -authors. -.SH AUTHORS -.nf -Tim Yamin -Eric Edgar -NFS Support by Thomas Seiler -.fi -.SH SEE ALSO -\fB/etc/genkernel.conf\fR \- genkernel configuration file -- 2.26.2