HACKING

   1 Information for GNU Gnulib maintainers and contributors
   2 *******************************************************
   3
   4 Using git
   5 =========
   6
   7 * We don't use topic branches.  Changes are usually small enough that
   8   they can be committed directly to the master branch, after appropriate
   9   testing.
  10
  11 * We maintain stable branches, though, as described in the documentation:
  12   https://www.gnu.org/software/gnulib/manual/html_node/Stable-Branches.html
  13   When backporting a commit to a stable branch of the last year, be sure
  14   to update the copyright year of each modified file (since we don't run
  15   "make update-copyright" on the stable branches).
  16
  17 * We update the ChangeLog by hand.  The commit message is usually identical
  18   to the ChangeLog entry, with the date and author line removed, with
  19   the leading tabs removed, and with a blank line after the commit's
  20   summary line.
  21
  22 * When you commit a contributor's patch, please
  23   - add a reasonable ChangeLog entry in the usual style (meaningful
  24     summary line and detailed change list),
  25   - if the contribution is so small that it does not require a
  26     copyright assignment (cf.
  27     https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html )
  28     add a line:
  29     Copyright-paperwork-exempt: Yes
  30   - use the 'git commit' option --author="Contributor Name <email@address>"
  31
  32 License Notices
  33 ===============
  34
  35 In *.m4 files, use a notice like this:
  36   dnl Copyright (C) YEARS Free Software Foundation, Inc.
  37   dnl This file is free software; the Free Software Foundation
  38   dnl gives unlimited permission to copy and/or distribute it,
  39   dnl with or without modifications, as long as this notice is preserved.
  40
  41 In lib/, tests/, build-aux/ files, except those that are shared with glibc,
  42 use the license notices from etc/license-notices/ . This avoids gratuitous
  43 differences in wording, as well misunderstandings when a license notice
  44 would say "This program ...".
  45
  46 Test Suite
  47 ==========
  48
  49 When adding a module, add a unit test module as well.  This is our best
  50 chance to catch portability problems.
  51
  52 Warning Options
  53 ===============
  54
  55 For packages that use Gnulib, we recommend to use the 'warnings' or
  56 'manywarnings' module, as documented in
  57 https://www.gnu.org/software/gnulib/manual/html_node/warnings.html
  58 https://www.gnu.org/software/gnulib/manual/html_node/manywarnings.html
  59
  60 When building Gnulib testdirs, e.g. when preparing a Gnulib patch,
  61 there are three possible approaches:
  62
  63 * The simplest approach, which warns about the most common mistakes, is to
  64   use GCC's -Wall option, both for C and C++ compilation units. Just set
  65     $ ./configure CPPFLAGS="-Wall"
  66     $ make
  67   You should generally fix all compiler warnings that you see from this
  68   approach.
  69
  70 * If you are developing on a glibc system and have GCC version 13 binaries
  71   available, here's a recipe that will find more mistakes, but is nearly
  72   as easy to use. Here, different warning options are needed for C and
  73   for C++:
  74     $ WARN_GCC13=`echo '
  75       -fanalyzer
  76       -Wall
  77       -Warith-conversion
  78       -Wcast-align=strict
  79       -Wdate-time
  80       -Wdisabled-optimization
  81       -Wduplicated-cond
  82       -Wextra
  83       -Wformat-signedness
  84       -Winit-self
  85       -Winvalid-pch
  86       -Wlogical-op
  87       -Wmissing-include-dirs
  88       -Wopenmp-simd
  89       -Woverlength-strings
  90       -Wpacked
  91       -Wpointer-arith
  92       -Wstrict-overflow
  93       -Wsuggest-final-methods
  94       -Wsuggest-final-types
  95       -Wsync-nand
  96       -Wsystem-headers
  97       -Wtrampolines
  98       -Wuninitialized
  99       -Wunknown-pragmas
 100       -Wunsafe-loop-optimizations
 101       -Wvariadic-macros
 102       -Wvector-operation-performance
 103       -Wwrite-strings
 104       -Warray-bounds=2
 105       -Wattribute-alias=2
 106       -Wformat-overflow=2
 107       -Wformat-truncation=2
 108       -Wshift-overflow=2
 109       -Wunused-const-variable=2
 110       -Wvla-larger-than=4031
 111       -Wno-empty-body
 112       -Wno-analyzer-allocation-size
 113       -Wno-analyzer-fd-double-close
 114       -Wno-analyzer-double-fclose
 115       -Wno-analyzer-double-free
 116       -Wno-analyzer-fd-leak
 117       -Wno-analyzer-fd-use-after-close
 118       -Wno-analyzer-fd-use-without-check
 119       -Wno-analyzer-free-of-non-heap
 120       -Wno-analyzer-malloc-leak
 121       -Wno-analyzer-mismatching-deallocation
 122       -Wno-analyzer-null-argument
 123       -Wno-analyzer-null-dereference
 124       -Wno-analyzer-out-of-bounds
 125       -Wno-analyzer-possible-null-argument
 126       -Wno-analyzer-possible-null-dereference
 127       -Wno-analyzer-use-after-free
 128       -Wno-analyzer-use-of-pointer-in-stale-stack-frame
 129       -Wno-analyzer-use-of-uninitialized-value
 130       -Wno-analyzer-va-arg-type-mismatch
 131       -Wno-attribute-warning
 132       -Wno-cast-align
 133       -Wno-clobbered
 134       -Wno-dangling-pointer
 135       -Wno-format
 136       -Wno-implicit-fallthrough
 137       -Wno-maybe-uninitialized
 138       -Wno-missing-field-initializers
 139       -Wno-restrict
 140       -Wno-sign-compare
 141       -Wno-switch
 142       -Wno-type-limits
 143       -Wno-unused-parameter
 144     ' | tr -d '\n' | sed -e 's/  */ /g'`
 145     $ WARN_CFLAGS_GCC13="$WARN_GCC13 -Wnested-externs -Wshadow=local -Wno-discarded-qualifiers"
 146     $ WARN_CXXFLAGS_GCC13="$WARN_GCC13 -Wno-cpp"
 147     $ ./configure CFLAGS="-O2 -g $WARN_CFLAGS_GCC13" CXXFLAGS="-O2 -g $WARN_CXXFLAGS_GCC13"
 148     $ make
 149   You should generally fix all compiler warnings that you see from this
 150   approach, or report when this approach produced a pointless warning
 151   (so that we can fix the value of WARN_GCC13 above).
 152
 153 * If you are developing on a glibc system and have GCC version 13 binaries
 154   available: Here's a recipe that will find even more mistakes, but it
 155   requires that you are willing to filter out and ignore pointless warnings.
 156     $ WARN_GCC13=`echo '
 157       -fanalyzer
 158       -Wall
 159       -Warith-conversion
 160       -Wcast-align=strict
 161       -Wdate-time
 162       -Wdisabled-optimization
 163       -Wduplicated-cond
 164       -Wextra
 165       -Wformat-signedness
 166       -Winit-self
 167       -Winvalid-pch
 168       -Wlogical-op
 169       -Wmissing-include-dirs
 170       -Wnull-dereference
 171       -Wopenmp-simd
 172       -Woverlength-strings
 173       -Wpacked
 174       -Wpointer-arith
 175       -Wstrict-overflow
 176       -Wsuggest-attribute=format
 177       -Wsuggest-final-methods
 178       -Wsuggest-final-types
 179       -Wsync-nand
 180       -Wsystem-headers
 181       -Wtrampolines
 182       -Wuninitialized
 183       -Wunknown-pragmas
 184       -Wunsafe-loop-optimizations
 185       -Wvariadic-macros
 186       -Wvector-operation-performance
 187       -Wwrite-strings
 188       -Warray-bounds=2
 189       -Wattribute-alias=2
 190       -Wformat-overflow=2
 191       -Wformat=2
 192       -Wformat-truncation=2
 193       -Wimplicit-fallthrough=5
 194       -Wshift-overflow=2
 195       -Wunused-const-variable=2
 196       -Wvla-larger-than=4031
 197       -Wno-empty-body
 198       -Wno-analyzer-double-fclose
 199       -Wno-analyzer-double-free
 200       -Wno-analyzer-free-of-non-heap
 201       -Wno-analyzer-malloc-leak
 202       -Wno-analyzer-null-argument
 203       -Wno-analyzer-null-dereference
 204       -Wno-analyzer-use-after-free
 205       -Wno-attribute-warning
 206       -Wno-cast-align
 207       -Wno-clobbered
 208       -Wno-format-nonliteral
 209       -Wno-sign-compare
 210       -Wno-type-limits
 211       -Wno-unused-parameter
 212     ' | tr -d '\n' | sed -e 's/  */ /g'`
 213     $ WARN_CFLAGS_GCC13="$WARN_GCC13 -Wnested-externs -Wshadow=local"
 214     $ WARN_CXXFLAGS_GCC13="$WARN_GCC13 -Wno-cpp"
 215     $ ./configure CFLAGS="-O2 -g $WARN_CFLAGS_GCC13" CXXFLAGS="-O2 -g $WARN_CXXFLAGS_GCC13"
 216     $ make
 217   With this approach, use your own judgement whether to fix warnings
 218   arising from your new code or not.
 219   Do *not* submit patches to silence warnings from existing code:
 220     - For these warnings, often the cure will be worse than the disease.
 221     - Some of the warnings are false positives. Rather than silencing
 222       these warnings, we prefer to report them in the GCC bug tracker
 223       and wait until they are fixed in a future GCC release.
 224
 225 Similarly, for clang version 16 you can use the following recipe, that uses
 226 selected warning options from
 227 https://releases.llvm.org/16.0.0/tools/clang/docs/DiagnosticsReference.html :
 228   $ WARN_CLANG16=`echo '
 229     -Wall
 230     -Wanon-enum-enum-conversion
 231     -Warc-repeated-use-of-weak
 232     -Warray-bounds-pointer-arithmetic
 233     -Warray-parameter
 234     -Watomic-properties
 235     -Wbinary-literal
 236     -Wbit-int-extension
 237     -Wbitfield-enum-conversion
 238     -Wbitwise-op-parentheses
 239     -Wbool-operation
 240     -Wc++-compat
 241     -Wc2x-compat
 242     -Wc2x-extensions
 243     -Wc99-compat
 244     -Wc99-designator
 245     -Wc99-extensions
 246     -Wcalled-once-parameter
 247     -Wcast-function-type
 248     -Wchar-subscripts
 249     -Wcomment
 250     -Wcompletion-handler
 251     -Wcomplex-component-init
 252     -Wcompound-token-split
 253     -Wconsumed
 254     -Wconversion
 255     -Wcstring-format-directive
 256     -Wcuda-compat
 257     -Wdate-time
 258     -Wdelimited-escape-sequence-extension
 259     -Wdeprecated
 260     -Wdeprecated-dynamic-exception-spec
 261     -Wdeprecated-implementations
 262     -Wdeprecated-this-capture
 263     -Wdeprecated-writable-strings
 264     -Wdirect-ivar-access
 265     -Wdocumentation
 266     -Wdocumentation-deprecated-sync
 267     -Wdocumentation-html
 268     -Wdocumentation-pedantic
 269     -Wdocumentation-unknown-command
 270     -Wdollar-in-identifier-extension
 271     -Wduplicate-decl-specifier
 272     -Wduplicate-enum
 273     -Wduplicate-method-arg
 274     -Wduplicate-method-match
 275     -Wdynamic-exception-spec
 276     -Wembedded-directive
 277     -Wempty-init-stmt
 278     -Wempty-translation-unit
 279     -Wenum-compare-conditional
 280     -Wenum-conversion
 281     -Wenum-enum-conversion
 282     -Wenum-float-conversion
 283     -Wexit-time-destructors
 284     -Wexpansion-to-defined
 285     -Wexplicit-ownership-type
 286     -Wextra
 287     -Wextra-semi
 288     -Wfixed-enum-extension
 289     -Wflexible-array-extensions
 290     -Wfloat-overflow-conversion
 291     -Wfloat-zero-conversion
 292     -Wfor-loop-analysis
 293     -Wformat
 294     -Wformat-pedantic
 295     -Wformat-type-confusion
 296     -Wformat=2
 297     -Wfour-char-constants
 298     -Wframe-address
 299     -Wfuse-ld-path
 300     -Wfuture-attribute-extensions
 301     -Wgcc-compat
 302     -Wgnu
 303     -Wgnu-anonymous-struct
 304     -Wgnu-auto-type
 305     -Wgnu-case-range
 306     -Wgnu-complex-integer
 307     -Wgnu-compound-literal-initializer
 308     -Wgnu-conditional-omitted-operand
 309     -Wgnu-designator
 310     -Wgnu-empty-initializer
 311     -Wgnu-empty-struct
 312     -Wgnu-flexible-array-initializer
 313     -Wgnu-flexible-array-union-member
 314     -Wgnu-folding-constant
 315     -Wgnu-imaginary-constant
 316     -Wgnu-label-as-value
 317     -Wgnu-line-marker
 318     -Wgnu-null-pointer-arithmetic
 319     -Wgnu-offsetof-extensions
 320     -Wgnu-pointer-arith
 321     -Wgnu-redeclared-enum
 322     -Wgnu-statement-expression
 323     -Wgnu-statement-expression-from-macro-expansion
 324     -Wgnu-union-cast
 325     -Wgnu-zero-line-directive
 326     -Wgnu-zero-variadic-macro-arguments
 327     -Wheader-hygiene
 328     -Widiomatic-parentheses
 329     -Wignored-qualifiers
 330     -Wimplicit
 331     -Wimplicit-fallthrough
 332     -Wimplicit-fallthrough-per-function
 333     -Wimplicit-function-declaration
 334     -Wimplicit-int
 335     -Wimplicit-retain-self
 336     -Wimport-preprocessor-directive-pedantic
 337     -Wincomplete-module
 338     -Winconsistent-missing-destructor-override
 339     -Winfinite-recursion
 340     -Wint-in-bool-context
 341     -Winvalid-or-nonexistent-directory
 342     -Winvalid-utf8
 343     -Wkeyword-macro
 344     -Wlanguage-extension-token
 345     -Wlocal-type-template-args
 346     -Wlogical-op-parentheses
 347     -Wlong-long
 348     -Wloop-analysis
 349     -Wmain
 350     -Wmax-tokens
 351     -Wmethod-signatures
 352     -Wmicrosoft
 353     -Wmicrosoft-anon-tag
 354     -Wmicrosoft-charize
 355     -Wmicrosoft-comment-paste
 356     -Wmicrosoft-cpp-macro
 357     -Wmicrosoft-end-of-file
 358     -Wmicrosoft-enum-value
 359     -Wmicrosoft-exception-spec
 360     -Wmicrosoft-fixed-enum
 361     -Wmicrosoft-flexible-array
 362     -Wmicrosoft-redeclare-static
 363     -Wmisleading-indentation
 364     -Wmismatched-tags
 365     -Wmissing-braces
 366     -Wmissing-method-return-type
 367     -Wmost
 368     -Wmove
 369     -Wnested-anon-types
 370     -Wnewline-eof
 371     -Wnon-gcc
 372     -Wnon-modular-include-in-framework-module
 373     -Wnon-modular-include-in-module
 374     -Wnon-virtual-dtor
 375     -Wnonportable-system-include-path
 376     -Wnull-pointer-arithmetic
 377     -Wnull-pointer-subtraction
 378     -Wnullability-extension
 379     -Wnullable-to-nonnull-conversion
 380     -Wopenmp
 381     -Wover-aligned
 382     -Woverlength-strings
 383     -Woverloaded-virtual
 384     -Woverriding-method-mismatch
 385     -Wpacked
 386     -Wpacked-non-pod
 387     -Wparentheses
 388     -Wpedantic
 389     -Wpedantic-core-features
 390     -Wpessimizing-move
 391     -Wpointer-arith
 392     -Wpoison-system-directories
 393     -Wpragma-pack
 394     -Wpragma-pack-suspicious-include
 395     -Wpragmas
 396     -Wpre-c2x-compat
 397     -Wpre-openmp-51-compat
 398     -Wprofile-instr-missing
 399     -Wquoted-include-in-framework-header
 400     -Wrange-loop-analysis
 401     -Wrange-loop-bind-reference
 402     -Wrange-loop-construct
 403     -Wreceiver-forward-class
 404     -Wredundant-move
 405     -Wredundant-parens
 406     -Wreorder
 407     -Wreorder-ctor
 408     -Wreserved-user-defined-literal
 409     -Wretained-language-linkage
 410     -Wselector
 411     -Wselector-type-mismatch
 412     -Wself-assign
 413     -Wself-assign-overloaded
 414     -Wself-move
 415     -Wsemicolon-before-method-body
 416     -Wshadow-all
 417     -Wshadow-field
 418     -Wshadow-field-in-constructor
 419     -Wshadow-field-in-constructor-modified
 420     -Wshadow-uncaptured-local
 421     -Wshift-sign-overflow
 422     -Wsigned-enum-bitfield
 423     -Wsometimes-uninitialized
 424     -Wsource-uses-openmp
 425     -Wspir-compat
 426     -Wstatic-in-inline
 427     -Wstrict-potentially-direct-selector
 428     -Wstrict-selector-match
 429     -Wstring-concatenation
 430     -Wstring-conversion
 431     -Wsuggest-destructor-override
 432     -Wsuggest-override
 433     -Wsuper-class-method-mismatch
 434     -Wtautological-bitwise-compare
 435     -Wtautological-compare
 436     -Wtautological-constant-in-range-compare
 437     -Wtautological-overlap-compare
 438     -Wtautological-type-limit-compare
 439     -Wtautological-unsigned-char-zero-compare
 440     -Wtautological-unsigned-enum-zero-compare
 441     -Wtautological-unsigned-zero-compare
 442     -Wtautological-value-range-compare
 443     -Wthread-safety
 444     -Wthread-safety-analysis
 445     -Wthread-safety-attributes
 446     -Wthread-safety-beta
 447     -Wthread-safety-negative
 448     -Wthread-safety-precise
 449     -Wthread-safety-reference
 450     -Wthread-safety-verbose
 451     -Wtype-limits
 452     -Wunaligned-access
 453     -Wundeclared-selector
 454     -Wundef-prefix
 455     -Wundefined-func-template
 456     -Wundefined-internal-type
 457     -Wundefined-reinterpret-cast
 458     -Wunguarded-availability
 459     -Wuninitialized
 460     -Wuninitialized-const-reference
 461     -Wunknown-pragmas
 462     -Wunnamed-type-template-args
 463     -Wunneeded-internal-declaration
 464     -Wunneeded-member-function
 465     -Wunreachable-code-fallthrough
 466     -Wunreachable-code-loop-increment
 467     -Wunsupported-dll-base-class-template
 468     -Wunused
 469     -Wunused-but-set-parameter
 470     -Wunused-but-set-variable
 471     -Wunused-const-variable
 472     -Wunused-exception-parameter
 473     -Wunused-function
 474     -Wunused-label
 475     -Wunused-lambda-capture
 476     -Wunused-local-typedef
 477     -Wunused-member-function
 478     -Wunused-private-field
 479     -Wunused-property-ivar
 480     -Wunused-template
 481     -Wunused-variable
 482     -Wvariadic-macros
 483     -Wvector-conversion
 484     -Wweak-template-vtables
 485     -Wweak-vtables
 486     -Wzero-length-array
 487     -Wno-bitwise-instead-of-logical
 488     -Wno-c11-extensions
 489     -Wno-cast-function-type-strict
 490     -Wno-float-conversion
 491     -Wno-format-nonliteral
 492     -Wno-gnu-include-next
 493     -Wno-implicit-float-conversion
 494     -Wno-implicit-int-conversion
 495     -Wno-implicit-int-float-conversion
 496     -Wno-include-next-absolute-path
 497     -Wno-missing-field-initializers
 498     -Wno-reserved-macro-identifier
 499     -Wno-shadow
 500     -Wno-shorten-64-to-32
 501     -Wno-sign-compare
 502     -Wno-sign-conversion
 503     -Wno-strict-prototypes
 504     -Wno-switch
 505     -Wno-unused-parameter
 506     -Wno-tautological-constant-out-of-range-compare
 507     -Wno-tautological-type-limit-compare
 508     -Wno-tautological-unsigned-zero-compare
 509     -Wno-tautological-value-range-compare
 510     -Wno-unused-command-line-argument
 511     -Wno-user-defined-warnings
 512   ' | tr -d '\n' | sed -e 's/  */ /g'`
 513   $ ./configure CFLAGS="-O2 -g $WARN_CLANG16" CXXFLAGS="-O2 -g $WARN_CLANG16"
 514   $ make
 515 Again, use your own judgement to determine whether to fix or ignore a
 516 specific warning.