From f8a8197e860ac89b6e07795d11b99d1b63ba54c8 Mon Sep 17 00:00:00 2001 From: Radostin Stoyanov Date: Sun, 3 Sep 2023 08:23:46 +0100 Subject: [PATCH 1/2] docs: Add man pages for checkpointctl This patch adds man pages for checkpointctl. Similar to CRIU, we use AsciiDoc language and Asciidoctor [1] for generating the man pages. [1] https://docs.asciidoctor.org/asciidoctor/latest/manpage-backend/ Signed-off-by: Radostin Stoyanov --- .github/workflows/tests.yml | 2 +- Makefile | 15 ++++++---- Makefile.versions | 5 ++++ docs/.gitattributes | 1 + docs/.gitignore | 2 ++ docs/Makefile | 49 ++++++++++++++++++++++++++++++++ docs/checkpointctl-inspect.adoc | 49 ++++++++++++++++++++++++++++++++ docs/checkpointctl-memparse.adoc | 25 ++++++++++++++++ docs/checkpointctl-show.adoc | 19 +++++++++++++ docs/checkpointctl.adoc | 49 ++++++++++++++++++++++++++++++++ docs/custom.xsl | 8 ++++++ 11 files changed, 217 insertions(+), 7 deletions(-) create mode 100644 Makefile.versions create mode 100644 docs/.gitattributes create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/checkpointctl-inspect.adoc create mode 100644 docs/checkpointctl-memparse.adoc create mode 100644 docs/checkpointctl-show.adoc create mode 100644 docs/checkpointctl.adoc create mode 100644 docs/custom.xsl diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 54f8b0c1..f7a10d50 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -11,7 +11,7 @@ jobs: steps: - uses: actions/checkout@v3 - name: Install tools - run: sudo dnf -y install ShellCheck bats golang criu + run: sudo dnf -y install ShellCheck bats golang criu asciidoctor - name: Run make shellcheck run: make shellcheck - name: Run make all diff --git a/Makefile b/Makefile index ee3bedb3..1a6e484a 100644 --- a/Makefile +++ b/Makefile @@ -8,11 +8,7 @@ GO_SRC = $(shell find . -name \*.go) GO_BUILD = $(GO) build NAME = checkpointctl -VERSION_MAJOR := 0 -VERSION_MINOR := 1 -VERSION_SUBLEVEL := 0 -VERSION_EXTRA := -VERSION := $(VERSION_MAJOR)$(if $(VERSION_MINOR),.$(VERSION_MINOR))$(if $(VERSION_SUBLEVEL),.$(VERSION_SUBLEVEL))$(if $(VERSION_EXTRA),.$(VERSION_EXTRA)) +include Makefile.versions COVERAGE_PATH ?= $(shell pwd)/.coverage @@ -52,14 +48,17 @@ install: $(NAME) @echo " INSTALL " $< @mkdir -p $(DESTDIR)$(BINDIR) @install -m0755 $< $(DESTDIR)$(BINDIR) + @make -C docs install uninstall: + @make -C docs uninstall @echo " UNINSTALL" $(NAME) @$(RM) $(addprefix $(DESTDIR)$(BINDIR)/,$(NAME)) clean: rm -f $(NAME) junit.xml $(NAME).coverage $(COVERAGE_PATH)/* if [ -d $(COVERAGE_PATH) ]; then rmdir $(COVERAGE_PATH); fi + @make -C docs clean golang-lint: golangci-lint run @@ -93,9 +92,13 @@ vendor: go mod vendor go mod verify +docs: + @make -C docs + help: @echo "Usage: make " @echo " * clean - remove artifacts" + @echo " * docs - build man pages" @echo " * lint - verify the source code (shellcheck/golangci-lint)" @echo " * golang-lint - run golangci-lint" @echo " * shellcheck - run shellcheck" @@ -109,4 +112,4 @@ help: @echo " * release - build a static binary" @echo " * help - show help" -.PHONY: clean install uninstall release lint golang-lint shellcheck vendor test help check-go-version test-junit +.PHONY: clean docs install uninstall release lint golang-lint shellcheck vendor test help check-go-version test-junit diff --git a/Makefile.versions b/Makefile.versions new file mode 100644 index 00000000..3d45871b --- /dev/null +++ b/Makefile.versions @@ -0,0 +1,5 @@ +VERSION_MAJOR := 0 +VERSION_MINOR := 1 +VERSION_SUBLEVEL := 0 +VERSION_EXTRA := +VERSION := $(VERSION_MAJOR)$(if $(VERSION_MINOR),.$(VERSION_MINOR))$(if $(VERSION_SUBLEVEL),.$(VERSION_SUBLEVEL))$(if $(VERSION_EXTRA),.$(VERSION_EXTRA)) diff --git a/docs/.gitattributes b/docs/.gitattributes new file mode 100644 index 00000000..ddb03013 --- /dev/null +++ b/docs/.gitattributes @@ -0,0 +1 @@ +*.txt whitespace diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..21283cf7 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +*.[1-8] +footer.adoc diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d89f0fce --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,49 @@ +PREFIX ?= /usr/local +MANDIR ?= $(PREFIX)/share/man + +ASCIIDOC := asciidoctor + +FOOTER := footer.adoc + +SRC1 += checkpointctl-inspect.adoc +SRC1 += checkpointctl-memparse.adoc +SRC1 += checkpointctl-show.adoc +SRC1 += checkpointctl.adoc +SRC := $(SRC1) + +MAN1S := $(patsubst %.adoc,%.1,$(SRC1)) +MANS := $(MAN1S) +MAN1DIR := $(MANDIR)/man1 + +all: check $(MANS) + +check: + @$(ASCIIDOC) --version > /dev/null || exit 1 + +include ../Makefile.versions +$(FOOTER): + $(call msg-gen, $@) + @echo "The CRIU team" > $@ + @echo "v$(VERSION)" >> $@ + @echo ":doctype: manpage" >> $@ + @echo ":mansource: checkpointctl" >> $@ + @echo ":manversion: $(VERSION)" >> $@ + @echo ":manmanual: CHECKPOINTCTL Manual" >> $@ + +%.1: %.adoc $(FOOTER) custom.xsl + $(call msg-gen, $@) + @$(ASCIIDOC) -b manpage -d manpage -o $@ $< + +clean: + @rm -f $(MANS) $(FOOTER) + +install: check $(MANS) + @echo " INSTALL " $(MAN1S) + @mkdir -p $(DESTDIR)$(MAN1DIR) + @install -m 644 $(MAN1S) $(DESTDIR)$(MAN1DIR) + +uninstall: + @echo " UNINSTALL" $(MAN1S) + @rm -rf $(addprefix $(DESTDIR)$(MAN1DIR)/,$(MAN1S)) + +.PHONY: all check clean install uninstall diff --git a/docs/checkpointctl-inspect.adoc b/docs/checkpointctl-inspect.adoc new file mode 100644 index 00000000..a2cb2c14 --- /dev/null +++ b/docs/checkpointctl-inspect.adoc @@ -0,0 +1,49 @@ += checkpointctl-inspect(1) +include::footer.adoc[] + +== Name + +*checkpointctl-inspect* - display low-level information about a container checkpoint + +== Synopsis + +*checkpointctl inspect* [_OPTION_]... _FILE_ + +== Options + +*-h*, *--help*:: + Show help for checkpointctl memparse + +*--all*:: + Show all information about container checkpoints + +*--files*:: + Display the open file descriptors for processes in the container checkpoint + +*--format*=_FORMAT_:: + Specify the output format: tree or json (default "tree") + +*--mounts*:: + Display an overview of mounts used in the container checkpoint + +*-p, --pid*=_PID_:: + Display the process tree of a specific PID + +*--ps-tree*:: + Display an overview of processes in the container checkpoint + +*--ps-tree-cmd*:: + Display an overview of processes in the container checkpoint with full command line arguments + +*--ps-tree-env*:: + Display an overview of processes in the container checkpoint with their environment variables + +*--sockets*:: + Display the open sockets for processes in the container checkpoint + +*--stats*:: + Display checkpoint statistics + +== See also + +checkpointctl(1) diff --git a/docs/checkpointctl-memparse.adoc b/docs/checkpointctl-memparse.adoc new file mode 100644 index 00000000..c5693331 --- /dev/null +++ b/docs/checkpointctl-memparse.adoc @@ -0,0 +1,25 @@ += checkpointctl-memparse(1) +include::footer.adoc[] + +== Name + +*checkpointctl-memparse* - analyze container checkpoint memory + +== Synopsis + +*checkpointctl memparse* [_OPTION_]... _FILE_ + +== Options + +*-h*, *--help*:: + Show help for checkpointctl memparse + +*-o, --output*=_FILE_:: + Specify the output file to be written to + +*-p, --pid*=_PID_:: + Specify the PID of a process to analyze + +== See also + +checkpointctl(1) \ No newline at end of file diff --git a/docs/checkpointctl-show.adoc b/docs/checkpointctl-show.adoc new file mode 100644 index 00000000..9193b07c --- /dev/null +++ b/docs/checkpointctl-show.adoc @@ -0,0 +1,19 @@ += checkpointctl-show(1) +include::footer.adoc[] + +== Name + +*checkpointctl-show* - show an overview of container checkpoints + +== Synopsis + +*checkpointctl show* [_OPTION_]... _FILE_... + +== Options + +*-h*, *--help*:: + Show help for checkpointctl show + +== See also + +checkpointctl(1) diff --git a/docs/checkpointctl.adoc b/docs/checkpointctl.adoc new file mode 100644 index 00000000..aacd006d --- /dev/null +++ b/docs/checkpointctl.adoc @@ -0,0 +1,49 @@ += checkpointctl(1) +include::footer.adoc[] + +== Name + +checkpointctl - a tool for advanced analysis of container checkpoints + +== Synopsis + +*checkpointctl* _COMMAND_ [_OPTION_]... + +== Description + +*checkpointctl* is a tool for advanced analysis of container checkpoints +created by Podman, CRI-O, and Kubernetes. It allows users to get an overview +of the checkpoint metadata, inspect the run-time state of processes in the +container, and perform in-depth analysis of checkpoint memory. + +== Options + +*-h, --help*:: + Show help for checkpointctl + +*-v, --version*:: + Show version of checkpointctl + +== COMMANDS + +[cols="1,1"] +|=== +|Command |Description + +|checkpointctl-completion +|Generate shell completion scripts + +|checkpointctl-inspect(1) +|Display low-level information about a container checkpoint + +|checkpointctl-memparse(1) +|Analyze container checkpoint memory + +|checkpointctl-show(1) +|Show an overview of container checkpoints +|=== + + +== SEE ALSO + +checkpointctl-inspect(1), checkpointctl-memparse(1), checkpointctl-show(1) diff --git a/docs/custom.xsl b/docs/custom.xsl new file mode 100644 index 00000000..663717ed --- /dev/null +++ b/docs/custom.xsl @@ -0,0 +1,8 @@ + + + + 1 + 1 + 1 + + From 9836bb1c60be504733cd813ba44001401b913900 Mon Sep 17 00:00:00 2001 From: Radostin Stoyanov Date: Sun, 3 Sep 2023 13:15:25 +0100 Subject: [PATCH 2/2] ci: enable codespell Signed-off-by: Radostin Stoyanov --- .github/workflows/verify.yml | 16 ++++++++++------ memparse.go | 2 +- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml index 7fd0112f..1d697a35 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -6,12 +6,16 @@ jobs: lint: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 - - name: golangci-lint - uses: golangci/golangci-lint-action@v3 - with: - version: latest - only-new-issues: true + - uses: actions/checkout@v3 + - name: golangci-lint + uses: golangci/golangci-lint-action@v3 + with: + version: latest + only-new-issues: true + - name: codespell + uses: codespell-project/actions-codespell@v2 + with: + skip: vendor gomod: runs-on: ubuntu-latest diff --git a/memparse.go b/memparse.go index 2fce6e09..a23806e7 100644 --- a/memparse.go +++ b/memparse.go @@ -131,7 +131,7 @@ func printProcessMemoryPages(task task) error { var compact bool if outputFilePath != "" { - // Write to ouput to file if --output is specified + // Write output to file if --output is specified f, err := os.Create(outputFilePath) if err != nil { return err