Skip to contentSkip to conversation

Add man page for fsverity

PATCH Applied Eric Biggers 3 participants 4 messages Jun 10, 2021 – Jun 11, 2021

Subsystems (2)
lore
Share & tools
lore

Eric Biggers

author maintainer
#0 lore raw

PATCH 1/1 Add man page for fsverity

From: Eric Biggers <[email protected]>

Add a manual page for the fsverity utility, documenting all subcommands and options.

The page is written in Markdown and is translated to groff using pandoc. It can be installed by 'make install-man'.

---
 .gitignore            |   1 +
 Makefile              |  32 ++++++-
 README.md             |  14 +++-
 man/fsverity.1.md     | 191 ++++++++++++++++++++++++++++++++++++++++++
 scripts/do-release.sh |   6 ++
 scripts/run-tests.sh  |   2 +-
 6 files changed, 239 insertions(+), 7 deletions(-)
 create mode 100644 man/fsverity.1.md
.gitignore +1 -0
index 6117e52..eba6ab6 100644
@@ -1,3 +1,4 @@
+*.[1-9]
 *.a
 *.exe
 *.o
Makefile +29 -3
index fd28b06..c97790e 100644
@@ -25,6 +25,9 @@
 # Define LIBDIR to override where to install libraries, like './configure
 # --libdir' in autotools-based projects (default: PREFIX/lib)
 #
+# Define MANDIR to override where to install man pages, like './configure
+# --mandir' in autotools-based projects (default: PREFIX/share/man)
+#
 # Define DESTDIR to override the installation destination directory
 # (default: empty string)
 #
@@ -61,12 +64,14 @@ QUIET_CCLD      = @echo '  CCLD    ' $@;
 QUIET_AR        = @echo '  AR      ' $@;
 QUIET_LN        = @echo '  LN      ' $@;
 QUIET_GEN       = @echo '  GEN     ' $@;
+QUIET_PANDOC    = @echo '  PANDOC  ' $@;
 endif
 USE_SHARED_LIB  ?=
 PREFIX          ?= /usr/local
 BINDIR          ?= $(PREFIX)/bin
 INCDIR          ?= $(PREFIX)/include
 LIBDIR          ?= $(PREFIX)/lib
+MANDIR          ?= $(PREFIX)/share/man
 DESTDIR         ?=
 ifneq ($(MINGW),1)
 PKGCONF         ?= pkg-config
@@ -92,6 +97,7 @@ FSVERITY        := fsverity$(EXEEXT)
 	fi
 
 DEFAULT_TARGETS :=
+EXTRA_TARGETS   :=
 COMMON_HEADERS  := $(wildcard common/*.h)
 LDLIBS          := $(shell "$(PKGCONF)" libcrypto --libs 2>/dev/null || echo -lcrypto)
 CFLAGS          += $(shell "$(PKGCONF)" libcrypto --cflags 2>/dev/null || echo)
@@ -187,9 +193,22 @@ DEFAULT_TARGETS += $(FSVERITY)
 $(TEST_PROGRAMS): %$(EXEEXT): programs/%.o $(PROG_COMMON_OBJ) libfsverity.a
 	$(QUIET_CCLD) $(CC) -o $@ $+ $(CFLAGS) $(LDFLAGS) $(LDLIBS)
 
+EXTRA_TARGETS += $(TEST_PROGRAMS)
+
 ##############################################################################
 
-SPECIAL_TARGETS := all test_programs check install uninstall help clean
+#### Manual pages
+
+man/fsverity.1:man/fsverity.1.md
+	$(QUIET_PANDOC) pandoc $+ -s -t man > $@
+
+MAN_PAGES := man/fsverity.1
+EXTRA_TARGETS += $(MAN_PAGES)
+
+##############################################################################
+
+SPECIAL_TARGETS := all test_programs check install install-man uninstall \
+		   help clean
 
 FORCE:
 
@@ -233,6 +252,10 @@ install:all
 		> $(DESTDIR)$(LIBDIR)/pkgconfig/libfsverity.pc
 	chmod 644 $(DESTDIR)$(LIBDIR)/pkgconfig/libfsverity.pc
 
+install-man:$(MAN_PAGES)
+	install -d $(DESTDIR)$(MANDIR)/man1
+	install -m644 $+ $(DESTDIR)$(MANDIR)/man1/
+
 uninstall:
 	rm -f $(DESTDIR)$(BINDIR)/$(FSVERITY)
 	rm -f $(DESTDIR)$(LIBDIR)/libfsverity.a
@@ -240,15 +263,18 @@ uninstall:
 	rm -f $(DESTDIR)$(LIBDIR)/libfsverity.so
 	rm -f $(DESTDIR)$(LIBDIR)/pkgconfig/libfsverity.pc
 	rm -f $(DESTDIR)$(INCDIR)/libfsverity.h
+	for page in $(notdir $(MAN_PAGES)); do \
+		rm -f $(DESTDIR)$(MANDIR)/man1/$$page; \
+	done
 
 help:
 	@echo "Available targets:"
 	@echo "------------------"
-	@for target in $(DEFAULT_TARGETS) $(TEST_PROGRAMS) $(SPECIAL_TARGETS); \
+	@for target in $(DEFAULT_TARGETS) $(EXTRA_TARGETS) $(SPECIAL_TARGETS); \
 	do \
 		echo $$target; \
 	done
 
 clean:
-	rm -f $(DEFAULT_TARGETS) $(TEST_PROGRAMS) \
+	rm -f $(DEFAULT_TARGETS) $(EXTRA_TARGETS) \
 		lib/*.o programs/*.o .build-config fsverity.sig
README.md +11 -3
index 2b63488..14c7bbe 100644
@@ -24,20 +24,22 @@ See `libfsverity.h` for the API of this library.
 
 ## Building and installing
 
-fsverity-utils uses the OpenSSL library, so you first must install the
-needed development files.  For example, on Debian-based systems, run:
+To build fsverity-utils, first install the needed build dependencies.  For
+example, on Debian-based systems, run:
 
 ```bash
     sudo apt-get install libssl-dev
+    sudo apt-get install pandoc  # optional
 ```
 
-OpenSSL must be version 1.0.0 or later.
+OpenSSL must be version 1.0.0 or later.  This is the only runtime dependency.
 
 Then, to build and install fsverity-utils:
 
 ```bash
     make
     sudo make install
+    sudo make install-man  # optional
 ```
 
 By default, the following targets are built and installed: the program
@@ -45,6 +47,9 @@ By default, the following targets are built and installed: the program
 `libfsverity.so`.  You can also run `make check` to build and run the
 tests, or `make help` to display all available build targets.
 
+`make install-man` installs the `fsverity.1` manual page.  This step requires
+that `pandoc` be installed.
+
 By default, `fsverity` is statically linked to `libfsverity`.  You can
 use `make USE_SHARED_LIB=1` to use dynamic linking instead.
 
@@ -63,6 +68,9 @@ A Windows build of OpenSSL/libcrypto needs to be available.
 
 ## Examples
 
+Full usage information for `fsverity` can be found in the manual page
+(`man fsverity`).  Here, we just show some typical examples.
+
 ### Basic use
 
 ```bash
man/fsverity.1.md new file +191 -0

191 lines not on this page · raw message

scripts/do-release.sh +6 -0
index 352fcf1..9f6bf73 100755
@@ -25,11 +25,17 @@ git clean -fdx
 
 major=$(echo "$VERS" | cut -d. -f1)
 minor=$(echo "$VERS" | cut -d. -f2)
+month=$(LC_ALL=C date +%B)
+year=$(LC_ALL=C date +%Y)
+
 sed -E -i -e "/FSVERITY_UTILS_MAJOR_VERSION/s/[0-9]+/$major/" \
 	  -e "/FSVERITY_UTILS_MINOR_VERSION/s/[0-9]+/$minor/" \
 	  include/libfsverity.h
 sed -E -i "/Version:/s/[0-9]+\.[0-9]+/$VERS/" \
 	  lib/libfsverity.pc.in
+sed -E -i -e "/^% /s/fsverity-utils v[0-9]+(\.[0-9]+)+/fsverity-utils v$VERS/" \
+	  -e "/^% /s/[a-zA-Z]+ 2[0-9]{3}/$month $year/" \
+	  man/*.[1-9].md
 git commit -a --signoff --message="v$VERS"
 git tag --sign "v$VERS" --message="$PKG"
 
scripts/run-tests.sh +1 -1
index 530fe34..9cdc7c1 100755
@@ -101,7 +101,7 @@ log "Check that all files have license and copyright info"
 list="$TMPDIR/filelist"
 filter_license_info() {
 	# files to exclude from license and copyright info checks
-	grep -E -v '(\.gitignore|LICENSE|NEWS|README|testdata|fsverity_uapi\.h|libfsverity\.pc\.in)'
+	grep -E -v '(\.gitignore|LICENSE|.*\.md|testdata|fsverity_uapi\.h|libfsverity\.pc\.in)'
 }
 git grep -L 'SPDX-License-Identifier: MIT' \
 	| filter_license_info > "$list" || true
Signature · 1 line
2.32.0
Acked-by on v1 1/1
#1 lore raw
Quoted 9 lines · Eric Biggers

From: Eric Biggers <[email protected]>

Add a manual page for the fsverity utility, documenting all subcommands and options.

The page is written in Markdown and is translated to groff using pandoc. It can be installed by 'make install-man'.

Quoted 9 lines
---
 .gitignore            |   1 +
 Makefile              |  32 ++++++-
 README.md             |  14 +++-
 man/fsverity.1.md     | 191 ++++++++++++++++++++++++++++++++++++++++++
 scripts/do-release.sh |   6 ++
 scripts/run-tests.sh  |   2 +-
 6 files changed, 239 insertions(+), 7 deletions(-)
 create mode 100644 man/fsverity.1.md
Signature · 2 lines
Kind regards,
Luca Boccassi
Reviewed-by on v1 1/1
#2 lore raw
In reply to Eric Biggers
Quoted 10 lines · Eric Biggers

From: Eric Biggers <[email protected]>

Add a manual page for the fsverity utility, documenting all subcommands and options.

The page is written in Markdown and is translated to groff using pandoc. It can be installed by 'make install-man'.

Quoted 9 lines
---
 .gitignore            |   1 +
 Makefile              |  32 ++++++-
 README.md             |  14 +++-
 man/fsverity.1.md     | 191 ++++++++++++++++++++++++++++++++++++++++++
 scripts/do-release.sh |   6 ++
 scripts/run-tests.sh  |   2 +-
 6 files changed, 239 insertions(+), 7 deletions(-)
 create mode 100644 man/fsverity.1.md
author maintainer Applied
#3 lore raw
In reply to Eric Biggers
Quoted 9 lines · Eric Biggers

From: Eric Biggers <[email protected]>

Add a manual page for the fsverity utility, documenting all subcommands and options.

The page is written in Markdown and is translated to groff using pandoc. It can be installed by 'make install-man'.

Quoted 9 lines
---
 .gitignore            |   1 +
 Makefile              |  32 ++++++-
 README.md             |  14 +++-
 man/fsverity.1.md     | 191 ++++++++++++++++++++++++++++++++++++++++++
 scripts/do-release.sh |   6 ++
 scripts/run-tests.sh  |   2 +-
 6 files changed, 239 insertions(+), 7 deletions(-)
 create mode 100644 man/fsverity.1.md

Applied.

- Eric