lib: create a Python symlink and add it to PATH

Helps to ensure a version of Python validated by lib/find-python.js
is used to run various Python scripts generated by gyp.

Known to affect gyp-mac-tool, probably affects gyp-flock-tool as well.

These Python scripts (such as `gyp-mac-tool`) are invoked directly,
via the generated Makefile, so their shebang lines determine
which Python binary is used to run them.
The shebang lines of these scripts are all `#!/usr/bin/env python3`,
so the first `python3` on the user's PATH will be used.

By adding a symlink to the Python binary validated by find-python.js,
and putting this symlink first on the PATH, we can ensure we use
a compatible version of Python to run these scripts.

(Only on Unix/Unix-like OSes. Symlinks are tricky on Windows,
and Python isn't used at build-time anyhow on Windows,
so this intervention isn't useful or necessary on Windows.

A similar technique for Windows, no symlinks required,
would be to make batch scripts which execute the target binary,
much like what Node does for its bundled copy of npm on Windows.)

Author: DeeDeeG

lib/build.js

@@ -185,6 +185,13 @@ function build (gyp, argv, callback) {
       }
     }
 
+    if (!win) {
+      // Add build-time dependency symlinks (such as Python) to PATH
+      const buildBinsDir = path.resolve('build', 'node_gyp_bins')
+      process.env.PATH = `${buildBinsDir}:${process.env.PATH}`
+      log.verbose('bin symlinks', `adding symlinks (such as Python), at "${buildBinsDir}", to PATH`)
+    }
+
     var proc = gyp.spawn(command, argv)
     proc.on('exit', onExit)
   }

lib/configure.js

@@ -17,6 +17,7 @@ if (win) {
 function configure (gyp, argv, callback) {
   var python
   var buildDir = path.resolve('build')
+  var buildBinsDir = path.join(buildDir, 'node_gyp_bins')
   var configNames = ['config.gypi', 'common.gypi']
   var configs = []
   var nodeDir
@@ -73,7 +74,9 @@ function configure (gyp, argv, callback) {
 
   function createBuildDir () {
     log.verbose('build dir', 'attempting to create "build" dir: %s', buildDir)
-    fs.mkdir(buildDir, { recursive: true }, function (err, isNew) {
+
+    const deepestBuildDirSubdirectory = win ? buildDir : buildBinsDir
+    fs.mkdir(deepestBuildDirSubdirectory, { recursive: true }, function (err, isNew) {
       if (err) {
         return callback(err)
       }
@@ -84,11 +87,22 @@ function configure (gyp, argv, callback) {
         findVisualStudio(release.semver, gyp.opts.msvs_version,
           createConfigFile)
       } else {
+        createPythonSymlink()
         createConfigFile()
       }
     })
   }
 
+  function createPythonSymlink () {
+    const symlinkDestination = path.join(buildBinsDir, 'python3')
+
+    log.verbose('python symlink', `creating symlink to "${python}" at "${symlinkDestination}"`)
+
+    fs.unlink(symlinkDestination, function () {
+      fs.symlink(python, symlinkDestination, function () {})
+    })
+  }
+
   function createConfigFile (err, vsInfo) {
     if (err) {
       return callback(err)