6.0.0 release checklist #154

What has to happen before libhxcpp 6.0.0 goes to haxelib. Pre-releases follow RELEASING.md: 6.0.0-rc.1 is out, and anything fixed before 6.0.0 ships as -rc.2 and on.

Find what we don't know

• Sanitizer CI: UBSan and ASan on the regression, std and GC stress suites, TSan on the thread tests (Run the test suites under sanitizers and CodeQL #148). HXCPP_SANITIZE, an ASan-safe GC stack scan and UBSan and ASan CI jobs on the regression suite are on main; std and TSan to follow
• Fix or file everything the sanitizers report: Constant allocations are only 4-byte aligned #155, String headers are read from unaligned string data #156, SSL casts the socket handle to its own copy of SocketWrapper #158, cppia: functions with an untyped return read an uninitialised return type #159 fixed; cppia frames store objects, Strings and doubles at misaligned offsets #157 is in the 6.0.0 list (6.0.0: critical runtime and cppia issues #192); the full regression suite is clean under both
• Architecture pass over the GC, threads, cppia and the build tool, filing what it finds

Critical fixes

• GC and thread races: Generational GC: a thread attaching during a mode switch gets no remembered set #139, ARM64: the collector can miss a thread leaving a GC-free zone #142, The moving GC ignores the pin flag on alloc finalizers #143, ThreadLocal reuses a slot without clearing its old values #68, Sys.exit destroys GC state while other threads still allocate #67
• Thread API correctness: Process.exitCode returns 0 when called again on POSIX #114, Thread wait timeouts break on negative, NaN, huge and sub-millisecond values #122, Natively attached threads all get thread id 0 #123, Windows semaphores cap at 134 million permits #125
• PCRE2 security backports (Dependency upgrades by priority #147, P1)
• Move the GitHub Actions off Node 20 (Dependency upgrades by priority #147, P2)
• SQLite 3.54.0, with the WAL-reset corruption fix (Dependency upgrades by priority #147, P2)
• Wrong-result fixes: Comparing a String with a Dynamic depends on the static types #97 to haxe.Utf8 truncates characters above U+FFFF #107, Bytes.ofString and urlEncode throw on a lone surrogate #110, Date.getTimezoneOffset ignores daylight saving time on Windows #112, Negative fractional times round toward zero #116, Sys.environment decodes the Windows environment as UTF-8 #117, Haxe 5 thread objects: pseudo-handles for names, and Scratch copy assignment #124, cppia JIT: String += drops null and turns an empty string into null #129, cppia: isOfType, cast and catch ignore interfaces inherited through other interfaces #131 to cppia: safe casts to Int, Float, Bool and String never throw #135 (cppia: script classes implementing a generic host interface misread their arguments #130 is in 6.0.0: critical runtime and cppia issues #192)
• High-severity bugs from the triage of @:nativeGen interfaces: second interface gets the object's address, and the collector misses it #193 to Native cleanup callbacks erase outer frames from a propagating exception stack #229: CFFI val_ocallN does not match its public argument-vector signature #228, Prevent copying thread-attachment and GC-free-zone ownership guards #227, File close discards buffered write errors and lets saveContent report success #215, Collected socket wrappers leave their OS descriptors open #221, Ordinary file descriptors leak into POSIX child processes #216, Process.exitCode reports success when retrieving child status fails #213, POSIX process launch hides exec failures and loses the actual error #211, The first POSIX process launch overwrites the host SIGPIPE handler #212, emscripten: pass --profiling-funcs with --spill-pointers on every version #81 (6.0.0: critical runtime and cppia issues #192)
• Performance: GC heap does not grow; HXCPP_MINIMUM_WORKING_MEMORY is ignored (allocation ~3x slower than stock) #230, Hash ObjectMap keys by address on 64-bit when objects do not move #77, Reduce per-byte stdio and GC handoff overhead in native file input #205, Avoid repeated pointer-array shifts when releasing GC block groups #207, Reuse freed GC block IDs without restarting a full-table search for every block #208, Use one hash lookup for successful dynamic-field reads #197, Honor the initial hash reservation to avoid repeated rehashing during storage conversion #189, Add resize hysteresis to prevent hash maps rebuilding on small add-remove cycles #225, Release excess weak-map bucket capacity after GC removes the keys #204, Shorten the large-buffer recycle lock around buffer clearing #191, each with a before and after measurement (6.0.0: critical runtime and cppia issues #192). Every performance fix that needs no change in Haxe is in scope for 6.0.0, including ones found later
• Everywhere libhxcpp is slower or uses more memory than stock hxcpp 4.3.53 in the benchmark suite: IntMap is 2.3x slower than stock hxcpp 4.3.53 (map_int benchmark) #231 (IntMap), ObjectMap is 20% slower than stock hxcpp 4.3.53 (map_object benchmark) #232 (ObjectMap), Small allocations are 2-10% slower than stock hxcpp 4.3.53 (alloc_small, alloc_arrays, string_substr) #233 (small allocations), Startup and exit take 0.7 ms longer than stock hxcpp 4.3.53 #234 (startup), Peak memory is 4-22% higher than stock hxcpp 4.3.53 on most benchmarks #235 (peak memory)

Everything else that needs no change in Haxe (details and notes in #192; issues labelled needs haxe are excluded)

• cppia frame slots (cppia frames store objects, Strings and doubles at misaligned offsets #157), fixed in the interpreter without changing the frame layout that Haxe's generated host glue relies on
• Wrong results with a narrow trigger: Zero-length process pipe operations grow empty byte buffers #209, POSIX child stdin is closed during exec when the parent has no fd 0 #210, Socket select and poll restart finite timeouts after every signal interruption #217, IPv6 socket host and peer queries return an IPv4 address instead of the endpoint #218, Whole-file reads return empty data for readable zero-size procfs files #219, Positive sub-microsecond socket timeouts disable the timeout on POSIX #220 (POSIX: WSL and CI), Reflect.hasField misses fields in fixed anonymous objects #222, Anonymous-object formatting shares its recursion limit across threads #223, Reflected Array.filter rereads source values after the predicate changes them #224, Native heap freezing duplicates shared objects instead of preserving graph identity #226, Native cleanup callbacks erase outer frames from a propagating exception stack #229, Print floats with the shortest digits that round-trip #93, HXCPP_GC_VERIFY reports unmarked row HaxeFoundation/hxcpp#1415
• Haxe 5 (API level 500, label haxe 5), tested on Haxe 5: Haxe nightly (API level 500): GC stress segfaults and suite failures #164, Scratch can reuse a live buffer when allocations are released out of order #184, Odd-sized Scratch allocations misalign the next reference counter #185, Avoid GC finalizers for trivially destructible native boxed values #186, Native View operations narrow 64-bit lengths and return wrong results for large buffers #187, Endian-aware native pointer readers instantiate the wrong pointer type #188, Avoid Dynamic boxing in typed Haxe 5 numeric array sorting #195, Weak bound-method liveness does not follow callable adapter chains #202
• Remaining performance: Box String elements once per sort, not per comparison #78, Bound repeated-prefix work in long string searches #190, Avoid the second allocation and output copy in native UTF-8 decoding #196, Avoid scanning the entire input to detect parseInt hexadecimal prefixes #198, Avoid flattening remembered-set chunks into a temporary array during collection #201, Reduce repeated ephemeron sweeps for weak-map dependency chains #203, Measure linear grouping for GC free-list rebuilds instead of comparison sorting #206, and Avoid string allocation for unchanged case conversion and whole-string substrings #194, Use known database result layouts to avoid a field hash table for every row #200, Report live bytes as well as line usage, and size the heap from live bytes #83 in the compatible forms noted in 6.0.0: critical runtime and cppia issues #192
• GC measurement and tests: GC liveness tests should wait for thread detach instead of sleeping #176, Measure and bound the large-allocation GC budget after temporary heap growth #177, Check unsynchronized counters and recycle probes in the large-allocation path #178, Measure large-object lookup costs during conservative root scanning #179, Collected ThreadLocal owners can leave their values rooted on long-lived threads #181
• Build, embedding and diagnostics: Name the hxcpp a build uses and warn when it differs from Haxe's #79, Mark hx::Throw and the debugger throw helpers noreturn #80, Document how embedders release and re-enter the runtime #84, Release-mode heap census by class #82, Make GC debugging and configuration first-class #87, Keep define-dependent GC code from falling through the cracks #88
• Process runner with concurrent pipe draining and deadlines (Provide a process runner with concurrent pipe draining and deadlines #214)
• Benchmark suite and baselines (Add a native benchmark suite, recorded baselines and performance regression checks #151), which the performance items use for their measurements
• Performance regression suite against stock hxcpp (Add a native benchmark suite, recorded baselines and performance regression checks #151), run on the same machine, Haxe version and flags
• Haxe 5 on every change (Test Haxe 5 on every change #153), output compared with the other targets (Compare test program output with the other Haxe targets #150), nightly downstream builds automated (Nightly downstream builds of Lime, OpenFL, Flixel, HaxeUI and CrossByte #149)

Docs

• README: install, haxelib run libhxcpp setup and off, what differs from hxcpp
• docs/build_xml/Defines.md covers every define libhxcpp added (GC, sanitizer, Tracy, SQLite)
• Changes.md 6.0.0 section grouped and readable
• SECURITY.md and the supported Haxe versions (Release process: versions, a stable branch and a security policy #152), private vulnerability reporting on
• README: a table of the main performance metrics, libhxcpp against stock hxcpp, with how it was measured (Add a native benchmark suite, recorded baselines and performance regression checks #151)

Release

• mbedTLS provider for static builds (Let a library provide mbedTLS for static builds #161): a library that bundles mbedTLS can offer its copy, so a static app links one; Lime 8.4.0 offers its copy. It's optional: without a provider, libhxcpp and Lime each use their own
• haxelib path output that hxp reads correctly (extraParams -D lines make hxp misread libhxcpp's path #165)
• Lime: lime setup installs and runs libhxcpp setup
• Lime static builds no longer compile curl against libhxcpp's mbedTLS: Lime 8.4.0 builds its own symbol-renamed mbedTLS 3.6 copy (Lime branch mbedtls-3.6, green on all 35 jobs)
• Build and run Lime/OpenFL, Flixel, Feathers UI and CrossByte samples against rc.1 (Nightly downstream builds of Lime, OpenFL, Flixel, HaxeUI and CrossByte #149). A local run on main as of 4149c48:
  • Windows: 41 of 42 Lime and OpenFL samples build; JoystickInput uses onTrackballMove, which Lime removed, and fails on hxcpp too. A Flixel and a Feathers UI test app build. CrossByte's native and stress suites build
  • Linux: CrossByte's stress suite passes 15 of 15 cases; its native suite passes 59530 of 59535 checks. Three of the five need the repository as the working directory, one (BsonTest) expects hxcpp's old boxing of small Int64 values as Int, which libhxcpp fixed, and one process test passes 3 of 3 runs on its own
• 6.0.0-rc.1 from a green main: on haxelib and as a GitHub pre-release (v6.0.0-rc.1)
• Before 6.0.0: the sanitizer follow-ups (Run the test suites under sanitizers and CodeQL #148), the architecture pass, the downstream builds against rc.1 (Nightly downstream builds of Lime, OpenFL, Flixel, HaxeUI and CrossByte #149), and lime setup running libhxcpp setup. Anything they turn up ships in -rc.2 and on
• Every item in 6.0.0: critical runtime and cppia issues #192 fixed, shown not to reproduce, or moved out with a reason
• A stable branch for fixes after 6.0.0 (Release process: versions, a stable branch and a security policy #152; tagged releases, SECURITY.md and the supported Haxe versions are done)
• 6.0.0 from a green main

Since rc.1 on main: #167 (cpp.Function fields under HXCPP_GC_GENERATIONAL), #70 (the build tool stops when generated file names differ only in case).

After 6.0.0: the issues labelled needs haxe (#70, #8, #5, #199), which wait on HaxeFoundation/haxe; the mbedTLS 4.1 port (#147), because static builds link the mbedTLS 3.6 copy that Lime 8.4.0 provides (#161) and the 3.6 LTS runs to March 2027.