Build a CLI executable with pear make

pear make packages a command-line app's JavaScript and its dependencies into one executable per OS and architecture. The executable runs on its own: users don't need Node.js, Bare, or the Pear CLI installed. Use it for CLIs, REPLs, TUIs, and other headless apps written for Bare, such as one started from the hello-pear-bare template.

Under the hood, pear make runs pear-make, a separate Pear CLI app that calls bare-build in standalone mode. It builds the executable and nothing else. To ship it over the air, you still assemble a deployment directory and stage it (see Where to go next). For an Electron desktop app, follow Build desktop distributables instead.

Before you beginCopy Anchor Link

• Pear 3.7.0 or newer.
• A project written for Bare, with a package.json. A Node.js app needs its built-ins swapped for bare-* modules first; see Migrate a Node.js app to Bare.
• Its dependencies installed with npm install. pear make bundles them from node_modules.
• Network access on the first run, to install pear-make from peers.

{
  "name": "hello-cli",
  "version": "1.0.0",
  "description": "Greet a peer from the terminal",
  "bin": "bin.mjs",
  "scripts": {
    "start": "bare bin.mjs"
  },
  "dependencies": {
    "bare-path": "^3.1.3",
    "paparam": "^1.15.0"
  },
  "devDependencies": {
    "bare": "^1.37.1"
  }
}

import { command, arg, flag, summary } from 'paparam'
import path from 'bare-path'
import pkg from './package.json'

// True under `bare bin.mjs`, false in the built executable
const isDev = path.basename(Bare.argv[0], path.extname(Bare.argv[0])) === 'bare'

const cmd = command(
  pkg.name,
  summary(pkg.description),
  arg('[name]', 'Who to greet'),
  flag('--shout|-s', 'Print the greeting in uppercase')
)

cmd.parse(Bare.argv.slice(isDev ? 2 : 1))
if (cmd.flags.help) Bare.exit()

const greeting = `Hello, ${cmd.args.name || 'peer'}!`
console.log(`${cmd.flags.shout ? greeting.toUpperCase() : greeting} (${pkg.name} v${pkg.version})`)

npm install

npx bare bin.mjs Ada

pear make -v

⚠️ The pear-make CLI needs to be installed. To confirm type "INSTALL"
Install pear-make?

v1.1.0
Success

pear install pear://u3d888539k964t6omfzxdmf1a9c4jx4iiprm8jyt56x91izm78sy

pear make --name hello-cli --path out/make

pear-make v1.1.0
/path/to/hello-cli/out/make/hello-cli

Build finished.

Success

./out/make/hello-cli Ada --shout

HELLO, ADA! (hello-cli v1.0.0)

for host in darwin-arm64 darwin-x64 linux-arm64 linux-x64 win32-arm64 win32-x64; do
  pear make --host "$host" --name hello-cli --path "out/make/$host"
done

foreach ($h in 'darwin-arm64','darwin-x64','linux-arm64','linux-x64','win32-arm64','win32-x64') {
  pear make --host $h --name hello-cli --path "out/make/$h"
}

Run it in CI or a scriptCopy Anchor Link

Without a terminal, pear make can't ask before installing pear-make, so a missing pear-make fails the run:

✖ The pear-make CLI was not found. Please install using: pear install pear://u3d888539k964t6omfzxdmf1a9c4jx4iiprm8jyt56x91izm78sy

Pass --install to install pear-make without asking, but only on a runner that doesn't have it yet. When a copy is already installed, pear install refuses to overwrite it, printing Refusing to overwrite existing:, and the run fails. On a runner that keeps its home directory between jobs, install only when it is missing:

command -v pear-make >/dev/null || pear install pear://u3d888539k964t6omfzxdmf1a9c4jx4iiprm8jyt56x91izm78sy
pear make --no-install --name hello-cli --path out/make

Make sure ~/.local/bin is on the job's PATH before the first pear command, because that command starts the sidecar (see the warning in Install pear-make). On GitHub Actions, append it with echo "$HOME/.local/bin" >> "$GITHUB_PATH" in an earlier step.

For machine-readable output, pass --json. Each piece of pear-make output arrives as a make object, and the stream ends with a final object or, on failure, an error object:

{"cmd":"make","tag":"make","data":{"chunk":"pear-make v1.1.0\n"}}
{"cmd":"make","tag":"make","data":{"chunk":"/path/to/hello-cli/out/make/hello-cli\n\nBuild finished.\n\n"}}
{"cmd":"make","tag":"final","data":{"success":true}}

In Pear 3.7.0 the objects are written back to back, with no newline between them (they're shown one per line here). jq reads them as they are, but tools that split on lines don't. To print the build log:

pear make --json --name hello-cli --path out/make | jq -rj 'select(.tag == "make") | .data.chunk'

A failed build exits with status 1.

Sign the executableCopy Anchor Link

Sign and notarize the executable before you hand it to users. The hello-pear templates' npm run make signs with the MAC_CODESIGN_IDENTITY, KEYCHAIN_PROFILE, and WINDOWS_CERT_SHA1 variables (see Build a standalone binary). In CI, the make-pear-app action provides the same credentials.

TroubleshootingCopy Anchor Link

• ✖ package.json not found in <dir>. Run pear make from the project root, or pass the entry file as the argument.
• ✖ bin field not found in package.json Add a bin field that points at your entry file, or pass the entry file as the argument.
• ✖ no such file or directory The sidecar can't find pear-make on its PATH. This happens when pear-make was installed, or its directory added to PATH, after the sidecar started, and when --no-install is passed with no pear-make installed. Check that command -v pear-make finds it, then run pear sidecar shutdown and build again.
• ✖ pear-make failed with exit code <n> pear-make itself failed, and the lines before this one are its error. MODULE_NOT_FOUND: Cannot find module 'file:///…' means the entry file doesn't exist. Unknown host '<host>' means pear-make doesn't recognize the --host id.
• Refusing to overwrite existing: You passed --install with pear-make already installed. Drop --install.
• The executable is called app. Pass --name; see Build for your machine.

Where to go nextCopy Anchor Link

• Deploy your application: set the upgrade link, then assemble your executables into a deployment directory with pear build, stage, provision, and seed. Users then install with pear install pear://<key>.
• Start a terminal app from the hello-pear-bare template and Start a short-lived CLI from the hello-pear-daemon template: CLI apps that already update themselves over the air.
• Bundle a Bare app: what bare-build does underneath, and the options pear make doesn't expose.
• pear make reference: every flag and error.