summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 15:45:07 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 15:45:07 +0000
commit3b043b08c9b52424072db56be6636ff44c737e83 (patch)
treed64185acc33a046c8bb297641a16b01ec167eaa5 /docs
parentInitial commit. (diff)
downloadinitramfs-tools-upstream.tar.xz
initramfs-tools-upstream.zip
Adding upstream version 0.142.upstream/0.142upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs')
-rw-r--r--docs/example_hook68
-rw-r--r--docs/example_script35
-rw-r--r--docs/framebuffer116
-rw-r--r--docs/maintainer-notes.md193
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
+ &lt;mailaddress&gt;' 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 &lt;[mika@debian.org](mailto:mika@debian.org)&gt;,
+Ben Hutchings &lt;[benh@debian.org](mailto:benh@debian.org)&gt;*