npm package: @labforward/driver-tools
Description: A CLI tool for building and managing Laboperator drivers.
Author: labforward GmbH
Latest version: 2.6.0

# @labforward/driver-tools

A CLI tool for building and managing Laboperator drivers.

## Install

This package should be added as a driver's development dependency:

- `yarn add -D @labforward/driver-tools`

After installing, the binary `laboperator-driver-tools` should be available. Run `npx laboperator-driver-tools --help` to get more information about what the tool can do.

## Development

1. Run `yarn install` and `yarn link`.
2. Run `yarn build:dev` to start the build process in watch mode.
3. Open a terminal on a driver repository and run `yarn link @labforward/driver-tools`.

## Builds

### Releases

Will create platform independent and fully contained drivers inside the driver's `release/` folder.

The naming scheme for builds follows the pattern:

`<driver name>-<tag>-<SHA-1 hash>-v<node modules version>-<os>-<arch>.zip`

- The Node version is specified according the `NODE_MODULES_VERSION` schema found [here](https://nodejs.org/en/download/releases/).

If bindings are not required for the build, a single release will be made with the os set to `any` and arch to `any`.

### Bundles

Will create a distributable zip file containing all multi-platform builds. The extension of this file is `dpak` (Driver Package).

The naming scheme for bundles follows the pattern:

`<driver name>-<tag>.dpak`

### Hashing

It's used to uniquely identify the contents of a release. The SHA-1 hash is created by hashing all files (excluding bindings in the `dist/build/` folder) inside the `dist/` folder.

The SHA-1 hash is trimmed to the first 8 hex characters. With 8 hex characters we need to generate 77000 hashes to have a 50% chance of having a collision.
Source: https://en.wikipedia.org/wiki/Birthday_problem#Probability_table

### Bindings

Changes in any of the following assumptions will break the build pipeline:

- All bindings have the extension `.node`.
- Webpack places all bindings inside the `dist/build/Release` folder.
- There is a single dependency with a `bindings` folder at its root-level.
- All bindings are stored inside the previously mentioned `bindings` folder.
- All bindings are compressed as `tar.gz` and contain a folder called `build/Release` with the bindings.
- All compressed bindings must contain the same number of bindings. Otherwise, a "dummy" binding should be added so that the amount matches.
- The compressed bindings use the standard gyp naming scheme:
  - `<bindings name>-<bindings version>-node-v<node modules version>-<os>-<arch>.tar.gz`

Notes on ARM bindings: currently an ARMv7 binding is provided which works with the RPi 3B+. Moving to a newer RPi will require us to recompile bindings for a newer architecture, such as ARMv8. Therefore, the ARM version is specified in the architecture.

### Assets

Drivers can have static assets included in the build. To use this feature, create an `assets` directory in the driver's directory. The `assets` directory will be copied to the final build. To access the assets during development and in production, use the following code:

```javascript
const assetsDir = process.env.ASSETS || '../../assets';
```

The variable `process.env.ASSETS` is defined via Webpack. The fallback path in the previous example is relative to the `src/lib/DeviceDriver.js` file.