Mercurial

annotate third_party/sqlite3/autosetup/README.md @ 279:b3b547563ec7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add Google connector service and agent wiki Implement the C/Seobeo Google Drive and Gmail connector with encrypted OAuth storage, Zenbu authentication, browser testing, AI tool discovery, chunked HTTP decoding, and Bazel coverage. Consolidate repository guidance into progressive wiki documentation and enforce arena-first allocation for new first-party C code. Co-authored-by: Copilot <[email protected]> Copilot-Session: 84c338fd-0939-4bb3-b7f3-1062eb213e5d
author MrJuneJune <me@mrjunejune.com>
date Mon, 17 Aug 2026 22:22:36 -0700
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