Work around broken -Os wasm builds by adding the -g3 flag. Unrelated documentation tweaks.

FossilOrigin-Name: f5d6bf8616341037fa3e229edf820d19acef3e0a6207a652b2b143de0a493214

ext/wasm/GNUmakefile

@@ -412,8 +412,14 @@ push-fiddle: $(fiddle_files)
 # painful.
 
 .PHONY: o0 o1 o2 o3 os oz
-o-xtra :=
-#o-xtra += -flto
+o-xtra := -g3
+# ^^^ -g3 is important to keep higher -O levels from mangling (via
+# minification), or outright removing, otherwise working code.
+
+o-xtra += -flto
+# ^^^^ -flto can have a considerably performance boost at -O0 but
+# doubles the build time and seems to have negligible effect on
+# higher optimization levels.
 o0: clean
 	$(MAKE) -e "emcc_opt=-O0 $(o-xtra)" fiddle_opt=-O0
 o1: clean

ext/wasm/api/sqlite3-api-glue.js

@@ -27,11 +27,11 @@ self.sqlite3ApiBootstrap.initializers.push(function(sqlite3){
     /*  "The problem" is that the following isn't type-safe.
         OTOH, nothing about WASM pointers is. */
     /**
-       Add the `.pointer` xWrap() signature entry to extend
-       the `pointer` arg handler to check for a `pointer`
-       property. This can be used to permit, e.g., passing
-       an SQLite3.DB instance to a C-style sqlite3_xxx function
-       which takes an `sqlite3*` argument.
+       Add the `.pointer` xWrap() signature entry to extend the
+       `pointer` arg handler to check for a `pointer` property. This
+       can be used to permit, e.g., passing an sqlite3.oo1.DB instance
+       to a C-style sqlite3_xxx function which takes an `sqlite3*`
+       argument.
     */
     const oldP = wasm.xWrap.argAdapter('pointer');
     const adapter = function(v){

ext/wasm/api/sqlite3-api-prologue.js

@@ -282,7 +282,7 @@ self.sqlite3ApiBootstrap = function sqlite3ApiBootstrap(
        https://www.sqlite.org/c3ref/open.html
 
        - The flags for use with its 3rd argument are installed in this
-       object using the C-cide names, e.g. SQLITE_OPEN_CREATE.
+       object using their C-side names, e.g. SQLITE_OPEN_CREATE.
 
        - If the combination of flags passed to it are invalid,
        behavior is undefined. Thus is is never okay to call this
@@ -293,18 +293,17 @@ self.sqlite3ApiBootstrap = function sqlite3ApiBootstrap(
        and cache-related flags, but they are retained in this
        API for consistency's sake.
 
-       - The final argument to this function specifies the VFS to
-       use, which is largely (but not entirely!) meaningless in
-       the WASM environment. It should always be null or
-       undefined, and it is safe to elide that argument when
-       calling this function.
+       - The final argument to this function specifies the VFS to use,
+       which is largely (but not entirely!) meaningless in the WASM
+       environment. It may be null, undefined, or 0 to denote the
+       default.
     */
     sqlite3_open_v2: function(filename,dbPtrPtr,flags,vfsStr){}/*installed later*/,
     /**
        The sqlite3_prepare_v3() binding handles two different uses
        with differing JS/WASM semantics:
 
-       1) sqlite3_prepare_v3(pDb, sqlString, -1, prepFlags, ppStmt [, null])
+       1) sqlite3_prepare_v3(pDb, sqlString, -1, prepFlags, ppStmt , null)
 
        2) sqlite3_prepare_v3(pDb, sqlPointer, sqlByteLen, prepFlags, ppStmt, sqlPointerToPointer)
 
@@ -325,44 +324,36 @@ self.sqlite3ApiBootstrap = function sqlite3ApiBootstrap(
 
        (pDb, sqlAsString, -1, prepFlags, ppStmt, null)
 
-       The pzTail argument is ignored in this case because its result
-       is meaningless when a string-type value is passed through
-       (because the string goes through another level of internal
+       The `pzTail` argument is ignored in this case because its
+       result is meaningless when a string-type value is passed
+       through: the string goes through another level of internal
        conversion for WASM's sake and the result pointer would refer
        to that transient conversion's memory, not the passed-in
-       string).
+       string.
 
        If the sql argument is not a string, it must be a _pointer_ to
        a NUL-terminated string which was allocated in the WASM memory
-       (e.g. using cwapi.wasm.alloc() or equivalent). In that case,
+       (e.g. using capi.wasm.alloc() or equivalent). In that case,
        the final argument may be 0/null/undefined or must be a pointer
        to which the "tail" of the compiled SQL is written, as
        documented for the C-side sqlite3_prepare_v3(). In case (2),
        the underlying C function is called with the equivalent of:
 
-       (pDb, sqlAsPointer, (sqlByteLen||-1), prepFlags, ppStmt, pzTail)
+       (pDb, sqlAsPointer, sqlByteLen, prepFlags, ppStmt, pzTail)
 
        It returns its result and compiled statement as documented in
        the C API. Fetching the output pointers (5th and 6th
-       parameters) requires using capi.wasm.getMemValue() (or
-       equivalent) and the pzTail will point to an address relative to
-       the sqlAsPointer value.
+       parameters) requires using `capi.wasm.getMemValue()` (or
+       equivalent) and the `pzTail` will point to an address relative to
+       the `sqlAsPointer` value.
 
        If passed an invalid 2nd argument type, this function will
-       return SQLITE_MISUSE but will unfortunately be able to return
-       any additional error information because we have no way to set
-       the db's error state such that this function could return a
-       non-0 integer and the client could call sqlite3_errcode() or
-       sqlite3_errmsg() to fetch it. See the RFE at:
+       return SQLITE_MISUSE and sqlite3_errmsg() will contain a string
+       describing the problem.
 
-       https://sqlite.org/forum/forumpost/f9eb79b11aefd4fc81d
-
-       The alternative would be to throw an exception for that case,
-       but that would be in strong constrast to the rest of the
-       C-level API and seems likely to cause more confusion.
-
-       Side-note: in the C API the function does not fail if provided
-       an empty string but its result output pointer will be NULL.
+       Side-note: if given an empty string, or one which contains only
+       comments or an empty SQL expression, 0 is returned but the result
+       output pointer will be NULL.
     */
     sqlite3_prepare_v3: function(dbPtr, sql, sqlByteLen, prepFlags,
                                  stmtPtrPtr, strPtrPtr){}/*installed later*/,

manifest

@@ -1,5 +1,5 @@
-C Minor\sdoc\scorrection.
-D 2022-09-27T17:03:01.635
+C Work\saround\sbroken\s-Os\swasm\sbuilds\sby\sadding\sthe\s-g3\sflag.\sUnrelated\sdocumentation\stweaks.
+D 2022-09-28T07:53:47.790
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -474,7 +474,7 @@ F ext/userauth/user-auth.txt e6641021a9210364665fe625d067617d03f27b04
 F ext/userauth/userauth.c 7f00cded7dcaa5d47f54539b290a43d2e59f4b1eb5f447545fa865f002fc80cb
 F ext/wasm/EXPORTED_FUNCTIONS.fiddle.in 27450c8b8c70875a260aca55435ec927068b34cef801a96205adb81bdcefc65c
 F ext/wasm/EXPORTED_RUNTIME_METHODS.fiddle 0e88c8cfc3719e4b7e74980d9da664c709e68acf863e48386cda376edfd3bfb0
-F ext/wasm/GNUmakefile 0baf7702a0e900af6a985ddc889181ded22d05f6442035a0d84f5ab5d55f9bd1
+F ext/wasm/GNUmakefile 984c33a37fa34786d6be2c79ef19421b3c1a054dfdb56ea09313077de4aa19f6
 F ext/wasm/README.md e1ee1e7c321c6a250bf78a84ca6f5882890a237a450ba5a0649c7a8399194c52
 F ext/wasm/api/EXPORTED_FUNCTIONS.sqlite3-api 77a5ee8bd209b5e75dd0e822bc3f6e7319dc9b36431463d4175c775170f92126
 F ext/wasm/api/EXPORTED_RUNTIME_METHODS.sqlite3-api 1ec3c73e7d66e95529c3c64ac3de2470b0e9e7fbf7a5b41261c367cf4f1b7287
@@ -482,10 +482,10 @@ F ext/wasm/api/README.md f54102d74cfde01ebe242fa1411e126a9cda8f19b3ac378afd1103b
 F ext/wasm/api/post-js-footer.js b64319261d920211b8700004d08b956a6c285f3b0bba81456260a713ed04900c
 F ext/wasm/api/post-js-header.js 2e5c886398013ba2af88028ecbced1e4b22dc96a86467f1ecc5ba9e64ef90a8b
 F ext/wasm/api/sqlite3-api-cleanup.js 4bd28e61216690b12d6f77bfce71b011995c29496397cfa77e08198eb8d19aeb
-F ext/wasm/api/sqlite3-api-glue.js fe5ca21ac519e6411f5e7a6403d06fe92c51ef81cca8e07ea8895df8ec9c2e4e
+F ext/wasm/api/sqlite3-api-glue.js 3b164f0ef690a838da8613a2aaec4fc49d29ad5e8fe39c8cdc0f5281f08f9d0b
 F ext/wasm/api/sqlite3-api-oo1.js 97a786b366fcac442e1557c3eedef3afa96877411bd6239094d4db5fd5b3c353
 F ext/wasm/api/sqlite3-api-opfs.js af65e056b9f5bc6182499f7e7767e3d01abc3772a62c8abbcc04e4c7bb0affc6
-F ext/wasm/api/sqlite3-api-prologue.js 9bcec56baf306d1d9341cbbdea59fe0abc195db0c3ecbbc396ec5098cdbda786
+F ext/wasm/api/sqlite3-api-prologue.js 2a0dedb8127e8983d3199edea55151a45186b462646cb1f2206587ac1ef4eddf
 F ext/wasm/api/sqlite3-api-worker1.js d5d5b7fac4c4731c38c7e03f4f404b2a95c388a2a1d8bcf361caada572f107e0
 F ext/wasm/api/sqlite3-wasi.h 25356084cfe0d40458a902afb465df8c21fc4152c1d0a59b563a3fba59a068f9
 F ext/wasm/api/sqlite3-wasm.c b756b9c1fee9d0598f715e6df6bf089b750da24aa91bb7ef9277a037d81e7612
@@ -2026,8 +2026,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P f61475ef8244fd1f6553eca9cc2317e5de2cc04443e24afb7b91ebd3fc1bd402
-R 1038455075fe2f7dad3cc913763db9e3
+P 093f6e4b36db294e8e47df2fc75a4bc4fc101e2b6ff0201c912ccd1dcf394479
+R f13bcaf00e26043effcfda9235e61887
 U stephan
-Z 68a3ada68256719e5271aa1c9a7ddec7
+Z ec2d0b4aa25d1549f3750ebec3c29f7f
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-093f6e4b36db294e8e47df2fc75a4bc4fc101e2b6ff0201c912ccd1dcf394479
+f5d6bf8616341037fa3e229edf820d19acef3e0a6207a652b2b143de0a493214