csexec: introduce a simple man page

doc/CMakeLists.txt

@@ -15,15 +15,22 @@
 # You should have received a copy of the GNU General Public License
 # along with cswrap.  If not, see <http://www.gnu.org/licenses/>.
 
-# build and install the man page (if asciidoc is available)
-find_program(A2X a2x)
-if(A2X)
-    add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/cswrap.1
-        COMMAND a2x -f manpage ${CMAKE_CURRENT_SOURCE_DIR}/cswrap.adoc
+# add man page for ${tool}
+macro(add_man_page tool)
+    add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${tool}.1
+        COMMAND a2x -f manpage ${CMAKE_CURRENT_SOURCE_DIR}/${tool}.adoc
         -D ${CMAKE_CURRENT_BINARY_DIR}
-        DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/cswrap.adoc
-        COMMENT "Generating cswrap.1 man page...")
-    add_custom_target(doc ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/cswrap.1)
-    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/cswrap.1
+        DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${tool}.adoc
+        COMMENT "Generating ${tool}.1 man page...")
+    set(man_pages ${man_pages} ${CMAKE_CURRENT_BINARY_DIR}/${tool}.1)
+    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${tool}.1
         DESTINATION share/man/man1)
+endmacro()
+
+# build and install man pages (if asciidoc is available)
+find_program(A2X a2x)
+if(A2X)
+    add_man_page(csexec)
+    add_man_page(cswrap)
+    add_custom_target(doc ALL DEPENDS ${man_pages})
 endif()

doc/csexec.adoc

@@ -0,0 +1,77 @@
+csexec(1)
+=========
+:doctype: manpage
+
+NAME
+----
+csexec - dynamic linker wrapper
+
+
+SYNOPSIS
+--------
+*csexec* '--help' | '--print-ld-exec-cmd [argv0]'
+
+
+DESCRIPTION
+-----------
+csexec is a wrapper of the system dynamic linker which helps to run dynamic
+analyzers and formal verifiers on unmodified source RPM packages fully
+automatically.  The wrapper needs to be be enabled while linking binaries
+using *cswrap* and *csexec-loader*:
+
+-------------------------------------------------
+$ export PATH=$(cswrap --print-path-to-wrap):$PATH
+$ export CSWRAP_ADD_CFLAGS=-Wl,--dynamic-linker,/usr/bin/csexec-loader
+-------------------------------------------------
+
+The dynamic analysis tool can be specified at run-time with the
+*CSEXEC_WRAP_CMD* environment variable, as in the following example:
+
+-------------------------------------------------
+$ export CSEXEC_WRAP_CMD=$'valgrind\a--quiet\a--log-file=/dev/tty\a--leak-check=full'
+-------------------------------------------------
+
+Then the instrumented binaries will automatically launch the specified analyzer
+for themselves each time they are executed.
+
+OPTIONS
+-------
+*--help*::
+    Print basic usage information.
+
+*--print-ld-exec-cmd [argv0]*::
+    Print a command prefix that can be used to invoke dynamic linker explicitly.
+
+
+EXIT STATUS
+-----------
+Non-zero exit status is returned when csexec fails to execute the binary.
+Otherwise the analyzer (or the binary itself) determines the exit status.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+**CSEXEC_WRAP_CMD**::
+    If set to a non-empty string, csexec prepends the command to be executed
+    with the specified program (analyzer).  The program name can be optionally
+    followed by a list of custom arguments for the analyzer, each of them
+    separated by the *BEL* character.  If the value of *`${CSEXEC_WRAP_CMD}`*
+    starts with *--skip-ld-linux* followed by *BEL*, csexec does not explicitly
+    invoke the system dynamic linker.
+
+
+BUGS
+----
+Please report bugs and feature requests at https://github.com/kdudka/cswrap .
+
+
+AUTHOR
+------
+Written by Kamil Dudka.
+
+
+COPYING
+-------
+Copyright \(C) 2020-2021 Red Hat, Inc. Free use of this software is granted
+under the terms of the GNU General Public License (GPL).  See the COPYING file
+for details.

make-srpm.sh

@@ -166,6 +166,7 @@ done
 %{_bindir}/csexec
 %{_bindir}/csexec-loader
 %{_libdir}/libcsexec-preload.so
+%{_mandir}/man1/csexec.1*
 %doc COPYING
 %endif
 EOF