threads / patch / 62013

patch, 6 partsunused parameters: the final countdown

Subject: [PATCH 0/6] unused parameters: the final countdown

## tl;dr

13 messages between Aug 28, 2024 and Aug 28, 2024. Diffs are folded; open one to read it.

replies: 12people: 4as markdown or json

Jeff King· Aug 28, 2024, 03:57 UTC · lore

After many long sets of patches fixing and annotating existing cases, this is the culminating series that actually turns on -Wunused-parameter in our DEVELOPER=1 builds.

When applied on 'master', everything should compile cleanly with the new warning. There are some new cases introduced in 'next', but I'll send separate patches to go on those individual topics.

The first two patches fix new spots that cropped up since the last round of fixes. Patches 3-5 address compat/ code. And then the interesting one is patch 6.

  [1/6]: gc: mark unused config parameter in virtual functions
  [2/6]: t-reftable-readwrite: mark unused parameter in callback function
  [3/6]: compat: disable -Wunused-parameter in 3rd-party code
  [4/6]: compat: disable -Wunused-parameter in win32/headless.c
  [5/6]: compat: mark unused parameters in win32/mingw functions
  [6/6]: config.mak.dev: enable -Wunused-parameter by default
 builtin/gc.c                        | 16 ++++++++--------
 compat/mingw.c                      | 15 ++++++++-------
 compat/mingw.h                      | 18 +++++++++---------
 compat/nedmalloc/nedmalloc.c        |  2 ++
 compat/regex/regcomp.c              |  2 ++
 compat/stub/procinfo.c              |  2 +-
 compat/win32/headless.c             |  2 ++
 compat/win32/pthread.c              |  2 +-
 compat/win32/pthread.h              |  4 ++--
 compat/win32/syslog.c               |  2 +-
 compat/win32mmap.c                  |  2 +-
 compat/winansi.c                    |  2 +-
 config.mak.dev                      |  1 -
 t/unit-tests/t-reftable-readwrite.c |  2 +-
 14 files changed, 39 insertions(+), 33 deletions(-)
-Peff
Jeff King· Aug 28, 2024, 03:57 UTC · re: Jeff King · lore

[PATCH 1/6] gc: mark unused config parameter in virtual functions

Commit d1ae15d68b (builtin/gc: refactor to read config into structure, 2024-08-16) added a new parameter to the maintenance_task virtual functions, but most of them don't need to look at it.

Signed-off-by: Jeff King <peff@peff.net>
---
 builtin/gc.c | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)
Show changes to builtin/gc.c +8 −8
diff --git a/builtin/gc.c b/builtin/gc.c
index 427faf1cfe..0e361253e3 100644
--- a/builtin/gc.c
+++ b/builtin/gc.c
@@ -967,7 +967,7 @@ static int dfs_on_ref(const char *refname UNUSED,
 	return result;
 }
 
-static int should_write_commit_graph(struct gc_config *cfg)
+static int should_write_commit_graph(struct gc_config *cfg UNUSED)
 {
 	int result;
 	struct cg_auto_data data;
@@ -1005,7 +1005,7 @@ static int run_write_commit_graph(struct maintenance_run_opts *opts)
 }
 
 static int maintenance_task_commit_graph(struct maintenance_run_opts *opts,
-					 struct gc_config *cfg)
+					 struct gc_config *cfg UNUSED)
 {
 	prepare_repo_settings(the_repository);
 	if (!the_repository->settings.core_commit_graph)
@@ -1040,7 +1040,7 @@ static int fetch_remote(struct remote *remote, void *cbdata)
 }
 
 static int maintenance_task_prefetch(struct maintenance_run_opts *opts,
-				     struct gc_config *cfg)
+				     struct gc_config *cfg UNUSED)
 {
 	if (for_each_remote(fetch_remote, opts)) {
 		error(_("failed to prefetch remotes"));
@@ -1051,7 +1051,7 @@ static int maintenance_task_prefetch(struct maintenance_run_opts *opts,
 }
 
 static int maintenance_task_gc(struct maintenance_run_opts *opts,
-			       struct gc_config *cfg)
+			       struct gc_config *cfg UNUSED)
 {
 	struct child_process child = CHILD_PROCESS_INIT;
 
@@ -1100,7 +1100,7 @@ static int loose_object_count(const struct object_id *oid UNUSED,
 	return 0;
 }
 
-static int loose_object_auto_condition(struct gc_config *cfg)
+static int loose_object_auto_condition(struct gc_config *cfg UNUSED)
 {
 	int count = 0;
 
@@ -1192,12 +1192,12 @@ static int pack_loose(struct maintenance_run_opts *opts)
 }
 
 static int maintenance_task_loose_objects(struct maintenance_run_opts *opts,
-					  struct gc_config *cfg)
+					  struct gc_config *cfg UNUSED)
 {
 	return prune_packed(opts) || pack_loose(opts);
 }
 
-static int incremental_repack_auto_condition(struct gc_config *cfg)
+static int incremental_repack_auto_condition(struct gc_config *cfg UNUSED)
 {
 	struct packed_git *p;
 	int incremental_repack_auto_limit = 10;
@@ -1317,7 +1317,7 @@ static int multi_pack_index_repack(struct maintenance_run_opts *opts)
 }
 
 static int maintenance_task_incremental_repack(struct maintenance_run_opts *opts,
-					       struct gc_config *cfg)
+					       struct gc_config *cfg UNUSED)
 {
 	prepare_repo_settings(the_repository);
 	if (!the_repository->settings.core_multi_pack_index) {
-- 
2.46.0.754.g24c813f009
Jeff King· Aug 28, 2024, 03:57 UTC · re: Jeff King · lore

[PATCH 2/6] t-reftable-readwrite: mark unused parameter in callback function

This spot was originally marked in in 4695c3f3a9 (reftable: mark unused parameters in virtual functions, 2024-08-17), but was copied in 5b539a5361 (t: move reftable/readwrite_test.c to the unit testing framework, 2024-08-13).

Signed-off-by: Jeff King <peff@peff.net>
---
 t/unit-tests/t-reftable-readwrite.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to t/unit-tests/t-reftable-readwrite.c +1 −1
diff --git a/t/unit-tests/t-reftable-readwrite.c b/t/unit-tests/t-reftable-readwrite.c
index 1eae36cc60..178296891c 100644
--- a/t/unit-tests/t-reftable-readwrite.c
+++ b/t/unit-tests/t-reftable-readwrite.c
@@ -26,7 +26,7 @@ static ssize_t strbuf_add_void(void *b, const void *data, size_t sz)
 	return sz;
 }
 
-static int noop_flush(void *arg)
+static int noop_flush(void *arg UNUSED)
 {
 	return 0;
 }
-- 
2.46.0.754.g24c813f009
Jeff King· Aug 28, 2024, 03:58 UTC · re: Jeff King · lore

[PATCH 3/6] compat: disable -Wunused-parameter in 3rd-party code

We carry some vendored 3rd-party code in compat/ that does not build cleanly with -Wunused-parameters. We could mark these with UNUSED, but there are two reasons not to:

  1. This is code imported from elsewhere, so we'd prefer to avoid
     modifying it in an invasive way that could create conflicts if we
     tried to pull in a new version.
  2. These files don't include git-compat-util.h at all, so we'd need to
     factor out (or repeat) our UNUSED macro.

In theory we could modify the build process to invoke the compiler with the extra warning disabled for these files, but there are tricky corner cases there (e.g., for NO_REGEX we cannot assume that the compiler understands -Wno-unused-parameter as an option, so we'd have to use our detect-compiler script).

Instead, let's rely on the gcc diagnostic #pragma. This is horribly unportable, of course, but it should do what we want. Compilers which don't understand this particular pragma should ignore it (per the standard), and compilers which do care about "-Wunused-parameter" will hopefully respect it, even if they are not gcc (e.g., clang does).

Signed-off-by: Jeff King <peff@peff.net>
---
 compat/nedmalloc/nedmalloc.c | 2 ++
 compat/regex/regcomp.c       | 2 ++
 2 files changed, 4 insertions(+)
Show changes to 2 files +4 −0

compat/nedmalloc/nedmalloc.c, compat/regex/regcomp.c

diff --git a/compat/nedmalloc/nedmalloc.c b/compat/nedmalloc/nedmalloc.c
index 2c0ace7075..145255da43 100644
--- a/compat/nedmalloc/nedmalloc.c
+++ b/compat/nedmalloc/nedmalloc.c
@@ -31,6 +31,8 @@ DEALINGS IN THE SOFTWARE.
 /*#pragma optimize("a", on)*/
 #endif
 
+#pragma GCC diagnostic ignored "-Wunused-parameter"
+
 /*#define FULLSANITYCHECKS*/
 
 #include "nedmalloc.h"
diff --git a/compat/regex/regcomp.c b/compat/regex/regcomp.c
index 6c5d455e92..8d93a9b93f 100644
--- a/compat/regex/regcomp.c
+++ b/compat/regex/regcomp.c
@@ -17,6 +17,8 @@
    License along with the GNU C Library; if not, see
    <http://www.gnu.org/licenses/>.  */
 
+#pragma GCC diagnostic ignored "-Wunused-parameter"
+
 #if defined __TANDEM
  /* This is currently duplicated from git-compat-utils.h */
 # ifdef NO_INTPTR_T
-- 
2.46.0.754.g24c813f009
Jeff King· Aug 28, 2024, 03:59 UTC · re: Jeff King · lore

[PATCH 4/6] compat: disable -Wunused-parameter in win32/headless.c

As with the files touched in the previous commit, win32/headless.c does not include git-compat-util.h, so it doesn't have our UNUSED macro. Unlike those ones, this is not third-party code, so it would not be a big deal to modify it.

However, I'm not sure if including git-compat-util.h would create other headaches (and I don't even have a machine to test this on; I'm relying on Windows CI to compile it at all). Given how trivial the file is, and that the unused parameters are not interesting (they are just boilerplate for the wWinMain() function), we can just use the same trick as the previous commit and disable the warnings via pragma.

Signed-off-by: Jeff King <peff@peff.net>
---
 compat/win32/headless.c | 2 ++
 1 file changed, 2 insertions(+)
Show changes to compat/win32/headless.c +2 −0
diff --git a/compat/win32/headless.c b/compat/win32/headless.c
index 8b00dfe3bd..11392a0b9a 100644
--- a/compat/win32/headless.c
+++ b/compat/win32/headless.c
@@ -11,6 +11,8 @@
 #include <stdlib.h>
 #include <wchar.h>
 
+#pragma GCC diagnostic ignored "-Wunused-parameter"
+
 /*
  * If `dir` contains the path to a Git exec directory, extend `PATH` to
  * include the corresponding `bin/` directory (which is where all those
-- 
2.46.0.754.g24c813f009
Jeff King· Aug 28, 2024, 04:00 UTC · re: Jeff King · lore

[PATCH 5/6] compat: mark unused parameters in win32/mingw functions

The compat/ directory contains many stub functions, wrappers, and so on that have to conform to a specific interface, but don't necessarily need to use all of their parameters. Let's mark them to avoid complaints from -Wunused-parameter.

This was done mostly via guess-and-check with the Windows build in GitHub CI. I also confirmed that the win+VS build is similarly happy.

Signed-off-by: Jeff King <peff@peff.net>
---
 compat/mingw.c         | 15 ++++++++-------
 compat/mingw.h         | 18 +++++++++---------
 compat/stub/procinfo.c |  2 +-
 compat/win32/pthread.c |  2 +-
 compat/win32/pthread.h |  4 ++--
 compat/win32/syslog.c  |  2 +-
 compat/win32mmap.c     |  2 +-
 compat/winansi.c       |  2 +-
 8 files changed, 24 insertions(+), 23 deletions(-)
Show changes to 8 files +24 −23

compat/mingw.c, compat/mingw.h, compat/stub/procinfo.c, compat/win32/pthread.c, compat/win32/pthread.h, compat/win32/syslog.c, compat/win32mmap.c, compat/winansi.c

diff --git a/compat/mingw.c b/compat/mingw.c
index 29d3f09768..eb13c02a76 100644
--- a/compat/mingw.c
+++ b/compat/mingw.c
@@ -243,7 +243,8 @@ static enum hide_dotfiles_type hide_dotfiles = HIDE_DOTFILES_DOTGITONLY;
 static char *unset_environment_variables;
 
 int mingw_core_config(const char *var, const char *value,
-		      const struct config_context *ctx, void *cb)
+		      const struct config_context *ctx UNUSED,
+		      void *cb UNUSED)
 {
 	if (!strcmp(var, "core.hidedotfiles")) {
 		if (value && !strcasecmp(value, "dotgitonly"))
@@ -453,7 +454,7 @@ static int set_hidden_flag(const wchar_t *path, int set)
 	return -1;
 }
 
-int mingw_mkdir(const char *path, int mode)
+int mingw_mkdir(const char *path, int mode UNUSED)
 {
 	int ret;
 	wchar_t wpath[MAX_PATH];
@@ -597,7 +598,7 @@ int mingw_open (const char *filename, int oflags, ...)
 	return fd;
 }
 
-static BOOL WINAPI ctrl_ignore(DWORD type)
+static BOOL WINAPI ctrl_ignore(DWORD type UNUSED)
 {
 	return TRUE;
 }
@@ -1085,7 +1086,7 @@ int mkstemp(char *template)
 	return git_mkstemp_mode(template, 0600);
 }
 
-int gettimeofday(struct timeval *tv, void *tz)
+int gettimeofday(struct timeval *tv, void *tz UNUSED)
 {
 	FILETIME ft;
 	long long hnsec;
@@ -2252,7 +2253,7 @@ char *mingw_query_user_email(void)
 	return get_extended_user_info(NameUserPrincipal);
 }
 
-struct passwd *getpwuid(int uid)
+struct passwd *getpwuid(int uid UNUSED)
 {
 	static unsigned initialized;
 	static char user_name[100];
@@ -2304,7 +2305,7 @@ static sig_handler_t timer_fn = SIG_DFL, sigint_fn = SIG_DFL;
  * length to call the signal handler.
  */
 
-static unsigned __stdcall ticktack(void *dummy)
+static unsigned __stdcall ticktack(void *dummy UNUSED)
 {
 	while (WaitForSingleObject(timer_event, timer_interval) == WAIT_TIMEOUT) {
 		mingw_raise(SIGALRM);
@@ -2352,7 +2353,7 @@ static inline int is_timeval_eq(const struct timeval *i1, const struct timeval *
 	return i1->tv_sec == i2->tv_sec && i1->tv_usec == i2->tv_usec;
 }
 
-int setitimer(int type, struct itimerval *in, struct itimerval *out)
+int setitimer(int type UNUSED, struct itimerval *in, struct itimerval *out)
 {
 	static const struct timeval zero;
 	static int atexit_done;
diff --git a/compat/mingw.h b/compat/mingw.h
index 27b61284f4..ebfb8ba423 100644
--- a/compat/mingw.h
+++ b/compat/mingw.h
@@ -122,27 +122,27 @@ struct utsname {
  * trivial stubs
  */
 
-static inline int readlink(const char *path, char *buf, size_t bufsiz)
+static inline int readlink(const char *path UNUSED, char *buf UNUSED, size_t bufsiz UNUSED)
 { errno = ENOSYS; return -1; }
-static inline int symlink(const char *oldpath, const char *newpath)
+static inline int symlink(const char *oldpath UNUSED, const char *newpath UNUSED)
 { errno = ENOSYS; return -1; }
-static inline int fchmod(int fildes, mode_t mode)
+static inline int fchmod(int fildes UNUSED, mode_t mode UNUSED)
 { errno = ENOSYS; return -1; }
 #ifndef __MINGW64_VERSION_MAJOR
 static inline pid_t fork(void)
 { errno = ENOSYS; return -1; }
 #endif
-static inline unsigned int alarm(unsigned int seconds)
+static inline unsigned int alarm(unsigned int seconds UNUSED)
 { return 0; }
 static inline int fsync(int fd)
 { return _commit(fd); }
 static inline void sync(void)
 {}
 static inline uid_t getuid(void)
 { return 1; }
-static inline struct passwd *getpwnam(const char *name)
+static inline struct passwd *getpwnam(const char *name UNUSED)
 { return NULL; }
-static inline int fcntl(int fd, int cmd, ...)
+static inline int fcntl(int fd UNUSED, int cmd, ...)
 {
 	if (cmd == F_GETFD || cmd == F_SETFD)
 		return 0;
@@ -151,17 +151,17 @@ static inline int fcntl(int fd, int cmd, ...)
 }
 
 #define sigemptyset(x) (void)0
-static inline int sigaddset(sigset_t *set, int signum)
+static inline int sigaddset(sigset_t *set UNUSED, int signum UNUSED)
 { return 0; }
 #define SIG_BLOCK 0
 #define SIG_UNBLOCK 0
-static inline int sigprocmask(int how, const sigset_t *set, sigset_t *oldset)
+static inline int sigprocmask(int how UNUSED, const sigset_t *set UNUSED, sigset_t *oldset UNUSED)
 { return 0; }
 static inline pid_t getppid(void)
 { return 1; }
 static inline pid_t getpgid(pid_t pid)
 { return pid == 0 ? getpid() : pid; }
-static inline pid_t tcgetpgrp(int fd)
+static inline pid_t tcgetpgrp(int fd UNUSED)
 { return getpid(); }
 
 /*
diff --git a/compat/stub/procinfo.c b/compat/stub/procinfo.c
index 12c0a23c9e..3168cd5714 100644
--- a/compat/stub/procinfo.c
+++ b/compat/stub/procinfo.c
@@ -6,6 +6,6 @@
  * Stub. See sample implementations in compat/linux/procinfo.c and
  * compat/win32/trace2_win32_process_info.c.
  */
-void trace2_collect_process_info(enum trace2_process_info_reason reason)
+void trace2_collect_process_info(enum trace2_process_info_reason reason UNUSED)
 {
 }
diff --git a/compat/win32/pthread.c b/compat/win32/pthread.c
index 85f8f7920c..58980a529c 100644
--- a/compat/win32/pthread.c
+++ b/compat/win32/pthread.c
@@ -21,7 +21,7 @@ static unsigned __stdcall win32_start_routine(void *arg)
 	return 0;
 }
 
-int pthread_create(pthread_t *thread, const void *unused,
+int pthread_create(pthread_t *thread, const void *attr UNUSED,
 		   void *(*start_routine)(void *), void *arg)
 {
 	thread->arg = arg;
diff --git a/compat/win32/pthread.h b/compat/win32/pthread.h
index cc3221cb2c..e2b5c4f64c 100644
--- a/compat/win32/pthread.h
+++ b/compat/win32/pthread.h
@@ -18,7 +18,7 @@
  */
 #define pthread_mutex_t CRITICAL_SECTION
 
-static inline int return_0(int i) {
+static inline int return_0(int i UNUSED) {
 	return 0;
 }
 #define pthread_mutex_init(a,b) return_0((InitializeCriticalSection((a)), 0))
@@ -70,7 +70,7 @@ static inline void NORETURN pthread_exit(void *ret)
 }
 
 typedef DWORD pthread_key_t;
-static inline int pthread_key_create(pthread_key_t *keyp, void (*destructor)(void *value))
+static inline int pthread_key_create(pthread_key_t *keyp, void (*destructor)(void *value) UNUSED)
 {
 	return (*keyp = TlsAlloc()) == TLS_OUT_OF_INDEXES ? EAGAIN : 0;
 }
diff --git a/compat/win32/syslog.c b/compat/win32/syslog.c
index 0af18d8882..4e4794743a 100644
--- a/compat/win32/syslog.c
+++ b/compat/win32/syslog.c
@@ -2,7 +2,7 @@
 
 static HANDLE ms_eventlog;
 
-void openlog(const char *ident, int logopt, int facility)
+void openlog(const char *ident, int logopt UNUSED, int facility UNUSED)
 {
 	if (ms_eventlog)
 		return;
diff --git a/compat/win32mmap.c b/compat/win32mmap.c
index 519d51f2b6..a4ab4cb939 100644
--- a/compat/win32mmap.c
+++ b/compat/win32mmap.c
@@ -40,7 +40,7 @@ void *git_mmap(void *start, size_t length, int prot, int flags, int fd, off_t of
 	return MAP_FAILED;
 }
 
-int git_munmap(void *start, size_t length)
+int git_munmap(void *start, size_t length UNUSED)
 {
 	return !UnmapViewOfFile(start);
 }
diff --git a/compat/winansi.c b/compat/winansi.c
index 575813bde8..1b3f916b9f 100644
--- a/compat/winansi.c
+++ b/compat/winansi.c
@@ -340,7 +340,7 @@ enum {
 	TEXT = 0, ESCAPE = 033, BRACKET = '['
 };
 
-static DWORD WINAPI console_thread(LPVOID unused)
+static DWORD WINAPI console_thread(LPVOID data UNUSED)
 {
 	unsigned char buffer[BUFFER_SIZE];
 	DWORD bytes;
-- 
2.46.0.754.g24c813f009
Jeff King· Aug 28, 2024, 04:00 UTC · re: Jeff King · lore

[PATCH 6/6] config.mak.dev: enable -Wunused-parameter by default

Having now removed or annotated all of the unused function parameters in our code base, I found that each instance falls into one of three categories:

  1. ignoring the parameter is a bug (e.g., a function takes a ptr/len
     pair, but ignores the length). Detecting these helps us find the
     bugs.
  2. the parameter is unnecessary (and usually left over from a
     refactoring or earlier iteration of a patches series). Removing
     these cleans up the code.
  3. the function has to conform to a specific interface (because it's
     used via a function pointer, or matches something on the other side
     of an #ifdef). These ones are annoying, but annotating them with
     UNUSED is not too bad (especially if the compiler tells you about
     the problem promptly).

Certainly instances of (3) are more common than (1), but after finding all of these, I think there were enough cases of (1) that it justifies the work in annotating all of the (3)s.

And since the code base is now at a spot where we compile cleanly with -Wunused-parameter, turning it on will make it the responsibility of individual patch writers going forward.

Signed-off-by: Jeff King <peff@peff.net>
---
 config.mak.dev | 1 -
 1 file changed, 1 deletion(-)
Show changes to config.mak.dev +0 −1
diff --git a/config.mak.dev b/config.mak.dev
index 5229c35484..50026d1e0e 100644
--- a/config.mak.dev
+++ b/config.mak.dev
@@ -54,7 +54,6 @@ ifeq ($(filter extra-all,$(DEVOPTS)),)
 DEVELOPER_CFLAGS += -Wno-empty-body
 DEVELOPER_CFLAGS += -Wno-missing-field-initializers
 DEVELOPER_CFLAGS += -Wno-sign-compare
-DEVELOPER_CFLAGS += -Wno-unused-parameter
 endif
 endif
 
-- 
2.46.0.754.g24c813f009
Eric Sunshine· Aug 28, 2024, 05:56 UTC · re: Jeff King · lore

Re: [PATCH 6/6] config.mak.dev: enable -Wunused-parameter by default

On Wed, Aug 28, 2024 at 12:01 AM Jeff King <peff@peff.net> wrote:
Show 28 quoted lines
> Having now removed or annotated all of the unused function parameters in
> our code base, I found that each instance falls into one of three
> categories:
>
>   1. ignoring the parameter is a bug (e.g., a function takes a ptr/len
>      pair, but ignores the length). Detecting these helps us find the
>      bugs.
>
>   2. the parameter is unnecessary (and usually left over from a
>      refactoring or earlier iteration of a patches series). Removing
>      these cleans up the code.
>
>   3. the function has to conform to a specific interface (because it's
>      used via a function pointer, or matches something on the other side
>      of an #ifdef). These ones are annoying, but annotating them with
>      UNUSED is not too bad (especially if the compiler tells you about
>      the problem promptly).
> [...]
> And since the code base is now at a spot where we compile cleanly with
> -Wunused-parameter, turning it on will make it the responsibility of
> individual patch writers going forward.
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> diff --git a/config.mak.dev b/config.mak.dev
> @@ -54,7 +54,6 @@ ifeq ($(filter extra-all,$(DEVOPTS)),)
>  DEVELOPER_CFLAGS += -Wno-sign-compare
> -DEVELOPER_CFLAGS += -Wno-unused-parameter

What is the expectation regarding newcomers to the project or even people who have not been following this topic and its cousins? Documentation/CodingGuidelines recommends enabling DEVELOPER mode, which is good, but this change means that such people may now be hit with a compiler complaint which they don't necessarily know how to deal with in the legitimate case #3 (described above). Should CodingGuidelines be updated to mention "UNUSED" and the circumstances under which it should be used?

Patrick Steinhardt· Aug 28, 2024, 08:21 UTC · re: Eric Sunshine · lore

Re: [PATCH 6/6] config.mak.dev: enable -Wunused-parameter by default

On Wed, Aug 28, 2024 at 01:56:13AM -0400, Eric Sunshine wrote:
Show 38 quoted lines
> On Wed, Aug 28, 2024 at 12:01 AM Jeff King <peff@peff.net> wrote:
> > Having now removed or annotated all of the unused function parameters in
> > our code base, I found that each instance falls into one of three
> > categories:
> >
> >   1. ignoring the parameter is a bug (e.g., a function takes a ptr/len
> >      pair, but ignores the length). Detecting these helps us find the
> >      bugs.
> >
> >   2. the parameter is unnecessary (and usually left over from a
> >      refactoring or earlier iteration of a patches series). Removing
> >      these cleans up the code.
> >
> >   3. the function has to conform to a specific interface (because it's
> >      used via a function pointer, or matches something on the other side
> >      of an #ifdef). These ones are annoying, but annotating them with
> >      UNUSED is not too bad (especially if the compiler tells you about
> >      the problem promptly).
> > [...]
> > And since the code base is now at a spot where we compile cleanly with
> > -Wunused-parameter, turning it on will make it the responsibility of
> > individual patch writers going forward.
> >
> > Signed-off-by: Jeff King <peff@peff.net>
> > ---
> > diff --git a/config.mak.dev b/config.mak.dev
> > @@ -54,7 +54,6 @@ ifeq ($(filter extra-all,$(DEVOPTS)),)
> >  DEVELOPER_CFLAGS += -Wno-sign-compare
> > -DEVELOPER_CFLAGS += -Wno-unused-parameter
> 
> What is the expectation regarding newcomers to the project or even
> people who have not been following this topic and its cousins?
> Documentation/CodingGuidelines recommends enabling DEVELOPER mode,
> which is good, but this change means that such people may now be hit
> with a compiler complaint which they don't necessarily know how to
> deal with in the legitimate case #3 (described above). Should
> CodingGuidelines be updated to mention "UNUSED" and the circumstances
> under which it should be used?

Updating our coding guidelines would certainly be welcome. Other than that this series looks good to me and is a step into the right direction in my opinion. Thanks!

Patrick
Jeff King· Aug 28, 2024, 14:48 UTC · re: Eric Sunshine · lore

[PATCH 7/6] CodingGuidelines: mention -Wunused-parameter and UNUSED

On Wed, Aug 28, 2024 at 01:56:13AM -0400, Eric Sunshine wrote:
Show 12 quoted lines
> > And since the code base is now at a spot where we compile cleanly with
> > -Wunused-parameter, turning it on will make it the responsibility of
> > individual patch writers going forward.
> [...]
> What is the expectation regarding newcomers to the project or even
> people who have not been following this topic and its cousins?
> Documentation/CodingGuidelines recommends enabling DEVELOPER mode,
> which is good, but this change means that such people may now be hit
> with a compiler complaint which they don't necessarily know how to
> deal with in the legitimate case #3 (described above). Should
> CodingGuidelines be updated to mention "UNUSED" and the circumstances
> under which it should be used?

Yeah, I agree some guidance is in order. How about this on top? I didn't go into the decision tree of when you should remove the parameter versus using it versus annotating it. I think in general that the first two are pretty obvious when they are appropriate, and we just need to focus on the annotating option.

-- >8 --
Subject: [PATCH] CodingGuidelines: mention -Wunused-parameter and UNUSED

Now that -Wunused-parameter is on by default for DEVELOPER=1 builds, people may trigger it, blocking their build. When it's a mistake for the parameter to exist, the path forward is obvious: remove it. But sometimes you need to suppress the warning, and the "UNUSED" mechanism for that is specific to our project, so people may not know about it.

Let's put some advice in CodingGuidelines, including an example warning message. That should help people who grep for the warning text after seeing it from the compiler.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/CodingGuidelines | 7 +++++++
 1 file changed, 7 insertions(+)
Show changes to Documentation/CodingGuidelines +7 −0
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index ccaea39752..d0fc7cfe60 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -258,6 +258,13 @@ For C programs:
    ensure your patch is clear of all compiler warnings we care about,
    by e.g. "echo DEVELOPER=1 >>config.mak".
 
+ - When using DEVELOPER=1 mode, you may see warnings from the compiler
+   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".
+
  - 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
    "__STDC_VERSION__"). You should not use features from a newer C
-- 
2.46.0.754.g24c813f009
Eric Sunshine· Aug 28, 2024, 19:53 UTC · re: Jeff King · lore

Re: [PATCH 7/6] CodingGuidelines: mention -Wunused-parameter and UNUSED

On Wed, Aug 28, 2024 at 10:48 AM Jeff King <peff@peff.net> wrote:
Show 28 quoted lines
> On Wed, Aug 28, 2024 at 01:56:13AM -0400, Eric Sunshine wrote:
> > What is the expectation regarding newcomers to the project or even
> > people who have not been following this topic and its cousins?
> > Documentation/CodingGuidelines recommends enabling DEVELOPER mode,
> > which is good, but this change means that such people may now be hit
> > with a compiler complaint which they don't necessarily know how to
> > deal with in the legitimate case #3 (described above). Should
> > CodingGuidelines be updated to mention "UNUSED" and the circumstances
> > under which it should be used?
>
> Yeah, I agree some guidance is in order. How about this on top? I didn't
> go into the decision tree of when you should remove the parameter versus
> using it versus annotating it. I think in general that the first two are
> pretty obvious when they are appropriate, and we just need to focus on
> the annotating option.
>
> -- >8 --
> Subject: [PATCH] CodingGuidelines: mention -Wunused-parameter and UNUSED
>
> Now that -Wunused-parameter is on by default for DEVELOPER=1 builds,
> people may trigger it, blocking their build. When it's a mistake for the
> parameter to exist, the path forward is obvious: remove it. But
> sometimes you need to suppress the warning, and the "UNUSED" mechanism
> for that is specific to our project, so people may not know about it.
>
> Let's put some advice in CodingGuidelines, including an example warning
> message. That should help people who grep for the warning text after
> seeing it from the compiler.
Makes sense.
Show 10 quoted lines
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> @@ -258,6 +258,13 @@ For C programs:
> + - When using DEVELOPER=1 mode, you may see warnings from the compiler
> +   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".

Perfect. This fully addresses the question expressed by my review comment. Thank you.

Junio C Hamano· Aug 28, 2024, 15:17 UTC · re: Eric Sunshine · lore

Re: [PATCH 6/6] config.mak.dev: enable -Wunused-parameter by default

Eric Sunshine <sunshine@sunshineco.com> writes:
Show 25 quoted lines
>>   3. the function has to conform to a specific interface (because it's
>>      used via a function pointer, or matches something on the other side
>>      of an #ifdef). These ones are annoying, but annotating them with
>>      UNUSED is not too bad (especially if the compiler tells you about
>>      the problem promptly).
>> [...]
>> And since the code base is now at a spot where we compile cleanly with
>> -Wunused-parameter, turning it on will make it the responsibility of
>> individual patch writers going forward.
>>
>> Signed-off-by: Jeff King <peff@peff.net>
>> ---
>> diff --git a/config.mak.dev b/config.mak.dev
>> @@ -54,7 +54,6 @@ ifeq ($(filter extra-all,$(DEVOPTS)),)
>>  DEVELOPER_CFLAGS += -Wno-sign-compare
>> -DEVELOPER_CFLAGS += -Wno-unused-parameter
>
> What is the expectation regarding newcomers to the project or even
> people who have not been following this topic and its cousins?
> Documentation/CodingGuidelines recommends enabling DEVELOPER mode,
> which is good, but this change means that such people may now be hit
> with a compiler complaint which they don't necessarily know how to
> deal with in the legitimate case #3 (described above). Should
> CodingGuidelines be updated to mention "UNUSED" and the circumstances
> under which it should be used?
I am not yet convinced 100%, but probably it is a good idea.

We have our idioms and conventions like use of UNLEAK(), UNUSED, __attribute__ to annotate varargs functions that take printf-like format, always using "{ 0 }" and no other form to zero-initialize an auto variable of an aggregate type, etc., that are unreasonable for somebody, who is new to the project but is fluent in and competent at C, to know all of them.

For things like UNLEAK() that require a bit more than general competence in the language, a bit more thought and peeking the implementation to understand how they work, we should document them to make it easier to learn for new people.

Consistently using "{ 0 }", instead of picking a single random member and initialize the aggrevate with "{ .it = 0 }", is asking the writer to pick between two _valid_ C language constructs and always use one of them, so it may make sense to document it, even though the general "do what the existing code does" may be sufficient.

Unlike them, UNUSED smells a lot more obvious, and because the code base is full of API functions that take callback functions, we have plenty of existing uses of it for those who are competent but are unfamiliar to the code base to notice and pick up quickly.

So I have a feeling that relatively speaking it is less necessary to help new contributors with documenting UNUSED than other conventions we have.

I have no objection if somebody else does a thoughtful job to document these things evenly, but if we are going to document UNUSED, we should explicitly document that it is our policy to document each and every one of these conventions to help new contributors.

Thanks.
Jeff King· Aug 28, 2024, 04:12 UTC · re: Jeff King · lore

Re: [PATCH 0/6] unused parameters: the final countdown

On Tue, Aug 27, 2024 at 11:57:23PM -0400, Jeff King wrote:
> When applied on 'master', everything should compile cleanly with the new
> warning. There are some new cases introduced in 'next', but I'll send
> separate patches to go on those individual topics.
Those are at:
  https://lore.kernel.org/git/20240828040944.GA4005021@coredump.intra.peff.net/
and:
  https://lore.kernel.org/git/20240828040803.GA4004932@coredump.intra.peff.net/

I double-checked against what's in 'seen', and there's nothing new there. Of course I won't be surprised if something new pops up while this topic is cooking, but CI will start catching it in any branch where this is merged (and the solution is usually pretty obvious).

-Peff

← back to recent threads