# HG changeset patch
# User ihse
# Date 1572344019 -3600
# Node ID ed9ef56bc7d53b412f5f26146443826979d4e9eb
# Parent  9a1676cf70786243ba48f89d373761e999e00fa3
Add documentation.

diff -r 9a1676cf7078 -r ed9ef56bc7d5 make/common/Execute.gmk
--- a/make/common/Execute.gmk	Fri Mar 01 13:49:52 2019 +0100
+++ b/make/common/Execute.gmk	Tue Oct 29 11:13:39 2019 +0100
@@ -40,15 +40,47 @@
 # Parameter 1 is the name of the rule. This name is used as variable prefix,
 # and the targets generated are listed in a variable by that name.
 #
+# You need to specify a COMMAND, the actual command line to execute. You are
+# strongly recommended to provide a INFO with the text to display for LOG=info
+# on what operation is performed. You can use DEPS to provide additional
+# dependencies for your command to run. You can optionally include a PRE_COMMAND
+# and a POST_COMMAND, intended for simple pre- and post-processing. The latter
+# might be e.g. a mv from a temporary file to the final destination, the former
+# e.g. a simple sed replacement on the input file. If the operations are
+# unrelated to the main COMMAND, this is not a suitable solution.
+#
+# If your command outputs a variety of files, or if it's really a single file
+# but you don't really care about the output from the perspective, you can just
+# supply an OUTPUT_DIR. You are supposed to make sure the command creates files
+# in this directory (which will be created for you if it does not exist), but
+# this can't be enforced by SetupExecute. Additional support files (like logs
+# and markers) are created in this directory. If you want support files in a
+# separate directory (e.g. if you're targeting an OUTPUT_DIR in the image
+# directly), you can specify a SUPPORT_DIR. If your command outputs only a
+# single file, you can get rid of the marker files (but not the log files) by
+# specifying OUTPUT_FILE. Note that if you specify an OUTPUT_FILE, support log
+# files will be placed in the same directory as the OUTPUT_FILE. If you do not
+# want that, use SUPPORT_DIR as well.
+#
+# After the call to SetupExecute, $1 will contain references to all generated
+# files (that make knows about), and $1_TARGET will contain a reference to the
+# final target (that is OUTPUT_FILE if it exists, or the $1_exec.marker file
+# otherwise).
+#
+# All the above keep functioning as expected even if PRE_COMMAND and
+# POST_COMMAND are given. One special case worth noting is that if OUTPUT_FILE
+# and POST_COMMAND is both given, the actual OUTPUT_FILE is considered to be a
+# result of running the POST_COMMAND.
+#
 # Remaining parameters are named arguments. These include:
 #   COMMAND     : The command to execute
-#   PRE_COMMAND :
-#   POST_COMMAND:
+#   PRE_COMMAND : A helper command to execute before COMMAND
+#   POST_COMMAND: A helper command to execute after COMMAND
 #   OUTPUT_DIR  : The directory that will contain the result from the command
-#   SUPPORT_DIR :
-#   OUTPUT_FILE : Use this if the command results in a single output file.
-#   INFO        : Message to display at LOG=info level when running command (optional).
-#   WARN        : Message to display at LOG=warn level when running command (optional).
+#   OUTPUT_FILE : Use this if the command results in a single output file
+#   SUPPORT_DIR : Where to store generated support files
+#   INFO        : Message to display at LOG=info level when running command (optional)
+#   WARN        : Message to display at LOG=warn level when running command (optional)
 #   DEPS        : Dependencies for the execution to take place
 #