refactor all code that builds csources (#17815)

* refactor all code that builds csources
* fixup
* nim_csourcesDir_v0 + nim_csourcesDir
* remove deprecated, unused scripts from ci/
* reuse nimCsourcesHash in ci
* simplify CI pipelines by reusing nimBuildCsourcesIfNeeded
* simplify ci_docs.yml by reusing nimBuildCsourcesIfNeeded
* cleanup
* use csources_v1 as destination dir
* fixup
* remove pushCsources
* address comment: remove build.sh support for now
* fixup

ci/funs.sh

@@ -1,5 +1,7 @@
-# utilities used in CI pipelines to avoid duplication.
+# Utilities used in CI pipelines and tooling to avoid duplication.
 # Avoid top-level statements.
+# Prefer nim scripts whenever possible.
+# functions starting with `_` are considered internal, less stable.
 
 echo_run () {
   # echo's a command before running it, which helps understanding logs
@@ -28,3 +30,72 @@ nimIsCiSkip(){
     return 1
   fi
 }
+
+nimDefineVars(){
+  nim_csourcesDir=csources_v1 # where we clone
+  nim_csourcesUrl=https://github.com/nim-lang/csources_v1.git
+  nim_csourcesHash=a8a5241f9475099c823cfe1a5e0ca4022ac201ff
+  nim_csources=bin/nim_csources_$nim_csourcesHash
+}
+
+_nimNumCpu(){
+  # linux: $(nproc)
+  # FreeBSD | macOS: $(sysctl -n hw.ncpu)
+  # OpenBSD: $(sysctl -n hw.ncpuonline)
+  # windows: $NUMBER_OF_PROCESSORS ?
+  echo $(nproc 2>/dev/null || sysctl -n hw.logicalcpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || 1)
+}
+
+_nimBuildCsourcesIfNeeded(){
+  # if some systems cannot use make or gmake, we could add support for calling `build.sh`
+  # but this is slower (not parallel jobs) and would require making build.sh
+  # understand the arguments passed to the makefile (e.g. `CC=gcc ucpu=amd64 uos=darwin`),
+  # instead of `--cpu amd64 --os darwin`.
+  unamestr=$(uname)
+  # uname values: https://en.wikipedia.org/wiki/Uname
+  if [ "$unamestr" = 'FreeBSD' ]; then
+    makeX=gmake
+  elif [ "$unamestr" = 'OpenBSD' ]; then
+    makeX=gmake
+  else
+    makeX=make
+  fi
+  nCPU=$(_nimNumCpu)
+  echo_run which $makeX
+  # parallel jobs (5X faster on 16 cores: 10s instead of 50s)
+  echo_run $makeX -C $nim_csourcesDir -j $((nCPU + 2)) -l $nCPU "$@"
+  # keep $nim_csources in case needed to investigate bootstrap issues
+  # without having to rebuild
+  echo_run cp bin/nim $nim_csources
+}
+
+nimCsourcesHash(){
+  nimDefineVars
+  echo $nim_csourcesHash
+}
+
+nimBuildCsourcesIfNeeded(){
+  # goal: allow cachine each tagged version independently
+  # to avoid rebuilding, so that tools like `git bisect`
+  # can grab a cached past version without rebuilding.
+  nimDefineVars
+  (
+    set -e
+    # avoid polluting caller scope with internal variable definitions.
+    if test -f "$nim_csources"; then
+      echo "$nim_csources exists."
+    else
+      if test -d "$nim_csourcesDir"; then
+        echo "$nim_csourcesDir exists."
+      else
+        # depth 1: adjust as needed in case useful for `git bisect`
+        echo_run git clone -q --depth 1 $nim_csourcesUrl "$nim_csourcesDir"
+        echo_run git -C "$nim_csourcesDir" checkout $nim_csourcesHash
+      fi
+      _nimBuildCsourcesIfNeeded "$@"
+    fi
+
+    echo_run cp $nim_csources bin/nim
+    echo_run $nim_csources -v
+  )
+}