From 149b88625d0202ad56731a2e4eb61c96c51c0974 Mon Sep 17 00:00:00 2001 From: illiliti Date: Fri, 4 Sep 2020 15:07:55 +0300 Subject: [PATCH] add man page about hooks --- Makefile | 3 + docs/tinyramfs.config.5.scd | 5 +- docs/tinyramfs.hooks.7 | 170 ++++++++++++++++++++++++++++++++++++ docs/tinyramfs.hooks.7.scd | 110 +++++++++++++++++++++++ 4 files changed, 285 insertions(+), 3 deletions(-) create mode 100644 docs/tinyramfs.hooks.7 create mode 100644 docs/tinyramfs.hooks.7.scd diff --git a/Makefile b/Makefile index 17438a0..1e34b83 100644 --- a/Makefile +++ b/Makefile @@ -9,16 +9,19 @@ install: mkdir -p ${DESTDIR}${DATADIR}/tinyramfs \ ${DESTDIR}${MANDIR}/man5 \ ${DESTDIR}${MANDIR}/man8 \ + ${DESTDIR}${MANDIR}/man7 \ ${DESTDIR}${BINDIR} cp -R hooks ${DESTDIR}${DATADIR}/tinyramfs cp device-helper ${DESTDIR}${DATADIR}/tinyramfs cp init ${DESTDIR}${DATADIR}/tinyramfs cp tinyramfs ${DESTDIR}${BINDIR}/tinyramfs cp docs/tinyramfs.8 ${DESTDIR}${MANDIR}/man8 + cp docs/tinyramfs.hooks.7 ${DESTDIR}${MANDIR}/man7 cp docs/tinyramfs.config.5 ${DESTDIR}${MANDIR}/man5 uninstall: rm -f ${DESTDIR}${BINDIR}/tinyramfs rm -rf ${DESTDIR}${DATADIR}/tinyramfs rm -f ${DESTDIR}${MANDIR}/man8/tinyramfs.8 + rm -f ${DESTDIR}${MANDIR}/man7/tinyramfs.hooks.7 rm -f ${DESTDIR}${MANDIR}/man5/tinyramfs.config.5 diff --git a/docs/tinyramfs.config.5.scd b/docs/tinyramfs.config.5.scd index 58bc639..6f755f1 100644 --- a/docs/tinyramfs.config.5.scd +++ b/docs/tinyramfs.config.5.scd @@ -133,9 +133,8 @@ you can simply prepend \#. If hook doesn't have options, then it's not yet documented or can be used "as is". - ; TODO tinyramfs.hooks(7) - ; More detailed information and how to write your own hooks described in - ; *tinyramfs.hooks*(7). + More detailed information and how to write your own hooks described in + *tinyramfs.hooks*(7). # HOOKS OPTIONS diff --git a/docs/tinyramfs.hooks.7 b/docs/tinyramfs.hooks.7 new file mode 100644 index 0000000..71667cb --- /dev/null +++ b/docs/tinyramfs.hooks.7 @@ -0,0 +1,170 @@ +.\" Generated by scdoc 1.11.0 +.\" Complete documentation for this program is not available as a GNU info page +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.nh +.ad l +.\" Begin generated content: +.TH "tinyramfs.hooks" "7" "2020-09-04" +.P +.SH NAME +.P +Tinyramfs - hooks and related stuff +.P +.SH DESCRIPTION +.P +Hooks can be located in \fB/usr/share/tinyramfs/hooks\fR (system path) and +\fB/etc/tinyramfs/hooks\fR (user path).\& Tinyramfs also allows you to specify custom +location via \fB-H\fR option.\& See \fBtinyramfs\fR(8) for more information.\& +.P +Hooks provides a way to extend build and init process.\& Hooks must be written in +POSIX shell.\& Bashisms and other non-portable extensions are forbidden.\& In order +to write hooks you must know about hook structure.\& +.P +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.IP \(bu 4 +.\} + - directory of hook scripts +.RS 4 +.RE +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.IP \(bu 4 +.\} + - invoked in build process.\& +.RE +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.IP \(bu 4 +.\} +.\&init - invoked in init process.\& +.RE +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.IP \(bu 4 +.\} +.\&init.\&late - invoked after root filesystem was mounted.\& + +.RE +.P +.RE +.SS MAN PAGE SYNTAX +.P +.nf +.RS 4 +- B: extension can be used in build process +- I: extension can be used in init process +- BI: extension can be used in both processes +.fi +.RE +.P +.SH EXTENSIONS +.P +Tinyramfs also provides some extensions and environment variables to easily +interact with build and init system.\& +.P +.SS BI: print +.P +.RS 4 +Print message to stdout.\& +.P +.RE +.SS BI: panic [message] +.P +.RS 4 +If message was not specified, then tinyramfs will print default error +message.\& otherwise message will be printed.\& +.P +.RE +.SS B: copy_module +.P +.RS 4 +Copy kernel module by path to tinyramfs working directory.\& +.P +.RE +.SS B: copy_binary +.P +.RS 4 +If full path was specified and it's has executable bit, then it's will +be copied to /bin location of tinyramfs working directory.\& +.P +If name was specified, then tinyramfs will try to find command by name +in PATH.\& If it's success, command will be copied to /bin location of +tinyramfs working directory.\& Otherwise error message will appear.\& +.P +.RE +.SS B: copy_file +.P +.RS 4 + must be full path to file.\& +.P + must be directory where should be stored.\& Tinyramfs +will automatically create that directory if it doesn't exist already.\& Also +no need to prepend path of tinyramfs working directory.\& +.P + permissions in octal format.\& +.P + if was set to 1, then tinyramfs will attempt to run strip +on file.\& Tinyramfs will silently ignore errors if strip doesn't +exists or failed to strip binary.\& +.P +.RE +.SH VARIABLES +.P +.nf +.RS 4 +- BI: debug - 1 if debug mode enabled +- I: break - breakpoint for debugging +- B: tmpdir - full path of tinyramfs working directory (initramfs rootfs in future) +- B: kernel - kernel version +- B: moddir - modules directory +- B: config - config location +- B: srcdir - directory of tinyramfs system files +- B: output - output path +- BI: see tinyramfs\&.config(5) +.fi +.RE +.P +.SH EXAMPLES +.P +This example will show how to handle soft dependencies of ext4 module.\& +Create \fB/etc/tinyramfs/hooks/ext4\fR directory and copy below scripts with +appropriate names to that directory.\& After that, prepend \fBext4\fR to \fBhooks\fR +option in tinyrams config.\& +.P +ext4 +.P +.nf +.RS 4 +print "Copying ext4 dependencies" + +for _mod in crc32c libcrc32c; do + copy_module "$_mod" +done +.fi +.RE +.P +ext4.\&init +.P +.nf +.RS 4 +modprobe -a crc32c libcrc32c +.fi +.RE +.P +.SH SEE ALSO +.P +\fBtinyramfs\fR(8) \fBtinyramfs.\&config\fR(5) \fBtinyramfs.\&cmdline\fR(7) \fBtinyramfs.\&hooks\fR(7) diff --git a/docs/tinyramfs.hooks.7.scd b/docs/tinyramfs.hooks.7.scd new file mode 100644 index 0000000..8612c6c --- /dev/null +++ b/docs/tinyramfs.hooks.7.scd @@ -0,0 +1,110 @@ +tinyramfs.hooks(7) + +# NAME + +Tinyramfs - hooks and related stuff + +# DESCRIPTION + +Hooks can be located in */usr/share/tinyramfs/hooks* (system path) and +*/etc/tinyramfs/hooks* (user path). Tinyramfs also allows you to specify custom +location via *-H* option. See *tinyramfs*(8) for more information. + +Hooks provides a way to extend build and init process. Hooks must be written in +POSIX shell. Bashisms and other non-portable extensions are forbidden. In order +to write hooks you must know about hook structure. + +- - directory of hook scripts + - - invoked in build process. + - .init - invoked in init process. + - .init.late - invoked after root filesystem was mounted. + +## MAN PAGE SYNTAX + +``` +- B: extension can be used in build process +- I: extension can be used in init process +- BI: extension can be used in both processes +``` + +# EXTENSIONS + +Tinyramfs also provides some extensions and environment variables to easily +interact with build and init system. + +## BI: print + + Print message to stdout. + +## BI: panic [message] + + If message was not specified, then tinyramfs will print default error + message. otherwise message will be printed. + +## B: copy_module + + Copy kernel module by path to tinyramfs working directory. + +## B: copy_binary + + If full path was specified and it's has executable bit, then it's will + be copied to /bin location of tinyramfs working directory. + + If name was specified, then tinyramfs will try to find command by name + in PATH. If it's success, command will be copied to /bin location of + tinyramfs working directory. Otherwise error message will appear. + +## B: copy_file + + must be full path to file. + + must be directory where should be stored. Tinyramfs + will automatically create that directory if it doesn't exist already. Also + no need to prepend path of tinyramfs working directory. + + permissions in octal format. + + if was set to 1, then tinyramfs will attempt to run strip + on file. Tinyramfs will silently ignore errors if strip doesn't + exists or failed to strip binary. + +# VARIABLES + +``` +- BI: debug - 1 if debug mode enabled +- I: break - breakpoint for debugging +- B: tmpdir - full path of tinyramfs working directory (initramfs rootfs in future) +- B: kernel - kernel version +- B: moddir - modules directory +- B: config - config location +- B: srcdir - directory of tinyramfs system files +- B: output - output path +- BI: see tinyramfs.config(5) +``` + +# EXAMPLES + +This example will show how to handle soft dependencies of ext4 module. +Create */etc/tinyramfs/hooks/ext4* directory and copy below scripts with +appropriate names to that directory. After that, prepend *ext4* to *hooks* +option in tinyrams config. + +ext4 + +``` +print "Copying ext4 dependencies" + +for _mod in crc32c libcrc32c; do + copy_module "$_mod" +done +``` + +ext4.init + +``` +modprobe -a crc32c libcrc32c +``` + +# SEE ALSO + +*tinyramfs*(8) *tinyramfs.config*(5) *tinyramfs.cmdline*(7) *tinyramfs.hooks*(7)