.\" /usr/share/man/man1/dphys-kernel-packages.1(.gz) .\" author Neil Franklin, last modification 2006.10.26 .\" copyright ETH Zuerich Physics Departement .\" use under either modified/non-advertising BSD or GPL license .TH DPHYS-KERNEL-PACKAGES 1 "2006.10.26" "D-PHYS Kernel Tools" .SH NAME dphys-kernel-packages \- generate customised kernels and modules .SH SYNOPSIS .B dphys-kernel-packages .SH DESCRIPTION dphys-kernel-packages generates an wide range of config file variants (for different processors, SMP options and memory sizes). It then compiles fitting kernels and their fitting external modules and packages these into Debian kernel packages. For the modules, it only requires an single user-written debian/rules script fragment per module. .PP It uses the standard Debian make-kpkg program for the actual compiling and packaging work. It also uses the debhelper package to generate the reboot packages. The standard Linux tools make and fakeroot are also used. .SH OPTIONS .TP .B \-s sourcedir: Find all input files (kernel/config/modules/scripts) to use in this directory. .TP .B \-k kernel: Use this specific kernel archive. .TP .B \-c config: Use this specific config file. .TP .B \-m modulesdir: Use this specific modules and rules directory. .TP .B \-t targetdir: Place all output files into this directory. .TP .B \-q quiet: Don't produce an running report of activities. .TP .B \-v verbose: Give large volume output, where sensible. .TP .B \-D Debug: Activate an debug option. See source for how to use this. .TP .B \-h help: Output help text, and then abort operation. .SH CONFIG The config files \fI/etc/dphys-kernel-packages\fP (sitewide), \fI~/.dphys-kernel-packages\fP (personal) and \fI./dphys-kernel-packages\fP (particular project) allow the admin and users to set up the working environment for \fBdphys-kernel-packages\fP. .PP These config files are sh script fragments full of assignments, which are sourced, in above row, later config files assignments overriding earlier ones. Standard sh syntax rules apply. .TP .B CONF_SOURCEDIR Set where all input files (kernel/config/modules/scripts) are to be found. Defaults to \fI./\fP (current directory). Option \fB-s\fP override this, \fB-k\fP, \fB-c\fP and \fB-m\fP override this partially. .TP .B CONF_TARGETDIR Set where all output files are to be placed. Defaults to default CONF_SOURCEDIR. Changing CONF_SOURCEDIR does not auto-change this! .TP .B CONF_NAMETAG Name tag to be inserted after kernel version and before kernel variant. Defaults to nothing. Examples: -dphys -2-dphys -dphys-2 -install. .TP .B CONF_VARIANTS Select what kernel variants to produce. It is a list of specifiers. Specifier format is <\fIprocessor\fP>[\fB-smp\fP]-<\fImemory\fP>. <\fIprocessor\fP> can be any of \fBp1\fP, \fBp3\fP, \fBp4\fP, \fBk7\fP or \fBk8\fP. \fB-smp\fP is added if SMP support is wanted. \fImemory\fP can be any of \fB1gb\fP, \fB4gb\fP or \fB64gb\fP. This is used to select what config to generate and to select /lib/modules/*/* and to name the .deb archives. The \fIdphys-kernel-cputype\fP(1) program uses the same format, and can be used to select which archive to install. Defaults to: \fIp1-1gb\fP. Examples: p3-1gb p4-4gb k7-smp-1gb k7-smp-64gb. .TP .B CONF_MAINT_NAME Used for the Maintainer: line in debian/control files and in debian/changelog files. Defaults to \fIdphys-kernel-packages\fP. .TP .B CONF_MAINT_EMAIL Used for the Maintainer: line in debian/control files and in debian/changelog files. Defaults to \fIroot@localhost\fP. .TP .B CONF_COPY Used for the copyright ownership remarks in file headers and debian/copyright. Defaults to placing of the files and package in the public domain. You need to change this if you want to be more restrictive. .SH FILES .TP .B /etc/dphys-kernel-packages site admin config .TP .B ~/.dphys-kernel-packages users personal config .TP .B ./dphys-kernel-packages individual projects config .TP .B ${CONF_SOURCEDIR}/linux-*.tar.bz2 and .TP .B ${CONF_SOURCEDIR}/linux-*.tar.gz Linux source code archive to be used. If multiple fitting files are present, the last one (ASCII sorted) will be used. Files with *.bz2 are tested before *.gz, and so override these. These must contain an directory linux-* with all the stuff in it. .TP .B ${CONF_SOURCEDIR}/config* Base configuration to be used, must be manually produced. Configure it for an Pentium1 processor, no SMP, standard <1G memory size, others will be auto-edited as needed. If multiple fitting files are present, the last one (filenames ASCII sorted) will be used. .TP .B ${CONF_SOURCEDIR}/modules/*.tar.bz2 and .TP .B ${CONF_SOURCEDIR}/modules/*.tar.gz External modules source code archives to be used. Files with *.bz2 are tested before *.gz, and so override these. .TP .B ${CONF_SOURCEDIR}/modules/*.rules Script fragment to be added to this modules debian/rules script. Must have same base name as the above archives, with each \fI.tar.[gz|bz2]\fP ending replaced by an \fI.rules\fP ending! .TP .B ${CONF_TARGETDIR}/kernel-image--_*_.deb Where the produced Debian package containing the kernel is stored. .TP .B ${CONF_TARGETDIR}/----_*_.deb Where all the produced Debian packages containing modules are stored. .TP .B ${CONF_TARGETDIR}/kernel-reboot---_*_.deb Auxillary package to make dphys-admin reboot the system after installation. .SH KERNEL MAKING Make an directory for all input and output files. .PP Fetch whatever kernel source archive you want and place it here. .PP Unpack the kernel (keeping the packed kernel) and produce an .config file, for Pentium1, no SMP, 1G memory (or use an existing one, cleaned up with make oldconfig). Copy the resulting .config to config-p1-1gb in the generated directory. Delete the unpacked kernel (the packed kernel will automatically be unpackt for each compile). .PP If you want external modules generate an subdirctory modules/, and place all their source archives as module/.tar.gz or module/.tar.bz2 in there. For each archive in modules/ make an module/.rules file containing instructions for configuring, compiling/building, installing and removing/cleaning. This is a Makefile fragment, so make syntax applies, tabs at beginnign of lines are neccessary. .PP Existing debianisation files (debian/* subdirectory) are treated as following: control and rules are overwritten (to prevent randomly large trouble), changelog is extended (no chance of trouble), copyright is left untouched or added if not present (content irrelevant, but Debian screams it it is missing), rest are left untouched (content irrelevant to us). .SH EXAMPLES A simple \fB./dphys-kernel-packages\fP may look like this: .PP .nf CONF_VARIANTS="p1-1gb p3-1gb p4-4gb k7-smp-1gb k7-smp-64gb" CONF_MAINT_NAME="Jay Random" CONF_MAINT_EMAIL="jrandom@example.org" .fi .PP A simple ${CONF_SOURCEDIR}/modules/alsa-driver-1.0.11.rules may look like this: .PP .nf # debian/rules dphys-kernel-packages fragment for alsa-driver-1.0.11 INSTALL_PATH=$(DESTDIR)/lib/modules/$(KVERS)/alsa configure-module: @./configure --with-kernel=$(KSRC) build-module: @/usr/bin/make -j 4 install-module: @if [ ! -d $(INSTALL_PATH) ] ; then \ /bin/mkdir -p $(INSTALL_PATH) ; \ fi @/bin/cp -p modules/* $(INSTALL_PATH) clean-module: @/bin/rm -rf $(INSTALL_PATH) .fi .PP Predefined variables are: $(KSRC) directory where the fitting unpacked kernel source is available, $(KVERS) kernel version string, $(KMAINT) contains ${CONF_MAINT_NAME}, $(KEMAIL) contains ${CONF_MAINT_EMAIL}, $(KDREV) contains debianised version number, $(DESTDIR) contains where module being packaged will be taken from. The targest must be named *-module. .PP Further examples of fragments for various modules are given in \fB/usr/share/doc/dphys-kernel-packages/\fP. .PP \fIdphys-kernel-cputype\fP(1) may be used to then install fitting kernels like this: .PP .nf apt-get install kernel-image-2.4.33.2-1-dphys-`dphys-kernel-cputype` apt-get install alsa-driver-1.0.11--2.4.33.2-1-dphys-`dphys-kernel-cputype` apt-get install kernel-reboot--2.4.33.2-1-dphys-`dphys-kernel-cputype` .fi .SH ERROR MESSAGES These are graded into categories and marked accordingly, and then sent to stderr output: .TP .B FATAL: Something happend that was not expected to be so. Looks seriously wrong. Operation will be immediately aborted. May require sysadmin to fix. Could even be sign of an bug. .TP .B ERROR: User input looks errorneous. Will try to give out help as far as applicable help is known. Check up on command line options and filenames. .TP .B WARNING: Something unusual is happening, most likely wrong, but it may be desired. So continue operation but warn user, to look if it was an desired thing. .TP .B NOTE: Something happend which is completely legal, but may be sign of trouble. Give user a note that it happened and continue. .TP .B INFO: Tell user what we are doing now. Only happens if user demanded -v verbosity. Not unexpected and not an error and demanded, so sent to stdout, not stderr. .TP .B DEBUG: Tell user in what state we are at the moment. Only happens if user demanded -D PRINT_STEP debug output. Not unexpected and not an error and demanded, so sent to stdout, not stderr. .SH SEE ALSO \fIdphys-kernel-cputype\fP(1), \fImake-kpkg\fP(1), \fIdpkg-buildpackage\fP(1) .SH AUTHOR franklin@phys.ethz.ch, http://www.phys.ethz.ch/~franklin/