Add note about the optional "vsversion" input (#77)

Instead of the v1 tag, that is. This makes it possible to push changes
to release/v1 branch and get CI test them without actually moving the
release tag which effectively publishes the updates to users.

.github/workflows/main.yml

@@ -13,25 +13,72 @@ jobs:
   test:
     name: default
     runs-on: windows-latest
-    strategy:
-      fail-fast: false
     steps:
       - name: Check out source code
-        uses: actions/checkout@v1
+        uses: actions/checkout@v4
+      - name: Download Internet
+        run: npm install
+      - name: Run eslint
+        run: npm run lint
+      - name: Enable Developer Command Prompt (amd64)
+        uses: ./
+        with:
+          arch: amd64
+      - name: Compile and run some C code (amd64)
+        shell: cmd
+        run: |
+          cl.exe hello.c
+          hello.exe
+      - name: Enable Developer Command Prompt (amd64_x86)
+        uses: ./
+        with:
+          arch: amd64_x86
+      - name: Compile and run some C code (x86)
+        shell: cmd
+        run: |
+          cl.exe hello.c
+          hello.exe
+      - name: Enable Developer Command Prompt (amd64_arm)
+        uses: ./
+        with:
+          arch: amd64_arm
+      - name: Compile some C code (arm)
+        shell: cmd
+        run: |
+          cl.exe hello.c
+          dumpbin /headers hello.exe
+      - name: Enable Developer Command Prompt (amd64_arm64)
+        uses: ./
+        with:
+          arch: amd64_arm64
+      - name: Compile some C code (arm64)
+        shell: cmd
+        run: |
+          cl.exe hello.c
+          dumpbin /headers hello.exe
+  audit:
+    name: npm audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source code
+        uses: actions/checkout@v4
+      - run: npm install
+      - run: npm audit --audit-level=moderate --production
+      - run: npm audit --audit-level=critical
+  alias-arch:
+    name: arch aliases
+    runs-on: windows-latest
+    steps:
+      - name: Check out source code
+        uses: actions/checkout@v4
       - name: Download Internet
         run: npm install
       - name: Enable Developer Command Prompt
         uses: ./
+        with:
+          arch: Win32
       - name: Compile and run some C code
         shell: cmd
         run: |
           cl.exe hello.c
           hello.exe
-  audit:
-    name: npm audit
-    runs-on: windows-latest
-    steps:
-      - name: Check out source code
-        uses: actions/checkout@v1
-      - run: npm install
-      - run: npm audit --audit-level=moderate

.github/workflows/release.yml

@@ -11,13 +11,11 @@ jobs:
   test:
     name: release
     runs-on: windows-latest
-    strategy:
-      fail-fast: false
     steps:
       - name: Setup Developer Command Prompt
-        uses: ilammy/msvc-dev-cmd@v1
+        uses: ilammy/msvc-dev-cmd@release/v1
       - name: Check out source code
-        uses: actions/checkout@v1
+        uses: actions/checkout@v4
       - name: Compile and run some C code
         shell: cmd
         run: |
@@ -25,8 +23,9 @@ jobs:
           hello.exe
   audit:
     name: npm audit
-    runs-on: windows-latest
+    runs-on: ubuntu-latest
     steps:
       - name: Check out source code
-        uses: actions/checkout@v1
-      - run: npm audit --audit-level=moderate
+        uses: actions/checkout@v4
+      - run: npm audit --audit-level=moderate --production
+      - run: npm audit --audit-level=critical

README.md

@@ -8,12 +8,57 @@ This sets up the environment for compiling C/C++ code from command line.
 
 Supports Windows. Does nothing on Linux and macOS.
 
+## Example usage
+
+Basic usage for default compilation settings is like this:
+
+```yaml
+jobs:
+  test:
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ilammy/msvc-dev-cmd@v1
+      - name: Build something requiring CL.EXE
+        run: |
+          cmake -G "NMake Makefiles" .
+          nmake
+      # ...
+```
+
+If you want something non-default,
+like using a specific version of Visual Studio,
+or cross-compling for a different target,
+you will need to configure those settings via inputs:
+
+```yaml
+jobs:
+  test:
+    # Run a job for each of the specified target architectures:
+    strategy:
+      matrix:
+        arch:
+          - amd64
+          - amd64_x86
+          - amd64_arm64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ilammy/msvc-dev-cmd@v1
+        with:
+          arch: ${{ matrix.arch }}
+      - name: Build something requiring CL.EXE
+        run: |
+          cmake -G "NMake Makefiles" .
+          nmake
+      # ...
+```
+
 ## Inputs
 
 - `arch` – target architecture
-  - native compilation: `x86`, `x64` (default), `amd64` (synonym for x64)
-  - cross-compilation: `x86_amd64`, `x86_arm`, `x86_arm64`,
-  	`amd64_x86`, `amd64_arm`, `amd64_arm64`
+  - native compilation:
+    - `x64` (default) or its synonyms: `amd64`, `win64`, `x86_64`, `x86-64`
+    - `x86` or its synonyms: `win32`
+  - cross-compilation: `x86_amd64`, `x86_arm`, `x86_arm64`, `amd64_x86`, `amd64_arm`, `amd64_arm64`
 - `sdk` – Windows SDK to use
   - do not specify to use the default SDK
   - or specify full Windows 10 SDK number (e.g, `10.0.10240.0`)
@@ -25,21 +70,66 @@ Supports Windows. Does nothing on Linux and macOS.
   - `14.XX.YYYYY` for a specific full version number (e.g, `14.11.25503`)
 - `uwp` – set `true` to build for Universal Windows Platform (i.e., for Windows Store)
 - `spectre` – set `true` to use Visual Studio libraries with [Spectre](https://meltdownattack.com) mitigations
+- `vsversion` – the Visual Studio version to use. This can be the version number (e.g. 16.0 for 2019) or the year (e.g. "2019"); omit this input to select the latest version of Visual Studio. On [GitHub-hosted runners](https://docs.github.com/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners), this input is not required because there is only one Visual Studio in the environment.
 
-## Example usage
+## Caveats
+
+### Name conflicts with `shell: bash`
+
+Using `shell: bash` in Actions may shadow some of the paths added by MSVC.
+In particular, `link.exe` (Microsoft C linker) is prone to be shadowed by `/usr/bin/link` (GNU filesystem link tool).
+
+Unfortunately, this happens because GitHub Actions unconditionally *prepend* GNU paths when `shell: bash` is used,
+on top of any paths set by `msvc-dev-cmd`, every time at the start of each new step.
+Hence, there aren't many non-destructive options here.
+
+If you experience compilation errors where `link` complains about unreasonable command-line arguments,
+“extra operand *something-something*” – that's probably it.
+Recommended workaround is to remove `/usr/bin/link` if that interferes with your builds.
+If this is not acceptable, please file an issue, then we'll figure out something better.
+
+### Reconfiguration
+
+You can invoke `ilammy/msvc-dev-cmd` multiple times during your jobs with different inputs
+to reconfigure the environment for building with different settings
+(e.g., to target multiple architectures).
 
 ```yaml
 jobs:
-  test:
-    - uses: actions/checkout@v1
-    - uses: ilammy/msvc-dev-cmd@v1
-    - name: Build something requiring CL.EXE
-      run: |
-        cmake -G "NMake Makefiles" .
-        nmake
+  release:
+    steps:
+      # ...
+      - name: Configure build for amd64
+        uses: ilammy/msvc-dev-cmd@v1
+        with:
+          arch: amd64
+
+      - run: build # (for amd64)
+
+      - name: Configure build for x86
+        uses: ilammy/msvc-dev-cmd@v1
+        with:
+          arch: amd64_x86
+
+      - run: build # (for x86)
+
+      - name: Configure build for ARM64
+        uses: ilammy/msvc-dev-cmd@v1
+        with:
+          arch: amd64_arm64
+
+      - run: build # (for ARM64)
+
       # ...
 ```
 
+This mostly works but it's not really recommended
+since Developer Command Prompt was not meant for recursive reconfiguration.
+That said, if it does not work for you, please file an issue.
+
+Consider using [`strategy.matrix`](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix)
+to execute different build configuration in parallel, independent environments.
+
 ## License
 
 MIT, see [LICENSE](LICENSE).

action.yml

@@ -12,8 +12,10 @@ inputs:
     description: VC++ compiler toolset version
   uwp:
     description: Build for Universal Windows Platform
+  vsversion:
+    description: The Visual Studio version to use. This can be the version number (e.g. 16.0 for 2019) or the year (e.g. "2019").
 runs:
-  using: node12
+  using: node20
   main: index.js
 branding:
   icon: terminal

index.js

@@ -1,110 +1,20 @@
+const { setupMSVCDevCmd } = require('./lib')
 const core = require('@actions/core')
-const child_process = require('child_process')
-const exec = require('util').promisify(child_process.exec)
-const fs = require('fs')
-const process = require('process')
 
-const EDITIONS = ['Enterprise', 'Professional', 'Community']
-const VERSIONS = ['2019', '2017']
-
-const InterestingVariables = [
-    'INCLUDE',
-    'LIB',
-    'LIBPATH',
-    'Path',
-    'Platform',
-    'VisualStudioVersion',
-    /^VCTools/,
-    /^VSCMD_/,
-    /^WindowsSDK/i,
-]
-
-function findWithVswhere(pattern) {
-    try {
-        let installationPath = child_process.execSync(`vswhere -products * -latest -prerelease -property installationPath`).toString().trim()
-        return installationPath + '\\' + pattern
-    } catch (e) {
-        core.warn(`vswhere failed: ${e}`)
-    }
-    return null
-}
-
-function findVcvarsall() {
-    // If vswhere is available, ask it about the location of the latest Visual Studio.
-    let path = findWithVswhere('VC\\Auxiliary\\Build\\vcvarsall.bat')
-    if (path && fs.existsSync(path)) {
-        core.debug(`found with vswhere: ${path}`)
-        return path
-    }
-
-    // If that does not work, try the standard installation locations,
-    // starting with the latest and moving to the oldest.
-    const programFiles = process.env['ProgramFiles(x86)']
-    for (const ver of VERSIONS) {
-        for (const ed of EDITIONS) {
-            path = `${programFiles}\\Microsoft Visual Studio\\${ver}\\${ed}\\VC\\Auxiliary\\Build\\vcvarsall.bat`
-            if (fs.existsSync(path)) {
-                core.debug(`found standard location: ${path}`)
-                return path
-            }
-        }
-    }
-
-    // Special case for Visual Studio 2015 (and maybe earlier), try it out too.
-    path = `${programFiles}\\Microsoft Visual C++ Build Tools\\vcbuildtools.bat`
-    if (fs.existsSync(path)) {
-        core.debug(`found VS 2015: ${path}`)
-        return path
-    }
-
-    throw new Error('Microsoft Visual Studio not found')
-}
-
-async function main() {
-    if (process.platform != 'win32') {
-        core.info('This is not a Windows virtual environment, bye!')
-        return
-    }
-
-    const arch    = core.getInput('arch')
+function main() {
+    var   arch    = core.getInput('arch')
     const sdk     = core.getInput('sdk')
     const toolset = core.getInput('toolset')
     const uwp     = core.getInput('uwp')
     const spectre = core.getInput('spectre')
+    const vsversion = core.getInput('vsversion')
 
-    // Due to the way Microsoft Visual C++ is configured, we have to resort to the following hack:
-    // Call the configuration batch file and then output *all* the environment variables.
-
-    var args = [arch]
-    if (uwp == 'true') {
-        args.push('uwp')
-    }
-    if (sdk) {
-        args.push(sdk)
-    }
-    if (toolset) {
-        args.push(`-vcvars_ver=${toolset}`)
-    }
-    if (spectre == 'true') {
-        args.push('-vcvars_spectre_libs=spectre')
-    }
-
-    const command = `"${findVcvarsall()}" ${args.join(' ')} && set`
-    core.debug(`Running: ${command}`)
-    const { stdout } = await exec(command, {shell: "cmd"})
-    const environment = stdout.split('\r\n')
-
-    for (let string of environment) {
-        const [name, value] = string.split('=')
-        for (let pattern of InterestingVariables) {
-            if (name.match(pattern)) {
-                core.exportVariable(name, value)
-                break
-            }
-        }
-    }
-
-    core.info(`Configured Developer Command Prompt`)
+    setupMSVCDevCmd(arch, sdk, toolset, uwp, spectre, vsversion)
 }
 
-main().catch((e) => core.setFailed('Could not setup Developer Command Prompt: ' + e.message))
+try {
+    main()
+}
+catch (e) {
+    core.setFailed('Could not setup Developer Command Prompt: ' + e.message)
+}

lib.js

@@ -0,0 +1,225 @@
+const core = require('@actions/core')
+const child_process = require('child_process')
+const fs = require('fs')
+const path = require('path')
+const process = require('process')
+
+const PROGRAM_FILES_X86 = process.env['ProgramFiles(x86)']
+const PROGRAM_FILES = [process.env['ProgramFiles(x86)'], process.env['ProgramFiles']]
+
+
+const EDITIONS = ['Enterprise', 'Professional', 'Community', 'BuildTools']
+const YEARS = ['2022', '2019', '2017']
+
+const VsYearVersion = {
+    '2022': '17.0',
+    '2019': '16.0',
+    '2017': '15.0',
+    '2015': '14.0',
+    '2013': '12.0',
+}
+
+function vsversion_to_versionnumber(vsversion) {
+    if (Object.values(VsYearVersion).includes(vsversion)) {
+        return vsversion
+    } else {
+        if (vsversion in VsYearVersion) {
+            return VsYearVersion[vsversion]
+        }
+    }
+    return vsversion
+}
+exports.vsversion_to_versionnumber = vsversion_to_versionnumber
+
+function vsversion_to_year(vsversion) {
+    if (Object.keys(VsYearVersion).includes(vsversion)) {
+        return vsversion
+    } else {
+        for (const [year, ver] of Object.entries(VsYearVersion)) {
+            if (ver === vsversion) {
+                return year
+            }
+        }
+    }
+    return vsversion
+}
+exports.vsversion_to_year = vsversion_to_year
+
+const VSWHERE_PATH = `${PROGRAM_FILES_X86}\\Microsoft Visual Studio\\Installer`
+
+function findWithVswhere(pattern, version_pattern) {
+    try {
+        let installationPath = child_process.execSync(`vswhere -products * ${version_pattern} -prerelease -property installationPath`).toString().trim()
+        return installationPath + '\\' + pattern
+    } catch (e) {
+        core.warning(`vswhere failed: ${e}`)
+    }
+    return null
+}
+exports.findWithVswhere = findWithVswhere
+
+function findVcvarsall(vsversion) {
+    const vsversion_number = vsversion_to_versionnumber(vsversion)
+    let version_pattern
+    if (vsversion_number) {
+        const upper_bound = vsversion_number.split('.')[0] + '.9'
+        version_pattern = `-version "${vsversion_number},${upper_bound}"`
+    } else {
+        version_pattern = "-latest"
+    }
+
+    // If vswhere is available, ask it about the location of the latest Visual Studio.
+    let path = findWithVswhere('VC\\Auxiliary\\Build\\vcvarsall.bat', version_pattern)
+    if (path && fs.existsSync(path)) {
+        core.info(`Found with vswhere: ${path}`)
+        return path
+    }
+    core.info("Not found with vswhere")
+
+    // If that does not work, try the standard installation locations,
+    // starting with the latest and moving to the oldest.
+    const years = vsversion ? [vsversion_to_year(vsversion)] : YEARS
+    for (const prog_files of PROGRAM_FILES) {
+        for (const ver of years) {
+            for (const ed of EDITIONS) {
+                path = `${prog_files}\\Microsoft Visual Studio\\${ver}\\${ed}\\VC\\Auxiliary\\Build\\vcvarsall.bat`
+                core.info(`Trying standard location: ${path}`)
+                if (fs.existsSync(path)) {
+                    core.info(`Found standard location: ${path}`)
+                    return path
+                }
+            }
+        }
+    }
+    core.info("Not found in standard locations")
+
+    // Special case for Visual Studio 2015 (and maybe earlier), try it out too.
+    path = `${PROGRAM_FILES_X86}\\Microsoft Visual C++ Build Tools\\vcbuildtools.bat`
+    if (fs.existsSync(path)) {
+        core.info(`Found VS 2015: ${path}`)
+        return path
+    }
+    core.info(`Not found in VS 2015 location: ${path}`)
+
+    throw new Error('Microsoft Visual Studio not found')
+}
+exports.findVcvarsall = findVcvarsall
+
+function isPathVariable(name) {
+    const pathLikeVariables = ['PATH', 'INCLUDE', 'LIB', 'LIBPATH']
+    return pathLikeVariables.indexOf(name.toUpperCase()) != -1
+}
+
+function filterPathValue(path) {
+    let paths = path.split(';')
+    // Remove duplicates by keeping the first occurance and preserving order.
+    // This keeps path shadowing working as intended.
+    function unique(value, index, self) {
+        return self.indexOf(value) === index
+    }
+    return paths.filter(unique).join(';')
+}
+
+/** See https://github.com/ilammy/msvc-dev-cmd#inputs */
+function setupMSVCDevCmd(arch, sdk, toolset, uwp, spectre, vsversion) {
+    if (process.platform != 'win32') {
+        core.info('This is not a Windows virtual environment, bye!')
+        return
+    }
+
+    // Add standard location of "vswhere" to PATH, in case it's not there.
+    process.env.PATH += path.delimiter + VSWHERE_PATH
+
+    // There are all sorts of way the architectures are called. In addition to
+    // values supported by Microsoft Visual C++, recognize some common aliases.
+    let arch_aliases = {
+        "win32": "x86",
+        "win64": "x64",
+        "x86_64": "x64",
+        "x86-64": "x64",
+    }
+    // Ignore case when matching as that's what humans expect.
+    if (arch.toLowerCase() in arch_aliases) {
+        arch = arch_aliases[arch.toLowerCase()]
+    }
+
+    // Due to the way Microsoft Visual C++ is configured, we have to resort to the following hack:
+    // Call the configuration batch file and then output *all* the environment variables.
+
+    var args = [arch]
+    if (uwp == 'true') {
+        args.push('uwp')
+    }
+    if (sdk) {
+        args.push(sdk)
+    }
+    if (toolset) {
+        args.push(`-vcvars_ver=${toolset}`)
+    }
+    if (spectre == 'true') {
+        args.push('-vcvars_spectre_libs=spectre')
+    }
+
+    const vcvars = `"${findVcvarsall(vsversion)}" ${args.join(' ')}`
+    core.debug(`vcvars command-line: ${vcvars}`)
+
+    const cmd_output_string = child_process.execSync(`set && cls && ${vcvars} && cls && set`, {shell: "cmd"}).toString()
+    const cmd_output_parts = cmd_output_string.split('\f')
+
+    const old_environment = cmd_output_parts[0].split('\r\n')
+    const vcvars_output   = cmd_output_parts[1].split('\r\n')
+    const new_environment = cmd_output_parts[2].split('\r\n')
+
+    // If vsvars.bat is given an incorrect command line, it will print out
+    // an error and *still* exit successfully. Parse out errors from output
+    // which don't look like environment variables, and fail if appropriate.
+    const error_messages = vcvars_output.filter((line) => {
+        if (line.match(/^\[ERROR.*\]/)) {
+            // Don't print this particular line which will be confusing in output.
+            if (!line.match(/Error in script usage. The correct usage is:$/)) {
+                return true
+            }
+        }
+        return false
+    })
+    if (error_messages.length > 0) {
+        throw new Error('invalid parameters' + '\r\n' + error_messages.join('\r\n'))
+    }
+
+    // Convert old environment lines into a dictionary for easier lookup.
+    let old_env_vars = {}
+    for (let string of old_environment) {
+        const [name, value] = string.split('=')
+        old_env_vars[name] = value
+    }
+
+    // Now look at the new environment and export everything that changed.
+    // These are the variables set by vsvars.bat. Also export everything
+    // that was not there during the first sweep: those are new variables.
+    core.startGroup('Environment variables')
+    for (let string of new_environment) {
+        // vsvars.bat likes to print some fluff at the beginning.
+        // Skip lines that don't look like environment variables.
+        if (!string.includes('=')) {
+            continue;
+        }
+        let [name, new_value] = string.split('=')
+        let old_value = old_env_vars[name]
+        // For new variables "old_value === undefined".
+        if (new_value !== old_value) {
+            core.info(`Setting ${name}`)
+            // Special case for a bunch of PATH-like variables: vcvarsall.bat
+            // just prepends its stuff without checking if its already there.
+            // This makes repeated invocations of this action fail after some
+            // point, when the environment variable overflows. Avoid that.
+            if (isPathVariable(name)) {
+                new_value = filterPathValue(new_value)
+            }
+            core.exportVariable(name, new_value)
+        }
+    }
+    core.endGroup()
+
+    core.info(`Configured Developer Command Prompt`)
+}
+exports.setupMSVCDevCmd = setupMSVCDevCmd

package.json

@@ -1,11 +1,10 @@
 {
   "name": "msvc-dev-cmd",
-  "version": "1.1.1",
+  "version": "1.13.0-dev",
   "description": "GitHub Action to setup Developer Command Prompt for Microsoft Visual C++",
   "main": "index.js",
   "scripts": {
-    "lint": "eslint index.js",
-    "test": "eslint index.js"
+    "lint": "eslint index.js"
   },
   "repository": {
     "type": "git",
@@ -28,9 +27,9 @@
   },
   "homepage": "https://github.com/ilammy/msvc-dev-cmd#readme",
   "dependencies": {
-    "@actions/core": "^1.2"
+    "@actions/core": "^1.10.0"
   },
   "devDependencies": {
-    "eslint": "^6.8.0"
+    "eslint": "^7"
   }
 }