build_docs: mrdocs, clang compiler support (#97)

.github/workflows/build_docs.yml

@@ -222,6 +222,7 @@ jobs:
             macosdocs.sh
             cd ../..
 
+            # 2025-04 Retry this after upgrading the antora version in boostorg/url
             # Run at least one antora build that installs everything
             # cd libs/url
             # macosdocs.sh
@@ -289,6 +290,7 @@ jobs:
             flags: "-boostrelease"
             skiplist: contract hana log parameter parameter_python python url
           - os: windows-2022
+            lint: yes
             flags: "-boostrelease"
             skiplist: contract hana log parameter parameter_python python url
 
@@ -297,7 +299,15 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-
+      - name: Install ScriptAnalyzer pre-reqs
+        if: ${{ matrix.lint == 'yes' }}
+        run: |
+          # is anything needed
+          $true
+      - name: ScriptAnalyzer
+        if: ${{ matrix.lint == 'yes' }}
+        run: |
+          Invoke-ScriptAnalyzer -EnableExit build_docs/windowsdocs.ps1
       - name: docs
         shell: powershell
         run: |
@@ -389,9 +399,9 @@ jobs:
             cd ../..
 
             # Run at least one antora build that installs everything
-            # cd libs/url
-            # Runwindowsdocs
-            # cd ../..
+            cd libs/url
+            Runwindowsdocs
+            cd ../..
 
             # For the rest --quick
             git submodule foreach 'powershell -command C:/scripts/cifunctions.ps1 $name'

build_docs/macosdocs.sh

@@ -115,6 +115,41 @@ else
     echo "Using current working directory ${workingdir}."
 fi
 
+function LocateCLCompiler {
+    # MrDocs requires a C++ compiler. Possibly other software will require a C++ compiler.
+    docsFolder=$1
+    startdir=$(pwd)
+    cd "$docsFolder"
+    clang_required="no"
+    if grep -r -i "mrdocs" . > /dev/null ; then
+        clang_required="yes"
+    fi
+    cd "${startdir}"
+
+    # Determine if a C++ compiler is available.
+    cl_available="no"
+    if command -v clang++ &> /dev/null
+    then
+        cl_available="yes"
+    fi
+    if command -v gcc &> /dev/null
+    then
+        cl_available="yes"
+    fi
+
+    if [ "${clang_required}" = "no" ] || [ "${cl_available}" = "yes" ]; then
+        # Success
+        true
+        return
+    else
+        echo "MrDocs was detected in the docs folder, however no clang compiler was found on the system. Please install a clang compiler (such as Xcode) and retry."
+        echo "It may be sufficient to run 'brew install gcc'."
+        echo "Please submit feedback if you believe this detection algorithm to be erroneous or if the function LocateCLCompiler can be improved."
+        echo "Exiting."
+        exit 1
+    fi
+}
+
 # DETERMINE REPOSITORY
 
 # shellcheck disable=SC2046
@@ -258,6 +293,13 @@ if [ "$skippackagesoption" != "yes" ]; then
     brew install gnu-sed
     brew install docbook
     brew install docbook-xsl
+    # zstd and cmake are required for mrdocs
+    brew install zstd
+    if ! command -v cmake &> /dev/null
+    then
+        echo "Installing cmake"
+        brew install cmake
+    fi
 
     if [ "$typeoption" = "main" ]; then
 
@@ -531,6 +573,12 @@ fi
 
 # -----------------------------------
 
+# a preflight compiler check
+
+LocateCLCompiler "$librarypath/doc"
+
+# -----------------------------------
+
 # the main compilation:
 
 if [ "$typeoption" = "main" ]; then

build_docs/other/windows-VS-2022-clang.ps1

@@ -3,7 +3,8 @@ iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.p
 
 echo "You may need to close and re-open your shell window."
 
-choco install -y visualstudio2022buildtools --parameters  \"--add Microsoft.VisualStudio.Component.VC.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset --add Microsoft.VisualStudio.ComponentGroup.NativeDesktop.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.CMake.Project\"
+choco feature disable --name='ignoreInvalidOptionsSwitches'
+choco install -y visualstudio2022buildtools --parameters  "--add Microsoft.VisualStudio.Component.VC.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset --add Microsoft.VisualStudio.ComponentGroup.NativeDesktop.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.CMake.Project"
 # choco install -y 7zip.install --version 22.1
 # choco install -y cmake.install --installargs '\"ADD_CMAKE_TO_PATH=System\"' --version 3.27.9
 # choco install -y curl --version 8.0.1
@@ -23,4 +24,5 @@ choco install -y vcredist2017 --version 14.16.27033
 choco install -y windows-sdk-10.1 --version 10.1.18362.1
 # choco install -y winscp --version 5.21.8
 # choco install -y winscp.install --version 5.21.8
-choco upgrade visualstudio2022-workload-vctools --package-parameters "--add Microsoft.VisualStudio.Component.VC.14.34.17.4.x86.x64" "--add Microsoft.VisualStudio.Component.VC.14.29.16.11.x86.x64" "--add Microsoft.VisualStudio.Component.VC.v141.x86.x64" "--add Microsoft.VisualStudio.Component.VC.140" -y 
+choco upgrade -y visualstudio2022-workload-vctools --package-parameters "--add Microsoft.VisualStudio.Component.VC.14.34.17.4.x86.x64 --add Microsoft.VisualStudio.Component.VC.14.29.16.11.x86.x64 --add Microsoft.VisualStudio.Component.VC.v141.x86.x64 --add Microsoft.VisualStudio.Component.VC.140"
+

build_docs/windowsdocs.ps1

@@ -22,7 +22,7 @@ $nvm_install_version="1.1.11"
 $node_version="20.17.0"
 $node_version_basic="20"
 
-Set-PSDebug -Trace 1
+# Set-PSDebug -Trace 1
 
 if ($help) {
 
@@ -49,6 +49,8 @@ standard arguments:
 "
 
 Write-Output $helpmessage
+# echo $helpmessage
+
 exit 0
 }
 if ($quick) { ${skip-boost} = $true ; ${skip-packages} = $true ; }
@@ -79,7 +81,7 @@ function refenv {
 
     # refreshenv might delete path entries. Return those to the path.
     $originalpath=$env:PATH
-    refreshenv
+    Update-SessionEnvironment
     $joinedpath="${originalpath};$env:PATH"
     $joinedpath=$joinedpath.replace(';;',';')
     $env:PATH = ($joinedpath -split ';' | Select-Object -Unique) -join ';'
@@ -131,6 +133,70 @@ function DownloadWithRetry([string] $url, [string] $downloadLocation, [int] $ret
     }
 }
 
+function LocateCLCompiler([string] $docsFolder) {
+
+    # MrDocs requires a C++ compiler. Possibly other software will require a C++ compiler.
+    $startdir = Get-Location | Foreach-Object { $_.Path }
+    Set-Location $docsFolder
+    # Determine if a C++ compiler is needed.
+    $clang_required="no"
+    $ResultList = (Get-ChildItem -Exclude test*,.test*,windowsdocs.ps1 | Select-String -quiet "mrdocs")
+    foreach ($result in $ResultList){
+        if ($result -eq "True") {
+              # Write-Output $result
+              $clang_required="yes"
+        }
+    }
+    # Now we know if $clang_required
+    Set-Location $startdir
+
+    # Determine if a C++ compiler is available.
+    $TmpErrorActionPreference = $ErrorActionPreference
+    $ErrorActionPreference = "Continue"
+    get-command cl.exe *>$null
+    if ( $? -eq "True" ) {
+            # Debugging info:
+            # Write-Output "Found cl.exe"
+            $cl_available="yes"
+    }
+    else {
+            # Debugging info:
+            # Write-Output "cl.exe not found"
+            $cl_available="no"
+    }
+
+    if ($clang_required -eq "no" -Or $cl_available -eq "yes") {
+        # Success
+        $ErrorActionPreference = $TmpErrorActionPreference
+        return
+    }
+    else {
+    # Include other Launch-VsDevShell.ps1 locations in this list:
+    $cl_command_attempts = @('C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\BuildTools\\Common7\\Tools\\Launch-VsDevShell.ps1',
+	                         'C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Launch-VsDevShell.ps1')
+    foreach ($cl_command_attempt in $cl_command_attempts) {
+        & $cl_command_attempt -arch amd64
+        get-command cl.exe *>$null
+        if ( $? -eq "True" ) {
+            # Debugging info:
+            # Write-Output "Found cl.exe"
+            $cl_available="yes"
+            $ErrorActionPreference = $TmpErrorActionPreference
+            return
+        }
+        else {
+            # Debugging info:
+            # Write-Output "cl.exe not found"
+            $cl_available="no"
+        }
+    }
+    Write-Output "MrDocs requires a C++ compiler, however one couldn't be found. There is a script here in build_docs/other/windows-VS-2022-clang.ps1 that may be used to install Visual Studio. After that, run this script again. If you believe the compiler cl.exe is available, feel free to examine this function LocateCLCompiler() and submit bug fixes."
+    Write-Output "Exiting."
+    $ErrorActionPreference = $TmpErrorActionPreference
+    exit 1
+    }
+}
+
 if ($pathoption) {
     Write-Output "Library path set to $pathoption. Changing to that directory."
     Set-Location $pathoption
@@ -696,6 +762,10 @@ if ("$REPONAME" -eq "geometry") {
     catch { Write-Output "couldn't find doxygen_xml2qbk.exe" }
 }
 
+# a preflight compiler check
+
+LocateCLCompiler("$librarypath/doc")
+
 # the main compilation:
 
 if ($typeoption -eq "antora") {