Makefile doc cleanups. No functional changes.

FossilOrigin-Name: 64add0ac706101c53e2d2877fdc0d1ccd071814cae969768d2741cee05f23c01

main.mk

@@ -105,6 +105,9 @@ TCLSH_CMD ?= tclsh
 # JIMSH requires a leading path component, even if it's ./, so that it
 # can be used as a shell command.
 #
+# On Windows platforms, if -DHAVE_REALPATH does not work then try
+# -DHAVE__FULLPATH (note the double-underscore).
+#
 CFLAGS.jimsh ?= -DHAVE_REALPATH
 JIMSH ?= ./jimsh$(T.exe)
 #
@@ -119,12 +122,12 @@ B.tclsh ?= $(JIMSH)
 
 #
 # Autotools-conventional vars which are (in this tree) used only by
-# package installation rules.
+# package installation rules and for generating sqlite3.pc (pkg-config
+# data file).
 #
 # The following ${XYZdir} vars are provided for the sake of clients
 # who expect to be able to override these using autotools-conventional
-# dir name vars. In this build they apply only to installation-related
-# rules.
+# dir name vars.
 #
 prefix      ?= /usr/local
 datadir     ?= $(prefix)/share
@@ -202,17 +205,22 @@ ENABLE_STATIC ?= 1
 #
 # 1 if the amalgamation (sqlite3.c/h) should be built/used, otherwise
 # the library is built from all of its original source files.
+# Certaint tools, like sqlite3$(T.exe), require the amalgamation and
+# will ignore this preference.
 #
 USE_AMALGAMATION ?= 1
 #
 # $(LINK_TOOLS_DYNAMICALLY)
 #
-# If true, certain binaries which typically statically link against
+# If 1, certain binaries which typically statically link against
 # libsqlite3 or its component object files will instead link against
 # the DLL. The caveat is that running such builds from the source tree
 # may require that the user specifically prepend "." to their
 # $LD_LIBRARY_PATH so that the dynamic linker does not pick up a
-# libsqlite3.so from outside the source tree.
+# libsqlite3.so from outside the source tree. Alternately, symlinking
+# the in-build-tree $(libsqlite3.SO) to some dir in the system's
+# library path will work for giving the apps access to the in-tree
+# DLL.
 #
 LINK_TOOLS_DYNAMICALLY ?= 0
 #
@@ -227,16 +235,21 @@ AMALGAMATION_GEN_FLAGS ?= --linemacros=0
 # Preprocessor flags for enabling and disabling specific libsqlite3
 # features (-DSQLITE_OMIT*, -DSQLITE_ENABLE*). The same set of OMIT
 # and ENABLE flags must be passed to the LEMON parser generator and
-# the mkkeywordhash tool as well.
+# the mkkeywordhash tool as well. This is normally set by the
+# configure process, and passing a custom value to a
+# coonfigure-filtered Makefile may not work.
 #
-# Add OPTIONS=... on the make command line to append additional options
-# to the OPT_FEATURE_FLAGS. Note that some flags only work if the
-# build is specifically configured to account for them. Adding them
-# later, when compiling the amalgamation, may or may not work.
+# When using the canonical makefile, add $(OPTIONS)=... on the make
+# command line to append additional options to the
+# $(OPT_FEATURE_FLAGS). Note that some flags, because they influence
+# generation of the SQL parser, only work if the build is specifically
+# configured to account for them. Adding them later, when compiling
+# the amalgamation separately, may or may not work.
 #
-# TO CLARIFY: OPTS=... has historically been expected in some
-# contexts, and is distinctly different from OPTIONS and
-# OPT_FEATURE_FLAGS, but its name is confusingly close to $(OPTIONS).
+# $(OPTS)=... is another way of influencing C compilation. It is
+# distinctly separate from $(OPTIONS) and $(OPT_FEATURE_FLAGS) but,
+# like those, $(OPTS) applies to all invocations of $(T.cc). The
+# configure process does not set either of $(OPTIONS) or $(OPTS).
 #
 OPT_FEATURE_FLAGS ?=
 #
@@ -248,15 +261,17 @@ SHELL_OPT ?=
 #
 # TCL_CONFIG_SH must, for some of the build targets, refer to a valid
 # tclConfig.sh. That script will be used to populate most of the other
-# TCL-related vars the build needs.
+# TCL-related vars the build needs. The core library does not require
+# TCL, but TCL is needed for running tests and certain tools, e.g.
+# sqlite3_analyzer.
 #
 TCL_CONFIG_SH ?=
 #
 # $(HAVE_WASI_SDK) =
 #
-# 1 when building with the WASI SDK. This disables certain build
-# targets. It is expected that the invoker assigns CC to the wasi-sdk
-# CC.
+# Set to 1 when building with the WASI SDK. This disables certain
+# build targets. It is expected that the invoker sets $(CC), $(LD),
+# and $(AR) to their counterparts from the wasi-sdk.
 #
 HAVE_WASI_SDK ?= 0
 #
@@ -312,22 +327,21 @@ T.cc += $(CFLAGS.core) $(CFLAGS.env)
 # The legacy build applied such LDFLAGS to all link operations for all
 # deliverables. The 3.48+ build applies them (as of this writing) more
 # selectively: search this file LDFLAGS.configure to see where they're
-# set. As of this writing, they only affect targets which use
-# $(LDFLAGS.libsqlite3) - see that var's docs for details.
+# set.
 #
 LDFLAGS.configure ?=
 
 #
 # The difference between $(OPT_FEATURE_FLAGS) and $(OPTS) is that the
-# former is historically provided by the configure script, whereas the
-# latter is intended to be provided as arguments to the make
+# former is historically provided by the configure script, whereas
+# $(OPTS) is intended to be provided as arguments to the make
 # invocation.
 #
 T.cc += $(OPT_FEATURE_FLAGS)
 
 #
 # Add in any optional global compilation flags on the make command
-# line ie.  make "OPTS=-DSQLITE_ENABLE_FOO=1 -DSQLITE_OMIT_FOO=1".
+# line i.e.  make "OPTS=-DSQLITE_ENABLE_FOO=1 -DSQLITE_OMIT_FOO=1".
 #
 T.cc += $(OPTS)
 

manifest

@@ -1,5 +1,5 @@
-C Remove\sthe\slibsqlite3.so.3\slink\sfrom\sthe\sinstallation\sprocess,\sas\sit\snow\sserves\sno\sfunctional\spurpose.\sWe\sretain\slibsqlite3.so.0\s(A)\sfor\scompatibility\swith\sclients\slinked\sagainst\slegacy\sbuilds\sand\s(B)\s0\sis\sstill\svalid\sas\sthe\slibrary's\sABI\sversion.
-D 2024-11-22T13:47:12.667
+C Makefile\sdoc\scleanups.\sNo\sfunctional\schanges.
+D 2024-11-22T14:12:18.841
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md e108e1e69ae8e8a59e93c455654b8ac9356a11720d3345df2a4743e9590fb20d
@@ -696,7 +696,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 9c6c9473eb83a72a4cd80aab95c7dd64bb59286c151d5745091a5a178d111c84
+F main.mk b19ce37b58d9378b89e868d9ef9546c0068e5e6b49b02e44e600b752519e888f
 F mptest/config01.test 3c6adcbc50b991866855f1977ff172eb6d901271
 F mptest/config02.test 4415dfe36c48785f751e16e32c20b077c28ae504
 F mptest/crash01.test 61e61469e257df0850df4293d7d4d6c2af301421
@@ -2199,8 +2199,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 c78dcc318a36af123676e54d85fc7f980c21b0ea366d164a96e2d998286d3813
-R c696fe78d3d189a1b874e36c608737fb
+P 91bd9813e04e34e088d5e73bfe2a4f338513363d9a99095a232b811c6b616354
+R 0e0e7948374fb4ea8d89262652e0cc24
 U stephan
-Z 044fe3be3927265c623f70a401222db0
+Z c67cb4da7f21bbdaef588069bb0cb4d5
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-91bd9813e04e34e088d5e73bfe2a4f338513363d9a99095a232b811c6b616354
+64add0ac706101c53e2d2877fdc0d1ccd071814cae969768d2741cee05f23c01