Skip to content

MACOS.md

Latest commit

 

History

History
277 lines (199 loc) · 5.77 KB

MACOS.md

File metadata and controls

277 lines (199 loc) · 5.77 KB

Building nut.js from Source on macOS

This guide will walk you through building nut.js from source on macOS, including building the native dependencies.

Prerequisites

System Dependencies

Install Xcode Command Line Tools:

xcode-select --install

This will install the necessary compilers and build tools.

Node.js and npm

Ensure you have Node.js installed (version 16 or higher for nut.js, 10.15.3+ for libnut-core):

node --version
npm --version

If not installed, install Node.js from nodejs.org or using Homebrew:

brew install node

Configure npm for User Installation (Avoid Permission Issues)

# Configure npm to use a directory in your home folder
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to your PATH (add this to ~/.zshrc or ~/.bash_profile)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Install pnpm

nut.js uses pnpm as its package manager. Install it:

npm install -g pnpm@8.15.2

pnpm verification

pnpm -v

macOS Permissions

nut.js requires Accessibility and Screen Recording permissions. The library will prompt you automatically, but you can grant them manually:

  1. Open System Settings (or System Preferences on older macOS)
  2. Go to Privacy & Security
  3. Enable Accessibility for your terminal/IDE
  4. Enable Screen Recording for your terminal/IDE

Note: You'll need to grant permissions to:

  • Terminal.app (if using Terminal)
  • iTerm.app (if using iTerm2)
  • Your IDE (VSCode, IntelliJ, etc.) if running scripts from there

Installation Steps

Step 1: Clone the Repositories

# Create a directory for the projects
mkdir -p nutjs-build
cd nutjs-build

# Clone libnut-core (the native dependency)
git clone https://github.com/nut-tree/libnut-core.git
cd libnut-core

Step 2: Build libnut-core

# Install npm dependencies
npm install

# Patch the package name for your platform (macOS)
CI=true npm run patch

# Build the release version
npm run build:release

This will compile the native C/C++/Objective-C code and create a .node module. The build output will be in build/Release/.

Note: The build supports both Intel (x86_64) and Apple Silicon (arm64) architectures.

Step 3: Clone nut.js

# Go back to your build directory (assuning you are in nutjs-build/libnut-cores)
cd ..

# Clone nut.js
git clone https://github.com/nut-tree/nut.js.git
cd nut.js

Step 4: Configure nut.js to Use Local libnut-core

Edit nut.js/providers/libnut/package.json and change the macOS dependency:

Find this line:

"@nut-tree/libnut-darwin": "2.7.1",

Replace with:

"@nut-tree/libnut-darwin": "file:../../../libnut-core",

Also update the peer dependency (change ^3 to ^4 to match workspace version):

Find:

"peerDependencies": {
  "@nut-tree/nut-js": "^3"
}

Replace with:

"peerDependencies": {
  "@nut-tree/nut-js": "^4"
}

Make Windows/Linux packages optional (move them to optionalDependencies):

Find:

"dependencies": {
  "@nut-tree/libnut-darwin": "file:../../../libnut-core",
  "@nut-tree/libnut-linux": "2.7.1",
  "@nut-tree/libnut-win32": "2.7.1"
}

Replace with:

"dependencies": {
  "@nut-tree/libnut-darwin": "file:../../../libnut-core"
},
"optionalDependencies": {
  "@nut-tree/libnut-linux": "2.7.1",
  "@nut-tree/libnut-win32": "2.7.1"
}

Step 5: Handle Premium Package Dependencies

Edit nut.js/examples/screen-test/package.json to make premium packages optional:

Find:

"dependencies": {
  "@nut-tree/nut-js": "workspace:*",
  "@nut-tree/nl-matcher": "2.2.0"
}

Replace with:

"dependencies": {
  "@nut-tree/nut-js": "workspace:*"
},
"optionalDependencies": {
  "@nut-tree/nl-matcher": "2.2.0"
}

Update peer dependencies in nut.js/providers/clipboardy/package.json:

Find:

"peerDependencies": {
  "@nut-tree/nut-js": "^3"
}

Replace with:

"peerDependencies": {
  "@nut-tree/nut-js": "^4"
}

Step 6: Install Dependencies and Build

# Remove old lock file to regenerate with workspace packages (in nutjs directory)
rm -f pnpm-lock.yaml

# Install all dependencies
pnpm install

# Compile all TypeScript packages
pnpm run compile

Verification

To verify the installation worked:

# Check that the compiled packages exist
ls -la core/nut.js/dist/
ls -la providers/libnut/dist/

Using Your Built nut.js

Step 1: Create a Global Link

From the nut.js package directory, create a global link:

cd nutjs-build/nut.js/core/nut.js
pnpm link --global

Step 2: Link in Your Project

Navigate to your project directory and link the package:

cd /path/to/your/project
pnpm link --global @nut-tree/nut-js

Step 3: Update Your Project's package.json

In your project's package.json:

{
  "dependencies": {
    "@nut-tree/nut-js": "link:"
  }
}

Then run pnpm install or npm install in your project.

Troubleshooting

Build Errors

  • Xcode Command Line Tools not found: Run xcode-select --install
  • Compiler errors: Ensure Xcode Command Line Tools are properly installed
  • Architecture issues: The build automatically supports both Intel and Apple Silicon

Package Not Found Errors

If you see errors about premium packages (@nut-tree/libnut-linux, @nut-tree/libnut-win32, @nut-tree/nl-matcher, etc.), ensure you've moved them to optionalDependencies as described in Step 4 and Step 5.

Apple Silicon (M1/M2/M3) Issues

The build should work automatically on Apple Silicon. If you encounter issues:

  • Ensure you're using a Node.js version compiled for arm64
  • Check that Xcode Command Line Tools are installed for your architecture