Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 0 additions & 23 deletions .github/workflows/c-cpp.yml

This file was deleted.

169 changes: 169 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
name: CI

on:
push:
branches: [master]
tags: ["v*"]
pull_request:

# A new push to a PR supersedes its running checks.
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
# TypeScript 7's compiler is not built for every target: compile once, test everywhere.
dist:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
- uses: dtolnay/rust-toolchain@stable
with:
components: clippy
- run: yarn install --frozen-lockfile && yarn build
- run: cargo clippy --all-targets -- -D warnings && cargo test --lib
working-directory: native
- uses: actions/upload-artifact@v7
with:
name: dist
path: dist/

# Cross-built with zig against old glibc releases, then tested in a container of the target arch
# (QEMU when it is not the runner's) with a two-screen Xvfb and an openbox per screen.
linux:
needs: dist
runs-on: ${{ matrix.runner || 'ubuntu-24.04' }}
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
include:
- { dir: linux-x64, target: x86_64-unknown-linux-gnu.2.17, platform: linux/amd64, image: node:22-bookworm-slim }
- { dir: linux-arm64, target: aarch64-unknown-linux-gnu.2.17, platform: linux/arm64, image: node:22-bookworm-slim, runner: ubuntu-24.04-arm }
- { dir: linux-arm, target: armv7-unknown-linux-gnueabihf.2.17, platform: linux/arm/v7, image: node:22-bookworm-slim }
- { dir: linux-ppc64, target: powerpc64le-unknown-linux-gnu.2.19, platform: linux/ppc64le, image: node:22-bookworm-slim }
# No official Node image for these: Debian's own nodejs package.
- { dir: linux-s390x, target: s390x-unknown-linux-gnu.2.17, platform: linux/s390x, image: "debian:trixie-slim" }
- { dir: linux-riscv64, target: riscv64gc-unknown-linux-gnu.2.27, platform: linux/riscv64, image: "debian:trixie-slim" }
- { dir: linux-x64-musl, target: x86_64-unknown-linux-musl, platform: linux/amd64, image: node:22-alpine }
- { dir: linux-arm64-musl, target: aarch64-unknown-linux-musl, platform: linux/arm64, image: node:22-alpine, runner: ubuntu-24.04-arm }
- { dir: linux-arm-musl, target: armv7-unknown-linux-musleabihf, platform: linux/arm/v7, image: node:22-alpine }
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
- uses: dtolnay/rust-toolchain@stable
- uses: mlugg/setup-zig@v2
with:
version: 0.16.0 # the glibc floors above are what this zig can provide
- uses: taiki-e/install-action@v2
with:
tool: cargo-zigbuild
- run: node scripts/build-native.js --zig --target ${{ matrix.target }} --dir ${{ matrix.dir }}
- uses: actions/download-artifact@v8
with:
name: dist
path: dist
- uses: docker/setup-qemu-action@v4
- run: >
docker run --rm --init --platform ${{ matrix.platform }} -v "$PWD:/repo" -w /repo
-e WMCTRLJS_FIXTURE=fixtures/${{ matrix.dir }}/fixture ${{ matrix.image }} sh -ec '
if command -v apk; then apk add --no-cache xvfb-run openbox;
else apt-get update && apt-get install -y --no-install-recommends xvfb xauth openbox $(command -v node >/dev/null || echo nodejs); fi;
xvfb-run -a -s "-screen 0 1280x1024x24 -screen 1 800x600x24" sh -c
"openbox & DISPLAY=\$DISPLAY.1 openbox & WMCTRLJS_SCREEN1=\$DISPLAY.1 node --test dist/test/*.test.js"'
- uses: actions/upload-artifact@v7
with:
name: prebuild-${{ matrix.dir }}
path: prebuilds/

# Builds and tests in a FreeBSD VM.
freebsd:
needs: dist
runs-on: ubuntu-24.04
timeout-minutes: 30
steps:
- uses: actions/checkout@v7
- uses: actions/download-artifact@v8
with:
name: dist
path: dist
- uses: vmactions/[email protected]
with:
usesh: true
prepare: pkg install -y rust node22 xorg-vfbserver openbox
run: |
set -e
node scripts/build-native.js
# Detached from the ssh session's output, or it stays open after the tests and the step never ends.
Xvfb :99 -screen 0 1280x1024x24 -screen 1 800x600x24 -nolisten tcp </dev/null >/dev/null 2>&1 & sleep 2
DISPLAY=:99 openbox </dev/null >/dev/null 2>&1 &
DISPLAY=:99.1 openbox </dev/null >/dev/null 2>&1 &
DISPLAY=:99 WMCTRLJS_SCREEN1=:99.1 WMCTRLJS_FIXTURE=fixtures/freebsd-x64/fixture node --test dist/test/*.test.js
- uses: actions/upload-artifact@v7
with:
name: prebuild-freebsd-x64
path: prebuilds/

# No X server on these runners: the X11 suite skips itself, the API suite still loads and calls the binary.
others:
needs: dist
runs-on: ${{ matrix.runner }}
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
include:
- { dir: darwin-arm64, target: aarch64-apple-darwin, runner: macos-latest, node: arm64 }
- { dir: darwin-x64, target: x86_64-apple-darwin, runner: macos-latest, node: x64 }
- { dir: win32-x64, target: x86_64-pc-windows-msvc, runner: windows-latest, node: x64 }
- { dir: win32-ia32, target: i686-pc-windows-msvc, runner: windows-latest, node: x86 }
- { dir: win32-arm64, target: aarch64-pc-windows-msvc, runner: windows-11-arm, node: arm64 }
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
architecture: ${{ matrix.node }}
- uses: dtolnay/rust-toolchain@stable
- run: node scripts/build-native.js --target ${{ matrix.target }} --dir ${{ matrix.dir }}
- uses: actions/download-artifact@v8
with:
name: dist
path: dist
- run: node --test dist/test/api.test.js dist/test/x11.test.js
- uses: actions/upload-artifact@v7
with:
name: prebuild-${{ matrix.dir }}
path: prebuilds/

publish:
if: startsWith(github.ref, 'refs/tags/v')
needs: [linux, freebsd, others]
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
registry-url: https://registry.npmjs.org
- uses: actions/download-artifact@v8
with:
name: dist
path: dist
- uses: actions/download-artifact@v8
with:
pattern: prebuild-*
path: prebuilds
merge-multiple: true
- run: test "$(ls prebuilds/*/wmctrljs.node | wc -l)" -eq 15
- run: npm publish --provenance --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
9 changes: 4 additions & 5 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
node_modules
*.out
*.so
*.o
*.a
build
.vscode
package-lock.json
dist
dist
prebuilds
native/target
fixtures
20 changes: 0 additions & 20 deletions .npmignore

This file was deleted.

75 changes: 59 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,62 @@
# wmctrljs

Be carefull this package can be use only on a linux X11 machine.
Native window management for Node.js on Linux X11 (works under XWayland too): `wmctrl` and more, without spawning a process.

You also need packages like libx11-dev, libxmu-dev
The native part is written in Rust ([napi-rs](https://napi.rs) + [x11rb](https://github.com/psychon/x11rb)). It talks the X11 protocol directly, so it needs no `libX11`/`libXmu`. Prebuilt binaries for every target below ship inside the npm package, and the right one is picked at runtime. Installing compiles nothing and needs no system packages.

## Update your indexes
`sudo apt update`
| OS | Architectures | Tested in CI |
|----|---------------|--------------|
| Linux, glibc 2.17+ (2.19+ on ppc64le, 2.27+ on riscv64) | x64, arm64, arm (armv7), ppc64le, s390x, riscv64 | full suite against Xvfb + openbox (QEMU for non-native arches) |
| Linux, musl (Alpine) | x64, arm64, arm (armv7) | full suite against Xvfb + openbox |
| FreeBSD | x64 | full suite against Xvfb + openbox, in a VM |
| macOS (XQuartz) | x64, arm64 | API suite only (no X server on the runners) |
| Windows (an X server such as VcXsrv, `DISPLAY=host:0`) | x64, ia32, arm64 | API suite only |

## Install your unbuntu packages
`sudo apt install libx11-dev -y`

`sudo apt install libxmu-dev -y`

## Install wmctrljs package
## Install

`npm install wmctrljs`

## Description
Wmctrljs is an adaptation of wmctrl command and more, with that library you can easily manage your windows very fastly beacause wmctrls does'nt make a fork of wmctrl process but directly call X11 library using N-API.
Every function exists in two flavours: `xxxSync` runs on the calling thread, `xxx` returns a promise and runs on the libuv thread pool.

Errors are `Error` objects whose message looks like `[functionName] NO_WINDOW_FOUND (24)`.
A bug that would have crashed the native code is reported as `INTERNAL_ERROR (43)` instead of taking the Node process down.

## Upgrading from 1.x

The JS API is unchanged. The behaviour changes below are fixes:

- No system packages are needed anymore (`libx11-dev`, `libxmu-dev`, node-gyp, a C++ compiler).
- Promises now reject with `Error` objects instead of strings. The message is the same.
- `getWindowsByPid*` / `getWindowsByClassName*` return `[]` when nothing matches instead of throwing `NO_WINDOW_FOUND`. Their windows now include `frame_extents`, and `getWindowsByPid(0)` no longer matches windows that have no pid.
- `closeWindowsByPidSync` / `closeWindowsByClassNameSync` return `true` on success. They used to throw even when they worked.
- Windows now carry `win_icon_name` (it was declared but never set). The `Aspect` type now says `numerator` / `denominator`, which is what was always returned.
- `windowMoveResizeTransition` really animates y (it used to step it with x) and starts from the window's absolute position.
- The 1.x C addon double-freed memory in `getActiveWindow()` and could crash the process. That is gone.
- `windowMoveResizeTransition` rejects an `await_time` no timer can hold (`Infinity`) and handles extreme coordinates without overflowing.

## Development

Requirements: Node.js 18+, a Rust toolchain, and for tests an X server with an EWMH window manager (for example `xvfb` + `openbox`).

To do that wmctrls has access to an addon natif using `N-API` for scalability between nodejs version.
```sh
yarn install
yarn build:native # cargo build -> prebuilds/<platform>-<arch>/wmctrljs.node (+ the test fixture window)
yarn build # TypeScript 7
xvfb-run -a -s '-screen 0 1280x1024x24 -screen 1 800x600x24' sh -c 'openbox & DISPLAY=$DISPLAY.1 openbox & WMCTRLJS_SCREEN1=$DISPLAY.1 yarn test'
cd native && cargo test --lib # Rust unit tests, no X server needed
```

Cross builds use [cargo-zigbuild](https://github.com/rust-cross/cargo-zigbuild) (and zig): `node scripts/build-native.js --zig --target aarch64-unknown-linux-gnu.2.17 --dir linux-arm64`.

The native code has no `unsafe`, `unwrap`, `expect`, `panic!`, unchecked indexing or unchecked arithmetic outside tests: lints in `native/Cargo.toml` reject them, and CI runs clippy with `-D warnings`.

Three suites guard against regressions:
- Rust unit tests: property decoding, window JSON, size hints, gravity flags, transitions, error codes.
- `api.test`: exports, argument validation and error messages of every function, and the binary loader. Runs without X.
- `x11.test`: every function against a real window manager. It spawns its own fixture windows (`native/examples/fixture.rs`) and only ever acts on those. It is skipped when `DISPLAY` is unset, and its second-screen tests when `WMCTRLJS_SCREEN1` (a display string for screen 1 of the same server, with its own window manager) is unset.

An implementation of async/IO is available, then it is possible to call each function on a `V8` different thread wich will highly improve performance results
CI builds and tests the 15 targets above, and publishes to npm when a `v*` tag is pushed.

## Window

Expand All @@ -43,6 +78,7 @@ interface Window {
win_geometry:Geometry|undefined;

wm_normal_hints_supplied:number;
wm_hints_supplied:number;
WM_NORMAL_HINTS:XSizeHints|undefined;
WM_HINTS:XSizeHints|undefined;
desktop_number:number;
Expand Down Expand Up @@ -74,6 +110,13 @@ interface Geometry {
```
wmctrljs also provide you XSizeHints propertis based on Xutils.h structure.

```TS
interface Aspect {
numerator:number
denominator:number
}
```

```TS
interface XSizeHints { //Based on Xutils.h
flags:number /* marks which fields in this structure are defined */
Expand Down Expand Up @@ -152,13 +195,13 @@ function getActiveWindowSync():Window
function getActiveWindow():Promise<Window>
```

Get a list of window with the pid provided, if this pid doesn't match with any window a not found exception is throw
Get a list of window with the pid provided, an empty list if no window matches
```TS
function getWindowsByPidSync(win_pid:number):Window[]
function getWindowsByPid(win_pid:number):Promise<Window[]>
```

Get a list of window with the class provided, it has the same issue as `getWindowsByPidSync`
Get a list of window with the class provided (`instance.Class`, e.g. `xeyes.XEyes`), an empty list if no window matches
```TS
function getWindowsByClassNameSync(win_class_name:string):Window[]
function getWindowsByClassName(win_class_name:string):Promise<Window[]>
Expand Down Expand Up @@ -206,7 +249,7 @@ function windowMoveResizeTransition(win_id:number, win_gravity:number, win_x:num
```
Here the `await_time` is the duration between all window's positions and dimensions, and `pad` allow you to control the number of step it will have.

Because of the duration of this animation it is available only with an `AsyncWorker`.
Because of the duration of this animation it is only available as a promise.

Make some action on window's states

Expand Down
22 changes: 0 additions & 22 deletions binding.gyp

This file was deleted.

Loading
Loading