Skip to content

Commit

Permalink
Merge branch 'master' into matttyson-master
Browse files Browse the repository at this point in the history
  • Loading branch information
mischnic committed May 29, 2024
2 parents 133f9c7 + 8dfd994 commit d11468a
Show file tree
Hide file tree
Showing 44 changed files with 2,256 additions and 691 deletions.
151 changes: 151 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
name: release
on:
workflow_dispatch:
release:
types: [published]

jobs:
build:
strategy:
fail-fast: false
matrix:
include:
- os: windows-latest
arch: x64
node: 16
- os: windows-latest
arch: arm64
node: 20
- os: windows-latest
arch: ia32
node: 16
- os: macos-latest
arch: x64
node: 16
- os: macos-latest
arch: arm64
node: 16
- os: ubuntu-latest
arch: x64
libc: glibc
image: ghcr.io/prebuild/centos7-devtoolset7:2.1.1
node: 16
- os: ubuntu-latest
arch: x64
libc: musl
image: ghcr.io/prebuild/alpine:2.1.1
node: 16
- os: ubuntu-latest
arch: arm64
libc: glibc
image: ghcr.io/prebuild/linux-arm64-lts:2.1.1
node: 16
- os: ubuntu-latest
arch: arm64
libc: musl
image: ghcr.io/prebuild/linux-arm64-musl:2.1.1
node: 16
- os: ubuntu-latest
arch: arm
libc: glibc
image: ghcr.io/prebuild/linux-armv7:2.1.1
node: 16
- os: ubuntu-latest
arch: arm64
image: ghcr.io/prebuild/android-arm64:2.1.1
node: 16
runs-on: ${{matrix.os}}
container:
image: ${{matrix.image}}
options: -u root
steps:
- uses: actions/checkout@v3
- run: corepack enable
- uses: actions/setup-node@v3
with:
cache: yarn
node-version: ${{matrix.node}}
- run: yarn --frozen-lockfile --ignore-scripts
- run: npm install node-gyp -g
- run: yarn prebuild --arch ${{ matrix.arch }} -t ${{ matrix.node }}.0.0
env:
PREBUILD_LIBC: ${{ matrix.libc }}
- name: Upload artifacts
uses: actions/upload-artifact@v3
with:
name: prebuilds
path: prebuilds

build-freebsd:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build FreeBSD
uses: vmactions/freebsd-vm@v1
with:
usesh: true
prepare: |
pkg install -y -f curl node libnghttp2 npm yarn
echo "~~~~ node -v ~~~~"
node -v
echo "~~~~ yarn --version ~~~~"
yarn --version
run: |
yarn --frozen-lockfile --ignore-scripts
npm install node-gyp -g
yarn prebuild --arch x64 -t 16.0.0
- name: Upload artifacts
uses: actions/upload-artifact@v3
with:
name: prebuilds
path: prebuilds

build-wasm:
runs-on: ubuntu-latest
container:
image: emscripten/emsdk
steps:
- uses: actions/checkout@v3
- run: corepack enable
- uses: actions/setup-node@v3
with:
cache: yarn
node-version: 18
- run: yarn --frozen-lockfile
- run: make wasm
- name: Upload artifacts
uses: actions/upload-artifact@v3
with:
name: wasm
path: build/Release/watcher.wasm

release:
runs-on: ubuntu-latest
needs:
- build
- build-freebsd
- build-wasm
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
cache: yarn
node-version: 16
- run: yarn --frozen-lockfile --ignore-scripts
- name: Download artifacts
uses: actions/download-artifact@v3
- name: Build npm packages
run: |
node scripts/build-npm.js
node scripts/build-wasm.js
- name: Publish to npm
env:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
run: |
echo //registry.npmjs.org/:_authToken=${NPM_TOKEN} > ~/.npmrc
for pkg in npm/*; do
echo "Publishing $pkg..."
cd $pkg;
npm publish;
cd ../..;
done
85 changes: 85 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
name: test
on:
push:
branches: [master]
pull_request:

jobs:
test:
strategy:
fail-fast: false
matrix:
node: [18, 20]
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{matrix.os}}
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
cache: yarn
node-version: ${{matrix.node}}
- name: Install watchman
if: ${{ matrix.os == 'macos-latest' }}
run: |
wget https://github.com/facebook/watchman/releases/download/v2023.05.01.00/watchman-v2023.05.01.00-macos.zip
unzip watchman-*-macos.zip
cd watchman-v2023.05.01.00-macos
sudo mkdir -p /usr/local/{bin,lib} /usr/local/var/run/watchman
sudo cp bin/* /usr/local/bin
sudo cp lib/* /usr/local/lib
sudo chmod 755 /usr/local/bin/watchman
sudo chmod 2777 /usr/local/var/run/watchman
watchman -v
- name: Install watchman
if: ${{ matrix.os == 'ubuntu-latest' }}
run: |
wget https://github.com/facebook/watchman/releases/download/v2023.06.19.00/watchman-v2023.06.19.00-linux.zip
unzip watchman-*-linux.zip
cd watchman-v2023.06.19.00-linux
sudo mkdir -p /usr/local/{bin,lib} /usr/local/var/run/watchman
sudo cp bin/* /usr/local/bin
sudo cp lib/* /usr/local/lib
sudo chmod 755 /usr/local/bin/watchman
sudo chmod 2777 /usr/local/var/run/watchman
- name: Copy watchman
if: ${{ matrix.os == 'windows-latest' }}
run: |
Copy-Item -Recurse -Path watchman -Destination $home
$env:PATH += ";$home\watchman\windows\bin"
Add-Content $env:GITHUB_PATH "$home\watchman\windows\bin"
watchman -v
- run: yarn --frozen-lockfile
- run: yarn test

test-freebsd:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Test in FreeBSD
uses: vmactions/freebsd-vm@v1
with:
usesh: true
prepare: |
pkg install -y -f curl node libnghttp2 npm yarn
echo "~~~~ node -v ~~~~"
node -v
echo "~~~~ yarn --version ~~~~"
yarn --version
run: |
yarn --frozen-lockfile
yarn test
test-wasm:
runs-on: ubuntu-latest
container:
image: emscripten/emsdk
steps:
- uses: actions/checkout@v3
- run: corepack enable
- uses: actions/setup-node@v3
with:
cache: yarn
node-version: 18
- run: yarn --frozen-lockfile
- run: make wasm-debug
- run: TEST_WASM=1 yarn test
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,4 @@ token.txt
stress-test
crash.log
test/snapshot.txt
npm
46 changes: 31 additions & 15 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,21 +1,37 @@
.PHONY: docker-build-centos docker-build-alpine docker-push-centos
NODE_PATH := $(dir $(shell which node))
HEADERS_URL := $(shell node -p "process.release.headersUrl")
NODE_VERSION := $(shell node -p "process.version")

current_dir = $(shell pwd)
GIT_SHA = $(shell git log -1 --pretty=%h)
INCS_Debug := \
-Ibuild/node-$(NODE_VERSION)/include/node \
-I$(shell node -p "require('node-addon-api').include_dir")

git_sha:
echo GIT_SHA is $(GIT_SHA)
SRC := src/binding.cc src/Watcher.cc src/Backend.cc src/DirTree.cc src/Glob.cc src/Debounce.cc src/shared/BruteForceBackend.cc src/unix/legacy.cc src/wasm/WasmBackend.cc
FLAGS := $(INCS_Debug) \
-Oz \
-flto \
-fwasm-exceptions \
-DNAPI_HAS_THREADS=1 \
-sEXPORTED_FUNCTIONS="['_napi_register_wasm_v1', '_wasm_backend_event_handler', '_malloc', '_free', '_on_timeout']" \
-sERROR_ON_UNDEFINED_SYMBOLS=0 \
-s INITIAL_MEMORY=524288000

docker-build-centos:
docker build -t jasperdm/centos-watchman:latest -t jasperdm/centos-watchman:$(GIT_SHA) -f ./docker-agents/centos.Dockerfile . --progress plain
build/node-headers.tar.gz:
curl $(HEADERS_URL) -o build/node-headers.tar.gz

docker-build-alpine:
docker build -t jasperdm/alpine-watchman:latest -t jasperdm/alpine-watchman:$(GIT_SHA) -f ./docker-agents/alpine.Dockerfile . --progress plain
build/node-$(NODE_VERSION): build/node-headers.tar.gz
tar -xvf build/node-headers.tar.gz -C build
touch build/node-$(NODE_VERSION)

docker-push-centos:
docker push jasperdm/centos-watchman:${GIT_SHA}
docker push jasperdm/centos-watchman:latest
build/Release/watcher.wasm: build/node-$(NODE_VERSION) $(SRC)
mkdir -p build/Release
em++ $(FLAGS) -sDECLARE_ASM_MODULE_EXPORTS=0 -o build/Release/watcher.js $(SRC)

docker-push-alpine:
docker push jasperdm/alpine-watchman:${GIT_SHA}
docker push jasperdm/alpine-watchman:latest
build/Debug/watcher.wasm: build/node-$(NODE_VERSION) $(SRC)
mkdir -p build/Debug
em++ -g $(FLAGS) -o build/Debug/watcher.js $(SRC)

wasm: build/Release/watcher.wasm
wasm-debug: build/Debug/watcher.wasm

.PHONY: wasm wasm-debug
23 changes: 19 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ A native C++ Node module for querying and subscribing to filesystem events. Used
- **Watch** - subscribe to realtime recursive directory change notifications when files or directories are created, updated, or deleted.
- **Query** - performantly query for historical change events in a directory, even when your program is not running.
- **Native** - implemented in C++ for performance and low-level integration with the operating system.
- **Cross platform** - includes backends for macOS, Linux, Windows, and Watchman.
- **Cross platform** - includes backends for macOS, Linux, Windows, FreeBSD, and Watchman.
- **Performant** - events are throttled in C++ so the JavaScript thread is not overwhelmed during large filesystem changes (e.g. `git checkout` or `npm install`).
- **Scalable** - tens of thousands of files can be watched or queried at once with good performance.

Expand Down Expand Up @@ -64,6 +64,7 @@ await subscription.unsubscribe();
- [Watchman](https://facebook.github.io/watchman/) if installed
- [inotify](http://man7.org/linux/man-pages/man7/inotify.7.html) on Linux
- [ReadDirectoryChangesW](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365465%28v%3Dvs.85%29.aspx) on Windows
- [kqueue](https://man.freebsd.org/cgi/man.cgi?kqueue) on FreeBSD, or as an alternative to FSEvents on macOS

You can specify the exact backend you wish to use by passing the `backend` option. If that backend is not available on the current platform, the default backend will be used instead. See below for the list of backend names that can be passed to the options.

Expand All @@ -89,7 +90,7 @@ The events returned are exactly the same as the events that would be passed to t

- [FSEvents](https://developer.apple.com/documentation/coreservices/file_system_events) on macOS
- [Watchman](https://facebook.github.io/watchman/) if installed
- [fts](http://man7.org/linux/man-pages/man3/fts.3.html) (brute force) on Linux
- [fts](http://man7.org/linux/man-pages/man3/fts.3.html) (brute force) on Linux and FreeBSD
- [FindFirstFile](https://docs.microsoft.com/en-us/windows/desktop/api/fileapi/nf-fileapi-findfirstfilea) (brute force) on Windows

The FSEvents (macOS) and Watchman backends are significantly more performant than the brute force backends used by default on Linux and Windows, for example returning results in miliseconds instead of seconds for large directory trees. This is because a background daemon monitoring filesystem changes on those platforms allows us to query cached data rather than traversing the filesystem manually (brute force).
Expand All @@ -103,9 +104,22 @@ You can specify the exact backend you wish to use by passing the `backend` optio
All of the APIs in `@parcel/watcher` support the following options, which are passed as an object as the last function argument.

- `ignore` - an array of paths or glob patterns to ignore. uses [`is-glob`](https://github.com/micromatch/is-glob) to distinguish paths from globs. glob patterns are parsed with [`micromatch`](https://github.com/micromatch/micromatch) (see [features](https://github.com/micromatch/micromatch#matching-features)).
- paths can be relative or absolute and can either be files or directories. No events will be emitted about these files or directories or their children.
- paths can be relative or absolute and can either be files or directories. No events will be emitted about these files or directories or their children.
- glob patterns match on relative paths from the root that is watched. No events will be emitted for matching paths.
- `backend` - the name of an explicitly chosen backend to use. Allowed options are `"fs-events"`, `"watchman"`, `"inotify"`, `"windows"`, or `"brute-force"` (only for querying). If the specified backend is not available on the current platform, the default backend will be used instead.
- `backend` - the name of an explicitly chosen backend to use. Allowed options are `"fs-events"`, `"watchman"`, `"inotify"`, `"kqueue"`, `"windows"`, or `"brute-force"` (only for querying). If the specified backend is not available on the current platform, the default backend will be used instead.

## WASM

The `@parcel/watcher-wasm` package can be used in place of `@parcel/watcher` on unsupported platforms. It relies on the Node `fs` module, so in non-Node environments such as browsers, an `fs` polyfill will be needed.

**Note**: the WASM implementation is significantly less efficient than the native implementations because it must crawl the file system to watch each directory individually. Use the native `@parcel/watcher` package wherever possible.

```js
import {subscribe} from '@parcel/watcher-wasm';

// Use the module as documented above.
subscribe(/* ... */);
```

## Who is using this?

Expand All @@ -114,6 +128,7 @@ All of the APIs in `@parcel/watcher` support the following options, which are pa
- [Tailwind CSS Intellisense](https://github.com/tailwindlabs/tailwindcss-intellisense)
- [Gatsby Cloud](https://twitter.com/chatsidhartha/status/1435647412828196867)
- [Nx](https://nx.dev)
- [Nuxt](https://nuxt.com)

## License

Expand Down
Loading

0 comments on commit d11468a

Please sign in to comment.