diff mbox series

[v4,7/9] Makefile: document SHA-1 and SHA-256 default and selection order

Message ID patch-v4-7.9-847be3d32e2-20221026T145255Z-avarab@gmail.com (mailing list archive)
State New, archived
Headers show
Series Makefile & docs: document SHA-{1,256} behavior, fix bug | expand

Commit Message

Ævar Arnfjörð Bjarmason Oct. 26, 2022, 2:56 p.m. UTC 
For the *_SHA1 and *_SHA256 flags we've discussed the various flags,
but not the fact that when you define multiple flags we'll pick one.

Which one we pick depends on the order they're listed in the Makefile,
which differed from the order we discussed them in this documentation.

Let's be explicit about how we select these, and re-arrange the
listings so that they're listed in the priority order we've picked.

I'd personally prefer that the selection was more explicit, and that
we'd error out if conflicting flags were provided, but per the
discussion downhtread of[1] the consensus was to keep theses semantics.

This behavior makes it easier to e.g. integrate with autoconf-like
systems, where the configuration can provide everything it can
support, and Git is tasked with picking the first one it prefers.

1. https://lore.kernel.org/git/220710.86mtdh81ty.gmgdl@evledraar.gmail.com/

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Makefile | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

Comments

Junio C Hamano Oct. 26, 2022, 10:30 p.m. UTC | #1 
Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> For the *_SHA1 and *_SHA256 flags we've discussed the various flags,
> but not the fact that when you define multiple flags we'll pick one.
>
> Which one we pick depends on the order they're listed in the Makefile,
> which differed from the order we discussed them in this documentation.
>
> Let's be explicit about how we select these, and re-arrange the
> listings so that they're listed in the priority order we've picked.

That makes sense.  What is not explicit enough, at least at this
stage, is that, even though we say "if you do not choose one, the
default is used" (which by the way is an awkward thing to see---that
is the definition of being the default, so the statement itself has
zero bit of useful information), we do not say what implementation
exactly is used as the default.

> This behavior makes it easier to e.g. integrate with autoconf-like
> systems, where the configuration can provide everything it can
> support, and Git is tasked with picking the first one it prefers.

Well explained.

> +# ==== Default SHA-1 backend ====
> +#
> +# If no *_SHA1 backend is picked we'll fall back on using the default.
> +#
> +# Multiple *_SHA1 backends can be selected, the first supported one
> +# listed in "Other SHA-1 implementations" will be picked.
diff mbox series

Patch

diff --git a/Makefile b/Makefile
index 992eba9e0c8..9f7cf1f22d4 100644
--- a/Makefile
+++ b/Makefile
@@ -481,6 +481,13 @@  include shared.mak
 #
 # === SHA-1 backend ===
 #
+# ==== Default SHA-1 backend ====
+#
+# If no *_SHA1 backend is picked we'll fall back on using the default.
+#
+# Multiple *_SHA1 backends can be selected, the first supported one
+# listed in "Other SHA-1 implementations" will be picked.
+#
 # ==== Options common to all SHA-1 implementations ====
 #
 # Define SHA1_MAX_BLOCK_SIZE to limit the amount of data that will be hashed
@@ -505,12 +512,12 @@  include shared.mak
 #
 # ==== Other SHA-1 implementations ====
 #
-# Define BLK_SHA1 to make use of optimized C SHA-1 routines bundled
-# with git (in the block-sha1/ directory).
-#
 # Define OPENSSL_SHA1 to link to the SHA-1 routines from the OpenSSL
 # library.
 #
+# Define BLK_SHA1 to make use of optimized C SHA-1 routines bundled
+# with git (in the block-sha1/ directory).
+#
 # === SHA-256 backend ===
 #
 # ==== Default SHA-256 backend ====
@@ -521,14 +528,17 @@  include shared.mak
 # The default SHA-256 backend is shipped with Git. No flag is required
 # to enable it. To select it don't define any other *_SHA256 flag.
 #
+# Multiple *_SHA256 backends can be selected, the first supported one
+# listed in "Other SHA-256 implementations" below will be picked.
+#
 # ==== Other SHA-256 implementations ====
 #
+# Define OPENSSL_SHA256 to use the SHA-256 routines in OpenSSL.
+#
 # Define NETTLE_SHA256 to use the SHA-256 routines in libnettle.
 #
 # Define GCRYPT_SHA256 to use the SHA-256 routines in libgcrypt.
 #
-# Define OPENSSL_SHA256 to use the SHA-256 routines in OpenSSL.
-#
 # == DEVELOPER defines ==
 #
 # Define DEVELOPER to enable more compiler warnings. Compiler version