Preparations for final release (#359)

* Updates/Corrections and clarifications to docs
* Updates to NuGet dependencies to non-preview version
* Updates to repo readme

Author: smaillet

.editorconfig

@@ -28,9 +28,12 @@ indent_size = 2
 tab_width = 2
 
 [*.md]
-# mark left margion for split screen preview of markdown files
+# mark left margin for split screen preview of markdown files
 # requires: https://marketplace.visualstudio.com/items?itemName=PaulHarrington.EditorGuidelinesPreview
 guidelines = 92
+# VSSPELL: Markdown Files
+vsspell_section_id = 3fa02c9f36bb41a5ac6206ceb9c564dc
+vsspell_exclusion_expressions_3fa02c9f36bb41a5ac6206ceb9c564dc = ```[\s\S]*?$[\s\S]*?```$(?@@PND@@/Options/Multiline)
 
 # match ISO standard requirement for C/C++
 [*.c,*.h,*.cpp]
@@ -133,31 +136,31 @@ dotnet_naming_rule.non_field_members_should_be_pascal_case.style = pascal_case
 
 dotnet_naming_symbols.interface.applicable_kinds = interface
 dotnet_naming_symbols.interface.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
-dotnet_naming_symbols.interface.required_modifiers = 
+dotnet_naming_symbols.interface.required_modifiers =
 
 dotnet_naming_symbols.types.applicable_kinds = class, struct, interface, enum
 dotnet_naming_symbols.types.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
-dotnet_naming_symbols.types.required_modifiers = 
+dotnet_naming_symbols.types.required_modifiers =
 
 dotnet_naming_symbols.non_field_members.applicable_kinds = property, event, method
 dotnet_naming_symbols.non_field_members.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
-dotnet_naming_symbols.non_field_members.required_modifiers = 
+dotnet_naming_symbols.non_field_members.required_modifiers =
 
 # Naming styles
 
 dotnet_naming_style.begins_with_i.required_prefix = I
-dotnet_naming_style.begins_with_i.required_suffix = 
-dotnet_naming_style.begins_with_i.word_separator = 
+dotnet_naming_style.begins_with_i.required_suffix =
+dotnet_naming_style.begins_with_i.word_separator =
 dotnet_naming_style.begins_with_i.capitalization = pascal_case
 
-dotnet_naming_style.pascal_case.required_prefix = 
-dotnet_naming_style.pascal_case.required_suffix = 
-dotnet_naming_style.pascal_case.word_separator = 
+dotnet_naming_style.pascal_case.required_prefix =
+dotnet_naming_style.pascal_case.required_suffix =
+dotnet_naming_style.pascal_case.word_separator =
 dotnet_naming_style.pascal_case.capitalization = pascal_case
 
-dotnet_naming_style.pascal_case.required_prefix = 
-dotnet_naming_style.pascal_case.required_suffix = 
-dotnet_naming_style.pascal_case.word_separator = 
+dotnet_naming_style.pascal_case.required_prefix =
+dotnet_naming_style.pascal_case.required_suffix =
+dotnet_naming_style.pascal_case.word_separator =
 dotnet_naming_style.pascal_case.capitalization = pascal_case
 dotnet_style_coalesce_expression = true:warning
 dotnet_style_null_propagation = true:warning

Directory.Packages.props

@@ -39,9 +39,15 @@
     <PackageVersion Include="System.Memory" Version="4.5.5" />
 
     <!-- Currently, only in preview -->
-    <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
+    <PackageVersion Include="System.CommandLine" Version="2.0.0" />
 
-    <!-- Security vulnerability overrides -->
+    <!--
+    Security vulnerability overrides.
+    NOTE: For these to work the assemblies ***MUST** also have an explicit reference in the
+          impacted projects. Otherwise no upgrade.override occurs and the projects remain
+          vulnerable. Ideally the dependent projects would update to resolve this but,
+          sadly they do not, and remain vulnerable, and we must stop it here.
+    -->
     <!-- https://github.com/dotnet/roslyn-sdk/issues/1191 -->
     <PackageVersion Include="System.Formats.Asn1" Version="10.0.0" />
     <!-- https://github.com/advisories/GHSA-7jgj-8wvc-jh57 -->
@@ -51,14 +57,13 @@
 
     <!-- Common packages for solution -->
     <PackageVersion Include="System.Linq.Async" Version="6.0.3" />
-    <PackageVersion Include="Ubiquity.NET.InteropHelpers" Version="20.1.8-rc.2" />
-    <PackageVersion Include="Ubiquity.NET.Extensions" Version="20.1.8-rc.2" />
-    <PackageVersion Include="Ubiquity.NET.Runtime.Utils" Version="20.1.8-rc.2" />
-    <PackageVersion Include="Ubiquity.NET.CommandLine" Version="20.1.8-rc.2" />
-    <PackageVersion Include="Ubiquity.NET.ANTLR.Utils" Version="20.1.8-rc.2" />
-
+    <PackageVersion Include="Ubiquity.NET.InteropHelpers" Version="20.1.8" />
+    <PackageVersion Include="Ubiquity.NET.Extensions" Version="20.1.8" />
+    <PackageVersion Include="Ubiquity.NET.Runtime.Utils" Version="20.1.8" />
+    <PackageVersion Include="Ubiquity.NET.CommandLine" Version="20.1.8" />
+    <PackageVersion Include="Ubiquity.NET.ANTLR.Utils" Version="20.1.8" />
     <PackageVersion Include="Ubiquity.NET.LibLLVM" Version="20.1.8" />
-    <PackageVersion Include="Ubiquity.NET.Versioning" Version="6.0.2-beta" />
+    <PackageVersion Include="Ubiquity.NET.Versioning" Version="6.0.2" />
     <PackageVersion Include="Antlr4BuildTasks" Version="12.11.0" />
     <PackageVersion Include="Antlr4.Runtime.Standard" Version="4.13.1" />
     <PackageVersion Include="OpenSoftware.DgmlBuilder" Version="2.1.0" />

IgnoredWords.dic

@@ -77,6 +77,7 @@ getelementptr
 getters
 gh
 github
+gitignore
 Globalization
 Hashtable
 Identifier
@@ -88,12 +89,15 @@ inlined
 inlining
 Interop
 ints
+Invokable
 jit
 len
 Lexer
+libclang
 LibLLVM
 Llilum
 llvm
+llvmroot
 llvmversion
 lookups
 LValue
@@ -110,6 +114,8 @@ minimalistic
 Mips
 msbuild
 msg
+namespace
+namespaces
 nav
 nint
 noinline
@@ -125,6 +131,7 @@ outdent
 pages
 paren
 perf
+performant
 pointee
 polyfills
 pragma
@@ -156,12 +163,14 @@ telliam
 templated
 templating
 tl
+tocyml
 trx
 typdef
 Typedef
 typedefs
 typelib
 typeof
+Uber
 uid
 uint
 unaryop

PsModules/CommonBuild/Public/Initialize-CommonBuildEnvironment.ps1

@@ -52,6 +52,7 @@ function Initialize-CommonBuildEnvironment
         [string]$repoRoot,
         [switch]$FullInit
     )
+
     try
     {
         # Script code should ALWAYS use the global CurrentBuildKind
@@ -101,9 +102,12 @@ function Initialize-CommonBuildEnvironment
             # "profile" and the actual command is exposed.
             if($null -eq (Find-OnPath vswhere))
             {
-                # NOTE: automated builds in Github do NOT include WinGet (for reasons unknown)
+                # NOTE: automated builds in Github do NOT include winget (for reasons unknown)
                 # However, they do contain VSWHERE so should not hit this.
                 winget install Microsoft.VisualStudio.Locator | Out-Null
+
+                # location is fixed and the same no matter what version!
+                $env:PATH +=';%ProgramFiles(x86)%\Microsoft Visual Studio\Installer'
             }
 
             $vsShellModulePath = vswhere -latest -find **\Microsoft.VisualStudio.DevShell.dll

PsModules/CommonBuild/Public/Show-FullBuildInfo.ps1

@@ -9,7 +9,7 @@ function Show-FullBuildInfo
     properties so that the full details are available in logs.
 
 .DESCRIPTION
-    This function displays all the properties of the buildinfo to the information stream. Additionally,
+    This function displays all the properties of the build info to the information stream. Additionally,
     details of the current PATH, the .NET SDKs and runtimes installed is logged to the Verbose stream.
 #>
     Param($buildInfo)

README.md

@@ -15,14 +15,15 @@ For details of releases, see the [release notes](https://github.com/UbiquityDotN
 Ubiquity.NET.Llvm provides LLVM language and runtime bindings for .NET based applications.
 Ubiquity.NET.Llvm's goal is to provide a robust Class library that accurately reflects the
 underlying LLVM C++ model. This is done through an extended LLVM-C API bundled as a native
-library (LibLLVM). Ubiquity.NET.Llvm uses the support of LibLLVM to gain access to the LLVM
-class library and project it into a .NET managed library that reflects the original class
-library design as best as possible.
+library (`Ubiquity.NET.LibLLVM`). Ubiquity.NET.Llvm uses the support of LibLLVM to gain
+access to the LLVM class library and project it into a .NET managed library that reflects
+the original class library design as best as possible.
 
 The goal is to match the original class model as closely as possible, while providing an
 object model to .NET applications that feels familiar and consistent with common styles and
 patterns in .NET Framework applications. Thus, while class, method and enumeration names are
-similar to their counterparts in LLVM, they are not always identical.
+similar to their counterparts in LLVM, they are not always identical (especially casing and
+use of `_`).
 
 ### Brief History
 Ubiquity.NET.Llvm was initially developed as a means to leverage LLVM as the back-end for an
@@ -36,24 +37,25 @@ code generator that was tied to the ARMv4 Instruction set. ([Llilum](https://www
 Ubiquity.NET.Llvm has continued to evolve and improve and remains a distinct project as it
 has no dependencies on Llilum or any of its components. Ubiquity.NET.Llvm is viable for any
 .NET applications wishing to leverage the functionality of the LLVM libraries from .NET
-applications.
+applications. In fact, it's most common use now is for supporting JIT execution of Domain
+Specific Languages (DSL) though it is not limited to that as the [Kaleidoscope Tutorials](#kaleidoscope-tutorial)
+show an interactive JIT implementation along with full AOT compilation.
 
 Ubiquity.NET.Llvm began with LLVM 3.4 as a C++/CLI wrapper which enabled a closer binding to
 the original C++ object model then the official LLVM-C API supported. As Ubiquity.NET.Llvm
 progressed so to did LLVM. Eventually, the LLVM code base migrated to requiring C++/11
 support in the language to build. This became an issue for the C++/CLI wrapper as the
-Microsoft C++/CLI compiler didn't support the C++11 syntax. Thus a change was made to
-Ubiquity.NET.Llvm to move to an extended C API with a C# adapter layer to provide the full
-experience .NET developers expect. While the transition was a tedious one very little
-application code required changes. LLVM and Ubiquity.NET.Llvm have continued to progress and
-Ubiquity.NET.Llvm is currently based on LLVM 20.1.x.
+Microsoft C++/CLI compiler didn't support the `C++11` syntax. Thus, a change was made to
+`Ubiquity.NET.Llvm` to move to an extended C API with a C# adapter layer to provide the full
+experience .NET developers expect. While the transition was a tedious one, very little
+application code required changes. LLVM and `Ubiquity.NET.Llvm` have continued to progress
+and `Ubiquity.NET.Llvm` is currently based on LLVM 20.1.x.
 
 There are a few major goals of the current release that required breaking changes:
 1) AOT compilation of applications leveraging this library
-    - While this goal is not yet fully realized many steps were taken to aid in getting
-      there.
 2) Platform independence
-    - Again, not fully realized yet but many steps were taken to aid in getting there.
+    - Not fully realized in this release yet but many steps were taken to aid in getting
+      there.
         * The largest impediment is the massive resource requirements of building the native
           LLVM libraries for a given runtime. Building them runs afoul of the limitations of
           every available OSS not to mention exceeding the size of a NUGET package to host
@@ -72,16 +74,16 @@ package is built for the "AnyCPU" platform and references the Ubiquity.NET.Llvm.
 package to bring in the native binary support. Ubiquity.NET.Llvm.Interop contains code to
 dynamically detect the platform it is running on and load the appropriate native library.
 This allows applications to build for AnyCPU without creating multiple build configurations
-and release vehicles for applications. (Any new platforms would need to update the dynamic
-loading support and include the appropriate P/Invokable binaries - consuming apps would not
-need to change except to pick up a new package version.)
+and release vehicles for applications. Any new platforms would need to update the dynamic
+loading support and include the appropriate P/Invokable binaries. Consuming apps would not
+need to change except to pick up a new package version.
 
 ### CI Build NuGet Packages
-The CI Builds of the NuGet package built from the latest source in the master branch are
-available as build artifacts from the build. Unfortunately with an all GitHub build via
-GitHub Actions we don't have a good story for accessing the packages from unreleased
-automated CI builds. While GitHub does support a package registry (GPR), it really doesn't
-meet the needs of CI builds. In particular:
+The CI Builds of the NuGet package built from the latest source in the `develop` branch are
+available as build artifacts. Unfortunately with an all GitHub build via GitHub Actions we
+don't have a good story for accessing the packages from unreleased automated CI builds.
+While GitHub does support a package registry (GPR), it really doesn't meet the needs of CI
+builds. In particular:
 * GPR Doesn't support deletion of older CI build packages (Cluttering the feed)
 * GPR requires complex login/Tokens just to get packages from the feed, despite being a
   public repository...
@@ -92,7 +94,8 @@ used for publishing releases. (Official NuGet will serve that role for releases)
 and PR build packages are available as artifacts from the GitHub actions that build them.
 
 ### API Documentation
-The full API documentation on using Ubiquity.NET.Llvm is available on the [Ubiquity.NET.Llvm documentation site](https://ubiquitydotnet.github.io/Llvm.NET/).
+The full API documentation on using Ubiquity.NET.Llvm is available on the
+[Ubiquity.NET.Llvm documentation site](https://ubiquitydotnet.github.io/Llvm.NET/).
 
 ### Sample Applications
 #### Code Generation With Debug Information
@@ -123,13 +126,13 @@ the use of the library.
  
 #### Using Visual Studio
 The repository contains Visual Studio solution files that allow building the components
-individually for modifying Ubiquity.NET.Llvm, as well as running the available unit tests
-and samples. This is the primary mode of working with the Ubiquity.NET.Llvm source code
+individually for modifying `Ubiquity.NET.Llvm`, as well as running the available unit tests
+and samples. This is the primary mode of working with the `Ubiquity.NET.Llvm` source code
 during development.
 
 ### Replicating the automated build
-The Automated build support for Ubiquity.NET.Llvm uses Build-All.ps1 PowerShell script to
-build all the binaries and generate a NuGet package. To build the full package simply run
+The Automated build support for `Ubiquity.NET.Llvm` uses `Build-All.ps1` PowerShell script
+to build all the binaries and generate a NuGet package. To build the full package simply run
 `Build-All.ps1 -ForceClean` from a PowerShell command prompt with MSBuild tools on the
 system search path.
 

docfx/ReadMe.md

@@ -18,7 +18,7 @@ constructed a complete custom template to deal with it... Sigh, what a waste of
 ## Changes Over Time
 DocFX has obsoleted the `docfxconsole` NuGet package that was used to run docfx for a
 project via MSBUILD. Instead it focused on a .NET tool to do it all via the command line.
-Ultimately the docfx.json serves as the corellary to a "project" file for the different site
+Ultimately the docfx.json serves as the corollary to a "project" file for the different site
 builds. The PowerShell script `Build-Docs.ps1` was updated to use the new tool directly.
 Using that script should have little or no impact on the overall flow. There is a
 "no-targets" project in the solution to enable easier access to the input files but does not
@@ -78,9 +78,9 @@ Since this is generated it is listed in the [.gitignore](#gitignore) file.
 These folders (named after the `*` portion of the [api-*](#api-*) folder names contains
 manually written additional files, articles, samples etc... related to a given library.
 
-## Guide to wrting XML DOC comments
+## Guide to writing XML DOC comments
 When dealing with doc comments the XML can sometimes get in the way of general readability
-of the source code. There is an inherent tension beween how a particular editor renders the
+of the source code. There is an inherent tension between how a particular editor renders the
 docs for a symbol/method (VS calls this "Quick Info") and how it is rendered in the final
 documentation by a tool like docfx. This guides general use to simplify things as much as
 possible.
@@ -144,7 +144,7 @@ render properly in final docs.
        everything is trimmed it is at least a distinct pattern that is readable.
 5) ***DO NOT*** put lists in any place other than inside a `remarks` region
     a) Usually, the remarks comments are not even rendered as the most useful part is the
-        API signaure and parameter info. Different editors may allow control of that.
+        API signature and parameter info. Different editors may allow control of that.
         i) In VS [2019|2022] for C# it is controlled by
             `Text Editor > C# > Advanced > Editor Help: "Show remarks in Quick Info."`
             1) Turning this off can greatly reduce the noise AND reduce the problems of

docfx/index.md

@@ -3,7 +3,7 @@ Ubiquity.NET family of libraries provides support for a number of scenarios but
 focus is AOT code generation of .NET for Embedded systems. We aren't quite there yet, but
 are rather close. In the mean time this set of libraries provides the building blocks needed
 for creating a Domain Specific Language (DSL) implementation or custom language compiler,
-including JIT execution. Several useful generalized libraries are also included.
+including JIT execution.
 
 ## The Libraries[<sup>1</sup>](#footnote_1) in this repository
 
@@ -12,7 +12,7 @@ including JIT execution. Several useful generalized libraries are also included.
 | [Ubiquity.NET.Llvm](llvm/index.md) | This library contains The core of the LLVM projection to .NET |
 
 ---
-<a id="footnote_1"/><sup>1</sup> The Ubiquity.NET.Llvm.Interop is intentionally NOT documented. It is an internal
-implementation detail subject to change in the future. There are plans to merge it with the
-OO wrapper library. Therefore, applications should NOT depend on it as it is likely to cease
-existing in the future.
+<a id="footnote_1"/><sup>1</sup> The Ubiquity.NET.Llvm.Interop is intentionally NOT
+documented. It is an internal implementation detail subject to change in the future. There
+are plans to merge it with the OO wrapper library. Therefore, applications should NOT depend
+on it as it is likely to cease existing in the future.

docfx/llvm/articles/InternalDetails/index.md

@@ -1,13 +1,13 @@
 # Internal details
 This section is focused on providing internal details of the Ubiquity.NET.Llvm
-implementation for developers contributing to the contents of the Ubiquity.NET.Llvm library
-itself. If you are only interested in using the `Ubiquity.NET.Llvm` APIs you don't need this
-information, though it may satisfy curiosity 8^).
+implementation for developers contributing to the contents of the `Ubiquity.NET.Llvm`
+library itself. If you are only interested in using the `Ubiquity.NET.Llvm` APIs you don't
+need this information, though it may satisfy curiosity :nerd_face:.
 
 ## Generate Handles
-The source for the handles is generated from the headers by the LibLLVM repository build.
-They are created  by the `LLvmBindingsGenerator` from the headers contained in the 
-`Ubiquity.NET.LibLLvm` package. The LibLLVM package is a bundle of the RID neutral headers
-along with any RID specific headers. It is ultimately a "Uber" package that references the
-RID specific native libraries. This keeps the size of each package down to meet NuGet
-standards.
+The source for the handles is generated from the headers by the `:lvmBindingGenerator` from
+the headers contained in the `Ubiquity.NET.LibLLvm` package. The LibLLVM package is a bundle
+of the RID neutral headers along with any RID specific headers. It is ultimately a "meta"
+package that references the RID specific native libraries. This keeps the size of each
+package down to meet NuGet standards while allowing easy addition of new runtimes in the
+future.