Docs: add section about cross-platform installation

docs/changelog.md

@@ -24,6 +24,10 @@ Requires libvips v8.10.6
   [#2687](https://github.com/lovell/sharp/pull/2687)
   [@JakobJingleheimer](https://github.com/JakobJingleheimer)
 
+* Add install-time flag to skip version compatibility checks.
+  [#2692](https://github.com/lovell/sharp/pull/2692)
+  [@xemle](https://github.com/xemle)
+
 ### v0.28.1 - 5th April 2021
 
 * Ensure all installation errors are logged with a more obvious prefix.

docs/install.md

@@ -49,13 +49,12 @@ The following platforms require compilation of both libvips and sharp from sourc
 
 The architecture and platform of Node.js used for `npm install`
 must be the same as the architecture and platform of Node.js used at runtime.
+See the [cross-platform](#cross-platform) section if this is not the case.
 
 When using npm v6 or earlier, the `npm install --unsafe-perm` flag must be used when installing as `root` or a `sudo` user.
 
 When using npm v7, the user running `npm install` must own the directory it is run in.
 
-When installing cross platform prebuilts on linux hosts an installation can be forced by `--sharp-install-force` flag or by setting `SHARP_INSTALL_FORCE` env variable.
-
 The `npm install --ignore-scripts=false` flag must be used when `npm` has been configured to ignore installation scripts.
 
 Check the output of running `npm install --verbose sharp` for useful error messages.
@@ -72,6 +71,33 @@ When this new ARM64 CPU is made freely available
 to open source projects via a CI service
 then prebuilt sharp binaries can also be provided.
 
+## Cross-platform
+
+At `npm install` time, prebuilt binaries are automatically selected for the
+current OS platform and CPU architecture, where available.
+
+The target platform and/or architecture can be manually selected using the following flags.
+
+```sh
+npm install --platform=... --arch=... --arm-version=... sharp
+```
+
+* `--platform`: one of `linux`, `linuxmusl`, `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`).
+* `--sharp-install-force`: skip version compatibility checks.
+
+These values can also be set via environment variables,
+`npm_config_platform`, `npm_config_arch`, `npm_config_arm_version`
+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
+```
+
 ## Custom libvips
 
 To use a custom, globally-installed version of libvips instead of the provided binaries,

install/libvips.js

@@ -50,7 +50,7 @@ const fail = function (err) {
 
 const handleError = function (err) {
   if (installationForced) {
-    console.warn(`${err.message}. Continue due forced installation`);
+    libvips.log(`Installation warning: ${err.message}`);
   } else {
     throw err;
   }
@@ -105,7 +105,8 @@ try {
     if (platformAndArch === 'freebsd-x64' || platformAndArch === 'openbsd-x64' || platformAndArch === 'sunos-x64') {
       throw new Error(`BSD/SunOS systems require manual installation of libvips >= ${minimumLibvipsVersion}`);
     }
-    if (detectLibc.family === detectLibc.GLIBC && detectLibc.version) {
+    // Linux libc version check
+    if (detectLibc.family === detectLibc.GLIBC && detectLibc.version && minimumGlibcVersionByArch[arch]) {
       if (semverLessThan(`${detectLibc.version}.0`, `${minimumGlibcVersionByArch[arch]}.0`)) {
         handleError(new Error(`Use with glibc ${detectLibc.version} requires manual installation of libvips >= ${minimumLibvipsVersion}`));
       }
@@ -115,7 +116,7 @@ try {
         handleError(new Error(`Use with musl ${detectLibc.version} requires manual installation of libvips >= ${minimumLibvipsVersion}`));
       }
     }
-
+    // Node.js minimum version check
     const supportedNodeVersion = process.env.npm_package_engines_node || require('../package.json').engines.node;
     if (!semverSatisfies(process.versions.node, supportedNodeVersion)) {
       handleError(new Error(`Expected Node.js version ${supportedNodeVersion} but found ${process.versions.node}`));