Jeff King <peff@xxxxxxxx> writes:
> On Wed, Aug 28, 2024 at 02:28:47PM -0700, Junio C Hamano wrote:
>
>> By the way, Peff, do we have MAYBE_UNUSED that can be used in a case
>> like this one? Platforms without symbolic links supported may well
>> define NO_SYMLINK_HEAD, which makes the incoming parameters unused.
>
> Yes, it would be fine to use MAYBE_UNUSED in a case like this.
It turns out that I was, without realizing it myself, making an
oblique reference to your patch 7/6 ;-)
Perhaps something along this line?
---- >8 ----
Subject: CodingGuidelines: also mention MAYBE_UNUSED
A function that uses a parameter in one build may lose all uses of
the parameter in another build, depending on the configuration. A
workaround for such a case, MAYBE_UNUSED, should also be mentioned
when we recommend the use of UNUSED to our developers.
Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx>
---
Documentation/CodingGuidelines | 5 +++--
git-compat-util.h | 21 +++++++++++++++++++++
2 files changed, 24 insertions(+), 2 deletions(-)
diff --git c/Documentation/CodingGuidelines w/Documentation/CodingGuidelines
index d0fc7cfe60..3263245b03 100644
--- c/Documentation/CodingGuidelines
+++ w/Documentation/CodingGuidelines
@@ -262,8 +262,9 @@ For C programs:
like "error: unused parameter 'foo' [-Werror=unused-parameter]",
which indicates that a function ignores its argument. If the unused
parameter can't be removed (e.g., because the function is used as a
- callback and has to match a certain interface), you can annotate the
- individual parameters with the UNUSED keyword, like "int foo UNUSED".
+ callback and has to match a certain interface), you can annotate
+ the individual parameters with the UNUSED (or MAYBE_UNUSED)
+ keyword, like "int foo UNUSED".
- We try to support a wide range of C compilers to compile Git with,
including old ones. As of Git v2.35.0 Git requires C99 (we check
diff --git c/git-compat-util.h w/git-compat-util.h
index 71b4d23f03..23307ce780 100644
--- c/git-compat-util.h
+++ w/git-compat-util.h
@@ -195,6 +195,17 @@ struct strbuf;
#define _NETBSD_SOURCE 1
#define _SGI_SOURCE 1
+/*
+ * UNUSED marks a function parameter that is always unused.
+ *
+ * A callback interface may dictate that a function accepts a
+ * parameter at that position, but the implementation of the function
+ * may not need to use the parameter. In such a case, mark the parameter
+ * with UNUSED.
+ *
+ * When a parameter may be used or unused, depending on conditional
+ * compilation, consider using MAYBE_UNUSED instead.
+ */
#if GIT_GNUC_PREREQ(4, 5)
#define UNUSED __attribute__((unused)) \
__attribute__((deprecated ("parameter declared as UNUSED")))
@@ -649,6 +660,16 @@ static inline int git_has_dir_sep(const char *path)
#define RESULT_MUST_BE_USED
#endif
+/*
+ * MAYBE_UNUSED marks a function parameter that may be unused, but
+ * whose use is not an error.
+ *
+ * Depending on a configuration, all uses of a function parameter may
+ * become #ifdef'ed away. Marking such a parameter with UNUSED would
+ * give a warning in a compilation where the parameter is indeed used,
+ * and not marking such a parameter would give a warning in a
+ * compilation where the parameter is unused.
+ */
#define MAYBE_UNUSED __attribute__((__unused__))
#include "compat/bswap.h"
