GdiPlus, AutoCompleteLib and VBComDlg sections; Experimental packages leave the book; three LLVM defects documented

bugs/gosub-llvm-exe-crash/repro.json

@@ -0,0 +1,13 @@
+{
+  "mode": "run",
+  "llvm": true,
+  "exe": true,
+  "expect": {
+    "exit": 6,
+    "output": [
+      "^G = 7$",
+      "^--- exe: exit -1073741819 \\(0xC0000005\\)$"
+    ],
+    "absent": ["^--- exe: exit 7$"]
+  }
+}

bugs/gosub-llvm-exe-crash/src/Settings

@@ -0,0 +1,61 @@
+{
+	"configuration.inherits": "Defaults",
+	"project.appTitle": "GosubLlvmExeCrash",
+	"project.buildPath": "${SourcePath}\\Build\\${ProjectName}_${Architecture}.${FileExtension}",
+	"project.buildType": "Standard EXE",
+	"project.description": "Reproduces: A GoSub in an exe built with LLVM ends the program with an access violation",
+	"project.exportPathIsV2": true,
+	"project.id": "{CC17473C-5FBA-479D-8B78-38E2AA3A85C1}",
+	"project.name": "GosubLlvmExeCrash",
+	"project.optionExplicit": true,
+	"project.references": [
+		{
+			"id": "{00020430-0000-0000-C000-000000000046}",
+			"lcid": 0,
+			"name": "OLE Automation",
+			"path32": "C:\\Windows\\SysWOW64\\stdole2.tlb",
+			"path64": "C:\\Windows\\System32\\stdole2.tlb",
+			"symbolId": "stdole",
+			"versionMajor": 2,
+			"versionMinor": 0
+		},
+		{
+			"id": "{F50B82D0-DCAB-43FE-9631-11959D4A4728}",
+			"isCompilerPackage": true,
+			"licence": "MIT",
+			"name": "[COMPILER PACKAGE] twinBASIC - VB Compatibility Package (Forms)",
+			"path32": "",
+			"path64": "",
+			"publisher": "TWINBASIC-COMPILER",
+			"symbolId": "VB",
+			"versionBuild": 0,
+			"versionMajor": 0,
+			"versionMinor": 0,
+			"versionRevision": 31
+		},
+		{
+			"id": "{C192FB39-64CA-4D9B-B477-A5502F48EFCC}",
+			"isCompilerPackage": true,
+			"licence": "MIT",
+			"name": "[COMPILER PACKAGE] twinBASIC - App global class object",
+			"path32": "",
+			"path64": "",
+			"publisher": "TWINBASIC-COMPILER",
+			"symbolId": "AppGlobalClassProject",
+			"versionBuild": 0,
+			"versionMajor": 1,
+			"versionMinor": 0,
+			"versionRevision": 0
+		}
+	],
+	"project.settingsVersion": 1,
+	"project.startupObject": "Sub Main",
+	"project.warnings": {
+		"errors": [],
+		"hints": [],
+		"ignored": [],
+		"info": [],
+		"warnings": []
+	},
+	"runtime.useUnicodeStandardLibrary": true
+}

bugs/gosub-llvm-exe-crash/src/Sources/Startup.twin

@@ -0,0 +1,32 @@
+' A GoSub in a program compiled with LLVM. G returns 7. Without LLVM the exe exits with code 7. With
+' LLVM on for the build the exe faults at the GoSub (exit code 0xC0000005, win32 and win64), with no
+' message box. The IDE's own run with LLVM on is correct: it prints "G = 7".
+Module Startup
+
+    Private Declare Sub ExitProcess Lib "kernel32" (ByVal uExitCode As Long)
+
+    Private Function G() As Long
+        Dim n As Long
+        GoSub L
+        G = n
+        Exit Function
+    L:
+        n = 7
+        Return
+    End Function
+
+    Public Sub Main()
+        If App.IsInIDE Then
+            Debug.Print "G = " & G()
+        Else
+            ExitProcess G()
+        End If
+    End Sub
+
+    [RunAfterBuild]
+    Private Sub Built()
+        Debug.Cls
+        Main
+    End Sub
+
+End Module

bugs/llvm-byval-to-byref-sub-codegen/repro.json

@@ -0,0 +1,14 @@
+{
+  "mode": "run",
+  "arch": "win64",
+  "llvm": true,
+  "exe": true,
+  "expect": {
+    "exit": 5,
+    "output": [
+      "^\\[LLVM\\] codegen error occurred when compiling 'Startup\\.Caller': Call parameter type does not match function signature!$",
+      "^--- exe: exit -1073741819 \\(0xC0000005\\)$"
+    ],
+    "absent": ["^Caller = 7$", "^--- exe: exit 7$"]
+  }
+}

bugs/llvm-byval-to-byref-sub-codegen/src/Settings

@@ -0,0 +1,61 @@
+{
+	"configuration.inherits": "Defaults",
+	"project.appTitle": "LlvmByvalToByrefSubCodegen",
+	"project.buildPath": "${SourcePath}\\Build\\${ProjectName}_${Architecture}.${FileExtension}",
+	"project.buildType": "Standard EXE",
+	"project.description": "Reproduces: LLVM: ByVal argument for a ByRef parameter of a twinBASIC Sub is a codegen error",
+	"project.exportPathIsV2": true,
+	"project.id": "{E7E6021D-E681-4888-8573-57E83DE35AE1}",
+	"project.name": "LlvmByvalToByrefSubCodegen",
+	"project.optionExplicit": true,
+	"project.references": [
+		{
+			"id": "{00020430-0000-0000-C000-000000000046}",
+			"lcid": 0,
+			"name": "OLE Automation",
+			"path32": "C:\\Windows\\SysWOW64\\stdole2.tlb",
+			"path64": "C:\\Windows\\System32\\stdole2.tlb",
+			"symbolId": "stdole",
+			"versionMajor": 2,
+			"versionMinor": 0
+		},
+		{
+			"id": "{F50B82D0-DCAB-43FE-9631-11959D4A4728}",
+			"isCompilerPackage": true,
+			"licence": "MIT",
+			"name": "[COMPILER PACKAGE] twinBASIC - VB Compatibility Package (Forms)",
+			"path32": "",
+			"path64": "",
+			"publisher": "TWINBASIC-COMPILER",
+			"symbolId": "VB",
+			"versionBuild": 0,
+			"versionMajor": 0,
+			"versionMinor": 0,
+			"versionRevision": 31
+		},
+		{
+			"id": "{C192FB39-64CA-4D9B-B477-A5502F48EFCC}",
+			"isCompilerPackage": true,
+			"licence": "MIT",
+			"name": "[COMPILER PACKAGE] twinBASIC - App global class object",
+			"path32": "",
+			"path64": "",
+			"publisher": "TWINBASIC-COMPILER",
+			"symbolId": "AppGlobalClassProject",
+			"versionBuild": 0,
+			"versionMajor": 1,
+			"versionMinor": 0,
+			"versionRevision": 0
+		}
+	],
+	"project.settingsVersion": 1,
+	"project.startupObject": "Sub Main",
+	"project.warnings": {
+		"errors": [],
+		"hints": [],
+		"ignored": [],
+		"info": [],
+		"warnings": []
+	},
+	"runtime.useUnicodeStandardLibrary": true
+}

bugs/llvm-byval-to-byref-sub-codegen/src/Sources/Startup.twin

@@ -0,0 +1,33 @@
+' A call that passes ByVal for a ByRef parameter of a twinBASIC Sub, in a program compiled with LLVM.
+' Caller returns 7. Without LLVM the call compiles and passes a NULL pointer (Take does not use it), and
+' the exe exits with code 7. With LLVM on, the build prints "[LLVM] codegen error occurred when compiling
+' 'Startup.Caller': Call parameter type does not match function signature!" and still makes the exe, and
+' Caller does not run: the exe faults (exit code 0xC0000005 in 64-bit, in ntdll or USER32). VB6 refuses the call
+' (Type mismatch).
+Module Startup
+
+    Private Declare PtrSafe Sub ExitProcess Lib "kernel32" (ByVal uExitCode As Long)
+
+    Private Sub Take(ByRef h As Long)
+    End Sub
+
+    Private Function Caller() As Long
+        Take ByVal 0&
+        Caller = 7
+    End Function
+
+    Public Sub Main()
+        If App.IsInIDE Then
+            Debug.Print "Caller = " & Caller()
+        Else
+            ExitProcess Caller()
+        End If
+    End Sub
+
+    [RunAfterBuild]
+    Private Sub Built()
+        Debug.Cls
+        Main
+    End Sub
+
+End Module

bugs/llvm64-byval-to-byref-declare-crash/repro.json

@@ -0,0 +1,14 @@
+{
+  "mode": "run",
+  "arch": "win64",
+  "llvm": true,
+  "exe": true,
+  "expect": {
+    "exit": 5,
+    "output": [
+      "^--- exe: exit -1073741819 \\(0xC0000005\\)$",
+      "^--- exe: exception 0xc0000005 in KERNELBASE\\.dll"
+    ],
+    "absent": ["^Count = 5$", "^--- exe: exit 5$"]
+  }
+}

bugs/llvm64-byval-to-byref-declare-crash/src/Settings

@@ -0,0 +1,61 @@
+{
+	"configuration.inherits": "Defaults",
+	"project.appTitle": "Llvm64ByvalToByrefDeclareCrash",
+	"project.buildPath": "${SourcePath}\\Build\\${ProjectName}_${Architecture}.${FileExtension}",
+	"project.buildType": "Standard EXE",
+	"project.description": "Reproduces: LLVM 64-bit: ByVal for a ByRef 8th parameter of a Declare crashes",
+	"project.exportPathIsV2": true,
+	"project.id": "{6CB72A7C-313A-4A92-B696-5866DC740F1B}",
+	"project.name": "Llvm64ByvalToByrefDeclareCrash",
+	"project.optionExplicit": true,
+	"project.references": [
+		{
+			"id": "{00020430-0000-0000-C000-000000000046}",
+			"lcid": 0,
+			"name": "OLE Automation",
+			"path32": "C:\\Windows\\SysWOW64\\stdole2.tlb",
+			"path64": "C:\\Windows\\System32\\stdole2.tlb",
+			"symbolId": "stdole",
+			"versionMajor": 2,
+			"versionMinor": 0
+		},
+		{
+			"id": "{F50B82D0-DCAB-43FE-9631-11959D4A4728}",
+			"isCompilerPackage": true,
+			"licence": "MIT",
+			"name": "[COMPILER PACKAGE] twinBASIC - VB Compatibility Package (Forms)",
+			"path32": "",
+			"path64": "",
+			"publisher": "TWINBASIC-COMPILER",
+			"symbolId": "VB",
+			"versionBuild": 0,
+			"versionMajor": 0,
+			"versionMinor": 0,
+			"versionRevision": 31
+		},
+		{
+			"id": "{C192FB39-64CA-4D9B-B477-A5502F48EFCC}",
+			"isCompilerPackage": true,
+			"licence": "MIT",
+			"name": "[COMPILER PACKAGE] twinBASIC - App global class object",
+			"path32": "",
+			"path64": "",
+			"publisher": "TWINBASIC-COMPILER",
+			"symbolId": "AppGlobalClassProject",
+			"versionBuild": 0,
+			"versionMajor": 1,
+			"versionMinor": 0,
+			"versionRevision": 0
+		}
+	],
+	"project.settingsVersion": 1,
+	"project.startupObject": "Sub Main",
+	"project.warnings": {
+		"errors": [],
+		"hints": [],
+		"ignored": [],
+		"info": [],
+		"warnings": []
+	},
+	"runtime.useUnicodeStandardLibrary": true
+}

bugs/llvm64-byval-to-byref-declare-crash/src/Sources/Startup.twin

@@ -0,0 +1,33 @@
+' ByVal 0& for the ByRef 8th parameter of a Declare. Count returns 5 (the length of the UTF-8
+' text). With LLVM on in a 64-bit build the call faults inside WideCharToMultiByte (0xC0000005, no
+' message box), in the exe and in the IDE run. 32-bit with LLVM, and 64-bit without it, return 5.
+' The fault depends on what the stack held before the call: the same call in a procedure with fewer
+' locals can pass on a clean stack. The 1st to 7th parameters, and a ByRef LongPtr 8th, are right.
+Module Startup
+
+    Private Declare PtrSafe Function WideCharToMultiByte Lib "kernel32" (ByVal CodePage As Long, ByVal dwFlags As Long, ByVal lpWideCharStr As LongPtr, ByVal cchWideChar As Long, ByVal lpMultiByteStr As LongPtr, ByVal cbMultiByte As Long, ByVal lpDefaultChar As LongPtr, ByRef lpUsedDefaultChar As Long) As Long
+    Private Declare PtrSafe Sub ExitProcess Lib "kernel32" (ByVal uExitCode As Long)
+
+    Private Function Count() As Long
+        Dim text As String, n As Long, a As String, b As String, c As Long, d As Double
+        text = "hello"
+        a = "x": b = "y": c = 1: d = 2
+        n = WideCharToMultiByte(65001, 0, StrPtr(text), Len(text), 0&, 0&, 0&, ByVal 0&)
+        If Len(a & b) + c + d = 5 Then Count = n
+    End Function
+
+    Public Sub Main()
+        If App.IsInIDE Then
+            Debug.Print "Count = " & Count()
+        Else
+            ExitProcess Count()
+        End If
+    End Sub
+
+    [RunAfterBuild]
+    Private Sub Built()
+        Debug.Cls
+        Main
+    End Sub
+
+End Module

builder/page-baseline.json

@@ -1,5 +1,5 @@
 {
   "src": "docs",
-  "pages": 1286,
+  "pages": 1472,
   "staticFiles": 1011
 }

docs/LLVM/Getting-Started.md

@@ -69,6 +69,15 @@ The main feature not yet supported is passing an error up to the calling procedu
 > [!WARNING] BETA 1005
 > Code compiled with LLVM rounds a **Single** or **Double** that is exactly halfway between two integers away from zero when it converts the value to an integer type: in [**CLng**](../tB/Modules/Conversion/CLng), **CInt** and **CLngLng** of a variable, in an assignment to an **Integer** or **Long**, and in the operands of [**\\**](../tB/Core/IntegerDivide). With a **Double** variable holding 2.5, `CLng(x)` is 3, and with -0.5 it is -1. Without LLVM the value is rounded to the even integer, 2 and 0, as VB6 does. A constant expression such as `CLng(2.5)`, a **Variant** argument, and [**Round**](../tB/Modules/Math/Round), **Int** and **Fix** are not affected.
 
+> [!WARNING] BETA 1005
+> A program built with LLVM ends with an access violation (0xC0000005) and no message box at the first [**GoSub**](../tB/Core/GoSub-Return) it runs, in a 32-bit and in a 64-bit build. A run in the IDE is not affected, and neither is a program built without LLVM. Replace the **GoSub** with a call to a **Private Sub**.
+
+> [!WARNING] BETA 1005
+> In a 64-bit build with LLVM, a call to a [**Declare**](../tB/Core/Declare)d procedure that passes `ByVal 0&` for its eighth parameter, declared `ByRef` with a 32-bit type such as **Long**, to give the procedure a NULL pointer, can end with an access violation (0xC0000005) and no message box, in the procedure. The eighth parameter of **WideCharToMultiByte** is one such case. Whether the call fails depends on what the stack held before it. The same override for the first to seventh parameters is right. Declare the parameter `ByVal ... As LongPtr` instead. It affects a built exe and a run in the IDE with LLVM turned on, and not a 32-bit build or a build without LLVM.
+
+> [!WARNING] BETA 1005
+> A call that passes an argument with `ByVal` for a `ByRef` parameter of a twinBASIC [**Sub**](../tB/Core/Sub) or [**Function**](../tB/Core/Function), such as `Take ByVal 0&` for `Sub Take(ByRef h As Long)`, does not compile with LLVM, in a 32-bit and in a 64-bit build. The build prints `[LLVM] codegen error occurred when compiling '<procedure>': Call parameter type does not match function signature!`, still makes the program, and the procedure that contains the call does not run: a 64-bit program ends with an access violation (0xC0000005) when it enters that procedure, and a 32-bit program skips the procedure and can fault later. Without LLVM the call passes a NULL pointer. VB6 refuses the call with the error *Type mismatch*. Pass a variable for the parameter instead.
+
 Code compiled with LLVM ignores [**Debug.Assert**](../tB/Modules/Debug#assert): the statement does not stop, and its condition is not evaluated.
 
 All other language features should work, in both 32-bit and 64-bit builds. Please [report](../FAQ#bug-reporting) any crash that LLVM causes, and any message saying "a feature used in your code is not yet supported with the LLVM compiler".

docs/Reference/Contributed/AutoCompleteLib/AutoComplete.md

@@ -53,7 +53,7 @@ Returns or sets the file-system objects enumerated when the source is **AutoComp
 Syntax: *object*.**FileSystemOptions** [ = *value* ]
 
 *value*
-: One or more **AutoCompleteFileSystemOptionConstants** values combined with `Or`.
+: One or more [**AutoCompleteFileSystemOptionConstants**](Enumerations/AutoCompleteFileSystemOptionConstants) values combined with `Or`.
 
 | Constant | Value | Description |
 |----------|-------|-------------|
@@ -77,7 +77,7 @@ Returns or sets flags that control how the completion works.
 Syntax: *object*.**Options** [ = *value* ]
 
 *value*
-: One or more **AutoCompleteOptionConstants** values combined with `Or`.
+: One or more [**AutoCompleteOptionConstants**](Enumerations/AutoCompleteOptionConstants) values combined with `Or`.
 
 | Constant | Value | Description |
 |----------|-------|-------------|
@@ -141,7 +141,7 @@ Syntax: *object*.**Init** *hWndEdit*, *Source*
 : *required* A **LongPtr** (32-bit: **Long**) containing the window handle of the edit control that should receive suggestions.
 
 *Source*
-: *required* An **AutoCompleteSourceConstants** value identifying where suggestions come from.
+: *required* An [**AutoCompleteSourceConstants**](Enumerations/AutoCompleteSourceConstants) value identifying where suggestions come from.
 
 | Constant | Value | Description |
 |----------|-------|-------------|