diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/example_hook | 54 | ||||
| -rw-r--r-- | docs/example_hook_cpiogz | 84 | ||||
| -rw-r--r-- | docs/example_script | 63 | ||||
| -rw-r--r-- | docs/framebuffer | 113 | ||||
| -rw-r--r-- | docs/maintainer-notes.html | 372 |
5 files changed, 493 insertions, 193 deletions
diff --git a/docs/example_hook b/docs/example_hook index a0d015a..1f35352 100644 --- a/docs/example_hook +++ b/docs/example_hook @@ -1,5 +1,5 @@ #!/bin/sh - +# # # This is an example hook script. It will be run by 'mkinitramfs' # when it creates the image. It's job is to decide which files to @@ -8,39 +8,12 @@ # package is installed, or when the administrator runs 'mkinitramfs' # by hand to update an initramfs image. # -# TODO: What about the case where you install something that should be -# added to the initramfs, but the linux-image it relates to has -# already been installed previously? Does this happen often -# enough that it needs to be handled? How can it be handled? -# -# * Think about the 'usplash'. The initramfs will need to be -# updated if a theme change or update is desired. Maybe it -# should not be totally automatic, but offered on upgrade -# predicated on a user response to a debconf question? That -# issue needs to be explored and a solution specified. -# -# * Do not assume that any needed subdirectories have been created -# yet, but don't bail out if they are already there. -# -# * All of the standard system tools are available, of course, since -# this hook is running in the real system, not the initramfs. -# -# * TODO: ... ? Anything else to tell them in this bullet-list? -# - -# -# The environment contains at least: -# -# CONFDIR -- usually /etc/mkinitramfs, can be set on mkinitramfs +# CONFDIR -- usually /etc/initramfs-tools, can be set on mkinitramfs # command line. # # DESTDIR -- The staging directory where we are building the image. # -# TODO: Decide what environment variables are meaningful and defined -# in this context, then document them as part of the interface. -# -# TODO: May need a version_compare function for comparison of VERSION? - +# see initramfs-tools(8) # # List the soft prerequisites here. This is a space separated list of @@ -80,7 +53,7 @@ esac # course may be other reasons to have custom logic deciding what to # install. The version variable may be useful for this. # -if [ -x /usr/bin/myprog ]; then +if command -v myprog >/dev/null 2>&1; then copy_exec /usr/bin/myprog usr/bin fi @@ -92,23 +65,4 @@ fi # ... and it should do what is necessary to have 'myprog' get run # inside the early runtime environment. -# Handle an error: -# -if [ -n "$an_error_occured" ]; -then - # - # TODO: Do we need 'warn()', 'error()', and/or 'fatal()' for this? - # - echo "An error occured in $0: $an_error_occured" >&2 - exit 1 - # - # TODO: Decide if different error codes are meaningful, what they - # mean, and what the semantics of them are wrt 'mkinitramfs' - # pass or fail. Consider naming the error values with - # mnemonic symbols rather than magic numbers. They may or - # may not be the same set of errors as the set for - # in-initramfs scripts. - # -fi - exit 0 diff --git a/docs/example_hook_cpiogz b/docs/example_hook_cpiogz deleted file mode 100644 index f3e44d9..0000000 --- a/docs/example_hook_cpiogz +++ /dev/null @@ -1,84 +0,0 @@ -#!/bin/sh - -# -# The environment contains at least: -# -# CONFDIR -- usually /etc/mkinitramfs, can be set on mkinitramfs -# command line. -# -# DESTDIR -- The staging directory where we are building the image. -# -# TODO: Decide what environment variables are meaningful and defined -# in this context, then document them as part of the interface. -# -# TODO: Write a common header for these examples or move this -# documentation to a man page and reference it here. :-) -# - -# -# List the soft prerequisites here. This is a space separated list of -# names, of scripts that are in the same directory as this one, that -# must be run before this one can be. -# -PREREQ="" - -prereqs() -{ - echo "$PREREQ" -} - -case $1 in -# get pre-requisites -prereqs) - prereqs - exit 0 - ;; -esac - -# -# Source the 'hook-functions' scriptlet (for 'catenate_cpiogz'): -# -. /usr/share/initramfs-tools/hook-functions - -# -# Lets pretend it has a conffile (think debconf), and we source it -# here. Don't make debconf lookup calls here. The postinst for the -# package owning this hook script should have done that and configured -# the "/etc/default/conffile" already. -# -# TODO: How does the package ensure that it's installed BEFORE the -# corresponding 'linux-image' package? Can it declare that, in -# the case where it's an add-on that the 'linux-image' is not -# aware of? This might be an apt and dpkg issue. -# -# * Eg. an optional usplash or suspend2ui_fbsplash package. -# -. /etc/default/mypackage-initramfs - -# -# Also pretend that we only include our initramfs overlay if an opion -# is not "no", and the 'linux-image' package we are generating this -# initramfs for matches the version this script's package is designed -# for. Just for example; pretend this example mkinitramfs hook script -# is part of a 'linux-image' or 'xxx-modules' package. -# -if [ "$MYOPTION" != "no" -a "$version" = "2.6.12+ss2.1.9.1" ]; then - catenate_cpiogz /usr/lib/mypackage/initramfs.cpio.gz -fi - -# -# In this case, there does not have to be an (eg.): -# -# "/etc/mkinitramfs/init-top/mypackage" -# -# ... since that script is probably inside of the initramfs overlay -# already. If it's a conffile though, it does not belong in there, -# and should be placed in the appropriate location inside of -# "/etc/mkinitramfs". Remember that if it needs access to the -# settings in our "/etc/default/mypackage-initramfs", then that file -# must also get copied into a location inside of ${DESTDIR} by this -# hook script in order to make it available inside of the initramfs -# environment. -# - -exit 0 diff --git a/docs/example_script b/docs/example_script index d7f407f..5e9153b 100644 --- a/docs/example_script +++ b/docs/example_script @@ -2,45 +2,11 @@ # # This script is run inside of the initramfs environment during the -# system boot process. It is installed there by 'mkinitramfs'. The -# package that owns it may opt to install it in either an appropriate -# location under "/usr/share/initramfs-tools/scripts/", or a similar -# location under "/etc/mkinitramfs/scripts/", depending upon whether -# it should be considered to be a user modifiable conffile or not. -# -# TODO: How do we deal with the case where the package that installed -# this has been removed but not purged, if we always arbitrarily -# copy all of these scripts into the initramfs? -# -# * The available toolset is limited inside this environment... -# -# TODO: document that toolset in the man page. -# -# * /dev, /proc, and /sys are already mounted. / is a ?? ro/rw -# filesystem... etc. more documentation. -# -# * It is expected that /proc and /sys will be umounted before -# changing over to the real root file system, so you must not keep -# any files open on them beyond these scripts. -# -# * You may like to strip these documentation comments from this -# example if you take it for a template, to save a little space in -# the initramfs, since nobody will ever read it from inside of -# there anyhow. -# - -# -# The environment contains at least the following variables: -# -# TODO: Decide what environment variables are meaningful and defined -# in this context, then document them as part of the interface. -# -# Because this script will be run as a full separate process, rather -# than sourced inside the context of the driver script, if it needs to -# pass information to another script that may run after it, it must do -# so by writing data to a file location known to both scripts. Simply -# setting an environment variable will not work. +# system boot process. It is installed there by 'update-initramfs'. +# The # package that owns it may opt to install it in an appropriate +# location under "/usr/share/initramfs-tools/scripts/". # +# see initramfs-tools(8) for more details. # # List the soft prerequisites here. This is a space separated list of @@ -66,25 +32,4 @@ esac echo "Got here!" -# Handle an error: - -if [ -n "$an_error_occured" ]; -then - # - # TODO: Do we need 'warn()', 'error()', and/or 'fatal()' for this? - # I think we ultimately do, and that they need to be in their own - # well-documented location so that an overlay can override them. - # Think 'usplash' progress updates. - # - echo "An error occured in $0: $an_error_occured" >&2 - exit 1 - # - # TODO: Decide if different error codes are meaningful, what they - # mean, and what the semantics of them are wrt 'init' pass - # or panic. Consider naming the error values with mnemonic - # symbols rather than magic numbers. - # -fi - exit 0 - diff --git a/docs/framebuffer b/docs/framebuffer new file mode 100644 index 0000000..47d8302 --- /dev/null +++ b/docs/framebuffer @@ -0,0 +1,113 @@ +#!/bin/sh + +PREREQ="" +prereqs() +{ + echo "$PREREQ" +} +case $1 in +# get pre-requisites +prereqs) + prereqs + exit 0 + ;; +esac + + +# The options part of the kernel "video=" argument (i.e. everyting +# after "video=<fbdriver>:") has very inconsistent rules. +# +# Generally the following applies: +# 1) options are comma-separated +# 2) options can be in either of these three forms: +# <arg>=<value>, <arg>:<value>, <boolean-arg>. +# 3) the "mode" or "mode_option" option (name depends on the framebuffer driver) +# has the form <xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m] +# and may or may not start with "mode=" or "mode_option=" +# -> please adjust as necessary in the parse_video_opts() function +# +# When the options are used with modules, they need to be space-separated +# and the following conversions are needed: +# <arg>:<value> -> <arg>=<value> +# <boolean-arg> -> <boolean-arg>=1 +# <modevalue> -> mode=<modevalue> or mode_option=<modevalue> +parse_video_opts() +{ + local OPTS="$1" + local IFS="," + + # Must be a line like video=<fbdriver>:<opt1>,[opt2]... + if [ "${OPTS}" = "${OPTS%%:*}" ]; then + return + fi + OPTS="${OPTS#*:}" + for opt in ${OPTS}; do + # Already in the "<arg>=<value>" form + if [ "${opt}" != "${opt#*=}" ]; then + echo -n "$opt " + # In the "<arg>:<value>" form + elif [ "${opt}" != "${opt#*:}" ]; then + echo -n "${opt%:*}=${opt#*:} " + # Presumably a modevalue without the "mode=" prefix + elif [ "${opt}" != "${opt#[0-9]*x[0-9]}" ]; then + # Adjust: mode= option? + echo -n "mode=$opt " + # ... or mode_option= option? + # echo -n "mode_option=$opt " + # Presumably a boolean + else + echo -n "${opt}=1 " + fi + done +} + +FB="" +OPTS="" + +for x in $(cat /proc/cmdline); do + case ${x} in + vga=*) + FB="vesafb"; + OPTS=""; + ;; + video=*) + FB=${x#*=} + FB="${FB%%:*}" + OPTS="$(parse_video_opts "${x}")" + esac +done + +# Module-specific workarounds +case ${FB} in +matroxfb) + # Map command line name to module name + FB=matroxfb_base + ;; +intelfb|i810fb|i915) + # Needs AGP driver loaded + modprobe intel-agp + ;; +uvesafb) + # v86d requires /dev/zero and dev/mem, but udev haven't been started yet + [ -e /dev/zero ] || mknod -m 0666 /dev/zero c 1 5 + [ -e /dev/mem ] || mknod -m 0640 /dev/mem c 1 1 + ;; +*) + ;; +esac + +if [ -n "${FB}" ]; then + unset MODPROBE_OPTIONS + modprobe -q fbcon + modprobe -q ${FB} ${OPTS} +fi + +if [ -e /proc/fb ]; then + while read fbno desc; do + if [ $(($fbno < 32)) ]; then + mknod -m 0640 /dev/fb${fbno} c 29 ${fbno} + fi + done < /proc/fb +else + mknod -m 0640 /dev/fb0 c 29 0 +fi diff --git a/docs/maintainer-notes.html b/docs/maintainer-notes.html new file mode 100644 index 0000000..e9cec2d --- /dev/null +++ b/docs/maintainer-notes.html @@ -0,0 +1,372 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<title>Maintainer documentation for initramfs-tools</title> +<style type="text/css"> +/*<![CDATA[*/ +a { color: black; } +a:hover { text-decoration: none; } +a:visited { color: gray; } +acronym { cursor: help; } +body { font-family: "DejaVu Sans", "Bitstream Vera Sans", sans-serif; } +pre { background-color: #EEEEEE; border: 1px dashed black; padding: 1em; } +div.right { text-align: right; } +/*]]>*/ +</style> +</head> + +<body> + +<div> +<hr /> + +<h1>Maintainer documentation for initramfs-tools</h1> + +<hr /> + +<h2><a name="toc">Table of Contents</a></h2> + +<ul> + +<li><a href="#definitions">1. Definitions</a></li> +<li><a href="#preparations">2. Preparations</a></li> + +<li><a href="#workflow">3. Workflow for daily work</a> +<ul> +<li><a href="#newfeature">3.1 Implement new features</a></li> +<li><a href="#merge">3.2 Merge branches</a></li> +<li><a href="#test">3.3 Test specific branch</a></li> +<li><a href="#snapshot">3.4 Build snapshot version</a></li> +</ul> +</li> + +<li><a href="#contribute">4. Contribute</a></li> +<li><a href="#release">5. Release new version</a></li> +<li><a href="#ressources">6. Ressources</a></li> +<li><a href="#credits">7. Credits</a></li> +<li><a href="#license">8. License</a></li> + +</ul> + +<hr /> + +<p><b>NOTE:</b> The most recent version of this document is available at +docs/maintainer-notes.html in the <a href="#checkout">the git repository</a> +or online at <a + href="http://git.debian.org/?p=kernel/initramfs-tools.git;a=blob_plain;f=docs/maintainer-notes.html;hb=HEAD">git.debian.org</a>.</p> + +<hr /> + +<h2><a name="definitions">1. Definitions</a></h2> + +<table> + <tr><td><code><b>$mailaddress:</b></code></td><td>mailaddress of the user</td></tr> + <tr><td><code><b>$username:</b></code></td><td>name of the alioth account</td></tr> + <tr><td><code><b>$version:</b></code></td><td>version string</td></tr> + <tr><td><code><b>$yourname:</b></code></td><td>your fullname</td></tr> +</table> + +<div class="right"><a href="#toc">^</a></div> +<hr /> + +<h2><a name="preparations">2. Preparations</a></h2> + +<ol> + +<li>Install required software (notice: git is named git-core on Debian/stable): +<pre> +<b># apt-get install git git-buildpackage dpkg-dev</b> +</pre> +</li> + +<li>Set environment variables (e.g. through your ~/.bashrc or ~/.zshrc) for devscripts (git dch): +<pre> +<b>export DEBEMAIL=$mailaddress +export DEBFULLNAME=$yourname</b> +</pre> +</li> + +<li>Set user name and email address for git (drop the --global option to use configuration per-repo basis): +<pre> +<b>% git config --global user.name "$yourname" +% git config --global user.email "$mailaddress"</b> +</pre> +</li> + +<li><a name="checkout">Checkout</a> repository (anonymous): +<pre> +<b>% git clone git://git.debian.org/git/kernel/initramfs-tools.git +% cd initramfs-tools</b> +</pre> +</li> + +<li>Checkout repository (with developer access): +<pre> +<b>% git clone ssh://<code><i>$username</i></code>@git.debian.org/git/kernel/initramfs-tools.git +% cd initramfs-tools</b> +</pre> +</li> + +</ol> + +<div class="right"><a href="#toc">^</a></div> +<hr /> + +<h2><a name="workflow">3. Workflow for daily work</a></h2> + +<h3><a name="newfeature">3.1 Implement new features</a></h3> + +<ol> + +<li>Checkout new branch and switch to it: +<pre> +<b>% git checkout -b <code><i>$username</i></code>/short-descr-of-new-feature</b> +</pre> +</li> + +<li>Hack and commit work: +<pre> +<b>% $EDITOR $somefile +% git add $somefile +% git commit -s</b> +</pre> + +<b>NOTE:</b> Use 'Closes: #BUGID' for closing a bugreport and 'Thanks: Fullname +<<code><i>mailaddress</i></code>>' for giving credits in your commit message. git dch will use +this information for generating the changelog using the --meta option later +on. + +</li> + +<li>Finally push your branch to alioth: +<pre> +<b>% git push origin <code><i>$username</i></code>/short-descr-of-new-feature</b> +</pre> +</li> + +</ol> + +<h3><a name="merge">3.2 Merge branches</a></h3> + +<ol> + +<li>Switch to the branch you want to merge: +<pre> +<b>% git checkout <code><i>$username</i></code>/new-feature</b> +</pre> +</li> + +<li>Rebase to master: +<pre> +<b>% git rebase master</b> +</pre> +</li> + +<li>Switch to master branch and merge: +<pre> +<b>% git checkout master +% git merge <code><i>$username</i></code>/new-feature</b> +</pre> +</li> + +<li>Push: +<pre> +<b>% git push</b> +</pre> +</li> + +<li>After branch is merged delete branch on server and locally: +<pre> +<b>% git push origin :<code><i>$username</i></code>/short-descr-of-new-feature +% git branch -d <code><i>$username</i></code>/short-descr-of-new-feature</b> +</pre> +</li> + +<li>If a branch is removed from the server it will stay locally. You can get of +any stale remote branches locally by executing: +<pre> +<b>% git remote prune origin</b> +</pre> +</li> + +</ol> + +<h3><a name="test">3.3 Test specific branch</a></h3> + +<ol> + +<li>Checkout a specific branch iff branch is not already present locally: +<pre> +<b>% git checkout -b somename/short-descr-of-new-feature origin/somename/short-descr-of-new-feature</b> +</pre> +</li> + +<li>Checkout a specific branch iff branch is already present locally: +<pre> +<b>% git checkout -b somename/short-descr-of-new-feature</b> +</pre> +</li> + +<li>Adjust debian/changelog accordingly: +<pre> +<b>% git dch --debian-branch="$(git branch | awk -F\*\ '/^* / { print $2}' )" \ + --since="$(dpkg-parsechangelog | awk '/^Version:/ {print $2}')" -S --id-length=7 --meta</b> +</pre> +</li> + +<li>Build package: +<pre> +<b>% git buildpackage --git-debian-branch="$(git branch | awk -F\*\ '/^* / { print $2}' )" -tc</b> +</pre> +</li> + +</ol> + +<div class="right"><a href="#toc">^</a></div> +<hr /> + +<h3><a name="snapshot">3.4 Build snapshot version</a></h3> + +<ol> + +<li>Adjust debian/changelog accordingly: +<pre> +<b>% git dch --debian-branch="$(git branch | awk -F\*\ '/^* / { print $2}' )" \ + --since="$(dpkg-parsechangelog | awk '/^Version:/ {print $2}')" -S --id-length=7 --meta</b> +</pre> +</li> + +<li>Build package: +<pre> +<b>% git buildpackage --git-debian-branch="$(git branch | awk -F\*\ '/^* / { print $2}' )" -tc [-us -uc]</b> +</pre> +</li> + +</ol> + +<div class="right"><a href="#toc">^</a></div> +<hr /> + +<h2><a name="contribute">4. Contribute</a></h2> + +<ol> +<li>Create patch: +<pre> +<b>% git format-patch -s -p origin/master</b> +</pre> +</li> + +<li>Send patch file(s) to maintainers via mail (requires Debian package git-email): +<pre> +<b>% git send-email --to=initramfs-tools@packages.qa.debian.org $PATCHFILE[S]</b> +</pre> +</li> + +<li>The development mailinglists are <a + href="mailto:debian-kernel@lists.debian.org">debian-kernel@lists.debian.org</a> +and <a href="mailto:initramfs@vger.kernel.org">initramfs@vger.kernel.org</a>. +Discussion of features, bugs and patches are more than welcome on one +of these lists.</li> + +</ol> + +<div class="right"><a href="#toc">^</a></div> +<hr /> + +<h2><a name="release">5. Release new version</a></h2> + +<ol> + +<li>Creating changelog: + +<pre> +<b>% git dch --debian-branch master --release --since <code><i>HASH</i></code></b> +</pre> + +or more dynamically: + +<pre> +<b>% git dch --meta --release --since v$(dpkg-parsechangelog | awk '/^Version:/ {print $2}') --debian-branch="$(git branch | awk -F\*\ '/^* / { print $2}' )" [--id-length=7] [--full]</b> +</pre> + +<b>NOTE:</b> we do not use history based sorting for the changelog entries but +sort them by author (doing that manually when reviewing the changelog, see <a + href="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=586165">#586165</a>). + +</li> + +<li>Releasing: +<pre> +<b>% git commit -a -s -m "Releasing version <code><i>$version</i></code>."</b> +</pre> +</li> + +<li>Tagging: +<pre> +<b>% git tag -s v"<code><i>$version</i></code>" -m "release <code><i>$version</i></code>"</b> +</pre> +</li> + +<li>Pushing: +<pre> +<b>% git push +% git push --tags</b> +</pre> +</li> + +<li>Build in chroot and upload to ftp-master.</li> + +<li>Send mail announcing the new initramfs-tools version with subject +"initramfs-tools $VERSION release" to initramfs@vger.kernel.org, +debian-kernel@lists.debian.org + kernel-team@lists.ubuntu.com - including a +shortlog (generated through "git shortlog $TAG..").</li> + +</ol> + +<div class="right"><a href="#toc">^</a></div> +<hr /> + +<h2><a name="ressources">6. Ressources</a></h2> + +<ul> + <li><a href="http://git.debian.org/?p=kernel/initramfs-tools.git">initramfs-tools git web interface</a></li> + <li><a href="http://wiki.debian.org/initramfs">initramfs @ debian-wiki</a></li> + <li><a href="http://bugs.debian.org/cgi-bin/pkgreport.cgi?pkg=initramfs-tools;dist=unstable">bugreports</a></li> + <li><a href="http://packages.qa.debian.org/i/initramfs-tools.html">initramfs-tools @ PTS</a></li> + <li><a href="http://qa.debian.org/popcon.php?package=initramfs-tools">popcon graph</a></li> + <li><a href="http://people.debian.org/~glandium/bts/i/initramfs-tools.png">bugcount for initramfs-tools</a></li> + <li><a href="https://launchpad.net/ubuntu/+source/initramfs-tools">bugreports @ ubuntu</a></li> + <li><a href="http://status.qa.ubuntu.com/qapkgstatus/initramfs-tools">qa page @ ubuntu</a></li> +</ul> + +<div class="right"><a href="#toc">^</a></div> +<hr /> + +<h2><a name="credits">7. Credits</a></h2> + +<ul> + <li>Thanks to Daniel Baumann for his "<a href="http://documentation.debian-projects.org/other/debian-packaging-git/">Debian Packaging with Git</a>" which inspired this document.</li> +</ul> + +<div class="right"><a href="#toc">^</a></div> +<hr /> + +<h2><a name="license">8. License</a></h2> + +<ul> + <li>This document is licensed under GPL v2 or any later version.</li> +</ul> + +<div class="right"><a href="#toc">^</a></div> +<hr /> + +<p> +<i>-- Michael Prokop <<a href="mailto:mika@debian.org" title="Send mail to the author of this document">mika@debian.org</a>></i> +</p> + +<hr /> + +</div> +</body> +</html> |