diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/example_hook | 68 | ||||
| -rw-r--r-- | docs/example_script | 35 | ||||
| -rw-r--r-- | docs/framebuffer | 116 | ||||
| -rw-r--r-- | docs/maintainer-notes.md | 193 |
4 files changed, 412 insertions, 0 deletions
diff --git a/docs/example_hook b/docs/example_hook new file mode 100644 index 0000000..85ff6c6 --- /dev/null +++ b/docs/example_hook @@ -0,0 +1,68 @@ +#!/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 +# install, then install them into the staging area, where the +# initramfs is being created. This happens when a new 'linux-image' +# package is installed, or when the administrator runs 'mkinitramfs' +# by hand to update an initramfs image. +# +# CONFDIR -- usually /etc/initramfs-tools, can be set on mkinitramfs +# command line. +# +# DESTDIR -- The staging directory where we are building the image. +# +# see initramfs-tools(7) + +# +# 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 + + +# You can do anything you need to from here on. +# + +# Source the optional 'hook-functions' scriptlet, if you need the +# functions defined within it. Read it to see what is available to +# you. It contains functions for copying dynamically linked program +# binaries, and kernel modules into the DESTDIR. +# +. /usr/share/initramfs-tools/hook-functions + + +# If this hook script is a conffile (and thus stored in +# /etc/mkinitramfs/hooks), it must take care to do the right thing +# when the package containing it is removed but not purged. There of +# course may be other reasons to have custom logic deciding what to +# install. The version variable may be useful for this. +# +if command -v myprog >/dev/null 2>&1; then + copy_exec /usr/bin/myprog usr/bin +fi + +# To accompany this, there should usually be a script for inside the +# initramfs named something like: +# +# "/etc/mkinitramfs/local-premount/myprog" +# +# ... and it should do what is necessary to have 'myprog' get run +# inside the early runtime environment. + +exit 0 diff --git a/docs/example_script b/docs/example_script new file mode 100644 index 0000000..accab37 --- /dev/null +++ b/docs/example_script @@ -0,0 +1,35 @@ +#!/bin/sh + +# +# This script is run inside of the initramfs environment during the +# 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(7) for more details. + +# +# 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 + +# Do the work here. + +echo "Got here!" + +exit 0 diff --git a/docs/framebuffer b/docs/framebuffer new file mode 100644 index 0000000..453ac8f --- /dev/null +++ b/docs/framebuffer @@ -0,0 +1,116 @@ +#!/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 + printf "%s" "$opt " + # In the "<arg>:<value>" form + elif [ "${opt}" != "${opt#*:}" ]; then + printf "%s" "${opt%:*}=${opt#*:} " + # Presumably a modevalue without the "mode=" prefix + elif [ "${opt}" != "${opt#[0-9]*x[0-9]}" ]; then + # Adjust: mode= option? + printf "%s" "mode=$opt " + # ... or mode_option= option? + # printf "%s" "mode_option=$opt " + # Presumably a boolean + else + printf "%s" "${opt}=1 " + fi + done +} + +FB="" +OPTS="" + +# shellcheck disable=SC2013 +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 + /sbin/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 + /sbin/modprobe -q fbcon + # shellcheck disable=SC2086 + /sbin/modprobe -q ${FB} ${OPTS} +fi + +if [ -e /proc/fb ]; then + # shellcheck disable=SC2034 + while read -r 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.md b/docs/maintainer-notes.md new file mode 100644 index 0000000..3b51046 --- /dev/null +++ b/docs/maintainer-notes.md @@ -0,0 +1,193 @@ +# Maintainer documentation for initramfs-tools + +[[_TOC_]] + +**NOTE:** The most recent version of this document is available at +docs/maintainer-notes.md in the [the git repository](#checkout) +or online at [salsa.debian.org](https://salsa.debian.org/kernel-team/initramfs-tools/blob/master/docs/maintainer-notes.md). + +## <a name="definitions">1. Definitions</a> + +| Name | Meaning | +| --- | --- | +| **`$mailaddress`** | mailaddress of the user | +| **`$username`** | name of the Salsa account | +| **`$version`** | version string | +| **`$yourname`** | your fullname | + +## <a name="preparations">2. Preparations</a> + +1. Install required software: + + # apt-get install git git-buildpackage dpkg-dev + +1. Set environment variables (e.g. through your ~/.bashrc or ~/.zshrc) for devscripts (gbp dch): + + export DEBEMAIL=$mailaddress + export DEBFULLNAME=$yourname + +1. Set user name and email address for git (drop the --global option to use configuration per-repo basis): + + % git config --global user.name "$yourname" + % git config --global user.email "$mailaddress" + +1. <a name="checkout">Checkout repository (anonymous):</a> + + % git clone https://salsa.debian.org/kernel-team/initramfs-tools.git + % cd initramfs-tools + +1. Checkout repository (with developer access): + + % git clone ssh://git@salsa.debian.org/kernel-team/initramfs-tools.git + % cd initramfs-tools + +## <a name="workflow">3. Workflow for daily work</a> + +### <a name="newfeature">3.1 Implement new features</a> + +1. Checkout new branch and switch to it: + + % git checkout -b $username/short-descr-of-new-feature + +1. Hack and commit work: + + % $EDITOR $somefile + % git add $somefile + % git commit -s + + **NOTE:** Use 'Closes: #BUGID' for closing a bugreport and 'Thanks: Fullname + <mailaddress>' for giving credits in your commit message. gbp dch will use + this information for generating the changelog using the --meta option later + on. + +1. Finally push your branch to Salsa: + + % git push origin $username/short-descr-of-new-feature + +### <a name="merge">3.2 Merge branches</a> + +1. Switch to the branch you want to merge: + + % git checkout $username/new-feature + +1. Rebase to master: + + % git rebase master + +1. Switch to master branch and merge: + + % git checkout master + % git merge $username/new-feature + +1. Push: + + % git push + +1. After branch is merged delete branch on server and locally: + + % git push origin :$username/short-descr-of-new-feature + % git branch -d $username/short-descr-of-new-feature + +1. If a branch is removed from the server it will stay locally. You can get of +any stale remote branches locally by executing: + + % git remote prune origin + +### <a name="test">3.3 Test specific branch</a> + +1. Checkout a specific branch iff branch is not already present locally: + + % git checkout -b somename/short-descr-of-new-feature origin/somename/short-descr-of-new-feature + +1. Checkout a specific branch iff branch is already present locally: + + % git checkout -b somename/short-descr-of-new-feature + +1. Adjust debian/changelog accordingly: + + % gbp dch --debian-branch="$(git branch | awk -F\*\ '/^* / { print $2}' )" \ + --since="v$(dpkg-parsechangelog | awk '/^Version:/ {print $2}')" -S --id-length=7 --meta --multimaint-merge + +1. Build package: + + % gbp buildpackage --git-ignore-new --git-debian-branch="$(git branch | awk -F\*\ '/^* / { print $2}' )" --post-clean + +### <a name="snapshot">3.4 Build snapshot version</a> + +1. Adjust debian/changelog accordingly: + + % gbp dch --debian-branch="$(git branch | awk -F\*\ '/^* / { print $2}' )" \ + --since="v$(dpkg-parsechangelog | awk '/^Version:/ {print $2}')" -S --id-length=7 --meta --multimaint-merge + +1. Build package: + + % gbp buildpackage --git-debian-branch="$(git branch | awk -F\*\ '/^* / { print $2}' )" --post-clean [-us -uc] + +## <a name="contribute">4. Contribute</a> + +1. Create patch: + + % git format-patch -s -p origin/master + +1. Send patch file(s) to maintainers via mail (requires Debian package git-email): + + % git send-email --to=initramfs-tools@packages.debian.org $PATCHFILE[S] + +1. The development mailinglists are [debian-kernel@lists.debian.org](mailto:debian-kernel@lists.debian.org) + and [initramfs@vger.kernel.org](mailto:initramfs@vger.kernel.org). + Discussion of features, bugs and patches are more than welcome on one + of these lists. + +## <a name="release">5. Release new version</a> + +1. Creating changelog: + + % gbp dch --debian-branch master --release --since HASH + + or more dynamically: + + % gbp dch --meta --release --since v$(dpkg-parsechangelog | awk '/^Version:/ {print $2}') --debian-branch="$(git branch | awk -F\*\ '/^* / { print $2}' )" --id-length=7 --meta --multimaint-merge + + **NOTE:** we do not use history based sorting for the changelog entries but + sort them by author. + +1. Releasing: + + % git commit -a -s -m "Releasing version $version." + +1. Tagging: + + % git tag -s v"$version" -m "release $version" + +1. Pushing: + + % git push + % git push --tags + +1. Build in chroot and upload to ftp-master. + +1. 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.."). + +## <a name="resources">6. Resources</a> + +* [initramfs-tools git web interface](https://salsa.debian.org/kernel-team/initramfs-tools) +* [initramfs @ debian-wiki](https://wiki.debian.org/initramfs) +* [bugreports](https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=initramfs-tools;dist=unstable) +* [initramfs-tools @ tracker](https://tracker.debian.org/pkg/initramfs-tools) +* [popcon graph](https://qa.debian.org/popcon.php?package=initramfs-tools) +* [bugreports @ ubuntu](https://bugs.launchpad.net/ubuntu/+source/initramfs-tools) +* [qa page @ ubuntu](http://status.qa.ubuntu.com/qapkgstatus/initramfs-tools) + +## <a name="credits">7. Credits</a> + +* Thanks to Daniel Baumann for his "[Debian Packaging with Git](https://web.archive.org/web/20110528125600/http://documentation.debian-projects.org/other/debian-packaging-git/)" which inspired this document. + +## <a name="license">8. License</a> + +* This document is licensed under GPL v2 or any later version. + +*-- Michael Prokop <[mika@debian.org](mailto:mika@debian.org)>, +Ben Hutchings <[benh@debian.org](mailto:benh@debian.org)>* |