Re: [PATCH] find-debuginfo.sh: Add --help, --version and man page.

["Dmitry V. Levin" <ldv@altlinux.org>]

On Fri, Apr 30, 2021 at 12:46:04AM +0200, Mark Wielaard wrote:
> Add a --version and --help option to find-debuginfo.sh and use that to
> generate a manual page.
[...]
> diff --git a/scripts/find-debuginfo.sh b/scripts/find-debuginfo.sh
> index 3d736e0..ebad647 100755
> --- a/scripts/find-debuginfo.sh
> +++ b/scripts/find-debuginfo.sh
> @@ -17,72 +17,83 @@
>  # You should have received a copy of the GNU General Public License
>  # along with this program; if not, see <http://www.gnu.org/licenses/>
>  
> -# Usage: find-debuginfo.sh [--strict-build-id] [-g] [-r] [-m] [-i] [-n]
> -#			   [--keep-section SECTION] [--remove-section SECTION]
> -#			   [--g-libs]
> -#	 		   [-j N] [--jobs N]
> -#	 		   [-o debugfiles.list]
> -#	 		   [-S debugsourcefiles.list]
> -#			   [--run-dwz] [--dwz-low-mem-die-limit N]
> -#			   [--dwz-max-die-limit N]
> -#			   [--dwz-single-file-mode]
> -#			   [--build-id-seed SEED]
> -#			   [--unique-debug-suffix SUFFIX]
> -#			   [--unique-debug-src-base BASE]
> -#			   [[-l filelist]... [-p 'pattern'] -o debuginfo.list]
> -#			   [builddir]
> -#
> -# The -g flag says to use strip -g instead of full strip on DSOs or EXEs.
> -# The --g-libs flag says to use strip -g instead of full strip ONLY on DSOs.
> -# Options -g and --g-libs are mutually exclusive.
> -# The -r flag says to use eu-strip --reloc-debug-sections.
> -# Use --keep-section SECTION or --remove-section SECTION to explicitly
> -# keep a (non-allocated) section in the main executable or explicitly
> -# remove it into the .debug file. SECTION is an extended wildcard pattern.
> -# Both options can be given more than once.
> -#
> -# The --strict-build-id flag says to exit with failure status if
> -# any ELF binary processed fails to contain a build-id note.
> -# The -m flag says to include a .gnu_debugdata section in the main binary.
> -# The -i flag says to include a .gdb_index section in the .debug file.
> -# The -n flag says to not recompute the build-id.
> -#
> -# The -j, --jobs N option will spawn N processes to do the debuginfo
> -# extraction in parallel.
> -#
> -# A single -o switch before any -l or -p switches simply renames
> -# the primary output file from debugfiles.list to something else.
> -# A -o switch that follows a -p switch or some -l switches produces
> -# an additional output file with the debuginfo for the files in
> -# the -l filelist file, or whose names match the -p pattern.
> -# The -p argument is an grep -E -style regexp matching the a file name,
> -# and must not use anchors (^ or $).
> -#
> -# The --run-dwz flag instructs find-debuginfo.sh to run the dwz utility
> -# if available, and --dwz-low-mem-die-limit and --dwz-max-die-limit
> -# provide detailed limits.  See dwz(1) -l and -L option for details.
> -# Use --dwz-single-file-mode to disable multi-file mode, see dwz(1) -m
> -# for more details.
> -
> -#
> -# If --build-id-seed SEED is given then debugedit is called to
> -# update the build-ids it finds adding the SEED as seed to recalculate
> -# the build-id hash.  This makes sure the build-ids in the ELF files
> -# are unique between versions and releases of the same package.
> -# (Use --build-id-seed "%{VERSION}-%{RELEASE}".)
> -#
> -# If --unique-debug-suffix SUFFIX is given then the debug files created
> -# for <FILE> will be named <FILE>-<SUFFIX>.debug.  This makes sure .debug
> -# are unique between package version, release and architecture.
> -# (Use --unique-debug-suffix "-%{VERSION}-%{RELEASE}.%{_arch}".)
> -#
> -# If --unique-debug-src-base BASE is given then the source directory
> -# will be called /usr/debug/src/<BASE>.  This makes sure the debug source
> -# directories are unique between package version, release and architecture.
> -# (Use --unique-debug-src-base "%{name}-%{VERSION}-%{RELEASE}.%{_arch}".)
> -#
> -# All file names in switches are relative to builddir (. if not given).
> -#
> +help()
> +{
> +  echo "Usage: find-debuginfo.sh [OPTION]... [builddir]"
> +  echo "automagically generates debug info and file lists"
> +  echo
> +  echo "Options:"
> +  echo "[--strict-build-id] [-g] [-r] [-m] [-i] [-n]"
> +  echo "[--keep-section SECTION] [--remove-section SECTION]"
> +  echo "[--g-libs]"
> +  echo "[-j N] [--jobs N]"
> +  echo "[-o debugfiles.list]"
> +  echo "[-S debugsourcefiles.list]"
> +  echo "[--run-dwz] [--dwz-low-mem-die-limit N]"
> +  echo "[--dwz-max-die-limit N]"
> +  echo "[--dwz-single-file-mode]"
> +  echo "[--build-id-seed SEED]"
> +  echo "[--unique-debug-suffix SUFFIX]"
> +  echo "[--unique-debug-src-base BASE]"
> +  echo "[[-l filelist]... [-p 'pattern'] -o debuginfo.list]"
> +  echo "[builddir]"
> +  echo
> +  echo "The -g flag says to use strip -g instead of full strip on DSOs or EXEs."
> +  echo "The --g-libs flag says to use strip -g instead of full strip ONLY on"
> +  echo "DSOs.  Options -g and --g-libs are mutually exclusive."
> +  echo
> +  echo "The -r flag says to use eu-strip --reloc-debug-sections."
> +  echo
> +  echo "Use --keep-section SECTION or --remove-section SECTION to explicitly"
> +  echo "keep a (non-allocated) section in the main executable or explicitly"
> +  echo "remove it into the .debug file. SECTION is an extended wildcard"
> +  echo "pattern.  Both options can be given more than once."
> +  echo
> +  echo "The --strict-build-id flag says to exit with failure status if"
> +  echo "any ELF binary processed fails to contain a build-id note."
> +  echo
> +  echo "The -m flag says to include a .gnu_debugdata section in the main"
> +  echo "binary."
> +  echo
> +  echo "The -i flag says to include a .gdb_index section in the .debug file."
> +  echo
> +  echo "The -n flag says to not recompute the build-id."
> +  echo
> +  echo "The -j, --jobs N option will spawn N processes to do the debuginfo"
> +  echo "extraction in parallel."
> +  echo
> +  echo "A single -o switch before any -l or -p switches simply renames"
> +  echo "the primary output file from debugfiles.list to something else."
> +  echo "A -o switch that follows a -p switch or some -l switches produces"
> +  echo "an additional output file with the debuginfo for the files in"
> +  echo "the -l filelist file, or whose names match the -p pattern."
> +  echo "The -p argument is an grep -E -style regexp matching the a file name,"
> +  echo "and must not use anchors (^ or $)."
> +  echo
> +  echo "The --run-dwz flag instructs find-debuginfo.sh to run the dwz utility"
> +  echo "if available, and --dwz-low-mem-die-limit and --dwz-max-die-limit"
> +  echo "provide detailed limits.  See dwz(1) -l and -L option for details."
> +  echo "Use --dwz-single-file-mode to disable multi-file mode, see dwz(1) -m"
> +  echo "for more details."
> +  echo
> +  echo "If --build-id-seed SEED is given then debugedit is called to"
> +  echo "update the build-ids it finds adding the SEED as seed to recalculate"
> +  echo "the build-id hash.  This makes sure the build-ids in the ELF files"
> +  echo "are unique between versions and releases of the same package."
> +  echo "(Use --build-id-seed \"%{VERSION}-%{RELEASE}\".)"
> +  echo
> +  echo "If --unique-debug-suffix SUFFIX is given then the debug files created"
> +  echo "for <FILE> will be named <FILE>-<SUFFIX>.debug.  This makes sure .debug"
> +  echo "are unique between package version, release and architecture."
> +  echo "(Use --unique-debug-suffix \"-%{VERSION}-%{RELEASE}.%{_arch}\".)"
> +  echo
> +  echo "If --unique-debug-src-base BASE is given then the source directory"
> +  echo "will be called /usr/debug/src/<BASE>.  This makes sure the debug source"
> +  echo "dirs are unique between package version, release and achitecture (Use"
> +  echo "--unique-debug-src-base \"%{name}-%{VERSION}-%{RELEASE}.%{_arch}\")"
> +  echo
> +  echo "All file names in switches are relative to builddir ('.' if not given)."
> +}

I suggest to use "cat" instead of multiple echoes, e.g.

  cat <<-'EOF'
	Usage: find-debuginfo.sh [OPTION]... [builddir]
	automagically generates debug info and file lists

	Options:
	[...]
	--unique-debug-src-base "%{name}-%{VERSION}-%{RELEASE}.%{_arch}")

	All file names in switches are relative to builddir ('.' if not given).
  EOF


-- 
ldv