add documentation about --{setup,extract,essential,customize}-hooks and --skip option, making them an official interface

This commit is contained in:
Johannes 'josch' Schauer 2020-06-23 23:14:37 +02:00
parent 40b6155967
commit 112c0a5a6d
Signed by untrusted user: josch
GPG key ID: F2CBA5C78FBD83E1

View file

@ -5087,11 +5087,7 @@ whether a package selection within a certain suite and variant can in principle
be installed as far as their dependencies go. If the output is a tarball, then be installed as far as their dependencies go. If the output is a tarball, then
no output is produced. If the output is a directory, then the directory will be no output is produced. If the output is a directory, then the directory will be
left populated with the skeleton files and directories necessary for apt to run left populated with the skeleton files and directories necessary for apt to run
in it. in it. No hooks are executed in with B<--simulate> or B<--dry-run>.
=begin comment
No hooks are executed in with B<--simulate> or B<--dry-run>.
=item B<--setup-hook>=I<command> =item B<--setup-hook>=I<command>
@ -5117,6 +5113,16 @@ Example: Setup chroot for installing a sub-essential busybox-based chroot with
--setup-hook='echo root:x:0:0:root:/root:/bin/sh > "$1/etc/passwd"' --setup-hook='echo root:x:0:0:root:/root:/bin/sh > "$1/etc/passwd"'
--setup-hook='printf "root:x:0:\nmail:x:8:\nutmp:x:43:\n" > "$1/etc/group"' --setup-hook='printf "root:x:0:\nmail:x:8:\nutmp:x:43:\n" > "$1/etc/group"'
=item B<--extract-hook>=I<command>
Execute arbitrary I<command>s after the Essential:yes packages have been
extracted but before installing them. See section B<HOOKS> for more
information.
Example: Install busybox symlinks
--extract-hook='chroot "$1" busybox --install -s'
=item B<--essential-hook>=I<command> =item B<--essential-hook>=I<command>
Execute arbitrary I<command>s after the Essential:yes packages have been Execute arbitrary I<command>s after the Essential:yes packages have been
@ -5153,7 +5159,12 @@ Example: Preparing a chroot for use with autopkgtest
--customize-hook='echo "127.0.0.1 localhost host" > "$1/etc/hosts"' --customize-hook='echo "127.0.0.1 localhost host" > "$1/etc/hosts"'
--customize-hook=/usr/share/autopkgtest/setup-commands/setup-testbed --customize-hook=/usr/share/autopkgtest/setup-commands/setup-testbed
=end comment =item B<--skip>=I<stage>[,I<stage>,...]
B<mmdebstrap> tries hard to implement sensible defaults and will try to stop
you before shooting yourself in the foot. This option is for when you are sure
you know what you are doing and allows one to skip certain actions and safety
checks.
=item B<-q,--quiet>, B<-s,--silent> =item B<-q,--quiet>, B<-s,--silent>
@ -5386,14 +5397,12 @@ support extended attributes, the resulting image will not contain them.
=back =back
=begin comment
=head1 HOOKS =head1 HOOKS
This section describes properties of the hook options B<--setup-hook>, This section describes properties of the hook options B<--setup-hook>,
B<--essential-hook> and B<--customize-hook> which are common to all three of B<--extract-hook>, B<--essential-hook> and B<--customize-hook> which are common
them. Any information specific to each hook is documented under the specific to all three of them. Any information specific to each hook is documented under
hook options in the section B<OPTIONS>. the specific hook options in the section B<OPTIONS>.
The options can be specified multiple times and the commands are executed in The options can be specified multiple times and the commands are executed in
the order in which they are given on the command line. There are three the order in which they are given on the command line. There are three
@ -5481,8 +5490,6 @@ inside can have a different name from the file on the outside.
=back =back
=end comment
=head1 EXAMPLES =head1 EXAMPLES
Use like debootstrap: Use like debootstrap:
@ -5547,8 +5554,6 @@ Use as debootstrap replacement in sbuild-createchroot:
--make-sbuild-tarball ~/.cache/sbuild/unstable-amd64.tar.gz \ --make-sbuild-tarball ~/.cache/sbuild/unstable-amd64.tar.gz \
unstable $(mktemp -d) unstable $(mktemp -d)
=begin comment
Create a bootable USB Stick that boots into a full Debian desktop: Create a bootable USB Stick that boots into a full Debian desktop:
$ mmdebstrap --aptopt='Apt::Install-Recommends "true"' --customize-hook \ $ mmdebstrap --aptopt='Apt::Install-Recommends "true"' --customize-hook \
@ -5621,8 +5626,6 @@ user namespaces instead. This fixes Debian bug #829134.
--setup-hook='env container=lxc debootstrap unstable "$1"' \ --setup-hook='env container=lxc debootstrap unstable "$1"' \
- debian-debootstrap.tar - debian-debootstrap.tar
=end comment
Build a non-Debian chroot like Ubuntu bionic: Build a non-Debian chroot like Ubuntu bionic:
$ mmdebstrap --aptopt='Dir::Etc::Trusted $ mmdebstrap --aptopt='Dir::Etc::Trusted
@ -5739,8 +5742,6 @@ B<mmdebstrap> treats any warning from "apt-get update" as an error. Fixing
this will require apt to provide a machine readable status interface. See this will require apt to provide a machine readable status interface. See
Debian bugs #778357, #776152, #696335, and #745735. Debian bugs #778357, #776152, #696335, and #745735.
=begin comment
Special hooks either require C<tar> or C<sh> and C<cat> be present inside the Special hooks either require C<tar> or C<sh> and C<cat> be present inside the
chroot or otherwise there is no support for absolute symlinks. This limitation chroot or otherwise there is no support for absolute symlinks. This limitation
can be dropped for the B<root> and B<unshare> modes as well as for the can be dropped for the B<root> and B<unshare> modes as well as for the
@ -5750,8 +5751,6 @@ symlinks are handled by B<fakechroot> and B<proot>, the requirement of having
C<tar> or C<sh> and C<cat> inside the chroot can never be dropped for these C<tar> or C<sh> and C<cat> inside the chroot can never be dropped for these
modes. modes.
=end comment
=head1 SEE ALSO =head1 SEE ALSO
debootstrap(8) debootstrap(8)