Update nuget packages

Build-All.ps1

@@ -1,3 +1,37 @@
+<#
+.SYNOPSIS
+    Script to build all of the LLvm.NET code base
+
+.PARAMETER Configuration
+    This sets the build configuration to use, default is "Release" though for inner loop development this may be set to "Debug"
+
+.PARAMETER AllowVsPreReleases
+    Switch to enable use of Visual Studio Pre-Release versions. This is NEVER enabled for official production builds, however it is
+    useful when adding support for new versions during the pre-release stages.
+
+.PARAMETER ForceClean
+    Forces a complete clean (Recursive delete of the build output)
+
+.PARAMETER BuildMode
+    Specifies the build mode, which may be one of the following:
+
+    |Name    | Description                                                               |
+    |--------|---------------------------------------------------------------------------|
+    | Source | Builds only the source code. This is useful for local development.        |
+    | Docs   | Builds only the docs. Saves on build time when only updating docs topics. |
+    | All    | [Default] Builds everything                                               |
+
+.DESCRIPTION
+    This script is used by the automated build to perform the actual build. The Ubiquity.NET
+    family of projects all a PowerShell driven build that is generally divorced from the
+    automated build infrastructure used. This is done for several reasons, but the most
+    important ones are the ability to reproduce the build locally for inner development and
+    for flexibility in selecting the actual back end. The back ends have changed a few times
+    over the years and re-writing the entire build in terms of those back ends each time is
+    a lot of wasted effort. Thus, the projects settled on PowerShell as the core automated
+    build tooling.
+#>
+[cmdletbinding()]
 Param(
     [string]$Configuration="Release",
     [switch]$AllowVsPreReleases,
@@ -10,9 +44,10 @@ pushd $PSScriptRoot
 $oldPath = $env:Path
 try
 {
-    . .\buildutils.ps1
+    # Pull in the repo specific support and force a full initialization of all the environment
+    # as this is a top level build command.
+    . .\repo-buildutils.ps1
     $buildInfo = Initialize-BuildEnvironment -FullInit -AllowVsPreReleases:$AllowVsPreReleases
-
     $BuildSource = $false
     $BuildDocs = $false;
 
@@ -43,7 +78,12 @@ try
 }
 catch
 {
-    Write-Error $_.Exception.Message
+    # everything from the official docs to the various articles in the blog-sphere says this isn't needed
+    # and in fact it is redundant - They're all WRONG! By re-throwing the exception the original location
+    # information is retained and the error reported will include the correct source file and line number
+    # data for the error. Without this, only the error message is retained and the location information is
+    # Line 1, Column 1, of the outer most script file, which is, of course, completely useless.
+    throw
 }
 finally
 {

Build-Docs.ps1

@@ -1,22 +1,43 @@
+<#
+.SYNOPSIS
+    Builds the docs for this repository
+
+.PARAMETER Configuration
+    This sets the build configuration to use, default is "Release" though for inner loop development this may be set to "Debug"
+
+.PARAMETER AllowVsPreReleases
+    Switch to enable use of Visual Studio Pre-Release versions. This is NEVER enabled for official production builds, however it is
+    useful when adding support for new versions during the pre-release stages.
+
+.PARAMETER FullInit
+    Performs a full initialization. A full initialization includes forcing a re-capture of the time stamp for local builds
+    as well as writes details of the initialization to the information and verbose streams.
+
+.PARAMETER NoClone
+    Skip cloning of the docs repository. Useful for inner loop development where you only do the clone once when iterating on
+    doc updates.
+#>
 Param(
     [string]$Configuration="Release",
     [switch]$AllowVsPreReleases,
+    [switch]$FullInit,
     [switch]$NoClone
 )
 
 pushd $PSScriptRoot
 $oldPath = $env:Path
 try
 {
-    . .\buildutils.ps1
-    $buildInfo = Initialize-BuildEnvironment
+    . .\repo-buildutils.ps1
+    $buildInfo = Initialize-BuildEnvironment -FullInit:$FullInit -AllowVsPreReleases:$AllowVsPreReleases
 
     $msBuildProperties = @{ Configuration = $Configuration
                             LlvmVersion = $buildInfo['LlvmVersion']
                           }
 
     $docsOutputPath = $buildInfo['DocsOutputPath']
-    # clone docs output location so it is available as a destination for the Generated docs content
+
+    # Clone docs output location so it is available as a destination for the Generated docs content
     # and the versioned docs links can function correctly for locally generated docs
     if(!$NoClone -and !(Test-Path (Join-Path $docsOutputPath '.git') -PathType Container))
     {
@@ -44,12 +65,18 @@ try
     $docfxBuildBinLogPath = Join-Path $buildInfo['BinLogsPath'] Ubiquity.NET.Llvm-docfx-Build.binlog
 
     Write-Information "Building Docs Solution"
+    # NOTE: Current state of DocFX requires a distinct restore pass.
     Invoke-MSBuild -Targets 'Restore' -Project docfx\Ubiquity.NET.Llvm.DocFX.sln -Properties $msBuildProperties -LoggerArgs ($buildInfo['MsBuildLoggerArgs'] + @("/bl:$docfxRestoreBinLogPath") )
     Invoke-MSBuild -Targets 'Build' -Project docfx\Ubiquity.NET.Llvm.DocFX.sln -Properties $msBuildProperties -LoggerArgs ($buildInfo['MsBuildLoggerArgs'] + @("/bl:$docfxBuildBinLogPath") )
 }
 catch
 {
-    Write-Error $_.Exception.Message
+    # everything from the official docs to the various articles in the blog-sphere says this isn't needed
+    # and in fact it is redundant - They're all WRONG! By re-throwing the exception the original location
+    # information is retained and the error reported will include the correct source file and line number
+    # data for the error. Without this, only the error message is retained and the location information is
+    # Line 1, Column 1, of the outer most script file, which is, of course, completely useless.
+    throw
 }
 finally
 {

Build-Interop.ps1

@@ -2,6 +2,17 @@
 .SYNOPSIS
     Builds the native code Extended LLVM C API DLL along with the interop .NET assembly for it
 
+.PARAMETER Configuration
+    This sets the build configuration to use, default is "Release" though for inner loop development this may be set to "Debug"
+
+.PARAMETER AllowVsPreReleases
+    Switch to enable use of Visual Studio Pre-Release versions. This is NEVER enabled for official production builds, however it is
+    useful when adding support for new versions during the pre-release stages.
+
+.PARAMETER FullInit
+    Performs a full initialization. A full initialization includes forcing a re-capture of the time stamp for local builds
+    as well as writes details of the initialization to the information and verbose streams.
+
 .NOTE
 This script is unfortunately necessary due to several factors:
   1. SDK projects cannot reference VCXPROJ files correctly since they are multi-targeting
@@ -30,21 +41,22 @@ This script is unfortunately necessary due to several factors:
   3. This script to control the ordering of the build so that the native code is built, then the
      interop lib is restored and finally the interop lib is built with multi-targeting.
   4. The interop assembly project includes the NuGet packing with "content" references to the
-     native assemblies to place the in the correct "native" "runtimes" folder for NuGet to handle
-     them.
+     native assemblies to place the binaries in the correct "native" "runtimes" folder for NuGet
+     to handle them.
 #>
+
 Param(
     [string]$Configuration="Release",
     [switch]$AllowVsPreReleases,
-    [switch]$NoClean
+    [switch]$FullInit
 )
 
 pushd $PSScriptRoot
 $oldPath = $env:Path
 try
 {
-    . .\buildutils.ps1
-    $buildInfo = Initialize-BuildEnvironment -AllowVsPreReleases:$AllowVsPreReleases
+    . .\repo-buildutils.ps1
+    $buildInfo = Initialize-BuildEnvironment -FullInit:$FullInit -AllowVsPreReleases:$AllowVsPreReleases
 
     # <HACK>
     # for details of why this is needed, see src\PatchVsForLibClang\readme.md
@@ -82,26 +94,27 @@ try
     # and incompatibilities libs are generally not something published in a package. However, since the build time
     # for the libraries exceeds the time allowed for most hosted build services these must be pre-built for the
     # automated builds.
-    Install-LlvmLibs $buildInfo['LlvmLibsRoot'] $buildInfo['LlvmLibsPackageReleaseName']
+    Install-LlvmLibs $buildInfo
 
     $msBuildProperties = @{ Configuration = $Configuration
                             LlvmVersion = $buildInfo['LlvmVersion']
                           }
 
     Write-Information "Building LllvmBindingsGenerator"
+    $generatorRestoreBuildLogPath = Join-Path $buildInfo['BinLogsPath'] LlvmBindingsGeneratorRestore.binlog
     $generatorBuildLogPath = Join-Path $buildInfo['BinLogsPath'] LlvmBindingsGenerator.binlog
 
     # manual restore needed so that the CppSharp libraries are available during the build phase
-    # as CppSharp NuGet package is basically hostile to the newer SDK project format.
-    Invoke-MSBuild -Targets 'Restore;Build' -Project 'src\Interop\LlvmBindingsGenerator\LlvmBindingsGenerator.csproj' -Properties $msBuildProperties -LoggerArgs ($buildInfo['MsBuildLoggerArgs'] + @("/bl:$generatorBuildLogPath"))
+    Invoke-MSBuild -Targets 'Restore' -Project 'src\Interop\LlvmBindingsGenerator\LlvmBindingsGenerator.csproj' -Properties $msBuildProperties -LoggerArgs ($buildInfo['MsBuildLoggerArgs'] + @("/bl:$generatorRestoreBuildLogPath"))
+    Invoke-MSBuild -Targets 'Build' -Project 'src\Interop\LlvmBindingsGenerator\LlvmBindingsGenerator.csproj' -Properties $msBuildProperties -LoggerArgs ($buildInfo['MsBuildLoggerArgs'] + @("/bl:$generatorBuildLogPath"))
 
     # At present CppSharp only supports the "desktop" framework, so limiting this to net47 for now
     # Hopefully they will support .NET Core soon, if not, the generation stage may need to move out
     # to a manual step with the results checked in.
     Write-Information "Generating P/Invoke Bindings"
     Write-Information "LlvmBindingsGenerator.exe $($buildInfo['LlvmLibsRoot']) $(Join-Path $buildInfo['SrcRootPath'] 'Interop\LibLLVM') $(Join-Path $buildInfo['SrcRootPath'] 'Interop\Ubiquity.NET.Llvm.Interop')"
 
-    & "$($buildInfo['BuildOutputPath'])\bin\LlvmBindingsGenerator\Release\net47\LlvmBindingsGenerator.exe" $buildInfo['LlvmLibsRoot'] (Join-Path $buildInfo['SrcRootPath'] 'Interop\LibLLVM') (Join-Path $buildInfo['SrcRootPath'] 'Interop\Ubiquity.NET.Llvm.Interop')
+    & "$($buildInfo['BuildOutputPath'])\bin\LlvmBindingsGenerator\Release\net5.0-windows\LlvmBindingsGenerator.exe" $buildInfo['LlvmLibsRoot'] (Join-Path $buildInfo['SrcRootPath'] 'Interop\LibLLVM') (Join-Path $buildInfo['SrcRootPath'] 'Interop\Ubiquity.NET.Llvm.Interop')
     if($LASTEXITCODE -eq 0)
     {
         # now build the projects that consume generated output for the bindings
@@ -121,12 +134,17 @@ try
     }
     else
     {
-        Write-Error "Generating LLVM Bindings failed"
+        Write-Error "Generating LLVM Bindings failed" -ErrorAction Stop
     }
 }
 catch
 {
-    Write-Error $_.Exception.Message
+    # everything from the official docs to the various articles in the blog-sphere says this isn't needed
+    # and in fact it is redundant - They're all WRONG! By re-throwing the exception the original location
+    # information is retained and the error reported will include the correct source file and line number
+    # data for the error. Without this, only the error message is retained and the location information is
+    # Line 1, Column 1, of the outer most script file, which is, of course, completely useless.
+    throw
 }
 finally
 {

Build-Source.ps1

@@ -1,14 +1,33 @@
+<#
+.SYNOPSIS
+    Builds just the source code to produce the binaries and NUGET packages for the Ubiquity.NET.Llvm libraries
+
+.PARAMETER Configuration
+    This sets the build configuration to use, default is "Release" though for inner loop development this may be set to "Debug"
+
+.PARAMETER AllowVsPreReleases
+    Switch to enable use of Visual Studio Pre-Release versions. This is NEVER enabled for official production builds, however it is
+    useful when adding support for new versions during the pre-release stages.
+
+.PARAMETER FullInit
+    Performs a full initialization. A full initialization includes forcing a re-capture of the time stamp for local builds
+    as well as writes details of the initialization to the information and verbose streams.
+#>
 Param(
     [string]$Configuration="Release",
-    [switch]$AllowVsPreReleases
+    [switch]$AllowVsPreReleases,
+    [switch]$FullInit
 )
 
 pushd $PSScriptRoot
 $oldPath = $env:Path
 try
 {
-    . .\buildutils.ps1
-    $buildInfo = Initialize-BuildEnvironment -AllowVsPreReleases:$AllowVsPreReleases
+    # Pull in the repo specific support and force a full initialization of all the environment
+    # based on the switch parameter. Normally FullInit is done in Build-All, which calls this
+    # script. But for a local "inner loop" development this might be the only script used.
+    . .\repo-buildutils.ps1
+    $buildInfo = Initialize-BuildEnvironment -FullInit:$FullInit -AllowVsPreReleases:$AllowVsPreReleases
 
     $packProperties = @{ version=$($buildInfo['PackageVersion'])
                          llvmversion=$($buildInfo['LlvmVersion'])
@@ -20,18 +39,27 @@ try
                             LlvmVersion = $buildInfo['LlvmVersion']
                           }
 
+    # build the interop layer first using the script to manage the complexities of generated marshaling Interop
+    # and dependencies between C# and C++ projects.
     .\Build-Interop.ps1 -AllowVsPreReleases:$AllowVsPreReleases
 
+    # build the Managed code OO Wrapper layer
     $buildLogPath = Join-Path $buildInfo['BinLogsPath'] Ubiquity.NET.Llvm.binlog
     Write-Information "Building Ubiquity.NET.Llvm"
     Invoke-MSBuild -Targets 'Restore;Build' -Project src\Ubiquity.NET.Llvm.sln -Properties $msBuildProperties -LoggerArgs ($buildInfo['MsBuildLoggerArgs'] + @("/bl:$buildLogPath") )
 
+    # Create a ZIP file of all the nuget packages
     pushd $buildInfo['NuGetOutputPath']
     Compress-Archive -Force -Path *.* -DestinationPath (join-path $buildInfo['BuildOutputPath'] Nuget.Packages.zip)
 }
 catch
 {
-    Write-Error $_.Exception.Message
+    # everything from the official docs to the various articles in the blog-sphere says this isn't needed
+    # and in fact it is redundant - They're all WRONG! By re-throwing the exception the original location
+    # information is retained and the error reported will include the correct source file and line number
+    # data for the error. Without this, only the error message is retained and the location information is
+    # Line 1, Column 1, of the outer most script file, which is, of course, completely useless.
+    throw
 }
 finally
 {

Invoke-UnitTests.ps1

@@ -1,17 +1,38 @@
+<#
+.SYNOPSIS
+    Runs the unit tests as well as a validation run of the sample app
+
+.PARAMETER Configuration
+    This sets the build configuration to use, default is "Release" though for inner loop development this may be set to "Debug"
+
+.PARAMETER AllowVsPreReleases
+    Switch to enable use of Visual Studio Pre-Release versions. This is NEVER enabled for official production builds, however it is
+    useful when adding support for new versions during the pre-release stages.
+
+.PARAMETER FullInit
+    Performs a full initialization. A full initialization includes forcing a re-capture of the time stamp for local builds
+    as well as writes details of the initialization to the information and verbose streams.
+#>
+Param(
+    [string]$Configuration="Release",
+    [switch]$AllowVsPreReleases,
+    [switch]$FullInit
+)
+
 try
 {
-    . .\buildutils.ps1
-    $buildInfo = Initialize-BuildEnvironment
+    . .\repo-buildutils.ps1
+    $buildInfo = Initialize-BuildEnvironment -FullInit:$FullInit -AllowVsPreReleases:$AllowVsPreReleases
 
     $testsFailed = $false
 
-    Write-Information 'Running Interop tests as x64'
+    Write-Information 'Running Interop tests...'
     $testsFailed = $testsFailed -or (Invoke-DotNetTest $buildInfo 'src\Interop\InteropTests\InteropTests.csproj')
 
-    Write-Information 'Running Core library tests as x64'
+    Write-Information 'Running Core library tests...'
     $testsFailed = $testsFailed -or (Invoke-DotNetTest $buildInfo 'src\Ubiquity.NET.Llvm.Tests\Ubiquity.NET.Llvm.Tests.csproj')
 
-    Write-Information 'Running tests for Kaleidoscope Samples as x64'
+    Write-Information 'Running tests for Kaleidoscope Samples...'
     $testsFailed = $testsFailed -or (Invoke-DotNetTest $buildInfo 'Samples\Kaleidoscope\Kaleidoscope.Tests\Kaleidoscope.Tests.csproj')
 
     Write-Information 'Running sample app for .NET Core'
@@ -33,6 +54,11 @@ try
 }
 catch
 {
-    Write-Error $_.Exception.Message
+    # everything from the official docs to the various articles in the blog-sphere says this isn't needed
+    # and in fact it is redundant - They're all WRONG! By re-throwing the exception the original location
+    # information is retained and the error reported will include the correct source file and line number
+    # data for the error. Without this, only the error message is retained and the location information is
+    # Line 1, Column 1, of the outer most script file, which is, of course, completely useless.
+    throw
 }
 

OneFlow/Finish-Feature.ps1

@@ -1,6 +1,17 @@
+<#
+.SYNOPSIS
+    Encapsulates the steps for finishing a feature branch using OneFlow
+
+.DESCRIPTION
+    Completes a feature branch using OneFlow. This requires that the remote for the branch is the official repository
+    as it needs to push the feature branch changes into the "develop" branch after merging the changes.
+
+.PARAMETER featurename
+    Name of the feature to finalize. This is the relative name under the feature\* path.
+#>
 param($featurename)
 
-. .\buildutils.ps1
+. .\repo-buildutils.ps1
 $buildInfo = Initialize-BuildEnvironment
 
 # feature branch merges must only be pushed from a repository with the official GitHub repository as the origin remote.

OneFlow/Publish-Release.ps1

@@ -1,4 +1,16 @@
-. .\buildutils.ps1
+<#
+.SYNOPSIS
+    Publishes the current branch state as an official release tag
+
+.DESCRIPTION
+    This function ensures that no changes exist in the local repository so that only the tag is pushed.
+    Pushing a release tag should trigger GitHub actions that starts the official build via a GitHub action
+    or other such automated build processes. These, normally, also include publication of the resulting
+    binaries as appropriate. This function only pushes the tag, the rest is up to the back-end configuration
+    of the repository.
+#>
+
+. .\repo-buildutils.ps1
 $buildInfo = Initialize-BuildEnvironment
 
 # Release tags must only be pushed from a repository with the official GitHub repository as the origin remote.
@@ -14,7 +26,7 @@ if($remoteUrl -ine "https://github.com/UbiquityDotNET/Llvm.NET.git")
 }
 
 # pushing the tag to GitHub triggers the official build and release of the Nuget Packages
-$tagName = Get-BuildVersionTag
+$tagName = Get-BuildVersionTag $buildInfo
 $releaseBranch = "release/$tagName"
 $currentBranch = git rev-parse --abbrev-ref HEAD
 if( $releaseBranch -ne $currentBranch )