Add SLANG_VERSION for source archives

.gitattributes

@@ -3,3 +3,6 @@
 
 # Set the line endings to LF for shell scripts
 *.sh text eol=lf
+
+# Enable git archive substitution for tagged version file
+cmake/slang_git_version export-subst

.github/workflows/release-linux-glibc-2-27.yml

@@ -16,6 +16,7 @@ jobs:
         with:
           submodules: "recursive"
           fetch-depth: "0"
+          fetch-tags: true
 
       # build the binary in docker image
       - name: Run the build process with Docker
@@ -42,6 +43,8 @@ jobs:
           else
             version=$triggering_ref
           fi
+          # Sanitize version for use in filenames (replace path separators)
+          version=${version//\//-}
           base=$(pwd)/slang-${version}-linux-x86_64-glibc-2.27
           sudo mv "$(pwd)/build/dist-release/slang.zip" "${base}.zip"
           echo "SLANG_BINARY_ARCHIVE_ZIP=${base}.zip" >> "$GITHUB_OUTPUT"

.github/workflows/release.yml

@@ -95,6 +95,7 @@ jobs:
         with:
           submodules: "recursive"
           fetch-depth: "0"
+          fetch-tags: true
 
       - name: Setup
         uses: ./.github/actions/common-setup
@@ -266,6 +267,8 @@ jobs:
           else
             version=$triggering_ref
           fi
+          # Sanitize version for use in filenames (replace path separators)
+          version=${version//\//-}
           base=slang-${version}-${{matrix.os}}-${{matrix.platform}}
 
           # WASM packaging

cmake/GitVersion.cmake

@@ -1,44 +1,106 @@
 find_package(Git)
 
+# Helper function to display consistent warning message about missing Slang version from git tags
+function(_warn_missing_git_version var version context_msg)
+    message(
+        WARNING
+        "${context_msg}\n"
+        "Git tags are the AUTHORITATIVE source for version information in this project.\n"
+        "If you cloned from https://github.com/shader-slang/slang.git, fetch tags:\n"
+        "    git fetch --tags\n"
+        "If you cloned from a mirror or fork, fetch tags from the official repository:\n"
+        "    git fetch https://github.com/shader-slang/slang.git 'refs/tags/*:refs/tags/*'\n"
+        "Key implications of using an incorrect version number:\n"
+        "  (a) Version APIs and headers will return incorrect version information\n"
+        "  (b) Versioned filenames will be incorrect\n"
+        "If you cannot fetch tags, you can use -D${var}=<version> as a fallback,\n"
+        "but this is NOT the preferred method.\n"
+        "Falling back to default version: ${version}"
+    )
+endfunction()
+
 # Extract a version from the latest tag matching something like v1.2.3.4
 function(get_git_version var_numeric var dir)
     if(NOT DEFINED ${var})
         set(version_numeric "0.0.0")
         set(version "0.0.0-unknown")
-        if(GIT_EXECUTABLE)
-            set(command
-                "${GIT_EXECUTABLE}"
-                -C
-                "${dir}"
-                describe
-                --tags
-                --match
-                v20[2-9][0-9].[0-9]*
-            )
-            execute_process(
-                COMMAND ${command}
-                RESULT_VARIABLE result
-                OUTPUT_STRIP_TRAILING_WHITESPACE
-                OUTPUT_VARIABLE version_out
+        set(version_out "")
+
+        # First, try reading from slang_git_version file
+        set(version_file "${dir}/cmake/slang_git_version")
+        if(EXISTS "${version_file}")
+            file(READ "${version_file}" version_file_content)
+            string(STRIP "${version_file_content}" version_file_content)
+            # Check if it's not a git archive format string and matches expected pattern
+            if(
+                NOT version_file_content MATCHES "^\\$Format:"
+                AND version_file_content MATCHES "^v20[2-9][0-9]\\.[0-9]"
             )
-            if(NOT result EQUAL 0)
+                set(version_out "${version_file_content}")
                 message(
-                    WARNING
-                    "Getting ${var} failed: ${command} returned ${result}\nIs this a Git repo with tags?\nConsider settings -D${var} to specify a version manually"
+                    STATUS
+                    "Using version from slang_git_version file: ${version_out}"
                 )
-            elseif("${version_out}" MATCHES "^v(([0-9]+(\\.[0-9]+)*).*)")
-                set(version "${CMAKE_MATCH_1}")
-                set(version_numeric "${CMAKE_MATCH_2}")
-            else()
-                message(
-                    WARNING
-                    "Couldn't parse version (like v2025.21 or v2025.21-foo) from ${version_out}, using ${version} for now"
+            endif()
+        endif()
+
+        # If slang_git_version file didn't provide a valid version, try git describe
+        if(NOT version_out)
+            if(GIT_EXECUTABLE AND EXISTS "${dir}/.git")
+                set(command
+                    "${GIT_EXECUTABLE}"
+                    -C
+                    "${dir}"
+                    describe
+                    --tags
+                    --match
+                    v20[2-9][0-9].[0-9]*
+                )
+                execute_process(
+                    COMMAND ${command}
+                    RESULT_VARIABLE result
+                    OUTPUT_STRIP_TRAILING_WHITESPACE
+                    OUTPUT_VARIABLE git_describe_out
+                )
+                if(result EQUAL 0)
+                    set(version_out "${git_describe_out}")
+                    message(
+                        STATUS
+                        "Using version from git describe: ${version_out}"
+                    )
+                else()
+                    _warn_missing_git_version(
+                        "${var}"
+                        "${version}"
+                        "Failed to get version information from git tags."
+                    )
+                endif()
+            elseif(NOT GIT_EXECUTABLE)
+                _warn_missing_git_version(
+                    "${var}"
+                    "${version}"
+                    "Git executable not found - unable to get version information from git tags.\nPlease install git and fetch tags from the remote repository."
+                )
+            elseif(NOT EXISTS "${dir}/.git")
+                _warn_missing_git_version(
+                    "${var}"
+                    "${version}"
+                    "Git repository not found - unable to get version information from git tags.\nIf you cloned the repository, please fetch tags from the remote."
                 )
             endif()
-        else()
+        endif()
+
+        # Parse the version string (from either slang_git_version file or git describe)
+        if(
+            version_out
+            AND "${version_out}" MATCHES "^v(([0-9]+(\\.[0-9]+)*).*)"
+        )
+            set(version "${CMAKE_MATCH_1}")
+            set(version_numeric "${CMAKE_MATCH_2}")
+        elseif(version_out)
             message(
                 WARNING
-                "Couldn't find git executable to get ${var}, please use -D${var}, using ${version} for now"
+                "Couldn't parse version (like v2025.21 or v2025.21-foo) from ${version_out}, using ${version} for now"
             )
         endif()
     endif()

cmake/slang_git_version

@@ -0,0 +1 @@
+$Format:%(describe:tags=true,match=v20[2-9][0-9].[0-9]*)$

docs/building.md

@@ -34,6 +34,16 @@ fetch the submodules also.
 git clone https://github.com/shader-slang/slang --recursive
 ```
 
+You will need the git tags from this repository, otherwise versioning
+information (including the Slang modules directory name and the library
+filenames on macOS and Linux) will be incorrect. The above command should fetch
+them for you, but if you're fetching from a fork you may need to explicitly
+fetch the latest tags from the shader-slang repository with:
+
+```bash
+git fetch https://github.com/shader-slang/slang.git 'refs/tags/*:refs/tags/*'
+```
+
 ## Configure and build
 
 > This section assumes cmake 3.25 or greater, if you're on a lower version
@@ -160,7 +170,7 @@ against the fully versioned library filenames (e.g.,
 `libslang-compiler.so.0.2025.21` instead of `libslang-compiler.so`).
 
 Slang libraries for **Windows** do not have an explicit version in the
-filename, but the same guidance about stability of the ABI applies.
+library filename, but the the same guidance about stability of the ABI applies.
 
 Downstream users of Slang distributing their products as binaries should
 therefor **on all platforms, including Windows** redistribute the Slang