From 59ac8f4c7fe534a13bdfeafb1fd3d4585ec4d9fb Mon Sep 17 00:00:00 2001 From: stephan Date: Mon, 21 Oct 2024 16:06:49 +0000 Subject: [PATCH] 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 | 122 +++++++++++++++++++++++++++++++++++++++++--------- manifest | 12 ++--- manifest.uuid | 2 +- 3 files changed, 107 insertions(+), 29 deletions(-) diff --git a/auto.def b/auto.def index 050d3a4af8..2c8a476e90 100644 --- a/auto.def +++ b/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 * } diff --git a/manifest b/manifest index bb21f1d2b6..3b6cbe82b1 100644 --- a/manifest +++ b/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. diff --git a/manifest.uuid b/manifest.uuid index 5807b3fb2d..1b90055c32 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -347a50e66fa17bba997f6cbaa5bd693d029df488e54c24f7e4db47b65e84ce81 +a6a275de3d975fdf7432d71a915b40426a976725ebd81a178b5e80d14cf3a2df