Mercurial

annotate third_party/sqlite3/autosetup/README.md @ 178:94705b5986b3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added WRK and luajit for load testing.
author MrJuneJune <me@mrjunejune.com>
date Thu, 22 Jan 2026 20:10:30 -0800
parents 589bab390fb4
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
167
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
1 Maintaining Autosetup in the SQLite Tree
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
2 ========================================================================
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
3
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
4 This document provides some tips and reminders for the SQLite
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
5 developers regarding using and maintaining the [Autosetup][]-based
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
6 build infrastructure. It is not an [Autosetup][] reference.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
7
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
8 **Table of Contents**:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
9
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
10 - [Autosetup API Reference](#apiref)
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
11 - [API Tips](#apitips)
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
12 - [Ensuring TCL Compatibility](#tclcompat)
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
13 - [Design Conventions](#conventions)
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
14 - Symbolic Names of Feature Flags
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
15 - Do Not Update Global Shared State
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
16 - [Updating Autosetup](#updating)
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
17 - ***[Patching Autosetup for Project-local changes](#patching)***
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
18 - [Branch-specific Customization](#branch-customization)
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
19
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
20
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
21 ------------------------------------------------------------------------
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
22
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
23 <a name="apiref"></a>
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
24 Autosetup API Reference
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
25 ========================================================================
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
26
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
27 The Autosetup API is quite extensive and can be read either in
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
28 the [files in the `autosetup` dir](/dir/autosetup) or using:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
29
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
30 >
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
31 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
32 $ ./configure --reference | less
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
33 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
34
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
35 That will include any docs from any TCL files in the `./autosetup` dir
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
36 which contain certain (simple) markup defined by autosetup.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
37
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
38 This project's own configuration-related TCL code is spread across the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
39 following files:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
40
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
41 - [proj.tcl][]: project-agnostic utility code for autosetup-driven
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
42 projects. This file is designed to be shared between this project,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
43 other projects managed under the SQLite/Hwaci umbrella
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
44 (e.g. Fossil), and personal projects of SQLite's developers. It is
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
45 essentially an amalgamation of a decade's worth of autosetup-related
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
46 utility code.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
47 - [sqlite-config.tcl][]: utility code which is too project-specific
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
48 for `proj.tcl`. We split this out of `auto.def` so that it can be
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
49 used by both `auto.def` and...
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
50 - [auto.def][]: the primary driver for the `./configure` process.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
51 When we talk about "the configure script," we're technically
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
52 referring to this file, though it actually contains very little
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
53 of the TCL code.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
54 - [autoconf/auto.def][]: the main driver script for the "autoconf"
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
55 bundle's configure script. It is essentially a slightly trimmed-down
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
56 version of the main `auto.def` file. The `autoconf` dir was ported
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
57 from the Autotools to Autosetup in the 3.49.0 dev cycle but retains
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
58 the "autoconf" name to minimize downstream disruption.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
59
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
60
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
61 <a name="apitips"></a>
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
62 Autosetup API Tips
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
63 ========================================================================
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
64
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
65 This section briefly covers only APIs which are frequently useful in
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
66 day-to-day maintenance and might not be immediately recognized as such
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
67 from a casual perusal of the relevant TCL files. The complete docs of
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
68 those with `proj-` prefix can be found in [proj.tcl][] and those with
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
69 an `sqlite-` prefix are in [sqlite-config.tcl][]. The others are part
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
70 of Autosetup's core packages and are scattered around [the TCL files
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
71 in ./autosetup](/dir/autosetup).
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
72
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
73 In (mostly) alphabetical order:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
74
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
75 - **`file-isexec filename`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
76 Should be used in place of `[file executable]`, as it will also
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
77 check for `${filename}.exe` on Windows platforms. However, on such
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
78 platforms it also assumes that _any_ existing file is executable.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
79
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
80 - **`get-env VAR ?default?`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
81 Will fetch an "environment variable" from the first of either: (1) a
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
82 KEY=VALUE passed to the configure script or (2) the system's
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
83 environment variables. Not to be confused with `getenv`, which only
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
84 does the latter and is rarely, if ever, useful in this tree.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
85 - **`proj-get-env VAR ?default?`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
86 Works like `get-env` but will, if that function finds no match,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
87 look for a file named `./.env-$VAR` and, if found, return its
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
88 trimmed contents. This can be used, e.g., to set a developer's
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
89 local preferences for the default `CFLAGS`.\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
90 Tip: adding `-O0` to `.env-CFLAGS` reduces rebuild times
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
91 considerably at the cost of performance in `make devtest` and the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
92 like.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
93
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
94 - **`proj-fatal msg`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
95 Emits `$msg` to stderr and exits with non-zero. Its differences from
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
96 autosetup's `user-error` are purely cosmetic.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
97
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
98 - **`proj-if-opt-truthy flag thenScript ?elseScript?`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
99 Evals `thenScript` if the given `--flag` is truthy, else it
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
100 evals the optional `elseScript`.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
101
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
102 - **`proj-indented-notice ?-error? ?-notice? msg`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
103 Breaks its `msg` argument into lines, trims them, and emits them
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
104 with consistent indentation. Exactly how it emits depends on the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
105 flags passed to it (or not), as covered in its docs. This will stick
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
106 out starkly from normal output and is intended to be used only for
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
107 important notices.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
108
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
109 - **`proj-opt-truthy flag`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
110 Returns 1 if `--flag`'s value is "truthy," i.e. one of (1, on,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
111 enabled, yes, true).
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
112
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
113 - **`proj-opt-was-provided FLAG`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
114 Returns 1 if `--FLAG` was explicitly provided to configure,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
115 else 0. This distinction can be used to determine, e.g., whether
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
116 `--with-readline` was provided or whether we're searching for
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
117 readline by default. In the former case, failure to find it should
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
118 be treated as fatal, where in the latter case it's not.\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
119 Unlike most functions which deal with `--flags`, this one does not
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
120 validate that `$FLAG` is a registered flag so will not fail fatally
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
121 if `$FLAG` is not registered as an Autosetup option.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
122
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
123 - **`proj-val-truthy value`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
124 Returns 1 if `$value` is "truthy," See `proj-opt-truthy` for the definition
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
125 of "truthy."
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
126
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
127 - **`proj-warn msg`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
128 Emits `$msg` to stderr. Closely-related is autosetup's `user-notice`
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
129 (described below).
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
130
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
131 - **`sqlite-add-feature-flag ?-shell? FLAG...`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
132 Adds the given feature flag to the CFLAGS which are specific to
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
133 building libsqlite3. It's intended to be passed one or more
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
134 `-DSQLITE_ENABLE_...`, or similar, flags. If the `-shell` flag is
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
135 used then it also passes its arguments to
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
136 `sqlite-add-shell-opt`. This is a no-op if `FLAG` is not provided or
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
137 is empty.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
138
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
139 - **`sqlite-add-shell-opt FLAG...`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
140 The shell-specific counterpart of `sqlite-add-feature-flag` which
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
141 only adds the given flag(s) to the CLI-shell-specific CFLAGS.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
142
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
143 - **`sqlite-configure BUILD-NAME {script}`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
144 This is where all configure `--flags` are defined for all known
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
145 build modes ("canonical" or "autoconf"). After processing all flags,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
146 this function runs `$script`, which contains the build-mode-specific
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
147 configuration bits, and then runs any finalization bits which are
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
148 common to all build modes. The `auto.def` files are intended to contain
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
149 exactly two commands:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
150 `use sqlite-config; sqlite-configure BUILD-NAME {script}`
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
151
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
152 - **`user-notice msg`**\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
153 Queues `$msg` to be sent to stderr, but does not emit it until
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
154 either `show-notices` is called or the next time autosetup would
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
155 output something (it internally calls `show-notices`). This can be
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
156 used to generate warnings between a "checking for..." message and
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
157 its resulting "yes/no/whatever" message in such a way as to not
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
158 spoil the layout of such messages.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
159
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
160
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
161 <a name="tclcompat"></a>
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
162 Ensuring TCL Compatibility
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
163 ========================================================================
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
164
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
165 One of the significant benefits of using Autosetup is that (A) this
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
166 project uses many TCL scripts in the build process and (B) Autosetup
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
167 comes with a TCL interpreter named [JimTCL][].
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
168
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
169 It is important that any TCL files used by the configure process and
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
170 makefiles remain compatible with both [JimTCL][] and the canonical
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
171 TCL. Though JimTCL has outstanding compatibility with canonical TCL,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
172 it does have a few corners with incompatibilities, e.g. regular
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
173 expressions. If a script runs in JimTCL without using any
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
174 JimTCL-specific features, then it's a certainty that it will run in
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
175 canonical TCL as well. The opposite, however, is not _always_ the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
176 case.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
177
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
178 When [`./configure`](/file/configure) is run, it goes through a
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
179 bootstrapping process to find a suitable TCL with which to run the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
180 autosetup framework. The first step involves [finding or building a
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
181 TCL shell](/file/autosetup/autosetup-find-tclsh). That will first
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
182 search for an available `tclsh` (under several common names,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
183 e.g. `tclsh8.6`) before falling back to compiling the copy of
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
184 `jimsh0.c` included in the source tree. i.e. it will prefer to use a
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
185 system-installed TCL for running the configure script. Once it finds
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
186 (or builds) a TCL shell, it then runs [a sanity test to ensure that
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
187 the shell is suitable](/file/autosetup/autosetup-test-tclsh) before
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
188 using it to run the main autosetup app.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
189
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
190 There are two simple ways to ensure that running of the configure
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
191 process uses JimTCL instead of the canonical `tclsh`, and either
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
192 approach provides equally high assurances about configure script
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
193 compatibility across TCL implementations:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
194
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
195 1. Build on a system with no `tclsh` installed in the `$PATH`. In that
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
196 case, the configure process will fall back to building the in-tree
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
197 copy of JimTCL.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
198
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
199 2. Manually build `./jimsh0` in the top of the checkout with:\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
200 `cc -o jimsh0 autosetup/jimsh0.c`\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
201 With that in place, the configure script will prefer to use that
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
202 before looking for a system-level `tclsh`. Be aware, though, that
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
203 `make distclean` will remove that file.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
204
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
205 **Note that `./jimsh0` is distinctly different from the `./jimsh`**
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
206 which gets built for code-generation purposes. The latter requires
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
207 non-default build flags to enable features which are
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
208 platform-dependent, most notably to make its `[file normalize]` work.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
209 This means, for example, that the configure script and its utility
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
210 APIs must not use `[file normalize]`, but autosetup provides a
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
211 TCL-only implementation of `[file-normalize]` (note the dash) for
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
212 portable use in the configure script. Contrariwise, code-generation
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
213 scripts invoked via `make` may use `[file normalize]`, as they'll use
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
214 `./jimsh` or `tclsh` instead of `./jimsh0`.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
215
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
216
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
217 Known TCL Incompatibilities
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
218 ------------------------------------------------------------------------
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
219
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
220 A summary of known incompatibilities in JimTCL
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
221
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
222 - **CRNL line endings**: prior to 2025-02-05 `fconfigure -translation ...`
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
223 was a no-op in JimTCL, and it emits CRNL line endings by default on
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
224 Windows. Since then, it supports `-translation binary`, which is
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
225 close enough to `-translation lf` for our purposes. When working
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
226 with files using the `open` command, it is important to use mode
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
227 `"rb"` or `"wb"`, as appropriate, so that the output does not get
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
228 CRNL-mangled on Windows.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
229
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
230 - **`file copy`** does not support multiple source files. See
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
231 [](/info/61f18c96183867fe) for a workaround.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
232
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
233 - **Regular expressions**:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
234
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
235 - Patterns treat `\nnn` octal values as back-references (which it
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
236 does not support). Those can be reformulated as demonstrated in
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
237 [](/info/aeac23359bb681c0).
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
238
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
239 - `regsub` does not support the `\y` flag. A workaround is demonstrated
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
240 in [](/info/c2e5dd791cce3ec4).
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
241
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
242
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
243 <a name="conventions"></a>
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
244 Design Conventions
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
245 ========================================================================
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
246
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
247 This section describes the motivations for the most glaring of the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
248 build's design decisions, in particular how they deviate from
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
249 historical, or even widely-conventional, practices.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
250
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
251 Symbolic Names of Feature Flags
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
252 ------------------------------------------------------------------------
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
253
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
254 Historically, the project's makefile has exclusively used
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
255 `UPPER_UNDERSCORE` form for makefile variables. This build, however,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
256 primarily uses `X.y` format, where `X` is often a category label,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
257 e.g. `CFLAGS`, and `y` is the specific instance of that category,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
258 e.g. `CFLAGS.readline`.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
259
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
260 When the configure script exports flags for consumption by filtered
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
261 files, e.g. [Makefile.in][] and the generated
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
262 `sqlite_cfg.h`, it does so in the more conventional `X_Y` form because
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
263 those flags get exported as as C `#define`s to `sqlite_cfg.h`, where
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
264 dots are not permitted.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
265
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
266 The `X.y` convention is used in the makefiles primarily because the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
267 person who did the initial port finds that considerably easier on the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
268 eyes and fingers. In practice, the `X_Y` form of such exports is used
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
269 exactly once in [Makefile.in][], where it's translated from `@X_Y@`
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
270 into into `X.y` form for consumption by [Makefile.in][] and
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
271 [main.mk][]. For example:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
272
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
273 >
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
274 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
275 LDFLAGS.shobj = @SHOBJ_LDFLAGS@
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
276 LDFLAGS.zlib = @LDFLAGS_ZLIB@
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
277 LDFLAGS.math = @LDFLAGS_MATH@
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
278 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
279
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
280 (That first one is defined by autosetup, and thus applies "LDFLAGS" as
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
281 the suffix rather than the prefix. Which is more legible is a matter
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
282 of taste, for which there is no accounting.)
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
283
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
284
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
285 Do Not Update Global Shared State
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
286 ------------------------------------------------------------------------
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
287
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
288 In both the legacy Autotools-driven build and common Autosetup usage,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
289 feature tests performed by the configure script may amend global flags
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
290 such as `LIBS`, `LDFLAGS`, and `CFLAGS`[^as-cflags]. That's
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
291 appropriate for a makefile which builds a single deliverable, but less
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
292 so for makefiles which produce multiple deliverables. Drawbacks of
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
293 that approach include:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
294
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
295 - It's unlikely that every single deliverable will require the same
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
296 core set of those flags.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
297 - It can be difficult to determine the origin of any given change to
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
298 that global state because those changes are hidden behind voodoo
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
299 performed outside the immediate visibility of the configure script's
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
300 maintainer.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
301 - It can force the maintainers of the configure script to place tests
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
302 in a specific order so that the resulting flags get applied at
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
303 the correct time and/or in the correct order.\
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
304 (A real-life example: before the approach described below was taken
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
305 to collecting build-time flags, the test for `-rpath` had to come
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
306 _after_ the test for zlib because the results of the `-rpath` test
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
307 implicitly modified global state which broke the zlib feature
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
308 test. Because the feature tests no longer (intentionally) modify
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
309 shared global state, that is not an issue.)
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
310
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
311 In this build, cases where feature tests modify global state in such a
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
312 way that it may impact later feature tests are either (A) very
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
313 intentionally defined to do so (e.g. the `--with-wasi-sdk` flag has
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
314 invasive side-effects) or (B) are oversights (i.e. bugs).
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
315
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
316 This tree's [configure script][auto.def], [utility APIs][proj.tcl],
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
317 [Makefile.in][], and [main.mk][] therefore strive to separate the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
318 results of any given feature test into its own well-defined
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
319 variables. For example:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
320
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
321 - The linker flags for zlib are exported from the configure script as
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
322 `LDFLAGS_ZLIB`, which [Makefile.in][] and [main.mk][] then expose as
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
323 `LDFLAGS.zlib`.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
324 - `CFLAGS_READLINE` (a.k.a. `CFLAGS.readline`) contains the `CFLAGS`
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
325 needed for including `libreadline`, `libedit`, or `linenoise`, and
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
326 `LDFLAGS_READLINE` (a.k.a. `LDFLAGS.readline`) is its link-time
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
327 counterpart.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
328
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
329 It is then up to the Makefile to apply and order the flags however is
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
330 appropriate.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
331
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
332 At the end of the configure script, the global `CFLAGS` _ideally_
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
333 holds only flags which are either relevant to all targets or, failing
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
334 that, will have no unintended side-effects on any targets. That said:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
335 clients frequently pass custom `CFLAGS` to `./configure` or `make` to
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
336 set library-level feature toggles, e.g. `-DSQLITE_OMIT_FOO`, in which
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
337 case there is no practical way to avoid "polluting" the builds of
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
338 arbitrary makefile targets with those. _C'est la vie._
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
339
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
340
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
341 [^as-cflags]: But see this article for a detailed discussion of how
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
342 autosetup currently deals specifically with CFLAGS:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
343 <https://msteveb.github.io/autosetup/articles/handling-cflags/>
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
344
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
345
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
346 <a name="updating"></a>
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
347 Updating Autosetup
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
348 ========================================================================
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
349
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
350 Updating autosetup is, more often than not, painless. It requires having
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
351 a checked-out copy of [the autosetup git repository][autosetup-git]:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
352
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
353 >
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
354 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
355 $ git clone https://github.com/msteveb/autosetup
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
356 $ cd autosetup
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
357 # Or, if it's already checked out:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
358 $ git pull
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
359 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
360
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
361 Then, from the top-most directory of an SQLite checkout:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
362
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
363 >
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
364 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
365 $ /path/to/autosetup-checkout/autosetup --install .
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
366 $ fossil status # show the modified files
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
367 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
368
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
369 Unless the upgrade made any incompatible changes (which is exceedingly
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
370 rare), that's all there is to it. After that's done, **apply a patch
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
371 for the change described in the following section**, test the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
372 configure process, and check it in.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
373
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
374 <a name="patching"></a>
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
375 Patching Autosetup for Project-local Changes
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
376 ------------------------------------------------------------------------
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
377
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
378 Autosetup reserves the flag name **`--debug`** for its own purposes,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
379 and its own special handling of `--enable-...` flags makes `--debug`
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
380 an alias for `--enable-debug`. As this project has a long history of
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
381 using `--enable-debug`, we patch autosetup to use the name
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
382 `--autosetup-debug` in place of `--debug`. That requires (as of this
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
383 writing) four small edits in
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
384 [/autosetup/autosetup](/file/autosetup/autosetup), as demonstrated in
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
385 [check-in 3296c8d3](/info/3296c8d3).
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
386
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
387 If autosetup is upgraded and this patch is _not_ applied the invoking
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
388 `./configure` will fail loudly because of the declaration of the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
389 `debug` flag in `auto.def` - duplicated flags are not permitted.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
390
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
391 <a name="branch-customization"></a>
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
392 Branch-specific Customization
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
393 ========================================================================
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
394
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
395 Certain vendor-specific branches require slight configure script
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
396 customization. Rather than editing `sqlite-config.tcl` for this,
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
397 which frequently leads to merge conflicts, the following approach
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
398 is recommended:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
399
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
400 In the vendor-specific branch, create a file named
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
401 `autosetup/sqlite-custom.tcl`.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
402
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
403 That file should contain the following content...
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
404
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
405 If flag customization is required, add:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
406
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
407 >
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
408 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
409 proc sqlite-custom-flags {} {
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
410 # If any existing --flags require different default values
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
411 # then call:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
412 options-defaults {
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
413 flag-name new-default-value
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
414 ...
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
415 }
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
416 # ^^^ That will replace the default value but will not update
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
417 # the --help text, which may lead to some confusion:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
418 # https://github.com/msteveb/autosetup/issues/77
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
419
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
420 return {
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
421 {*} {
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
422 new-flag-name => {Help text}
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
423 ...
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
424 }
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
425 }; #see below
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
426 }
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
427 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
428
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
429 That function must return either an empty string or a list in the form
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
430 used internally by [sqlite-config.tcl][]'s `sqlite-configure`.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
431
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
432 Next, define:
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
433
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
434 >
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
435 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
436 proc sqlite-custom-handle-flags {} {
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
437 ... do any custom flag handling here ...
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
438 }
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
439 ```
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
440
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
441 That function, if defined, will be called relatively late in the
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
442 configure process, before any filtered files are generated but after
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
443 all other significant processing.
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
444
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
445
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
446 [Autosetup]: https://msteveb.github.io/autosetup/
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
447 [auto.def]: /file/auto.def
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
448 [autoconf/auto.def]: /file/autoconf/auto.def
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
449 [autosetup-git]: https://github.com/msteveb/autosetup
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
450 [proj.tcl]: /file/autosetup/proj.tcl
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
451 [sqlite-config.tcl]: /file/autosetup/sqlite-config.tcl
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
452 [Makefile.in]: /file/Makefile.in
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
453 [main.mk]: /file/main.mk
589bab390fb4 [ThirdParty] Added sqlite3 to the third_party.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
454 [JimTCL]: https://jim.tcl.tk