Add a section to autosetup/README.md describing the motivations for the more glaring...

FossilOrigin-Name: c0940a822a63bff74585bd37401eca92f74ddf9fe95748d2474039ee9b2bd9b6

diff --git a/autosetup/README.md b/autosetup/README.md
index 8bb2a8c3aed763c474ba304135e662550234fa18..8b989754a4dfb951cb485888dee1755e80eb3618 100644 (file)
--- a/autosetup/README.md
+++ b/autosetup/README.md
@@ -10,6 +10,7 @@ build infrastructure. It is not an [Autosetup][] reference.
 - [Autosetup API Reference](#apiref)
 - [API Tips](#apitips)
 - [Ensuring TCL Compatibility](#tclcompat)
+- [Design Conventions](#conventions)
 - [Updating Autosetup](#updating)
 
 ------------------------------------------------------------------------
@@ -36,6 +37,7 @@ projects) and all have a `proj-` name prefix. The latter is the main
 configure script driver and contains related functions which are
 specific to this tree.
 
+
 <a name="apitips"></a>
 Autosetup API Tips
 ========================================================================
@@ -69,7 +71,7 @@ In (mostly) alphabetical order:
 
 - **`proj-indented-notice ?-error? msg`**\  
   Breaks its `msg` argument into lines, trims them, and emits them
-  with consistent indentation. If the `-error` flag is used, it them
+  with consistent indentation. If the `-error` flag is used, it then
   exits with non-0. This will stick out starkly from normal output
   and is intended to be used only for important notices.
 
@@ -88,6 +90,15 @@ In (mostly) alphabetical order:
   Returns 1 if `$value` is "truthy," i.e. one of (1, on, enabled,
   yes).
 
+- **`sqlite-add-feature-flag ?-shell? FLAG...`**\  
+  Adds the given feature flag to the CFLAGS which are specific to building
+  the library. It's intended to be passed one or more `-DSQLITE_ENABLE_...`,
+  or similar, flags. If the `-shell` flag is used then it also passes
+  its arguments to `sqlite-add-shell-opt`. This is a no-op if `FLAG`
+  is not provided or is empty.
+
+- **`sqlite-add-shell-opt FLAG...`**\  
+  The shell-specific counterpart of `sqlite-add-feature-flag`.
 
 <a name="tclcompat"></a>
 Ensuring TCL Compatibility
@@ -106,8 +117,9 @@ By default, the configure script will search for an available `tclsh`
 compiling the copy of `jimsh0.c` included in the source tree.
 
 There are two simple ways to ensure that the configure process uses
-JimTCL instead of the canonical `tclsh`, and either approach ensures
-configure script compatibility:
+JimTCL instead of the canonical `tclsh`, and either approach provides
+equally high assurances about configure script compatibility across
+TCL implementations:
 
 1. Build on a system with no `tclsh` installed. In that case, the
    configure process will fall back to building the in-tree copy of
@@ -128,6 +140,74 @@ utility APIs must not use `[file normalize]`, but autosetup provides a
 TCL implementation of `[file-normalize]` (note the dash) for portable
 use in the configure script.
 
+
+<a name="conventions"></a>
+Design Conventions
+========================================================================
+
+This section describes the motivations for the most glaring of the
+build's design decisions, in particular how they deviate from
+historical, or even widely-conventional, practices.
+
+Do Not Update Global Shared State
+------------------------------------------------------------------------
+
+In both the legacy Autotools-driven build and in common Autosetup
+usage, feature tests performed by the configure script may ammend
+values to global flags such as `CFLAGS`, `LDFLAGS`, and `LIBS`.
+That's appropriate for a makefile which builds a single deliverable,
+but less so for makefiles which produce multiple deliverables, as it's
+unlikely that every single deliverable will require the same core set
+of those flags.  In addition, that approach can make it difficult to
+determine the origin of any given change to those flags because those
+changes are hidden behind voodoo performed outside the immediate
+visibility of the configure script's maintainer. It can also force the
+maintainers of the configure script to place tests in a specific order
+so that the resulting flags get applied at the correct time.
+
+> A real-life example of the latter point: before the approach
+  described below was taken to collecting build-time flags, the test
+  for `-rflag` had to come _after_ the test for zlib because the
+  results of the `-rflag` test implicitly modified the `CFLAGS`,
+  breaking the zlib feature test. Because the feature tests no longer
+  (intentionally) modify global state, that is not an issue.
+
+Cases where feature tests modify global state in such a way that it
+may impact later feature tests are either (A) very intentionally
+defined to do so (e.g. the `--with-wasi-sdk` flag needs to modify the
+build tool chain) or (B) are oversights (i.e. bugs).
+
+This tree's configure script, utility APIs,
+[`Makefile.in`](/file/Makefile.in), and [`main.mk`](/file/main.mk)
+therefore strive to separate the results of any given feature test
+into its own well-defined variables. For example:
+
+- The linker flags for zlib are exported from the configure script as
+  `LDFLAGS_ZLIB`, which `Makefile.in` and `main.mk` then expose as
+  `LDFLAGS.zlib`.
+- `CFLAGS_READLINE` (a.k.a. `CFLAGS.readline`) contains the `CFLAGS`
+  needed for including `libreadline`, `libedit`, or `linenoise`, and
+  `LDFLAGS_READLINE` (a.k.a. `LDFLAGS.readline`) is its link-time
+  counterpart.
+
+It is then up to the Makefile to apply and order the flags however is
+appropriate.
+
+> Sidebar: the `X_Y` convention is used used on the configure-script
+  side because that process exports those flags as C `#define`s to
+  `sqlite_cfg.h`, where dots are not permitted.  The `X.y` convention
+  is used in the Makefile side primarily because the person who did
+  the initial port finds that easier on the eyes and fingers.
+
+At the end of the configure script, the global `CFLAGS` _ideally_
+holds only flags which are either relevant to all targets or, failing
+that, will have no unintended side-effects on any targets. That said:
+clients frequently pass custom `CFLAGS` to `./configure` or `make` to
+set library-level feature toggles, e.g. `-DSQLITE_OMIT_FOO`, in which
+case there is no practical way to avoid "polluting" the builds of
+arbitrary makefile targets with those. _C'est la vie._
+
+
 <a name="updating"></a>
 Updating Autosetup
 ========================================================================
@@ -158,7 +238,7 @@ configure process, and check it in.
 
 
 [Autosetup]: https://msteveb.github.io/autosetup/
-[auto.def]: ../auto.def?mimetype=text/plain
+[auto.def]: /file/auto.def
 [autosetup-git]: https://github.com/msteveb/autosetup
-[proj.tcl]: ./proj.tcl?mimetype=text/plain
+[proj.tcl]: /file/autosetup/proj.tcl
 [JimTCL]: https://jim.tcl.tk

diff --git a/main.mk b/main.mk
index bcb642398e95a65990fcddd5578ff0eebca7336f..2dc7f9ce788bcbfad88ab6932c92c768877d7441 100644 (file)
--- a/main.mk
+++ b/main.mk
@@ -165,8 +165,8 @@ LDFLAGS.icu ?= # -licui18n -licuuc -licudata
 LDFLAGS.soname.libsqlite3 ?=
 # libreadline (or a workalike):
 # To activate readline in the shell: SHELL_OPT = -DHAVE_READLINE=1
-LDFLAGS.readline ?= -lreadline # these vary wildly across platforms
-CFLAGS.readline ?= -I$(prefix)/include/readline
+LDFLAGS.readline ?= -lreadline # these vary across platforms
+CFLAGS.readline ?= -I$(prefix)/include
 # ^^^ When using linenoise instead of readline, do something like:
 # SHELL_OPT += -DHAVE_LINENOISE=1
 # CFLAGS.readline = -I$(HOME)/linenoise $(HOME)/linenoise/linenoise.c

diff --git a/manifest b/manifest
index 4069de9c00185aa964249eba620d944fa4df49aa..6d5872463f3eec0f8089cbe5af6444cf4cbe97c1 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Add\sautosetup/README.md\s-\smaintenance-related\sdocs\sfor\sSQLite\sdevelopers\s(e.g.\show\sto\supdate\sautosetup).\sStart\smarking\sup\sthe\sproj.tcl\sAPIs\swith\sautosetup's\sdoc\smarkup\sso\sthat\sthey\sappear\sin\sthe\s./configure\s--reference\soutput.
-D 2024-11-06T04:38:05.379
+C Add\sa\ssection\sto\sautosetup/README.md\sdescribing\sthe\smotivations\sfor\sthe\smore\sglaring\sdesign\sdecisions.
+D 2024-11-06T05:54:27.295
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md c5b4009dca54d127d2d6033c22fd9cc34f53bedb6ef12c7cbaa468381c74ab28
@@ -37,7 +37,7 @@ F autoconf/tea/win/rules.vc 94a18c3e453535459b4a643983acca52fb8756e79055bd2ad4b0
 F autoconf/tea/win/targets.vc 96a25a1fa6e9e9cfb348fd3760a5395b4ce8acafc8ed10f0412937ec200d5dbd
 F autosetup/LICENSE 41a26aebdd2cd185d1e2b210f71b7ce234496979f6b35aef2cbf6b80cbed4ce4
 F autosetup/README.autosetup a78ff8c4a3d2636a4268736672a74bf14a82f42687fcf0631a70c516075c031e
-F autosetup/README.md 94a117db60b2a8efbfed58e548809631f1941a8df9c3c6a356080771b772e31c
+F autosetup/README.md 1dfdbe705c95400a722f0a012b6780ad2c7f12948d15cbdcbf95e030b46c4824
 F autosetup/autosetup 9416ffdcdd6e2dbf7f6d1e5c890078518930f8af7722a950eacc28c7f151d2d6 x
 F autosetup/autosetup-config.guess dfa101c5e8220e864d5e9c72a85e87110df60260d36cb951ad0a85d6d9eaa463 x
 F autosetup/autosetup-config.sub a38fb074d0dece01cf919e9fb534a26011608aa8fa606490864295328526cd73 x
@@ -699,7 +699,7 @@ F ext/wasm/tests/opfs/concurrency/test.js d08889a5bb6e61937d0b8cbb78c9efbefbf65a
 F ext/wasm/tests/opfs/concurrency/worker.js 0a8c1a3e6ebb38aabbee24f122693f1fb29d599948915c76906681bb7da1d3d2
 F ext/wasm/wasmfs.make bc8bb227f35d5bd3863a7bd2233437c37472a0d81585979f058f9b9b503bef35
 F magic.txt 5ade0bc977aa135e79e3faaea894d5671b26107cc91e70783aa7dc83f22f3ba0
-F main.mk ef087df40894cf2c024ec5f4d763853616c9616b073fb86b71146f11fa003af3
+F main.mk 949721d1f7400fd9f2c9a8818d66eed7b4c5937c9fd2635f8364755858ddcc78
 F mptest/config01.test 3c6adcbc50b991866855f1977ff172eb6d901271
 F mptest/config02.test 4415dfe36c48785f751e16e32c20b077c28ae504
 F mptest/crash01.test 61e61469e257df0850df4293d7d4d6c2af301421
@@ -2200,8 +2200,8 @@ F tool/version-info.c 3b36468a90faf1bbd59c65fd0eb66522d9f941eedd364fabccd7227350
 F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7
 F tool/warnings.sh 49a486c5069de041aedcbde4de178293e0463ae9918ecad7539eedf0ec77a139
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P 9724b747caa926bca09653ea6ac3c0f7869824c9a476eb81f03e1a6763552da1
-R 22b44d94fb3a53e904cadda0982c176f
+P aa6213767f0d7e63c753e33aadb95cbeb8e522c22f2fe1bbfa4df66bea6e3380
+R 31c89bc32b0e171b0e74463a095b8565
 U stephan
-Z e3f63aefb44fb343dd26a948d9892eb7
+Z 316096fa02be870ff4dfd5f1350db8c8
 # Remove this line to create a well-formed Fossil manifest.

diff --git a/manifest.uuid b/manifest.uuid
index 2c9936220705446e9527f105adf428286501660d..ef952f7545739bf3e7383024d7c0cc6d03d11b95 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-aa6213767f0d7e63c753e33aadb95cbeb8e522c22f2fe1bbfa4df66bea6e3380
+c0940a822a63bff74585bd37401eca92f74ddf9fe95748d2474039ee9b2bd9b6