From 8da9b083a127e019455485467ebf00901dca769a Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Mon, 28 May 2018 15:31:54 +0800 Subject: [PATCH] Document arguments in 'contrib/utilities/indent'. --- contrib/utilities/indent | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/contrib/utilities/indent b/contrib/utilities/indent index 20dcab3cb9..ab8b209058 100755 --- a/contrib/utilities/indent +++ b/contrib/utilities/indent @@ -64,6 +64,17 @@ fi # Collect all header and source files and process them in batches of 50 # files with up to 10 in parallel # +# The command line is a bit complicated, so let's discuss the more +# complicated arguments: +# - For 'find', -print0 makes sure that file names are separated by \0 +# characters, as opposed to the default \n. That's because, surprisingly, +# \n is a valid character in a file name, whereas \0 is not -- so it +# serves as a good candidate to separate individual file names. +# - For 'xargs', -0 does the opposite: it separates filenames that are +# delimited by \0 +# - -n 50 calls the following script with up to 50 file names at a time +# - -P 10 calls the following script up to 10 times in parallel +# find tests include source examples \ \( -name '*.cc' -o -name '*.h' -o -name '*.cu' -o -name '*.cuh' \) -print0 | xargs -0 -n 50 -P 10 clang-format -i @@ -119,5 +130,22 @@ format_inst() } export -f format_inst +# +# Now do the formatting. The arguments are as discussed above, plus the +# following: +# - '-n 1' implies that the following script is called for each file +# individually +# - '-I {}' tells 'xargs' to substitute '{}' in the following by the +# one file name we process at a time +# - 'bash -c' executes the command that follows. Here, this is +# 'format_inst "$@"' where 'format_inst' is the macro exported +# above, and '$@' expands to the list of arguments passed on the +# command line, starting at $1. Because we execute a command with +# -c, there is no $0 for this bash invokation, and if we just had +# {} following the argument of -c, then the first element of that +# list would be ignored. To avoid this, we need a dummy argument +# to take the role of $0 so that {} can be expanded into $1. We +# simply use '_' here, but any other string would do fine as well. +# find source -name '*.inst.in' -print0 | xargs -0 -n 1 -P 10 -I {} bash -c 'format_inst "$@"' _ {} -- 2.39.5