General updates to autosetup/README.md.

FossilOrigin-Name: be8ad5cf579662c54b7e7bc492d8ca03b1f9032c5dad9a6b20590ca1ac00840b

autosetup/README.md

@@ -14,7 +14,7 @@ build infrastructure. It is not an [Autosetup][] reference.
   - Symbolic Names of Feature Flags
   - Do Not Update Global Shared State
 - [Updating Autosetup](#updating)
-  - [Patching Autosetup for Project-local changes](#patching)
+  - ***[Patching Autosetup for Project-local changes](#patching)***
 
 ------------------------------------------------------------------------
 
@@ -42,12 +42,13 @@ following files:
   (e.g. Fossil), and personal projects of SQLite's developers.  It is
   essentially an amalgamation of a decade's worth of autosetup-related
   utility code.
-- [auto.def][]: the primary driver for the `./configure` process.
-  When we talk about "the configure script," we're referring to
-  this file.
 - [sqlite-config.tcl][]: utility code which is too project-specific
   for `proj.tcl`. We split this out of `auto.def` so that it can be
   used by both `auto.def` and...
+- [auto.def][]: the primary driver for the `./configure` process.
+  When we talk about "the configure script," we're technically
+  referring to this file, though it actually contains very little
+  of the TCL code.
 - [autoconf/auto.def][]: the main driver script for the "autoconf"
   bundle's configure script. It is essentially a slightly trimmed-down
   version of the main `auto.def` file. The `autoconf` dir was ported
@@ -61,11 +62,11 @@ Autosetup API Tips
 
 This section briefly covers only APIs which are frequently useful in
 day-to-day maintenance and might not be immediately recognized as such
-obvious from a casual perusal of the relevant TCL files. The complete
-docs of those with `proj-` prefix can be found in [proj.tcl][] and
-those with an `sqlite-` prefix are in [sqlite-config.tcl][]. The
-others are scattered around [the TCL files in
-./autosetup](/dir/autosetup).
+from a casual perusal of the relevant TCL files. The complete docs of
+those with `proj-` prefix can be found in [proj.tcl][] and those with
+an `sqlite-` prefix are in [sqlite-config.tcl][]. The others are part
+of Autosetup's core packages and are scattered around [the TCL files
+in ./autosetup](/dir/autosetup).
 
 In (mostly) alphabetical order:
 
@@ -83,19 +84,14 @@ In (mostly) alphabetical order:
     Works like `get-env` but will, if that function finds no match,
     look for a file named `./.env-$VAR` and, if found, return its
     trimmed contents. This can be used, e.g., to set a developer's
-    local preferences for the default `CFLAGS`.
-
-- **`define-for-opt flag defineName ?checkingMsg? ?yesVal=1? ?noVal=0?`**\  
-  `[define $defineName]` to either `$yesVal` or `$noVal`, depending on
-  whether `--$flag` is truthy or not. `$checkingMsg` is a
-  human-readable description of the check being made, e.g. "enable foo?"
-  If no `checkingMsg` is provided, the operation is silent.\  
-  Potential TODO: change the final two args to `-yes` and `-no`
-  flags. They're rarely needed, though: search [auto.def][] for
-  `TSTRNNR_OPTS` for an example of where they are used.
+    local preferences for the default `CFLAGS`.\  
+    Tip: adding `-O0` to `.env-CFLAGS` reduces rebuild times
+    considerably at the cost of performance in `make devtest` and the
+    like.
 
 - **`proj-fatal msg`**\  
-  Emits `$msg` to stderr and exits with non-zero.
+  Emits `$msg` to stderr and exits with non-zero. Its differences from
+  autosetup's `user-error` are purely cosmetic.
 
 - **`proj-if-opt-truthy flag thenScript ?elseScript?`**\  
   Evals `thenScript` if the given `--flag` is truthy, else it
@@ -117,7 +113,10 @@ In (mostly) alphabetical order:
   else 0. This distinction can be used to determine, e.g., whether
   `--with-readline` was provided or whether we're searching for
   readline by default. In the former case, failure to find it should
-  be treated as fatal, where in the latter case it's not.
+  be treated as fatal, where in the latter case it's not.\  
+  Unlike most functions which deal with `--flags`, this one does not
+  validate that `$FLAG` is a registered flag so will not fail fatally
+  if `$FLAG` is not registered as an Autosetup option.
 
 - **`proj-val-truthy value`**\  
   Returns 1 if `$value` is "truthy," See `proj-opt-truthy` for the definition
@@ -139,6 +138,15 @@ In (mostly) alphabetical order:
   The shell-specific counterpart of `sqlite-add-feature-flag` which
   only adds the given flag(s) to the CLI-shell-specific CFLAGS.
 
+- **`sqlite-configure BUILD-NAME {script}`**\  
+  This is where all configure `--flags` are defined for all known
+  build modes ("canonical" or "autoconf"). After processing all flags,
+  this function runs `$script`, which contains the build-mode-specific
+  configuration bits, and then runs any finalization bits which are
+  common to all build modes. The `auto.def` files are intended to contain
+  exactly two commands:
+  `use sqlite-config; sqlite-configure BUILD-NAME {script}`
+
 - **`user-notice msg`**\  
   Queues `$msg` to be sent to stderr, but does not emit it until
   either `show-notices` is called or the next time autosetup would
@@ -152,13 +160,18 @@ In (mostly) alphabetical order:
 Ensuring TCL Compatibility
 ========================================================================
 
-It is important that any TCL files used by the configure process
-remain compatible with both [JimTCL][] and the canonical TCL. Though
-JimTCL has outstanding compatibility with canonical TCL, it does have
-a few corners with incompatibilities, e.g. regular expressions. If a
-script runs in JimTCL without using any JimTCL-specific features, then
-it's a certainty that it will run in canonical TCL as well. The
-opposite, however, is not _always_ the case.
+One of the significant benefits of using Autosetup is that (A) this
+project uses many TCL scripts in the build process and (B) Autosetup
+comes with a TCL interpreter named [JimTCL][].
+
+It is important that any TCL files used by the configure process and
+makefiles remain compatible with both [JimTCL][] and the canonical
+TCL. Though JimTCL has outstanding compatibility with canonical TCL,
+it does have a few corners with incompatibilities, e.g. regular
+expressions. If a script runs in JimTCL without using any
+JimTCL-specific features, then it's a certainty that it will run in
+canonical TCL as well. The opposite, however, is not _always_ the
+case.
 
 When [`./configure`](/file/configure) is run, it goes through a
 bootstrapping process to find a suitable TCL with which to run the
@@ -187,14 +200,17 @@ compatibility across TCL implementations:
    before looking for a system-level `tclsh`. Be aware, though, that
    `make distclean` will remove that file.
 
-**Note that `jimsh0` is distinctly different from the `jimsh`** which
-gets built for code-generation purposes.  The latter requires
+**Note that `./jimsh0` is distinctly different from the `./jimsh`**
+which gets built for code-generation purposes.  The latter requires
 non-default build flags to enable features which are
 platform-dependent, most notably to make its `[file normalize]` work.
 This means, for example, that the configure script and its utility
 APIs must not use `[file normalize]`, but autosetup provides a
 TCL-only implementation of `[file-normalize]` (note the dash) for
-portable use in the configure script.
+portable use in the configure script. Contrariwise, code-generation
+scripts invoked via `make` may use `[file normalize]`, as they'll use
+`./jimsh` or `tclsh` instead of `./jimsh0`.
+
 
 Known TCL Incompatibilities
 ------------------------------------------------------------------------
@@ -221,6 +237,7 @@ A summary of known incompatibilities in JimTCL
   - `regsub` does not support the `\y` flag. A workaround is demonstrated
     in [](/info/c2e5dd791cce3ec4).
 
+
 <a name="conventions"></a>
 Design Conventions
 ========================================================================
@@ -247,8 +264,9 @@ dots are not permitted.
 The `X.y` convention is used in the makefiles primarily because the
 person who did the initial port finds that considerably easier on the
 eyes and fingers. In practice, the `X_Y` form of such exports is used
-exactly once in [Makefile.in][], where it's translated into into `X.y`
-form for consumption by [Makefile.in][] and [main.mk][]. For example:
+exactly once in [Makefile.in][], where it's translated from `@X_Y@`
+into into `X.y` form for consumption by [Makefile.in][] and
+[main.mk][]. For example:
 
 >
 ```
@@ -265,9 +283,9 @@ of taste, for which there is no accounting.)
 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 amend
-global flags such as `LIBS`, `LDFLAGS`, and `CFLAGS`[^as-cflags].  That's
+In both the legacy Autotools-driven build and common Autosetup usage,
+feature tests performed by the configure script may amend global flags
+such as `LIBS`, `LDFLAGS`, and `CFLAGS`[^as-cflags].  That's
 appropriate for a makefile which builds a single deliverable, but less
 so for makefiles which produce multiple deliverables. Drawbacks of
 that approach include:
@@ -275,8 +293,8 @@ that approach include:
 - It's unlikely that every single deliverable will require the same
   core set of those flags.
 - It can be difficult to determine the origin of any given change to
-  that global state because those changes are hidden behind voodoo performed
-  outside the immediate visibility of the configure script's
+  that global state because those changes are hidden behind voodoo
+  performed outside the immediate visibility of the configure script's
   maintainer.
 - It can force the maintainers of the configure script to place tests
   in a specific order so that the resulting flags get applied at
@@ -357,12 +375,11 @@ Patching Autosetup for Project-local Changes
 
 Autosetup reserves the flag name **`--debug`** for its own purposes,
 and its own special handling of `--enable-...` flags makes `--debug`
-an alias for `--enable-debug`. As we have a long history of using
-`--enable-debug` for this project's own purposes, we patch autosetup
-to use the name `--autosetup-debug` in place of `--debug`. That
-requires (as of this writing) four small edits in
-[](/file/autosetup/autosetup), as demonstrated in [check-in
-3296c8d3](/info/3296c8d3).
+an alias for `--enable-debug`. As this project has a long history of
+using `--enable-debug`, we patch autosetup to use the name
+`--autosetup-debug` in place of `--debug`. That requires (as of this
+writing) four small edits in [](/file/autosetup/autosetup), as
+demonstrated in [check-in 3296c8d3](/info/3296c8d3).
 
 If autosetup is upgraded and this patch is _not_ applied the invoking
 `./configure` will fail loudly because of the declaration of the

manifest

@@ -1,5 +1,5 @@
-C Update\sthe\sdocs\sin\stool/mkccode.tcl\sto\sreflect\sthat\sit's\smore\sgeneric\sthan\sit\swas\swhen\sthe\sdocs\swere\swritten.\sChange\sthe\sshebang\sline\sto\suse\s/bin/env\stclsh\sinstead\sof\sa\shard-coded\stclsh\spath.
-D 2025-03-18T10:28:56.725
+C General\supdates\sto\sautosetup/README.md.
+D 2025-03-18T11:36:15.450
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md e108e1e69ae8e8a59e93c455654b8ac9356a11720d3345df2a4743e9590fb20d
@@ -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 b306314e8a87ccf873cb5b2a360c4a27bbf841df5b76f3acbd65322cff165476
+F autosetup/README.md f98cc827a162a1da4877e9656d749d414ba3f408d457d30e029afc66590c00c3
 F autosetup/autosetup 74a9782b68d07934510190fbd03fc6ad92e63f0ea3b5cbffa5f0bd271ad60f01 x
 F autosetup/autosetup-config.guess dfa101c5e8220e864d5e9c72a85e87110df60260d36cb951ad0a85d6d9eaa463 x
 F autosetup/autosetup-config.sub a38fb074d0dece01cf919e9fb534a26011608aa8fa606490864295328526cd73 x
@@ -2215,8 +2215,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 1a5283d7dab210badb8a33eac29f44dc8c1c210ffb5ef84f43e348170aa406a6
-R a929af68b23ab89a4ef69e835299c074
+P 9300f7f42dfd143f77fd51aa9e080099540854d36b6997ab1a16be7d77f78d8e
+R a74ff5093dd14720da044ecaa9143a8b
 U stephan
-Z cc5c9a3f1559d25c8e48b1b5fb513517
+Z 7470894fe299edfa712004a6589105cc
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-9300f7f42dfd143f77fd51aa9e080099540854d36b6997ab1a16be7d77f78d8e
+be8ad5cf579662c54b7e7bc492d8ca03b1f9032c5dad9a6b20590ca1ac00840b