@matheusbsbs / matheus-bagliano / commits / 34b660e3e6

Makefile: create and use sections for "define" flag listing

Since the "Define ..." template of comments at the top of the Makefile was started in 5bdac8b3269 ([PATCH] Improve the compilation-time settings interface, 2005-07-29) we've had a lot more flags added, including flags that come in "groups". Not having any obvious structure to the >500 line comment at the top of the Makefile has made it hard to follow. This change is almost entirely a move-only change, the two paragraphs at the start of the first two sections are new, and so are the added sections themselves, but other than that no lines are changed, only moved. We now list Makefile-only flags at the start, followed by stand-alone flags, and then cover "optional library" flags in their respective groups, followed by SHA-1 and SHA-256 flags, and finally DEVELOPER-specific flags. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Taylor Blau <me@ttaylorr.com>

Ævar Arnfjörð Bjarmason committed Nov 7, 2022 at 22:23 UTC 34b660e3e60b094cd456dbaf9484ba261a7a9faa
1 file changed +128 -92
Makefile
+128 -92
@@ -4,8 +4,20 @@ all::
4 # Import tree-wide shared Makefile behavior and libraries
5 include shared.mak
6
7 +# == Makefile defines ==
8 +#
9 +# These defines change the behavior of the Makefile itself, but have
10 +# no impact on what it builds:
11 +#
12 # Define V=1 to have a more verbose compile.
13 #
14 +# == Portability and optional library defines ==
15 +#
16 +# These defines indicate what Git can expect from the OS, what
17 +# libraries are available etc. Much of this is auto-detected in
18 +# config.mak.uname, or in configure.ac when using the optional "make
19 +# configure && ./configure" (see INSTALL).
20 +#
21 # Define SHELL_PATH to a POSIX shell if your /bin/sh is broken.
22 #
23 # Define SANE_TOOL_PATH to a colon-separated list of paths to prepend
@@ -30,68 +42,8 @@ include shared.mak
42 #
43 # Define NO_OPENSSL environment variable if you do not have OpenSSL.
44 #
33 -# Define USE_LIBPCRE if you have and want to use libpcre. Various
34 -# commands such as log and grep offer runtime options to use
35 -# Perl-compatible regular expressions instead of standard or extended
36 -# POSIX regular expressions.
37 -#
38 -# Only libpcre version 2 is supported. USE_LIBPCRE2 is a synonym for
39 -# USE_LIBPCRE, support for the old USE_LIBPCRE1 has been removed.
40 -#
41 -# Define LIBPCREDIR=/foo/bar if your PCRE header and library files are
42 -# in /foo/bar/include and /foo/bar/lib directories.
43 -#
45 # Define HAVE_ALLOCA_H if you have working alloca(3) defined in that header.
46 #
46 -# Define NO_CURL if you do not have libcurl installed. git-http-fetch and
47 -# git-http-push are not built, and you cannot use http:// and https://
48 -# transports (neither smart nor dumb).
49 -#
50 -# Define CURLDIR=/foo/bar if your curl header and library files are in
51 -# /foo/bar/include and /foo/bar/lib directories.
52 -#
53 -# Define CURL_CONFIG to curl's configuration program that prints information
54 -# about the library (e.g., its version number). The default is 'curl-config'.
55 -#
56 -# Define CURL_LDFLAGS to specify flags that you need to link when using libcurl,
57 -# if you do not want to rely on the libraries provided by CURL_CONFIG. The
58 -# default value is a result of `curl-config --libs`. An example value for
59 -# CURL_LDFLAGS is as follows:
60 -#
61 -# CURL_LDFLAGS=-lcurl
62 -#
63 -# Define NO_EXPAT if you do not have expat installed. git-http-push is
64 -# not built, and you cannot push using http:// and https:// transports (dumb).
65 -#
66 -# Define EXPATDIR=/foo/bar if your expat header and library files are in
67 -# /foo/bar/include and /foo/bar/lib directories.
68 -#
69 -# Define EXPAT_NEEDS_XMLPARSE_H if you have an old version of expat (e.g.,
70 -# 1.1 or 1.2) that provides xmlparse.h instead of expat.h.
71 -#
72 -# Define NO_GETTEXT if you don't want Git output to be translated.
73 -# A translated Git requires GNU libintl or another gettext implementation,
74 -# plus libintl-perl at runtime.
75 -#
76 -# Define USE_GETTEXT_SCHEME and set it to 'fallthrough', if you don't trust
77 -# the installed gettext translation of the shell scripts output.
78 -#
79 -# Define HAVE_LIBCHARSET_H if you haven't set NO_GETTEXT and you can't
80 -# trust the langinfo.h's nl_langinfo(CODESET) function to return the
81 -# current character set. GNU and Solaris have a nl_langinfo(CODESET),
82 -# FreeBSD can use either, but MinGW and some others need to use
83 -# libcharset.h's locale_charset() instead.
84 -#
85 -# Define CHARSET_LIB to the library you need to link with in order to
86 -# use locale_charset() function. On some platforms this needs to set to
87 -# -lcharset, on others to -liconv .
88 -#
89 -# Define LIBC_CONTAINS_LIBINTL if your gettext implementation doesn't
90 -# need -lintl when linking.
91 -#
92 -# Define NO_MSGFMT_EXTENDED_OPTIONS if your implementation of msgfmt
93 -# doesn't support GNU extensions like --check and --statistics
94 -#
47 # Define HAVE_PATHS_H if you have paths.h and want to use the default PATH
48 # it specifies.
49 #
@@ -152,38 +104,6 @@ include shared.mak
104 # and do not want to use Apple's CommonCrypto library. This allows you
105 # to provide your own OpenSSL library, for example from MacPorts.
106 #
155 -# Define BLK_SHA1 environment variable to make use of the bundled
156 -# optimized C SHA1 routine.
157 -#
158 -# Define DC_SHA1 to enable the collision-detecting sha1
159 -# algorithm. This is slower, but may detect attempted collision attacks.
160 -#
161 -# Define DC_SHA1_EXTERNAL in addition to DC_SHA1 if you want to build / link
162 -# git with the external SHA1 collision-detect library.
163 -# Without this option, i.e. the default behavior is to build git with its
164 -# own built-in code (or submodule).
165 -#
166 -# Define DC_SHA1_SUBMODULE in addition to DC_SHA1 to use the
167 -# sha1collisiondetection shipped as a submodule instead of the
168 -# non-submodule copy in sha1dc/. This is an experimental option used
169 -# by the git project to migrate to using sha1collisiondetection as a
170 -# submodule.
171 -#
172 -# Define OPENSSL_SHA1 environment variable when running make to link
173 -# with the SHA1 routine from openssl library.
174 -#
175 -# Define SHA1_MAX_BLOCK_SIZE to limit the amount of data that will be hashed
176 -# in one call to the platform's SHA1_Update(). e.g. APPLE_COMMON_CRYPTO
177 -# wants 'SHA1_MAX_BLOCK_SIZE=1024L*1024L*1024L' defined.
178 -#
179 -# Define BLK_SHA256 to use the built-in SHA-256 routines.
180 -#
181 -# Define NETTLE_SHA256 to use the SHA-256 routines in libnettle.
182 -#
183 -# Define GCRYPT_SHA256 to use the SHA-256 routines in libgcrypt.
184 -#
185 -# Define OPENSSL_SHA256 to use the SHA-256 routines in OpenSSL.
186 -#
107 # Define NEEDS_CRYPTO_WITH_SSL if you need -lcrypto when using -lssl (Darwin).
108 #
109 # Define NEEDS_SSL_WITH_CRYPTO if you need -lssl when using -lcrypto (Darwin).
@@ -489,6 +409,122 @@ include shared.mak
409 # to the "<name>" of the corresponding `compat/fsmonitor/fsm-settings-<name>.c`
410 # that implements the `fsm_os_settings__*()` routines.
411 #
412 +# === Optional library: libintl ===
413 +#
414 +# Define NO_GETTEXT if you don't want Git output to be translated.
415 +# A translated Git requires GNU libintl or another gettext implementation,
416 +# plus libintl-perl at runtime.
417 +#
418 +# Define USE_GETTEXT_SCHEME and set it to 'fallthrough', if you don't trust
419 +# the installed gettext translation of the shell scripts output.
420 +#
421 +# Define HAVE_LIBCHARSET_H if you haven't set NO_GETTEXT and you can't
422 +# trust the langinfo.h's nl_langinfo(CODESET) function to return the
423 +# current character set. GNU and Solaris have a nl_langinfo(CODESET),
424 +# FreeBSD can use either, but MinGW and some others need to use
425 +# libcharset.h's locale_charset() instead.
426 +#
427 +# Define CHARSET_LIB to the library you need to link with in order to
428 +# use locale_charset() function. On some platforms this needs to set to
429 +# -lcharset, on others to -liconv .
430 +#
431 +# Define LIBC_CONTAINS_LIBINTL if your gettext implementation doesn't
432 +# need -lintl when linking.
433 +#
434 +# Define NO_MSGFMT_EXTENDED_OPTIONS if your implementation of msgfmt
435 +# doesn't support GNU extensions like --check and --statistics
436 +#
437 +# === Optional library: libexpat ===
438 +#
439 +# Define NO_EXPAT if you do not have expat installed. git-http-push is
440 +# not built, and you cannot push using http:// and https:// transports (dumb).
441 +#
442 +# Define EXPATDIR=/foo/bar if your expat header and library files are in
443 +# /foo/bar/include and /foo/bar/lib directories.
444 +#
445 +# Define EXPAT_NEEDS_XMLPARSE_H if you have an old version of expat (e.g.,
446 +# 1.1 or 1.2) that provides xmlparse.h instead of expat.h.
447 +
448 +# === Optional library: libcurl ===
449 +#
450 +# Define NO_CURL if you do not have libcurl installed. git-http-fetch and
451 +# git-http-push are not built, and you cannot use http:// and https://
452 +# transports (neither smart nor dumb).
453 +#
454 +# Define CURLDIR=/foo/bar if your curl header and library files are in
455 +# /foo/bar/include and /foo/bar/lib directories.
456 +#
457 +# Define CURL_CONFIG to curl's configuration program that prints information
458 +# about the library (e.g., its version number). The default is 'curl-config'.
459 +#
460 +# Define CURL_LDFLAGS to specify flags that you need to link when using libcurl,
461 +# if you do not want to rely on the libraries provided by CURL_CONFIG. The
462 +# default value is a result of `curl-config --libs`. An example value for
463 +# CURL_LDFLAGS is as follows:
464 +#
465 +# CURL_LDFLAGS=-lcurl
466 +#
467 +# === Optional library: libpcre2 ===
468 +#
469 +# Define USE_LIBPCRE if you have and want to use libpcre. Various
470 +# commands such as log and grep offer runtime options to use
471 +# Perl-compatible regular expressions instead of standard or extended
472 +# POSIX regular expressions.
473 +#
474 +# Only libpcre version 2 is supported. USE_LIBPCRE2 is a synonym for
475 +# USE_LIBPCRE, support for the old USE_LIBPCRE1 has been removed.
476 +#
477 +# Define LIBPCREDIR=/foo/bar if your PCRE header and library files are
478 +# in /foo/bar/include and /foo/bar/lib directories.
479 +#
480 +# == SHA-1 and SHA-256 defines ==
481 +#
482 +# === SHA-1 backend ===
483 +#
484 +# ==== Options common to all SHA-1 implementations ====
485 +#
486 +# Define SHA1_MAX_BLOCK_SIZE to limit the amount of data that will be hashed
487 +# in one call to the platform's SHA1_Update(). e.g. APPLE_COMMON_CRYPTO
488 +# wants 'SHA1_MAX_BLOCK_SIZE=1024L*1024L*1024L' defined.
489 +#
490 +# ==== SHA-1 implementations ====
491 +#
492 +# Define DC_SHA1 to enable the collision-detecting sha1
493 +# algorithm. This is slower, but may detect attempted collision attacks.
494 +#
495 +# Define BLK_SHA1 environment variable to make use of the bundled
496 +# optimized C SHA1 routine.
497 +#
498 +# Define OPENSSL_SHA1 environment variable when running make to link
499 +# with the SHA1 routine from openssl library.
500 +#
501 +# ==== Options for the sha1collisiondetection library ====
502 +#
503 +# Define DC_SHA1_EXTERNAL in addition to DC_SHA1 if you want to build / link
504 +# git with the external SHA1 collision-detect library.
505 +# Without this option, i.e. the default behavior is to build git with its
506 +# own built-in code (or submodule).
507 +#
508 +# Define DC_SHA1_SUBMODULE in addition to DC_SHA1 to use the
509 +# sha1collisiondetection shipped as a submodule instead of the
510 +# non-submodule copy in sha1dc/. This is an experimental option used
511 +# by the git project to migrate to using sha1collisiondetection as a
512 +# submodule.
513 +#
514 +# === SHA-256 backend ===
515 +#
516 +# ==== SHA-256 implementations ====
517 +#
518 +# Define BLK_SHA256 to use the built-in SHA-256 routines.
519 +#
520 +# Define NETTLE_SHA256 to use the SHA-256 routines in libnettle.
521 +#
522 +# Define GCRYPT_SHA256 to use the SHA-256 routines in libgcrypt.
523 +#
524 +# Define OPENSSL_SHA256 to use the SHA-256 routines in OpenSSL.
525 +#
526 +# == DEVELOPER defines ==
527 +#
528 # Define DEVELOPER to enable more compiler warnings. Compiler version
529 # and family are auto detected, but could be overridden by defining
530 # COMPILER_FEATURES (see config.mak.dev). You can still set