From: stephan Date: Wed, 6 Nov 2024 05:54:27 +0000 (+0000) Subject: Add a section to autosetup/README.md describing the motivations for the more glaring... X-Git-Tag: major-relase~212 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=199925a3529eafd41321c5a5673b4493df9a3a48;p=thirdparty%2Fsqlite.git Add a section to autosetup/README.md describing the motivations for the more glaring design decisions. FossilOrigin-Name: c0940a822a63bff74585bd37401eca92f74ddf9fe95748d2474039ee9b2bd9b6 --- diff --git a/autosetup/README.md b/autosetup/README.md index 8bb2a8c3ae..8b989754a4 100644 --- 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. + 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`. 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. + + +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._ + + 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 bcb642398e..2dc7f9ce78 100644 --- 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 4069de9c00..6d5872463f 100644 --- 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 2c99362207..ef952f7545 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -aa6213767f0d7e63c753e33aadb95cbeb8e522c22f2fe1bbfa4df66bea6e3380 +c0940a822a63bff74585bd37401eca92f74ddf9fe95748d2474039ee9b2bd9b6