install-artifact-from-github

install-artifact-from-github

This is a no-dependency micro helper for developers of binary addons for Node. It is a companion project for save-artifact-to-github. These two projects are integrated with GitHub facilities and solve two problems:

• save-artifact-to-github saves a binary artifact according to the platform, architecture, and Node ABI.
• install-artifact-from-github retrieves such artifact, tests if it works properly, and rebuilds a project from sources in the case of failure.

In general, it can save your users from a long recompilation and, in some cases, even save them from installing build tools. By using GitHub facilities (Releases and Actions) the whole process of publishing and subsequent installations are secure, transparent, painless, inexpensive, or even free for public repositories.

How to install

Installation:

npm install --save install-artifact-from-github

How to use

In your package.json (pseudo-code with comments):

{
  // your custom package.json stuff
  // ...
  "scripts": {
    // your scripts go here
    // ...

    // creates an artifact (from save-artifact-to-github)
    "save-to-github": "save-to-github --artifact build/Release/ABC.node",

    // installs using pre-created artifacts
    "install": "install-from-cache --artifact build/Release/ABC.node",

    // used by "install" to test the artifact
    "verify-build": "node scripts/verify-build.js"

    // used by "install" to rebuild from sources
    "rebuild": "node-gyp rebuild"
  }
}

When a project, which uses install-artifact-from-github, is being installed, it does the following actions:

• Acquiring an artifact from the cache (an appropriate GitHub release).
  1. If the environment variable DEVELOPMENT_SKIP_GETTING_ASSET set to a non-empty value ⇒ it builds from sources.
  2. If the file .development is present in the project folder ⇒ it builds from sources.
  3. It tries to download an appropriate artifact compressed by brotli, if it is available. If it succeeds ⇒ it checks if it works.
  4. It tries to download an appropriate artifact compressed by gzip. If it succeeds ⇒ it checks if it works.
  5. If all downloads have failed ⇒ it builds from sources.
• In order to check that the downloaded artifact works:
  • It runs npm run verify-build. You may provide the script verify-build to do the checking.
    • If it returns with 0 exit code, we are done. Otherwise ⇒ it builds from sources.
  • If there is no verify-build, it tries npm test.
    • If it returns with 0 exit code, we are done. Otherwise ⇒ it builds from sources.
  • If both scripts are missing ⇒ it builds from sources.
• If it was determined to build the artifact from sources, it runs npm run rebuild, which should be provided.

Environment variables

• DEVELOPMENT_SKIP_GETTING_ASSET — if it is set to a non-empty value, it forces the build from sources. It is useful for development and testing.
• DEVELOPMENT_SHOW_VERIFICATION_RESULTS — if it is non-empty, it shows the verification output. Otherwise, the output is suppressed so not to scary unsuspecting users with possible errors. It is useful for development and testing.
• DOWNLOAD_HOST — if set, its value is used instead of https://github.com.

This script is meant to be run using npm run. It relies on npm environment variables to learn about the project.

Command-line parameters

• --artifact path — points where to place the downloaded artifact. It is a required parameter.
• --prefix prefix — provides a prefix for the generated artifact name. Default: ''.
• --suffix suffix — provides a suffix for the generated artifact name. Default: ''.
• --host host — provides a prefix for the download host. It should not end with /. Example: --host https://sample.com/repo.
  • If specified and non-empty, its value sets the host.
• --host-var ENVVAR — provides a name of an environment variable, which value will specify the download host. Example: --host-var RE2_DOWNLOAD_MIRROR.
  • Used only if --host is not specified.
  • If it is not specified, DOWNLOAD_HOST name is assumed.
  • If the specified environment variable is empty, https://github.com will be used.

Ultimately, the downloadable file name has the following format:

`${host}/${user}/${repo}/releases/download/${tag}/${prefix}${platform}-${arch}-${abi}${suffix}.${compression}`

Where:

• platform is process.platform.
  • Because Linux has different implementations of the C standard library, a special case is made for musl used by such popular distributions like Alpine. Such platforms have a code linux-musl.
• arch is process.arch.
• abi is process.versions.modules.
• compression can be br or gz.

Example with default values: https://github.com/uhop/node-re2/releases/download/1.15.2/linux-x64-83.br.

Documentation

The additional documentation is available in the wiki.

Example

The realistic complex example can be found in uhop/node-re2:

• package.json sets it up.
• builds.yaml implements a complex workflow.

Release history

• 1.1.0 moved save-to-github here from a separate project, reduced 3rd-party dependencies.
• 1.0.2 fixed a yarn-specific bug.
• 1.0.1 fixed a bug in the environment variable parameter.
• 1.0.0 initial release (extracted from node-re2).