Add docs introducing how to define and use autosetup configure flags. Use -DJIM_COMPAT when building jimsh to force its expr command to be syntax-compatible with canonical TCL.

FossilOrigin-Name: a6a275de3d975fdf7432d71a915b40426a976725ebd81a178b5e80d14cf3a2df

auto.def

@@ -1,9 +1,10 @@
+#/usr/bin/tclsh
+# ^^^ help out editors which guess this file's content type.
+#
 # This is the main autosetup-compatible configure script for the
 # SQLite project.
-global autosetup
 use cc cc-db cc-shared cc-lib hwaci-common
 set DUMP_DEFINES_FILE ./defines.list
-define ENABLE_SHARED 1
 
 # Are we cross-compiling?
 set cross_compiling 0
@@ -27,6 +28,83 @@ if {[get-define host] ne [get-define build]} {
 #
 #   2.1) --enable-tempstore[=no] to --with-tempstore[=no].
 #
+########################################################################
+# A gentle introduction to flags handling in autosetup
+#
+# Reference: https://msteveb.github.io/autosetup/developer/
+#
+# All configure flags must be described in an 'options' call, which
+# must appear very early on in this script. The general syntax is:
+#
+#  FLAG => {Help text}
+#
+# Where FLAG can have any of the following formats:
+#
+#   boolopt            => "a boolean option which defaults to disabled"
+#   boolopt2=1         => "a boolean option which defaults to enabled"
+#   stringopt:         => "an option which takes an argument, e.g. --stringopt=value"
+#   stringopt2:=value  => "an option where the argument is optional and defaults to 'value'"
+#   optalias booltopt3 => "a boolean with a hidden alias. --optalias is not shown in --help"
+#
+# Autosetup does no small amount of specialized handling for flags,
+# especially booleans. Each bool-type --FLAG implicitly gets
+# --enable-FLAG and --disable-FLAG forms, and explicitly adding flags
+# with those prefixes will force them to be boolean flags. e.g. we
+# define a flag "readline", which will be interpreted in one of two
+# ways, depending on how it's invoked and how its default is defined:
+#
+#   --enable-readline ==> boolean true
+#   --disable-readline ==> boolean false
+#
+# Trying to pass --readline or --readline=1 or --readline=0 will
+# result in an "unrecognized option" error, despite the the options
+# call listing the flag as "readline".
+#
+# The behavior described above can lead lead to some confusion when
+# writing help text. For example:
+#
+#   options { json=1 {Disable JSON functions} }
+#
+# The reason the help text says "disable" is because a boolean option
+# defaulting to true is, in the --help text, rendered as:
+#
+#   --disable-json          Disable JSON functions
+#
+# Whereas a bool flag which defaults to false will instead render as:
+#
+#   --enable-FLAG
+#
+# Non-boolean flags, in contrast, use the names specifically given to
+# them in the 'options' invocation. e.g. "with-tcl" is the --with-tcl
+# flag. Autosetup may, however, choose to automatically alter the help
+# text, as demonstrated here:
+#
+#   options {
+#    readline=1           => {Disable readline support}
+#    with-readline-lib:   => {Readline library}
+#    with-readline-inc:   => {Readline include paths}
+#   }
+#
+#   $ ./configure --help | grep readline
+#   --disable-readline      disable readline support
+#   --with-readline-lib     specify readline library
+#   --with-readline-inc     specify readline include paths
+#
+# Note that it prefixed and lower-case the help message. Whether
+# that's a feature or a bug can be debated.
+#
+# Fetching values for flags:
+#
+#   booleans: use one of:
+#     - [opt-bool FLAG] is autosetup's built-in command for this, but we
+#       have some convenience variants:
+#     - [hwaci-opt-truthy FLAG]
+#     - [hwaci-opt-if-truthy FLAG {THEN} {ELSE}]
+#
+#   Non-boolean (i.e. string) flags:
+#     - [opt-val FLAG]
+#
+########################################################################
 options [subst {
   with-debug:=1        => {Enable debug build flags}
   with-tclsh:PATH      => {Full pathname of tclsh to use}
@@ -38,8 +116,8 @@ options [subst {
   editline=0           => {BSD editline support}
   readline=1           => {Disable readline support}
   largefile=1          => {Disable large file support}
-  with-readline-lib    => {readline library}
-  with-readline-inc    => {readline include paths}
+  with-readline-lib:   => {Readline library}
+  with-readline-inc:   => {Readline include paths}
   with-linenoise:DIR   => {}
   amalgamation=1       => {Disable the amalgamation and instead build all files separately}
   load-extension=1     => {Disable loading of external extensions}
@@ -60,7 +138,7 @@ options [subst {
   with-wasi-sdk:=/opt/wasi-sdk
                        => {Top-most dir of the wasi-sdk for a WASI build.}
   with-emsdk:DIR       => {Top-most dir of the Emscripten SDK installation}
-  dump-defines=0       => {Dump autosetup defines to $DUMP_DEFINES_FILE}
+  dump-defines=0       => {Dump autosetup defines to $DUMP_DEFINES_FILE (for build debugging)}
 }]
 
 ########################################################################
@@ -69,20 +147,18 @@ options [subst {
 #  --releasemode: libtool-specific (which we don't have now)
 #
 #
-
-
-set srcdir $autosetup(srcdir)
+set srcdir $::autosetup(srcdir)
 set top_srcdir [get-define abs_top_srcdir]
 puts "srcdir = $srcdir"
 puts "top_srcdir = $top_srcdir"
-set RELEASE [readfile $autosetup(srcdir)/VERSION]
+set RELEASE [readfile $::autosetup(srcdir)/VERSION]
 regsub {([0-9]*\.*[0-9]*).*} $RELEASE {\1} VERSION
 define VERSION $VERSION
 define RELEASE $RELEASE
 puts "RELEASE = $RELEASE"
 puts "VERSION = $VERSION"
 
-define-append SQLITE_AUTOREMAKE cd $autosetup(srcdir) && $top_srcdir/configure {*}$autosetup(argv)
+define-append SQLITE_AUTOREMAKE cd $::autosetup(srcdir) && $top_srcdir/configure {*}$::autosetup(argv)
 
 set outOfTreeBuild 0
 if {![file exists sqlite3.pc.in]} {
@@ -210,6 +286,7 @@ if {"" eq [hwaci-bin-define install]} {
 # cross-compiling.
 define BUILD_CC [get-define CC_FOR_BUILD]
 define BUILD_CFLAGS [get-env CFLAGS {-g}]
+define ENABLE_SHARED 1
 
 ########################################################################
 # Handle --with-wasi-sdk=DIR
@@ -443,9 +520,10 @@ proc hwaci-check-tcl {} {
   define TCL_CONFIG_SH $cfg
   # The historical configure.ac sources tclConfig.sh so that it can
   # use the several TCL_... env vars. We obviously cannot do that from
-  # TCL, so we apply a level of indirection. If the config is not
-  # available, this generates empty-string entries for the various
-  # options we're interested in.
+  # TCL, so we apply a level of indirection which sources that script
+  # then emits the pieces we're interested in as TCL code. If the
+  # config is not available, this emits empty-string entries for the
+  # various options we're interested in.
   eval [exec "${top_srcdir}/tool/tclConfigShToTcl.sh" "[get-define TCL_CONFIG_SH]"]
   #puts "hwaci-check-tcl: with_tclsh=$with_tclsh"
   #puts "hwaci-check-tcl: with_tcl=$with_tcl"
@@ -500,7 +578,6 @@ proc hwaci-check-tcl {} {
     define TCLLIB_RPATH ""
   }
 
-
   if {"" eq $with_tclsh} {
     hwaci-warn "Cannot find a usable tclsh."
   } else {
@@ -513,16 +590,23 @@ hwaci-check-tcl
 ########################################################################
 # Check which TCL to use as a code generator. Prefer jimsh simply
 # because we have it in-tree (it's part of autosetup).
-define CFLAGS_JIMSH {}
+#
+# Building jimsh0.c with -DJIM_COMPAT changes certain behavior to be
+# compatible with canonical TCL. Specifically: jim's [expr] only
+# accepts one arg unless JIM_COMPAT is defined.
+define CFLAGS_JIMSH {-DJIM_COMPAT}
+set useOwnJimsh 0
 puts "Which TCL to use for code generation... "
 set cgtcl jimtcl
 if {[cc-check-functions realpath]} {
   define-append CFLAGS_JIMSH -DHAVE_REALPATH
   define BTCLSH "\$(JIMSH)"
+  set useOwnJimsh 1
 } elseif {[cc-check-functions _fullpath]} {
   # _fullpath() is a Windows API
   define-append CFLAGS_JIMSH -DHAVE__FULLPATH
   define BTCLSH "\$(JIMSH)"
+  set useOwnJimsh 1
 } elseif {"" ne [get-define TCLSH_CMD]} {
   set cgtcl [get-define TCLSH_CMD]
   define BTCLSH "\$(TCLSH_CMD)"
@@ -850,12 +934,6 @@ if {0 && "" ne [get-define CFLAGS_JIMSH]} {
   define-append CFLAGS_JIMSH -DHAVE_LONG_LONG; # SQLite relies on long long, so we know it's available
 }; # JimTCL
 
-if {"" eq [get-define CFLAGS_JIMSH]} {
-  define USE_OWN_JIMSH 0
-} else {
-  define USE_OWN_JIMSH 1
-}
-
 ########################################################################
 # Determine proper rpath-handling flags
 hwaci-check-rpath
@@ -877,7 +955,7 @@ if {0} {
   make-config-header sqlite_cfg.h \
     -bare {SIZEOF_* HAVE_DECL_*} \
     -none {HAVE_CFLAG_* LDFLAGS_* SH_* SQLITE_AUTOREMAKE
-      TARGET_* USE_GCOV USE_OWN_JIMSH TCL_*} \
+      TARGET_* USE_GCOV TCL_*} \
     -auto {HAVE_* PACKAGE_*} \
     -none *
 }

manifest

@@ -1,5 +1,5 @@
-C Merge\strunk\sinto\sautosetup\sbranch.
-D 2024-10-21T13:11:43.662
+C Add\sdocs\sintroducing\show\sto\sdefine\sand\suse\sautosetup\sconfigure\sflags.\sUse\s-DJIM_COMPAT\swhen\sbuilding\sjimsh\sto\sforce\sits\sexpr\scommand\sto\sbe\ssyntax-compatible\swith\scanonical\sTCL.
+D 2024-10-21T16:06:49.337
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -14,7 +14,7 @@ F art/icon-80x90.gif 65509ce3e5f86a9cd64fe7fca2d23954199f31fe44c1e09e208c80fb83d
 F art/sqlite370.eps aa97a671332b432a54e1d74ff5e8775be34200c2
 F art/sqlite370.ico af56c1d00fee7cd4753e8631ed60703ed0fc6e90
 F art/sqlite370.jpg d512473dae7e378a67e28ff96a34da7cb331def2
-F auto.def a392650e2c34738c179f2f7d2c731f90906dcbfb78c236348930997d79281702
+F auto.def aec40855b0321857f679ff53cbb72042e5006260f72d1526db786d0bbcf254e3
 F autoconf/INSTALL 83e4a25da9fd053c7b3665eaaaf7919707915903
 F autoconf/Makefile.am adedc1324b6a87fdd1265ddd336d2fb7d4f36a0e77b86ea553ae7cc4ea239347
 F autoconf/Makefile.fallback 22fe523eb36dfce31e0f6349f782eb084e86a5620b2b0b4f84a2d6133f53f5ac
@@ -2240,8 +2240,8 @@ F vsixtest/vsixtest.tcl 6195aba1f12a5e10efc2b8c0009532167be5e301abe5b31385638080
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 109d441bf1bcdbc01d1f3f2aa145039539fc5aad02f91fc987a0c3702e21809d 9f642b3dbc8febfacad97076030f44e9b40067e27222f2bcb84813c5765d3d2a
-R efd09ae4017e3cac1b5cf47493ec2640
+P 347a50e66fa17bba997f6cbaa5bd693d029df488e54c24f7e4db47b65e84ce81
+R 4ae42afdfc94f9c9fa6e904f46862477
 U stephan
-Z 9f0bf45ab85b7fbd154d377a0233cf43
+Z 1d7aa6ac6fc1c8fa8cc634105d5b45fa
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-347a50e66fa17bba997f6cbaa5bd693d029df488e54c24f7e4db47b65e84ce81
+a6a275de3d975fdf7432d71a915b40426a976725ebd81a178b5e80d14cf3a2df