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 use a linear git history — no merges. To work in this setting, it's
  18   recommended that you configure git with 'git config pull.rebase = true'.
  19
  20 * Before pushing a commit, it is highly recommended that you review it in
  21   its entirety. The easiest ways to do so are
  22     * to run
  23         $ git format-patch -1
  24       and then read the patch in an editor that has syntax-colouring of patch
  25       files, or
  26     * to run
  27         $ gitk
  28
  29 * We update the ChangeLog by hand.  The commit message is usually identical
  30   to the ChangeLog entry, with the date and author line removed, with
  31   the leading tabs removed, and with a blank line after the commit's
  32   summary line.
  33   In order to work efficiently with ChangeLog files, it is recommended that
  34   you configure git to use the git-merge-changelog driver; see the instructions
  35   in the lib/git-merge-changelog.c file.
  36   Note: This driver reasonably keeps the ChangeLog entries together; however,
  37   it does not always keep them in the order you would desire. For example,
  38   when you had prepared a commit, you try to "git push" it but that fails due
  39   to someone else's commit that came earlier, what you need to do is:
  40     1. $ git pull
  41     2. Verify that your ChangeLog entry is still the top-most one.
  42     3. If it is not, then edit ChangeLog to move it to the top, and
  43        $ git commit --amend ChangeLog
  44     4. $ gitk
  45     5. $ git push
  46
  47 * When you commit a contributor's patch, please
  48   - add a reasonable ChangeLog entry in the usual style (meaningful
  49     summary line and detailed change list),
  50   - if the contribution is so small that it does not require a
  51     copyright assignment (cf.
  52     https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html )
  53     add a line:
  54     Copyright-paperwork-exempt: Yes
  55   - use the 'git commit' option --author="Contributor Name <email@address>"
  56
  57
  58 License Notices
  59 ===============
  60
  61 In *.m4 files, use a notice like this:
  62   dnl Copyright (C) YEARS Free Software Foundation, Inc.
  63   dnl This file is free software; the Free Software Foundation
  64   dnl gives unlimited permission to copy and/or distribute it,
  65   dnl with or without modifications, as long as this notice is preserved.
  66   dnl This file is offered as-is, without any warranty.
  67
  68 In lib/, tests/, build-aux/ files, except those that are shared with glibc,
  69 use the license notices from etc/license-notices/ . This avoids gratuitous
  70 differences in wording, as well misunderstandings when a license notice
  71 would say "This program ...".
  72
  73
  74 Test Suite
  75 ==========
  76
  77 When adding a module, add a unit test module as well.  This is our best
  78 chance to catch portability problems.
  79
  80 A unit test can have many sub-tests. Try to make the sub-tests independent
  81 of each other, so that it becomes easy to disable some sub-tests by enclosing
  82 them in #if 0 ... #endif.
  83
  84 The main() function's exit code meaning is:
  85   - 0: PASS
  86   - 77: SKIP; you should print the reason why the test is skipped.
  87   - 99: ERROR, i.e. test framework error
  88   - any other exit code < 126: FAIL
  89
  90 In tests that #include "macros.h" and use the ASSERT macro:
  91 The main() function should, before it returns 0 (for PASS) or 77 (for SKIP)
  92 test the value of test_exit_status and return that instead. So:
  93   - not
  94         return 0;
  95     but instead
  96         return test_exit_status;
  97   - not
  98         return result; // where result can be 0 or 1
  99     but instead
 100         return (result ? result : test_exit_status);
 101   - not
 102         fputs ("Skipping test: <reason>\n", stderr);
 103         return 77;
 104     but instead
 105         if (test_exit_status != EXIT_SUCCESS)
 106           return test_exit_status;
 107         fputs ("Skipping test: <reason>\n", stderr);
 108         return 77;
 109     Only at the beginning of the main() function, when ASSERT has not yet been
 110     invoked, we know that test_exit_status must be zero and can therefore write
 111         fputs ("Skipping test: <reason>\n", stderr);
 112         return 77;
 113     directly.
 114
 115
 116 Maintaining high quality
 117 ========================
 118
 119 It is a good idea to occasionally create a testdir of all of Gnulib:
 120   $ rm -rf ../testdir-all; ./gnulib-tool --create-testdir --dir=../testdir-all --with-c++-tests --without-privileged-tests --single-configure `./all-modules`
 121 and test this directory on various platforms:
 122   - Linux/glibc systems,
 123   - Linux/musl systems,
 124   - macOS,
 125   - FreeBSD,
 126   - NetBSD,
 127   - OpenBSD,
 128   - AIX,
 129   - Solaris 10 and 11,
 130   - Cygwin,
 131   - Haiku,
 132   - Android,
 133   - and other platforms of your choice.
 134
 135 There are two continuous integrations that regularly perform this testing:
 136 * On a Linux/glibc system only:
 137   https://gitlab.com/gnulib/gnulib-ci
 138   This one will catch only the most blatant mistakes.
 139 * On many platforms:
 140   https://github.com/gnu-gnulib/ci-testdir-check/actions
 141   This one runs on many platforms, currently (as of June 2024):
 142   - Ubuntu GNU/Linux 22.04
 143   - CentOS GNU/Linux 7
 144   - Alpine Linux
 145   - macOS 11, 12, 13 (all x86_64)
 146   - macOS 14 (arm64)
 147   - FreeBSD 14.0
 148   - NetBSD 10.0
 149   - OpenBSD 7.5
 150   - Solaris 11.4
 151   - Solaris 11 OmniOS
 152   - Cygwin 3.3.6 (32 bit) and 3.5.3 (64 bit)
 153   - mingw (32 bit and 64 bit)
 154   - MSVC (32 bit and 64 bit)
 155   and also
 156   - on Ubuntu GNU/Linux 22.04 with clang's UBSAN and ASAN sanitizers.
 157   This one catches real portability problems.
 158   Note that the following platforms are not covered and thus still require
 159   occasional manual testing:
 160   - AIX
 161   - Solaris 10
 162   - Haiku
 163   - Android
 164   - and other platforms of your choice.
 165
 166
 167 Warning Options
 168 ===============
 169
 170 For packages that use Gnulib, we recommend to use the 'warnings' or
 171 'manywarnings' module, as documented in
 172 https://www.gnu.org/software/gnulib/manual/html_node/warnings.html
 173 https://www.gnu.org/software/gnulib/manual/html_node/manywarnings.html
 174
 175 When building Gnulib testdirs, e.g. when preparing a Gnulib patch,
 176 there are three possible approaches:
 177
 178 * The simplest approach, which warns about the most common mistakes, is to
 179   use GCC's -Wall option, both for C and C++ compilation units. Just set
 180     $ ./configure CPPFLAGS="-Wall"
 181     $ make
 182   You should generally fix all compiler warnings that you see from this
 183   approach.
 184
 185 * If you are developing on a glibc system and have GCC version 13 binaries
 186   available, here's a recipe that will find more mistakes, but is nearly
 187   as easy to use. Here, different warning options are needed for C and
 188   for C++:
 189     $ WARN_GCC13=`echo '
 190       -fanalyzer
 191       -Wall
 192       -Warith-conversion
 193       -Wcast-align=strict
 194       -Wdate-time
 195       -Wdisabled-optimization
 196       -Wduplicated-cond
 197       -Wextra
 198       -Wformat-signedness
 199       -Winit-self
 200       -Winvalid-pch
 201       -Wlogical-op
 202       -Wmissing-include-dirs
 203       -Wopenmp-simd
 204       -Woverlength-strings
 205       -Wpacked
 206       -Wpointer-arith
 207       -Wstrict-overflow
 208       -Wsuggest-final-methods
 209       -Wsuggest-final-types
 210       -Wsync-nand
 211       -Wsystem-headers
 212       -Wtrampolines
 213       -Wuninitialized
 214       -Wunknown-pragmas
 215       -Wunsafe-loop-optimizations
 216       -Wvariadic-macros
 217       -Wvector-operation-performance
 218       -Wwrite-strings
 219       -Warray-bounds=2
 220       -Wattribute-alias=2
 221       -Wformat-overflow=2
 222       -Wformat-truncation=2
 223       -Wshift-overflow=2
 224       -Wunused-const-variable=2
 225       -Wvla-larger-than=4031
 226       -Wno-empty-body
 227       -Wno-analyzer-allocation-size
 228       -Wno-analyzer-fd-double-close
 229       -Wno-analyzer-double-fclose
 230       -Wno-analyzer-double-free
 231       -Wno-analyzer-fd-leak
 232       -Wno-analyzer-fd-use-after-close
 233       -Wno-analyzer-fd-use-without-check
 234       -Wno-analyzer-free-of-non-heap
 235       -Wno-analyzer-malloc-leak
 236       -Wno-analyzer-mismatching-deallocation
 237       -Wno-analyzer-null-argument
 238       -Wno-analyzer-null-dereference
 239       -Wno-analyzer-out-of-bounds
 240       -Wno-analyzer-possible-null-argument
 241       -Wno-analyzer-possible-null-dereference
 242       -Wno-analyzer-use-after-free
 243       -Wno-analyzer-use-of-pointer-in-stale-stack-frame
 244       -Wno-analyzer-use-of-uninitialized-value
 245       -Wno-analyzer-va-arg-type-mismatch
 246       -Wno-attribute-warning
 247       -Wno-cast-align
 248       -Wno-clobbered
 249       -Wno-dangling-pointer
 250       -Wno-format
 251       -Wno-implicit-fallthrough
 252       -Wno-maybe-uninitialized
 253       -Wno-missing-field-initializers
 254       -Wno-restrict
 255       -Wno-sign-compare
 256       -Wno-switch
 257       -Wno-type-limits
 258       -Wno-unused-parameter
 259     ' | tr -d '\n' | sed -e 's/  */ /g'`
 260     $ WARN_CFLAGS_GCC13="$WARN_GCC13 -Wnested-externs -Wshadow=local -Wno-discarded-qualifiers"
 261     $ WARN_CXXFLAGS_GCC13="$WARN_GCC13 -Wno-cpp"
 262     $ ./configure CFLAGS="-O2 -g $WARN_CFLAGS_GCC13" CXXFLAGS="-O2 -g $WARN_CXXFLAGS_GCC13"
 263     $ make
 264   You should generally fix all compiler warnings that you see from this
 265   approach, or report when this approach produced a pointless warning
 266   (so that we can fix the value of WARN_GCC13 above).
 267
 268 * If you are developing on a glibc system and have GCC version 13 binaries
 269   available: Here's a recipe that will find even more mistakes, but it
 270   requires that you are willing to filter out and ignore pointless warnings.
 271     $ WARN_GCC13=`echo '
 272       -fanalyzer
 273       -Wall
 274       -Warith-conversion
 275       -Wcast-align=strict
 276       -Wdate-time
 277       -Wdisabled-optimization
 278       -Wduplicated-cond
 279       -Wextra
 280       -Wformat-signedness
 281       -Winit-self
 282       -Winvalid-pch
 283       -Wlogical-op
 284       -Wmissing-include-dirs
 285       -Wnull-dereference
 286       -Wopenmp-simd
 287       -Woverlength-strings
 288       -Wpacked
 289       -Wpointer-arith
 290       -Wstrict-overflow
 291       -Wsuggest-attribute=format
 292       -Wsuggest-final-methods
 293       -Wsuggest-final-types
 294       -Wsync-nand
 295       -Wsystem-headers
 296       -Wtrampolines
 297       -Wuninitialized
 298       -Wunknown-pragmas
 299       -Wunsafe-loop-optimizations
 300       -Wvariadic-macros
 301       -Wvector-operation-performance
 302       -Wwrite-strings
 303       -Warray-bounds=2
 304       -Wattribute-alias=2
 305       -Wformat-overflow=2
 306       -Wformat=2
 307       -Wformat-truncation=2
 308       -Wimplicit-fallthrough=5
 309       -Wshift-overflow=2
 310       -Wunused-const-variable=2
 311       -Wvla-larger-than=4031
 312       -Wno-empty-body
 313       -Wno-analyzer-double-fclose
 314       -Wno-analyzer-double-free
 315       -Wno-analyzer-free-of-non-heap
 316       -Wno-analyzer-malloc-leak
 317       -Wno-analyzer-null-argument
 318       -Wno-analyzer-null-dereference
 319       -Wno-analyzer-use-after-free
 320       -Wno-attribute-warning
 321       -Wno-cast-align
 322       -Wno-clobbered
 323       -Wno-format-nonliteral
 324       -Wno-sign-compare
 325       -Wno-type-limits
 326       -Wno-unused-parameter
 327     ' | tr -d '\n' | sed -e 's/  */ /g'`
 328     $ WARN_CFLAGS_GCC13="$WARN_GCC13 -Wnested-externs -Wshadow=local"
 329     $ WARN_CXXFLAGS_GCC13="$WARN_GCC13 -Wno-cpp"
 330     $ ./configure CFLAGS="-O2 -g $WARN_CFLAGS_GCC13" CXXFLAGS="-O2 -g $WARN_CXXFLAGS_GCC13"
 331     $ make
 332   With this approach, use your own judgement whether to fix warnings
 333   arising from your new code or not.
 334   Do *not* submit patches to silence warnings from existing code:
 335     - For these warnings, often the cure will be worse than the disease.
 336     - Some of the warnings are false positives. Rather than silencing
 337       these warnings, we prefer to report them in the GCC bug tracker
 338       and wait until they are fixed in a future GCC release.
 339
 340 Similarly, for clang version 16 you can use the following recipe, that uses
 341 selected warning options from
 342 https://releases.llvm.org/16.0.0/tools/clang/docs/DiagnosticsReference.html :
 343   $ WARN_CLANG16=`echo '
 344     -Wall
 345     -Wanon-enum-enum-conversion
 346     -Warc-repeated-use-of-weak
 347     -Warray-bounds-pointer-arithmetic
 348     -Warray-parameter
 349     -Watomic-properties
 350     -Wbinary-literal
 351     -Wbit-int-extension
 352     -Wbitfield-enum-conversion
 353     -Wbitwise-op-parentheses
 354     -Wbool-operation
 355     -Wc++-compat
 356     -Wc2x-compat
 357     -Wc2x-extensions
 358     -Wc99-compat
 359     -Wc99-designator
 360     -Wc99-extensions
 361     -Wcalled-once-parameter
 362     -Wcast-function-type
 363     -Wchar-subscripts
 364     -Wcomment
 365     -Wcompletion-handler
 366     -Wcomplex-component-init
 367     -Wcompound-token-split
 368     -Wconsumed
 369     -Wconversion
 370     -Wcstring-format-directive
 371     -Wcuda-compat
 372     -Wdate-time
 373     -Wdelimited-escape-sequence-extension
 374     -Wdeprecated
 375     -Wdeprecated-dynamic-exception-spec
 376     -Wdeprecated-implementations
 377     -Wdeprecated-this-capture
 378     -Wdeprecated-writable-strings
 379     -Wdirect-ivar-access
 380     -Wdocumentation
 381     -Wdocumentation-deprecated-sync
 382     -Wdocumentation-html
 383     -Wdocumentation-pedantic
 384     -Wdocumentation-unknown-command
 385     -Wdollar-in-identifier-extension
 386     -Wduplicate-decl-specifier
 387     -Wduplicate-enum
 388     -Wduplicate-method-arg
 389     -Wduplicate-method-match
 390     -Wdynamic-exception-spec
 391     -Wembedded-directive
 392     -Wempty-init-stmt
 393     -Wempty-translation-unit
 394     -Wenum-compare-conditional
 395     -Wenum-conversion
 396     -Wenum-enum-conversion
 397     -Wenum-float-conversion
 398     -Wexit-time-destructors
 399     -Wexpansion-to-defined
 400     -Wexplicit-ownership-type
 401     -Wextra
 402     -Wextra-semi
 403     -Wfixed-enum-extension
 404     -Wflexible-array-extensions
 405     -Wfloat-overflow-conversion
 406     -Wfloat-zero-conversion
 407     -Wfor-loop-analysis
 408     -Wformat
 409     -Wformat-pedantic
 410     -Wformat-type-confusion
 411     -Wformat=2
 412     -Wfour-char-constants
 413     -Wframe-address
 414     -Wfuse-ld-path
 415     -Wfuture-attribute-extensions
 416     -Wgcc-compat
 417     -Wgnu
 418     -Wgnu-anonymous-struct
 419     -Wgnu-auto-type
 420     -Wgnu-case-range
 421     -Wgnu-complex-integer
 422     -Wgnu-compound-literal-initializer
 423     -Wgnu-conditional-omitted-operand
 424     -Wgnu-designator
 425     -Wgnu-empty-initializer
 426     -Wgnu-empty-struct
 427     -Wgnu-flexible-array-initializer
 428     -Wgnu-flexible-array-union-member
 429     -Wgnu-folding-constant
 430     -Wgnu-imaginary-constant
 431     -Wgnu-label-as-value
 432     -Wgnu-line-marker
 433     -Wgnu-null-pointer-arithmetic
 434     -Wgnu-offsetof-extensions
 435     -Wgnu-pointer-arith
 436     -Wgnu-redeclared-enum
 437     -Wgnu-statement-expression
 438     -Wgnu-statement-expression-from-macro-expansion
 439     -Wgnu-union-cast
 440     -Wgnu-zero-line-directive
 441     -Wgnu-zero-variadic-macro-arguments
 442     -Wheader-hygiene
 443     -Widiomatic-parentheses
 444     -Wignored-qualifiers
 445     -Wimplicit
 446     -Wimplicit-fallthrough
 447     -Wimplicit-fallthrough-per-function
 448     -Wimplicit-function-declaration
 449     -Wimplicit-int
 450     -Wimplicit-retain-self
 451     -Wimport-preprocessor-directive-pedantic
 452     -Wincomplete-module
 453     -Winconsistent-missing-destructor-override
 454     -Winfinite-recursion
 455     -Wint-in-bool-context
 456     -Winvalid-or-nonexistent-directory
 457     -Winvalid-utf8
 458     -Wkeyword-macro
 459     -Wlanguage-extension-token
 460     -Wlocal-type-template-args
 461     -Wlogical-op-parentheses
 462     -Wlong-long
 463     -Wloop-analysis
 464     -Wmain
 465     -Wmax-tokens
 466     -Wmethod-signatures
 467     -Wmicrosoft
 468     -Wmicrosoft-anon-tag
 469     -Wmicrosoft-charize
 470     -Wmicrosoft-comment-paste
 471     -Wmicrosoft-cpp-macro
 472     -Wmicrosoft-end-of-file
 473     -Wmicrosoft-enum-value
 474     -Wmicrosoft-exception-spec
 475     -Wmicrosoft-fixed-enum
 476     -Wmicrosoft-flexible-array
 477     -Wmicrosoft-redeclare-static
 478     -Wmisleading-indentation
 479     -Wmismatched-tags
 480     -Wmissing-braces
 481     -Wmissing-method-return-type
 482     -Wmost
 483     -Wmove
 484     -Wnested-anon-types
 485     -Wnewline-eof
 486     -Wnon-gcc
 487     -Wnon-modular-include-in-framework-module
 488     -Wnon-modular-include-in-module
 489     -Wnon-virtual-dtor
 490     -Wnonportable-system-include-path
 491     -Wnull-pointer-arithmetic
 492     -Wnull-pointer-subtraction
 493     -Wnullability-extension
 494     -Wnullable-to-nonnull-conversion
 495     -Wopenmp
 496     -Wover-aligned
 497     -Woverlength-strings
 498     -Woverloaded-virtual
 499     -Woverriding-method-mismatch
 500     -Wpacked
 501     -Wpacked-non-pod
 502     -Wparentheses
 503     -Wpedantic
 504     -Wpedantic-core-features
 505     -Wpessimizing-move
 506     -Wpointer-arith
 507     -Wpoison-system-directories
 508     -Wpragma-pack
 509     -Wpragma-pack-suspicious-include
 510     -Wpragmas
 511     -Wpre-c2x-compat
 512     -Wpre-openmp-51-compat
 513     -Wprofile-instr-missing
 514     -Wquoted-include-in-framework-header
 515     -Wrange-loop-analysis
 516     -Wrange-loop-bind-reference
 517     -Wrange-loop-construct
 518     -Wreceiver-forward-class
 519     -Wredundant-move
 520     -Wredundant-parens
 521     -Wreorder
 522     -Wreorder-ctor
 523     -Wreserved-user-defined-literal
 524     -Wretained-language-linkage
 525     -Wselector
 526     -Wselector-type-mismatch
 527     -Wself-assign
 528     -Wself-assign-overloaded
 529     -Wself-move
 530     -Wsemicolon-before-method-body
 531     -Wshadow-all
 532     -Wshadow-field
 533     -Wshadow-field-in-constructor
 534     -Wshadow-field-in-constructor-modified
 535     -Wshadow-uncaptured-local
 536     -Wshift-sign-overflow
 537     -Wsigned-enum-bitfield
 538     -Wsometimes-uninitialized
 539     -Wsource-uses-openmp
 540     -Wspir-compat
 541     -Wstatic-in-inline
 542     -Wstrict-potentially-direct-selector
 543     -Wstrict-selector-match
 544     -Wstring-concatenation
 545     -Wstring-conversion
 546     -Wsuggest-destructor-override
 547     -Wsuggest-override
 548     -Wsuper-class-method-mismatch
 549     -Wtautological-bitwise-compare
 550     -Wtautological-compare
 551     -Wtautological-constant-in-range-compare
 552     -Wtautological-overlap-compare
 553     -Wtautological-type-limit-compare
 554     -Wtautological-unsigned-char-zero-compare
 555     -Wtautological-unsigned-enum-zero-compare
 556     -Wtautological-unsigned-zero-compare
 557     -Wtautological-value-range-compare
 558     -Wthread-safety
 559     -Wthread-safety-analysis
 560     -Wthread-safety-attributes
 561     -Wthread-safety-beta
 562     -Wthread-safety-negative
 563     -Wthread-safety-precise
 564     -Wthread-safety-reference
 565     -Wthread-safety-verbose
 566     -Wtype-limits
 567     -Wunaligned-access
 568     -Wundeclared-selector
 569     -Wundef-prefix
 570     -Wundefined-func-template
 571     -Wundefined-internal-type
 572     -Wundefined-reinterpret-cast
 573     -Wunguarded-availability
 574     -Wuninitialized
 575     -Wuninitialized-const-reference
 576     -Wunknown-pragmas
 577     -Wunnamed-type-template-args
 578     -Wunneeded-internal-declaration
 579     -Wunneeded-member-function
 580     -Wunreachable-code-fallthrough
 581     -Wunreachable-code-loop-increment
 582     -Wunsupported-dll-base-class-template
 583     -Wunused
 584     -Wunused-but-set-parameter
 585     -Wunused-but-set-variable
 586     -Wunused-const-variable
 587     -Wunused-exception-parameter
 588     -Wunused-function
 589     -Wunused-label
 590     -Wunused-lambda-capture
 591     -Wunused-local-typedef
 592     -Wunused-member-function
 593     -Wunused-private-field
 594     -Wunused-property-ivar
 595     -Wunused-template
 596     -Wunused-variable
 597     -Wvariadic-macros
 598     -Wvector-conversion
 599     -Wweak-template-vtables
 600     -Wweak-vtables
 601     -Wzero-length-array
 602     -Wno-bitwise-instead-of-logical
 603     -Wno-c11-extensions
 604     -Wno-cast-function-type-strict
 605     -Wno-float-conversion
 606     -Wno-format-nonliteral
 607     -Wno-gnu-include-next
 608     -Wno-implicit-float-conversion
 609     -Wno-implicit-int-conversion
 610     -Wno-implicit-int-float-conversion
 611     -Wno-include-next-absolute-path
 612     -Wno-missing-field-initializers
 613     -Wno-reserved-macro-identifier
 614     -Wno-shadow
 615     -Wno-shorten-64-to-32
 616     -Wno-sign-compare
 617     -Wno-sign-conversion
 618     -Wno-strict-prototypes
 619     -Wno-switch
 620     -Wno-unused-parameter
 621     -Wno-tautological-constant-out-of-range-compare
 622     -Wno-tautological-type-limit-compare
 623     -Wno-tautological-unsigned-zero-compare
 624     -Wno-tautological-value-range-compare
 625     -Wno-unused-command-line-argument
 626     -Wno-user-defined-warnings
 627   ' | tr -d '\n' | sed -e 's/  */ /g'`
 628   $ ./configure CFLAGS="-O2 -g $WARN_CLANG16" CXXFLAGS="-O2 -g $WARN_CLANG16"
 629   $ make
 630 Again, use your own judgement to determine whether to fix or ignore a
 631 specific warning.
 632
 633
 634 Information for gnulib-tool maintenance
 635 ***************************************
 636
 637 Running the unit tests
 638 ======================
 639
 640 The unit tests of gnulib-tool reside in the maint-tools repository, that is a
 641 satellite repository of the main gnulib repository. Instructions how to obtain
 642 it are in https://savannah.gnu.org/git/?group=gnulib .
 643
 644 To run the unit tests of gnulib-tool.sh:
 645   $ cd maint-tools/gnulib-tool-tests/
 646   $ GNULIB_TOOL_IMPL=sh ./test-all.sh
 647
 648 To run the unit tests of gnulib-tool.py:
 649   $ cd maint-tools/gnulib-tool-tests/
 650   $ GNULIB_TOOL_IMPL=py ./test-all.sh
 651
 652 It is *mandatory* that you run the test suite before pushing any change to
 653 gnulib-tool.sh or gnulib-tool.py! If you fail to do so, and your change contains
 654 a bug, it will start to affect users immediately.
 655
 656
 657 Debugging the Python implementation of gnulib-tool
 658 ==================================================
 659
 660 With Eclipse and PyDev as IDE
 661 -----------------------------
 662
 663 * Download and configuration:
 664   - Eclipse IDE from https://www.eclipse.org/downloads/packages/
 665     (either the build for Java or for C/C++ should work fine;
 666     either use the Eclipse Installer program at the top of the page,
 667     or one of the individual download links below).
 668   - PyDev from https://www.pydev.org/download.html
 669     section "Install as Plugin".
 670     (Don't use LiClipse, since the license costs money.)
 671   - Follow https://www.pydev.org/manual_101_install.html,
 672     replacing http://www.pydev.org/updates
 673     with      https://www.pydev.org/updates
 674   - Once installed, restart the IDE.
 675   - Window > Preferences > PyDev > Interpreters > Python Interpreter:
 676     New > path: /usr/bin/python3
 677   - Window > Preferences > PyDev > Editor > Code Analysis:
 678     Others > Redefinition of builtin symbols: Ignore
 679
 680 * Create a project:
 681   Let GNULIB_DIR be my gnulib checkout.
 682   - File > New > Project... > PyDev > PyDev Project. Call it 'gnulib-tool'.
 683     Note that this is a project inside the Eclipse workspace, so far
 684     unrelated to the GNULIB_DIR.
 685   - Popup menu > New > Link to Existing Source
 686     Name: gnulib
 687     Path: <GNULIB_DIR>
 688
 689 * Create a run configuration:
 690   - Run > Run Configurations... > Python Run
 691     Popup menu > New configuration
 692       Name: gnulib-tool.py
 693       Main > Project: gnulib-tool
 694       Main > Main Module: ${workspace_loc:gnulib-tool/gnulib/.gnulib-tool.py}
 695       Arguments > Program arguments: --help
 696   - Test it: Run this configuration.
 697
 698 * Create a debug configuration:
 699   - Run > Debug Configurations... > gnulib-tool.py
 700     Popup menu > Duplicate
 701   - In the duplicate, set
 702     Arguments > Working directory: /tmp/oath-toolkit/lib
 703     Arguments > Program arguments: --add-import
 704
 705 * Debug it:
 706   - Open GLImport.py.
 707   - On the left-hand border of this editor, do "Add breakpoint".
 708   - Run > Debug Configurations... > pick the duplicate. Press Debug.
 709
 710
 711 Maintaining high quality
 712 ========================
 713
 714 There is a continuous integration of gnulib-tool.py that runs the unit tests,
 715 at https://gitlab.com/gnulib/gnulib-tool-ci/ .