Add support for --libc flag to improve cross-platform install (#3160)

This deprecates the libc-as-suffix approach of --platform=linuxmusl

Author: joonamo

docs/install.md

@@ -74,20 +74,28 @@ The target platform and/or architecture can be manually selected using the follo
 npm install --platform=... --arch=... --arm-version=... sharp
 ```
 
-* `--platform`: one of `linux`, `linuxmusl`, `darwin` or `win32`.
+* `--platform`: one of `linux`, `darwin` or `win32`.
 * `--arch`: one of `x64`, `ia32`, `arm` or `arm64`.
 * `--arm-version`: one of `6`, `7` or `8` (`arm` defaults to `6`, `arm64` defaults to `8`).
+* `--libc`: one of `glibc` or `musl`. This option only works with platform `linux`, defaults to `glibc`
 * `--sharp-install-force`: skip version compatibility and Subresource Integrity checks.
 
 These values can also be set via environment variables,
-`npm_config_platform`, `npm_config_arch`, `npm_config_arm_version`
+`npm_config_platform`, `npm_config_arch`, `npm_config_arm_version`, `npm_config_libc`
 and `SHARP_INSTALL_FORCE` respectively.
 
 For example, if the target machine has a 64-bit ARM CPU and is running Alpine Linux,
 use the following flags:
 
 ```sh
-npm install --arch=arm64 --platform=linuxmusl sharp
+npm install --arch=arm64 --platform=linux --libc=musl sharp
+```
+
+If the current machine is Alpine Linux and the target machine is Debian Linux on x64 cpu,
+use the following flags:
+
+```sh
+npm install --arch=x64 --platform=linux --libc=glibc sharp
 ```
 
 ## Custom libvips
@@ -215,7 +223,8 @@ run the following additional command after `npm install`:
 
 ```sh
 npm install
-SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install --arch=x64 --platform=linux sharp
+rm -rf node_modules/sharp
+SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install --arch=x64 --platform=linux --libc=glibc sharp
 ```
 
 To get the best performance select the largest memory available.

lib/platform.js

@@ -7,10 +7,12 @@ const env = process.env;
 module.exports = function () {
   const arch = env.npm_config_arch || process.arch;
   const platform = env.npm_config_platform || process.platform;
-  /* istanbul ignore next */
-  const libc = (platform === 'linux' && detectLibc.isNonGlibcLinuxSync()) ? detectLibc.familySync() : '';
+  const libc = process.env.npm_config_libc ||
+    /* istanbul ignore next */
+    (detectLibc.isNonGlibcLinuxSync() ? detectLibc.familySync() : '');
+  const libcId = platform !== 'linux' || libc === detectLibc.GLIBC ? '' : libc;
 
-  const platformId = [`${platform}${libc}`];
+  const platformId = [`${platform}${libcId}`];
 
   if (arch === 'arm') {
     const fallback = process.versions.electron ? '7' : '6';

package.json

@@ -131,7 +131,7 @@
     "color": "^4.2.3",
     "detect-libc": "^2.0.1",
     "node-addon-api": "^4.3.0",
-    "prebuild-install": "^7.0.1",
+    "prebuild-install": "^7.1.0",
     "semver": "^7.3.7",
     "simple-get": "^4.0.1",
     "tar-fs": "^2.1.1",

test/unit/platform.js

@@ -61,4 +61,28 @@ describe('Platform-detection', function () {
     delete process.env.npm_config_arch;
     delete process.versions.electron;
   });
+
+  it('Can override libc if platform is linux', function () {
+    process.env.npm_config_platform = 'linux';
+    process.env.npm_config_libc = 'test';
+    assert.strictEqual('linuxtest', platform().split('-')[0]);
+    delete process.env.npm_config_platform;
+    delete process.env.npm_config_libc;
+  });
+
+  it('Handles libc value "glibc" as default linux', function () {
+    process.env.npm_config_platform = 'linux';
+    process.env.npm_config_libc = 'glibc';
+    assert.strictEqual('linux', platform().split('-')[0]);
+    delete process.env.npm_config_platform;
+    delete process.env.npm_config_libc;
+  });
+
+  it('Discards libc value on non-linux platform', function () {
+    process.env.npm_config_platform = 'win32';
+    process.env.npm_config_libc = 'gnuwin32';
+    assert.strictEqual('win32', platform().split('-')[0]);
+    delete process.env.npm_config_platform;
+    delete process.env.npm_config_libc;
+  });
 });