repo-buildutils.ps1

<#
.SYNOPSIS
    Project/Repo specific extensions to common support

.DESCRIPTION
    This provides repository specific functionality used by the various
    scripts. It will import the common repo neutral module such that this
    can be considered an extension of that module. It is expected that the
    various build scrips will "dot source" this one to consume common
    functionality.
#>

# reference the common build library. This library is intended
# for re-use across multiple repositories so should remain independent
# of the particular details of any specific repository. Over time, this
# may migrate to a git sub module for easier sharing between projects.
using module 'PSModules\CommonBuild\CommonBuild.psd1'

# Repo specific PS CSemVer support to avoid circular dependency on what
# is being built... (i.e, this project can't use itself to provide CSemVer
# info during the build)
using module 'PSModules\CSemVer\CSemVerBuild.psd1'

Set-StrictMode -version 3.0

$ErrorActionPreference = "Stop"
$InformationPreference = "Continue"

function ConvertTo-BuildIndex
{
    param([Parameter(Mandatory=$true, ValueFromPipeLine)][DateTime]$timeStamp)

    $timeStamp = $timeStamp.ToUniversalTime()
    $midnightTodayUtc = [DateTime]::new($timeStamp.Year, $timeStamp.Month, $timeStamp.Day, 0, 0, 0, [DateTimeKind]::Utc)
    $baseDate = [DateTime]::new(2000, 1, 1, 0, 0, 0, [DateTimeKind]::Utc)
    $buildNumber = ([Uint32]($timeStamp - $baseDate).Days) -shl 16
    $buildNUmber += [UInt16](($timeStamp - $midnightTodayUtc).TotalSeconds / 2)
    return $buildNumber
}

function Initialize-BuildEnvironment
{
<#
.SYNOPSIS
    Initializes the build environment for the build scripts

.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 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.

.DESCRIPTION
    This script is used to initialize the build environment in a central place, it returns the
    build info Hashtable with properties determined for the build. Script code should use these
    properties instead of any environment variables. While this script does setup some environment
    variables for non-script tools (i.e., MSBuild) script code should not rely on those.

    This script will setup the PATH environment variable to contain the path to MSBuild so it is
    readily available for all subsequent script code.

    Environment variables set for non-script tools:

    | Name               | Description |
    |--------------------|-------------|
    | IsAutomatedBuild   | "true" if in an automated build environment "false" for local developer builds |
    | IsPullRequestBuild | "true" if this is a build from an untrusted pull request (limited build, no publish etc...) |
    | IsReleaseBuild     | "true" if this is an official release build |
    | CiBuildName        | Name of the build for Constrained Semantic Version construction |
    | BuildTime          | ISO-8601 formatted time stamp for the build (local builds are based on current time, automated builds use the time from the HEAD commit)
 #>
    # support common parameters
    [cmdletbinding()]
    Param([switch]$FullInit,
          [switch]$AllowVsPreReleases
         )
    try
    {
        # use common repo-neutral function to perform most of the initialization
        $buildInfo = Initialize-CommonBuildEnvironment -FullInit:$FullInit -AllowVsPreReleases:$AllowVsPreReleases
        $buildInfo['OfficialGitRemoteUrl'] = 'https://github.com/UbiquityDotNET/Argument.Validators.git'
        
        $verInfo = Get-ParsedBuildVersionXML -BuildInfo $buildInfo
        $verInfo['CiBuildIndex'] = ConvertTo-BuildIndex $buildInfo['BuildTime']
        $verInfo['CiBuildName'] = $buildInfo['CiBuildName']

        # force env overloads of variables, normally generated by tasks
        # but the tasks cannot be used in this build as it is building the tasks
        $csemVer = [CSemVer]::New($verInfo)
        $env:BuildMajor = $csemVer.Major
        $env:BuildMinor = $csemVer.Minor
        $env:BuildPatch = $csemVer.Patch
        $env:BuildMeta = $csemVer.BuildMetadata
        $env:FullBuildNumber = $csemVer.ToString()
        $env:PackageVersion = $csemVer.ToString($false,$true)

        $fileVer = $csemVer.FileVersion
        $env:FileVersion = $fileVer.ToString()
        $env:FileVersionMajor = $fileVer.Major
        $env:FileVersionMinor = $fileVer.Minor
        $env:FileVersionBuild = $fileVer.Build
        $env:FileVersionRevision = $fileVer.Revision

        if($csemVer.PrereleaseVersion)
        {
            $env:PreReleaseName = $csemVer.PrereleaseVersion.Name
            $env:PreReleaseNumber = $csemVer.PrereleaseVersion.Number
            $env:PreReleaseFix = $csemVer.PrereleaseVersion.Fix
            $env:CiBuildName = $csemVer.PrereleaseVersion.CiBuildName
            $env:CiBuildIndex = $csemVer.PrereleaseVersion.CiBuildIndex
        }
        if($FullInit)
        {
            Show-FullBuildInfo $buildInfo
        }
        else
        {
            Write-Information "FullBuildNumber: $env:FullBuildNumber"
        }
    }
    catch
    {
        # Ensure exception location information bubbles up with any exceptions
        # So users aren't left scratching their heads on what went wrong, or more
        # importantly, WHERE it went wrong!
        # This is surprising, and dumb, but it's how PS core exceptions work
        throw
    }
    return $buildInfo
}