Simon Josefsson wrote:
> There are some checks that I struggle to understand the point of,
> and one that I simply disagree with (sc_prohibit_strcmp).
Likewise for me. [1]
> Having a link
> to discussion helps to determine how to deal with errors.
>
> What do you think about:
>
> 1) using a URL to the gnulib online manual instead? For most users,
> that allows easier lookup, and for people who are really offline,
> the URL contains sufficient detail to find the relevant in the
> manual, and
>
> 2) print the rationale link as part of the error message instead of a
> comment in the code
>
> ?
We can do this. But it needs your input. With your input, I can put each
sc's rationale into a separate doc subsection, group these subsections
through sections, then republish the doc, then find out about the URLs
and store them in maint.mk.
Please reply to this mail, with a rationale for the following. Don't
omit references to standards (ISO C 23, POSIX:2018, GNU Coding Style)
when relevant.
sc_avoid_if_before_free:
sc_cast_of_argument_to_free:
sc_cast_of_x_alloc_return_value:
sc_cast_of_alloca_return_value:
sc_space_tab:
# Don't use *scanf or the old ato* functions in "real" code.
# They provide no error checking mechanism.
# Instead, use strto* functions.
sc_prohibit_atoi_atof:
# Use STREQ rather than comparing strcmp == 0, or != 0.
sc_prohibit_strcmp:
# Really. You don't want to use this function.
# It may fail to NUL-terminate the destination,
# and always NUL-pads out to the specified length.
sc_prohibit_strncpy:
# Pass EXIT_*, not number, to usage, exit, and error (when exiting)
sc_prohibit_magic_number_exit:
# Check that we don't use $< in non-implicit Makefile rules.
sc_prohibit_gnu_make_extensions:
# Using EXIT_SUCCESS as the first argument to error is misleading,
# since when that parameter is 0, error does not exit. Use '0' instead.
sc_error_exit_success:
# "FATAL:" should be fully upper-cased in error messages
# "WARNING:" should be fully upper-cased, or fully lower-cased
sc_error_message_warn_fatal:
# Error messages should not start with a capital letter
sc_error_message_uppercase:
# Error messages should not end with a period
sc_error_message_period:
sc_file_system:
# Don't use cpp tests of this symbol. All code assumes config.h is included.
sc_prohibit_have_config_h:
# Nearly all .c files must include <config.h>. However, we also permit this
# via inclusion of a package-specific header, if cfg.mk specified one.
# config_h_header must be suitable for grep -E.
# Rationale: The Gnulib documentation, node 'Include <config.h>'.
sc_require_config_h:
# You must include <config.h> before including any other header file.
# This can possibly be via a package-specific header, if given by cfg.mk.
# Rationale: The Gnulib documentation, node 'Include <config.h>'.
sc_require_config_h_first:
# Suggest using '#include <header.h>' instead of '#include "header.h"' for
# headers that override system headers.
# Rationale: The Gnulib documentation, node 'Style of #include statements'.
sc_prefer_angle_bracket_headers:
sc_prohibit_HAVE_MBRTOWC:
# Prohibit the inclusion of assert.h without an actual use of assert.
sc_prohibit_assert_without_use:
# Prohibit the inclusion of close-stream.h without an actual use.
sc_prohibit_close_stream_without_use:
# Prohibit the inclusion of getopt.h without an actual use.
sc_prohibit_getopt_without_use:
# Don't include quotearg.h unless you use one of its functions.
sc_prohibit_quotearg_without_use:
# Don't include quote.h unless you use one of its functions.
sc_prohibit_quote_without_use:
# Don't include this header unless you use one of its functions.
sc_prohibit_long_options_without_use:
# Don't include this header unless you use one of its functions.
sc_prohibit_inttostr_without_use:
# Don't include this header unless you use one of its functions.
sc_prohibit_ignore_value_without_use:
# Don't include this header unless you use one of its functions.
sc_prohibit_error_without_use:
# Don't include xalloc.h unless you use one of its symbols.
sc_prohibit_xalloc_without_use:
sc_prohibit_hash_without_use:
sc_prohibit_cloexec_without_use:
sc_prohibit_posixver_without_use:
sc_prohibit_same_without_use:
sc_prohibit_hash_pjw_without_use:
sc_prohibit_safe_read_without_use:
sc_prohibit_argmatch_without_use:
sc_prohibit_canonicalize_without_use:
sc_prohibit_root_dev_ino_without_use:
sc_prohibit_openat_without_use:
# Prohibit the inclusion of c-ctype.h without an actual use.
sc_prohibit_c_ctype_without_use:
# Prohibit the inclusion of signal.h without an actual use.
sc_prohibit_signal_without_use:
# Don't include stdio--.h unless you use one of its functions.
sc_prohibit_stdio--_without_use:
# Don't include stdio-safer.h unless you use one of its functions.
sc_prohibit_stdio-safer_without_use:
# Prohibit the inclusion of strings.h without a sensible use.
# Using the likes of bcmp, bcopy, bzero, index or rindex is not sensible.
sc_prohibit_strings_without_use:
# Prohibit the inclusion of intprops.h without an actual use.
sc_prohibit_intprops_without_use:
# Prohibit the inclusion of stddef.h without an actual use.
sc_prohibit_stddef_without_use:
# Prohibit the inclusion of dirent.h without an actual use.
sc_prohibit_dirent_without_use:
# Prohibit the inclusion of verify.h without an actual use.
sc_prohibit_verify_without_use:
# Don't include xfreopen.h unless you use one of its functions.
sc_prohibit_xfreopen_without_use:
sc_obsolete_symbols:
# Each nonempty ChangeLog line must start with a year number, or a TAB.
sc_changelog:
# Ensure that each .c file containing a "main" function also
# calls bindtextdomain.
sc_bindtextdomain:
# Require that the final line of each test-lib.sh-using test be this one:
# Exit $fail
sc_require_test_exit_idiom:
sc_trailing_blank:
sc_two_space_separator_in_usage:
# Look for diagnostics that aren't marked for translation.
# This won't find any for which error's format string is on a separate line.
sc_unmarked_diagnostics:
# Avoid useless parentheses like those in this example:
# #if defined (SYMBOL) || defined (SYM2)
sc_useless_cpp_parens:
sc_prohibit_always_true_header_tests:
sc_prohibit_defined_have_decl_tests:
# Don't define macros that we already get from gnulib header files.
sc_prohibit_always-defined_macros:
# Prohibit checked in backup files.
sc_prohibit_backup_files:
# Require the latest GPL.
sc_GPL_version:
# Require the latest GFDL.
sc_GFDL_version:
# Don't use Texinfo's @acronym{}.
# https://lists.gnu.org/r/bug-gnulib/2010-03/msg00321.html
sc_texinfo_acronym:
sc_prohibit_cvs_keyword:
sc_prohibit_empty_lines_at_EOF:
# Make sure we don't use st_blocks. Use ST_NBLOCKS or STP_NBLOCKS instead.
# This is a bit of a kludge, since it prevents use of the string
# even in comments, but for now it does the job with no false positives.
sc_prohibit_stat_st_blocks:
# Make sure we don't define any S_IS* macros in src/*.c files.
# They're already defined via gnulib's sys/stat.h replacement.
sc_prohibit_S_IS_definition:
sc_prohibit_doubled_word:
# A regular expression matching undesirable combinations of words like
# "can not"; this matches them even when the two words appear on different
# lines, but not when there is an intervening delimiter like "#" or "*".
# Similarly undesirable, "See @xref{...}", since an @xref should start
# a sentence. Explicitly prohibit any prefix of "see" or "also".
# Also prohibit a prefix matching "\w+ +".
# @pxref gets the same see/also treatment and should be parenthesized;
# presume it must *not* start a sentence.
# POSIX spells it "timestamp" rather than "time\s+stamp", so we do, too.
sc_prohibit_undesirable_word_seq:
# Except for shell files and for loops, double semicolon is probably a mistake
sc_prohibit_double_semicolon:
# Using test's -a and -o operators is not portable.
# We prefer test over [, since the latter is spelled [[ in configure.ac.
sc_prohibit_test_minus_ao:
# Avoid a test bashism.
sc_prohibit_test_double_equal:
# Each program that uses proper_name_utf8 must link with one of the
# ICONV libraries. Otherwise, some ICONV library must appear in LDADD.
sc_proper_name_utf8_requires_ICONV:
# Warn about "c0nst struct Foo const foo[]",
# but not about "char const *const foo" or "#define const const".
sc_redundant_const:
sc_const_long_option:
# Ensure that we don't accidentally insert an entry into an old NEWS block.
sc_immutable_NEWS:
# Ensure that we use only the standard $(VAR) notation,
# not @...@ in Makefile.am, now that we can rely on automake
# to emit a definition for each substituted variable.
# However, there is still one case in which @VAR@ use is not just
# legitimate, but actually required: when augmenting an automake-defined
# variable with a prefix. For example, gettext uses this:
# MAKEINFO = env LANG= LC_MESSAGES= LC_ALL= LANGUAGE= @MAKEINFO@
# otherwise, makeinfo would put German or French (current locale)
# navigation hints in the otherwise-English documentation.
sc_makefile_at_at_check:
sc_makefile_TAB_only_indentation:
sc_m4_quote_check:
# Verify that all source files using _() (more specifically, files that
# match $(_gl_translatable_string_re)) are listed in po/POTFILES.in.
sc_po_check:
# Sometimes it is useful to change the PATH environment variable
# in Makefiles. When doing so, it's better not to use the Unix-centric
# path separator of ':', but rather the automake-provided '$(PATH_SEPARATOR)'.
sc_makefile_path_separator_check:
sc_makefile_DISTCHECK_CONFIGURE_FLAGS:
# Make sure that the copyright date in $(v_etc_file) is up to date.
# Do the same for the $(sample-test) and the main doc/.texi file.
sc_copyright_check:
# If tests/help-version exists and seems to be new enough, assume that its
# use of init.sh and path_prepend_ is correct, and ensure that every other
# use of init.sh is identical.
# This is useful because help-version cross-checks prog --version
# with $(VERSION), which verifies that its path_prepend_ invocation
# sets PATH correctly. This is an inexpensive way to ensure that
# the other init.sh-using tests also get it right.
sc_cross_check_PATH_usage_in_tests:
# In tests, use "compare expected actual", not the reverse.
sc_prohibit_reversed_compare_failure:
# #if HAVE_... will evaluate to false for any non numeric string.
# That would be flagged by using -Wundef, however gnulib currently
# tests many undefined macros, and so we can't enable that option.
# So at least preclude common boolean strings as macro values.
sc_Wundef_boolean:
# Even if you use pathmax.h to guarantee that PATH_MAX is defined, it might
# not be constant, or might overflow a stack. In general, use PATH_MAX as
# a limit, not an array or alloca size.
sc_prohibit_path_max_allocation:
sc_vulnerable_makefile_CVE-2009-4029:
sc_vulnerable_makefile_CVE-2012-3386:
sc_unportable_grep_q:
# The GNU Coding standards say that README should refer to both
# INSTALL and the file that contains the copying conditions. This
# shall be COPYING for GPL and COPYING.LESSER for LGPL.
sc_readme_link_install:
sc_readme_link_copying:
Bruno
[1] https://lists.gnu.org/archive/html/poke-devel/2024-02/msg00082.html
