From 42594787554468959ccf9a6afa5e35dee940c044 Mon Sep 17 00:00:00 2001 From: Clayton Craft Date: Sat, 18 Feb 2023 16:43:33 -0800 Subject: [PATCH] doc/mkinitfs.1: add manpage --- .gitignore | 1 + .gitlab-ci.yml | 2 +- Makefile | 20 +++++++-- doc/mkinitfs.1.scd | 105 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 124 insertions(+), 4 deletions(-) create mode 100644 doc/mkinitfs.1.scd diff --git a/.gitignore b/.gitignore index 6baa194..a4f1e51 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ /mkinitfs +/*.1 diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 0e35c82..07b1f61 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -28,7 +28,7 @@ build: stage: build <<: *only-default before_script: - - apk -q add go staticcheck make + - apk -q add go staticcheck make scdoc script: - make test - make diff --git a/Makefile b/Makefile index 5e2d77d..16adbc3 100644 --- a/Makefile +++ b/Makefile @@ -1,8 +1,10 @@ .POSIX: -.SUFFIXES: +.SUFFIXES: .1 .1.scd +VPATH=doc PREFIX?=/usr/local BINDIR?=$(PREFIX)/sbin +MANDIR?=$(PREFIX)/share/man SHAREDIR?=$(PREFIX)/share GO?=go GOFLAGS?= @@ -13,11 +15,19 @@ GOTEST=go test -count=1 -race GOSRC!=find * -name '*.go' GOSRC+=go.mod go.sum -all: mkinitfs +DOCS := \ + mkinitfs.1 + +all: mkinitfs $(DOCS) mkinitfs: $(GOSRC) $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o mkinitfs ./cmd/mkinitfs +.1.scd.1: + scdoc < $< > $@ + +doc: $(DOCS) + .PHONY: fmt fmt: gofmt -w . @@ -33,19 +43,23 @@ test: @$(GOTEST) ./... clean: - $(RM) mkinitfs + $(RM) mkinitfs $(DOCS) install: $(DOCS) mkinitfs install -Dm755 mkinitfs -t $(DESTDIR)$(BINDIR)/ + install -Dm644 mkinitfs.1 -t $(DESTDIR)$(MANDIR)/man1/ .PHONY: checkinstall checkinstall: test -e $(DESTDIR)$(BINDIR)/mkinitfs + test -e $(DESTDIR)$(MANDIR)/man1/mkinitfs.1 RMDIR_IF_EMPTY:=sh -c '! [ -d $$0 ] || ls -1qA $$0 | grep -q . || rmdir $$0' uninstall: $(RM) $(DESTDIR)$(BINDIR)/mkinitfs ${RMDIR_IF_EMPTY} $(DESTDIR)$(BINDIR) + $(RM) $(DESTDIR)$(MANDIR)/man1/mkinitfs.1 + $(RMDIR_IF_EMPTY) $(DESTDIR)$(MANDIR)/man1 .PHONY: all clean install uninstall test diff --git a/doc/mkinitfs.1.scd b/doc/mkinitfs.1.scd new file mode 100644 index 0000000..1dde2de --- /dev/null +++ b/doc/mkinitfs.1.scd @@ -0,0 +1,105 @@ +mkinitfs(1) "mkinitfs" + +# NAME + +mkinitfs + +# DESCRIPTION + +mkinitfs is a simple, generic tool for generating an initramfs, primarily +developed for use in postmarketOS + +# CONCEPTS + +mkinitfs is designed to generate two archives, "initramfs" and +"initramfs-extra", however it's possible to configure mkinitfs to run without +generating an initramfs-extra archive. mkinitfs is primarily configured through +the placement of files in specific directories detailed below in the +*DIRECTORIES* section. *deviceinfo* files are also used to provide other +configuration options to mkinitfs, these are covered under the *DEVICEINFO* +section below. + +mkinitfs does not provide an init script, or any boot-time logic, it's purpose +is purely to generate the archive(s). mkinitfs does call *boot-deploy* after +creating the archive(s), in order to install/deploy them and any other relevant +boot-related items onto the system. + +# DEVICEINFO + +TODO: where is this specified? + +# DIRECTORIES + +The following directories are used by mkinitfs to generate the initramfs and +initramfs-extra archives. Directories that end in *-extra* indicate directories +that are used for constructing the initramfs-extra archive, while those without +it are for constructing the initramfs archive. + +Configuration under */usr/share/mkinitfs* is intended to be managed by +distributions, while configuration under */etc/mkinitfs* is for users to +create/manage. mkinitfs reads configuration from */usr/share/mkinitfs* first, and then from */etc/mkinitfs*. + +## /usr/share/mkinitfs/files, /etc/mkinitfs/files +## /usr/share/mkinitfs/files-extra, /etc/mkinitfs/files-extra + + Files with the *.files* extension are read as a list of + files/directories. Each line is in the format: + + ``` + : + ``` + + The source path is the location, at runtime, of the file or directory + which will be copied to the destination path within the initramfs + archive. Specifying a destination path, with *:* is + optional. If it is omitted, then the source path will be used as the + destination path within the archive. The source and destination paths + are delimited by a *:* (colon.) Destination path is ignored if the source + path is a glob that returns more than 1 file. This may change in the future. + +[[ *Line in .files* +:< Comment +| */usr/share/bazz* +: File or directory */usr/share/bazz* would be added to the archive under */usr/share/bazz* +| */usr/share/bazz:/bazz* +: File or directory */usr/share/bazz* would be added to the archive under */bazz* +| */root/something/\** +: Everything under */root/something* would be added to the archive under */root/something* +| */etc/foo/\*/bazz:/foo* +: Anything that matches the glob will be installed under the source path in the archive. For example, */etc/foo/bar/bazz* would be installed at */etc/foo/bar/bazz* in the archive. The destination path is ignored. + + It's possible to overwrite file/directory destinations from + configuration in */usr/share/mkinitfs* by specifying the same source + path(s) under the relevant directory in */etc/mkinitfs*, and changing + the destination path. + +## /usr/share/mkinitfs/hooks, /etc/mkinitfs/hooks +## /usr/share/mkinitfs/hooks-extra*, /etc/mkinitfs/hooks-extra + + Any files listed under these directories are copied as-is into the + relevant archives. Hooks are generally script files, but how they are + treated in the initramfs is entirely up to whatever init script is run + there on boot. + + Hooks are installed in the initramfs under the */hooks* directory, and + under */hooks-extra* for the initramfs-extra. + +## /usr/share/mkinitfs/modules, /etc/mkinitfs/modules + + Files with the *.modules* extention in these directories are lists of + kernel modules to include in the initramfs. No modules are placed in + the initramfs-extra archive. Individual modules and directories can be + listed in the files here. Globbing is also supported. + + Modules are installed in the initramfs archive under the same path they + exist on the system where mkinitfs is executed. + +## /usr/share/mkinitfs/dirs, /etc/mkinitfs/dirs + + Files with the *.dirs* extension in these directories are lists of + directories to create within the initramfs. There is no *-extra* variant, + since directories are of negligible size. + +# AUTHORS + +*Clayton Craft*