add back notes-to-self.txt

notes-to-self.txt

@@ -0,0 +1,277 @@
+** builds/makefiles **
+add to clang --lto-O3 \ # Aggressive link-time optimizations 
+add to clang -flto \ # Add metadata for link-time optimizations
+use wasm2wat on helloworld to see code size optimizations possible.
+what is -lwasm? clang --target=wasm32-unknown-unknown-wasm -o test.wasm test.c -lwasm
+change my examples to all use one (the same) makefile?
+double check "C_Cpp.default.defines": is correct location in workspace file. is it needed in makefile? can it be moved to vscode
+give a warning when trying to buildazure and no source found (from npm). Or don't include the script in the build.
+in the npm package add source?
+have buildazure also build lib/twr.a
+should I remove include, lib-js, lib-c, etc from github? They are all built.
+buildall / clean needs to delete include folder before rebuilding it
+change build all examples scripts to also rebuild the libraries make files
+consider creating a sysroot -- see https://danielmangum.com/posts/wasm-wasi-clang-17/
+
+** docs/examples **
+add a sitemap for examples source and live examples https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap
+add analytics JS header code (azure insights or google analytics eg)
+in balls demo (and other demos), await appears to not work in browser older than 3 years.  Add try/catch and report browser error (currently shows error only in console)
+add await and dynamic import to my index.html compatibility tester?
+use of await (and maybe dynamic import) has limited demos working with older browsers.  Add to docs?  Create a test page index.html with no await?
+document issues with await in examples readme?
+determine if this is still true then add back to key feature list in doc and readme: - linked with helloworld,  code+data < 3K
+review and qa all the docs
+weird (ver small) min (in title bar) of balls debug build.  Window seems to need to be wide.
+got a large negative number for min fps running balls demo from npmjs readme link.  Wasn't immediately reproducible.
+add an example that shows how to call back into javascript from C
+index.html/examples/unbundled switch is hard coded to web site so i cant test it locally  (i think this is fixed, verify)
+why do bundled examples flash when launched in debugger with file versions?
+balls example still shows error async.html:1 An import map is added after module script load was triggered.
+doc? -- if (strcmp(b, "1.234568e+2")!=0) return 0;  // NOTE gcc printf %e gives 1.234568e+02
+and 	if (strcmp(b, "1.00000e+7")!=0) return 0;    // GCC give 1e+07
+sometimes in ball demo steptime==0.  Gens an assert.  Need to make sure this code path is okay, but seems to work.
+remove this line in balls for better performance:  m_canvas.fillRect(0, 0, m_width, m_height);
+balls performance analysis -- when lots of balls, "drawSeq" is 1/3 of time, moveAllBallsis 1/3, isCollisionNext 12%, moveSingleBall 17%
+not sure why "W" of "Hello World" in stdio-canvas example looks funny
+twr_malloc_debug_stats() is undocumented.  Either document, or rename to __malloc_debug_stats
+
+* api to add **
+add gets (currently there is just twr_gets)?
+add buffer size to io_gets()
+add twr_getkey() as well as existing twr_getchar().
+add twrDivInkey?  Its mostly implemented
+add some JS Date functions
+add more JS Math functions
+add ability to query global browser variables.  eg   val location = window["location"]; 
+    std::string search = location["search"].as<std::string>();
+add ability to pass JS object to C/C++
+add twr_cache_free_cache() api and use in windowed console in some places?  Or set max cache size in malloc cache API?
+add overload: fillText(text, x, y, maxWidth)
+add D2D for textAlign (set)
+add last new call (fillchar) to balls test c++ class
+add function that shows a wait icon, for use eg when loading wasm code
+add js bigint support? https://v8.dev/features/wasm-bigint
+add 'front-end' keyword
+add int ungetc(int ch, FILE *stream);  // place holder only, not implemented
+add a function that gets the full key, like "Shift"?
+
+** unit tests improvements **
+memstats - clean up output (everything in hex + dec).  Verify numbers.  avail seems small given the size of the code.
+unittests are in two places: tests and tests-user -- consolidate?
+unittests malloc failing tests-user
+add automated tests to units-tests that use utf8 prints then read terminal memory and check utf32 values
+add tests for div, abort
+add unittest for memmove() in string.c
+add unitests for fprintf with stderr, stdin, stdout
+add test cases for all new string functions.  example strcoll. _l versions, etc.
+malloc_unit_test() can't be called twice because cache mem tests don't clean up. fix.
+some of the length printf tests are failing with optimization on.  Why? 
+
+** existing API implementation improvements **
+add stack trace to assert
+have assert trap
+mod assert to use twr_conlog()
+a form like this can be used to improve GetVALUE() functions in wasmModule: const z = new Uint8ClampedArray(buffer, 1, 4); ?
+need to improve implementation of getU8Arr/32combine magic word and size in malloc from two alloc units to one alloc unit.
+seed rand() with time upon startup
+add overflow detection and set errno in stdclib conversion functions
+need better overflow detection? see square example, enter very large number
+strtoull, strtod etc do not set the errno ERANGE and return correct value (see strtoull doc)
+malloc is slow
+check out malloc and other crt at https://github.com/rebol/rebol
+callC calls are slow (i did a performance test, and way way slower then the import calls)
+if (twr_strcmp(buffer, "0.100000")!=0) return 0;  // see unittests.c comment
+substitution strings not support in mod.divLob(), eg console.log("The price is %.2f.", price);      
+printf() is missing a few bits
+realloc() needs improving
+std c functions that are supposed to be declared with 'restrict' parameters are not because I can't get them to compile.
+is_terminal -> should it be renamed twr_is_terminal, or better, io_isterminal() ?
+replace rnd() with call to js
+//twr_snprintf(b, sizeof(b), "%6.2d", -5);   // NOT IMPLEMENTED YET
+printf ("%f", 1.0/0.0); displays "Infinity"
+change memmove from C to wast?
+add option for debuginfo display. 
+    For example, stack size, heap size, etc.  Mem high water mark.  both crt and ts info.  
+   add debuginfo option to display graphic 2d calls and sizes
+   malloc alloc & free warnings
+change twrWasmModule to not use 'await' on callC, malloc, etc calls?
+twrDiv vs twrCanvas cursor management discrepancies
+   - io_putc will call twrDiv::charOut(), which used block cursor and will enable focus on the div when curor enabled
+   - io_putc uses its internal default implementation ofr twr::Canvas, which uses underscore as cursor and can't set the canvas focus
+   - io_putc logic doesn't seem right - it assumes if io->charout.io_putc not set, the console is windowed, and if 
+      io->charout.io_putc is set, it just sort of punts for windowed?  
+change canvas cursor (hollow) when canvas doesn't have focus
+add check of response.ok to fetchAndPutURL 0 fetch (see loadWasm)
+io_putc() used unsigned char, which will fail with EOF, and unicode code points (should i add that?)
+not clear why IModOpts.isd2dcanvas exists.  Perhaps related, d2d and io canvas not supported at same time.
+bug: setlocale(LC_ALL, NULL) should return different locals separated by semicolon.  see https://chatgpt.com/c/30a0e4f7-8e04-427c-9943-950e74633292
+rename nstrcopy to __nstrcopy
+
+** misc **
+I pulled some of the headers from LLVM that are under the Apache-2.0 license.  Does that affect what needs to be in my top-level LICENSE file?
+in keyEventProcess, cntr-c etc are not handled.  Add support?
+add a io_canvas option for wide/narrow chars to select between const sampleText="          "; AND const sampleText=String.fromCharCode(2593).repeat(6);
+mbgetc when locale is C returns "?" -- is that what i want to happen?
+would be nice to be able to "copy" out of the IoWindow terminal
+are full source paths (from my dev folder) being included in twrd.a -- investigate
+in buildlibcxx.sh, should i delete "include-next" when cleaning build?
+mac os Catalina ( Version 13.1.2 (15609.3.5.1.3) ) failing to parse bundled javascript
+should i changed boot up default to "" instead of "C"?  if so, should i change C to be ASCII all the time? Ie, remove utf8 "c" limited support.
+remove these two lines: console.log("keyDownDiv SKIPPED: ",ev.key, ev.code, ev.key.codePointAt(0), ev);
+build with LIBCXX_ENABLE_UNICODE=ON?  And then add tests for utf-32/16/etc and add to docs -- see https://chatgpt.com/c/30a0e4f7-8e04-427c-9943-950e74633292
+ADD ansi terminal escape codes for windows term
+\x1b[30m - Black
+\x1b[31m - Red
+\x1b[32m - Green
+\x1b[33m - Yellow
+\x1b[34m - Blue
+\x1b[35m - Magenta
+\x1b[36m - Cyan
+\x1b[37m - White
+\x1b[0m - Reset to default
+
+rename windows console to terminal?
+better modularize twrWasmModule & twrWasmModuleAsync classes -- see notes 5-11-24 paper.
+need a better system than this to check for crossOriginIsolated.  Check in module constructor?
+         if (typeof window !== 'undefined') { // this check only works if window valid
+            if (!crossOriginIsolated && !(window.location.protocol === 'file:')) 
+                throw new Error("twrSignal constructor, crossOriginIsolated="+crossOriginIsolated+". See SharedArrayBuffer docs.");
+        }
+cstart.o (cstart.s) - is it handled correctly? double check.
+remind my self why modasync uses const urlToLoad = new URL(pathToLoad, document.URL); and not new Worker(new URL('twrmodworker.js', import.meta.url), {type: "module" });
+see C:\GitHubClonesDev\llvm-project\build\include\c++\v1\cstdlib for list of C stdlib funcs to implement, and note about order of includes
+(unreachable) is one way to term a web assembly function and throw an exception in JS (used in twr_trap). Are there others?
+/0 in hangs with no exception or error.  Investigation shows:  Integer /0 results in exception in called function.  Double /0 returns infinity
+check this out: https://github.com/hybridgroup/mechanoid
+awbasic gnu build needs ioconsole support - it disappeared when i took out twr-wasm
+awbasic - test all workspace buildsupdate awbasic to convert codes before calling io_putc():
+	else if (c >=192)	// 192 to 255 are shortcuts for 0 to 63 spaces, respectively
+	{
+		for (int i=0; i < (c-192); i++)
+			io_putc(io, ' ');
+
+		return;
+	}
+twrmodbase.copyString() could be made more performant - replace for loop with a copy and use encodeinto()
+--- better way to decode string ---
+function consoleLogString(offset, length) {
+  const bytes = new Uint8Array(memory.buffer, offset, length);
+  const string = new TextDecoder("utf8").decode(bytes);
+  console.log(string);
+}
+investigate exceptions more: https://emscripten.org/docs/porting/exceptions.html
+----
+Debugging Exceptions
+Stack Traces
+For native Wasm exceptions, when ASSERTIONS is enabled, uncaught exceptions will print stack traces for debugging. 
+ASSERTIONS is enabled by default in -O0 and disabled in optimized builds (-O1 and above). 
+To display Wasm function names in stack traces, you also need –profiling-funcs (or -g or -gsource-map).
+ Google didn't index a given page because it's a duplicate of a different page, and none of the pages was indicated as the canonical one using the canonical tag.
+
+In JavaScript, you can also examine the stack traces using WebAssembly.Exception.prototype.stack property. For example:
+
+try {
+  ... // some code that calls WebAssembly
+} catch (e) {
+  // Do something with e.stack
+  console.log(e.stack);
+}
+Stack traces within Wasm code are not supported in JavaScript-based exceptions.
+----
+
+regarding: std::locale("").name().c_str() - this returns a name of "", as opposed to "en-US.UTF-8" (for example).  
+This is not what I expected based on various internet documentation.  But after lots of looking at the source and varous tests, it appears to be correct.  
+Note that on both clang++ and g++, this will throw an exception, which also isn't what I expected. In TWR, even though the name is not as expected, it does work as a locale when used.
+
+NOTES:
+# C:\GitHubClonesDev\llvm-project\llvm\lib\Target\WebAssembly\README.txt
+# https://github.com/emscripten-core/emscripten/tree/main/system/lib/libcxx
+
+# https://danielmangum.com/posts/wasm-wasi-clang-17/
+# try cxx cxxabi unwind
+# take a look at this https://github.com/ARM-software/LLVM-embedded-toolchain-for-Arm/blob/main/docs/building-from-source.md
+doxeygon theme: https://github.com/jothepro/doxygen-awesome-css
+typedoc home page: https://github.com/TypeStrong/typedoc-site/tree/masterlibstdc++ https://gcc.gnu.org/git/?p=gcc.git;a=tree;f=libstdc%2B%2B-v3/libsupc%2B%2B;hb=HEAD
+https://github.com/emscripten-core/emscripten/blob/df74d74f5dfce1c2128fdb0dde1b09c178f7a38a/tools/system_libs.py#L1505-L1506
+https://github.com/WebAssembly/tool-conventions/blob/main/EHScheme.md
+https://github.com/llvm/llvm-project
+https://libcxx.llvm.org/BuildingLibcxx.html
+https://github.com/gnikoloff/wasm-snake/tree/main
+good wasm article: https://surma.dev/things/c-to-webassembly/index.html
+https://mike.zwobble.org/2021/04/adventures-in-webassembly-object-files-and-linking/
+https://www.reddit.com/r/WebAssembly/
+compile-rt crtbegin.C
+https://github.com/llvm/llvm-project/blob/7ef1a59ed1ca176cf3c38672fe1d3f49c1758e49/compiler-rt/lib/builtins/crtbegin.c#L24
+CORS on github:
+https://stackoverflow.com/questions/68609682/is-there-any-way-to-use-sharedarraybuffer-on-github-pages#:~:text=4%20Answers&text=You%20can%20get%20SharedArrayBuffer%20to,have%20the%20appropriate%20headers%20set.
+https://github.com/wuzhouhui/c_standard_lib/tree/master
+https://daniel-hug.github.io/characters/#k_70
+https://depth-first.com/articles/2020/01/13/first-steps-in-webassembly-hello-world/
+https://ddr0.ca/blog-posts/13.Shared_Array_Buffers_With_WASM
+https://blog.scottlogic.com/2019/07/15/multithreaded-webassembly.html
+https://stackoverflow.com/questions/53142710/howto-notify-npm-of-dependency-on-native-c-library
+
+From old Makefile dev:
+
+# The LLVM Project is a collection of modular and reusable compiler and toolchain technologies.
+# What is commonly known as the LLVM bitcode file format (also, sometimes anachronistically known as bytecode)
+# is actually two things: a bitstream container format and an encoding of LLVM IR into the container format.
+# llvm-link takes several LLVM bitcode files and links them together into a single LLVM bitcode file.
+# The llc command compiles LLVM source inputs into assembly language for a specified architecture
+# llc doc - The choice of architecture for the output assembly code is automatically determined from the input file
+# The -cc1 argument indicates that the compiler front-end is to be used, and not the gcc driver. 
+
+#out/awbasic.wasm: glue.c
+#	clang -cc1 -emit-llvm-bc -triple=wasm32-unknown-unknown-wasm -std=c11  glue.c -o out/glue.bc                
+#	llvm-link -o out/wasm.bc out/glue.bc
+#	llc -O3 -filetype=obj out/wasm.bc -o out/glue.o
+#	wasm-ld out/glue.o -o out/awbasic.wasm  --no-entry --allow-undefined  --import-memory --export=glue --export=get_heap_base
+
+#
+# build command line executable
+#
+
+#	-resource-dir C:/msys64/ucrt64/lib/clang/17 \
+#	-internal-isystem C:/msys64/ucrt64/lib/clang/17/include \
+
+#	-internal-isystem ../lib-twr/std-crt-include \
+
+
+# why doesn't -fno-exceptions or -fno-trappping-math work? probably because using -cc1
+
+# below also works with link line updated to just use wasm-ld
+#CFLAGS =  --target=wasm32-unknown-unknown-wasm  -g -Wall -c -v \
+
+# below does not produce an output.  It seems --allow-undefined symbols is required
+#	wasm-ld $(OBJOUTDIR)/wasm.o -o $(OBJOUTDIR)/awbasic.wasm  -v --no-entry --warn-unresolved-symbols --import-undefined --import-memory --export=run_basic_file  --export=twr_capi_malloc
+
+
+# i found this useful to look at symbols
+# llc -filetype=asm wasm.bc -o wasm.asm
+# other good tools: wasm-decompile, wasm-validate, llvm-objdump -S
+# and wasm2wat awbasic.wasm -o aw.asm
+
+----
+when converting from -cc1 to the standard gcc compatible clang options, i discovered the following when creating twr-a:
+the gcc ar (original ar i used) generated output that wasm-ld would not accept.  However, I found this work around:
+   (using -cc1 clang options to compile)
+	llvm-ar cr $(OBJOUTDIR)/twr-a0.bc $(OBJECTS)
+	llvm-link -o $(OBJOUTDIR)/twr-a.bc $(OBJOUTDIR)/twr-a0.bc
+	llc -filetype=obj $(OBJOUTDIR)/twr-a.bc -o $(TWRA)
+
+   (ar works as well as llvm-ar)
+
+in addition this works with the "gcc" style clang.
+	llvm-ar crsv $(TWRA) $(OBJECTS)
+
+however, files that used to work like this:
+__attribute__((export_name("twr_wasm_init")))
+void twr_wasm_init(int pf, unsigned long mem_size) 
+
+now required an wasm-ld option like: --export=twr_wasm_init 
+
+note: there is supposedly an wasm-ar, but i could not find it. It is supposedly part of emscripten.
+
+as a result, i went back to the first option in this comment
+----