Skip to content

Commit d2f7423

Browse files
sgammonsgammon
committed
doc: update action readme
Signed-off-by: Sam Gammon <sam@elide.ventures>
1 parent 15570ed commit d2f7423

2 files changed

Lines changed: 191 additions & 48 deletions

File tree

‎.dev/README.md‎

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,60 @@
11

2-
This directory is used for local testing. Nothing to see here.
2+
# Development
3+
4+
Local development helpers for the `setup-elide` action.
5+
6+
## Prerequisites
7+
8+
- [Bun](https://bun.sh) (latest)
9+
- [Node.js](https://nodejs.org) 24+
10+
- [Docker](https://docs.docker.com/get-docker/) (for `test:docker`)
11+
12+
## Quick Reference
13+
14+
```bash
15+
bun install # install dependencies
16+
bun run build # format + bundle (dist/index.js + dist/post.js)
17+
bun run test # run all unit tests (sequenced batches)
18+
bun run test:ci # same as test, but produces JUnit XML + merged lcov
19+
bun run test:docker # build + test in Docker container
20+
bun run lint # oxlint
21+
bun run format:check # biome format check
22+
bun run format:write # biome format + write
23+
bun run all # format + build + test
24+
```
25+
26+
## Directory Layout
27+
28+
| Path | Purpose |
29+
|---|---|
30+
| `.dev/test-env.ts` | Preloaded by bun test to set `RUNNER_TEMP`, `RUNNER_TOOL_CACHE`, `ELIDE_HOME` |
31+
| `.dev/tmp/` | Temp files created during test runs |
32+
| `.dev/target/` | Simulated `ELIDE_HOME` for tests |
33+
| `.dev/tool-cache/` | Simulated tool cache for tests |
34+
35+
## Test Batching
36+
37+
Tests run in sequenced batches because `bun:test`'s `mock.module()` creates
38+
process-wide module replacements. Test files that mock the same module differently
39+
must run in separate `bun test` invocations. The `test` script in `package.json`
40+
handles this automatically.
41+
42+
## Architecture
43+
44+
See the [main README](../README.md) for user-facing documentation. Key source files:
45+
46+
| File | Role |
47+
|---|---|
48+
| `src/index.ts` | Entry point (calls `run()`) |
49+
| `src/post.ts` | Post-step entry point (flushes telemetry) |
50+
| `src/main.ts` | Orchestrator: option parsing, installer routing, outputs, summary |
51+
| `src/options.ts` | Option types, defaults, normalization, validation, input parsing |
52+
| `src/releases.ts` | CDN URL building, archive download/extract, tool cache, GitHub API |
53+
| `src/command.ts` | Elide CLI interaction (`elide info`, `elide --version`) |
54+
| `src/platform.ts` | Platform detection (`isDebianLike`, `isRpmBased`) |
55+
| `src/telemetry.ts` | Sentry init/report/flush with aggressive scrubbing |
56+
| `src/install-apt.ts` | apt installer |
57+
| `src/install-shell.ts` | bash/PowerShell install script runner |
58+
| `src/install-msi.ts` | Windows MSI installer |
59+
| `src/install-pkg.ts` | macOS PKG installer |
60+
| `src/install-rpm.ts` | Linux RPM installer |

‎README.md‎

Lines changed: 132 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -3,83 +3,168 @@
33

44
[![Elide](https://elide.dev/shield)](https://elide.dev)
55
[![CI](https://github.com/elide-dev/setup-elide/actions/workflows/ci.yml/badge.svg)](https://github.com/elide-dev/setup-elide/actions)
6-
[![Coverage](./.github/badges/coverage.svg)](https://codecov.io/gh/elide-dev/setup-elide)
6+
[![codecov](https://codecov.io/gh/elide-dev/setup-elide/graph/badge.svg)](https://codecov.io/gh/elide-dev/setup-elide)
77
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v1.4-ff69b4.svg)](.github/CODE_OF_CONDUCT.md)
88

9-
This repository provides a [GitHub Action][0] to setup the [Elide][1] runtime within your workflows.
9+
This repository provides a [GitHub Action][0] to install the [Elide][1] runtime within your workflows.
1010

11-
## Usage
11+
## Quick Start
1212

13-
**Install the latest Elide version and add it to the `PATH`**
1413
```yaml
15-
- name: "Setup: Elide"
16-
uses: elide-dev/setup-elide@v2
14+
- name: "Setup: Elide"
15+
uses: elide-dev/setup-elide@v4
1716
```
1817
19-
**Install a specific Elide version and add it to the `PATH`**
18+
This installs the latest nightly build of Elide and adds it to the `PATH`.
19+
20+
## Usage Examples
21+
22+
**Install a specific version**
23+
```yaml
24+
- name: "Setup: Elide"
25+
uses: elide-dev/setup-elide@v4
26+
with:
27+
version: 1.0.0
28+
channel: release
29+
```
30+
31+
**Install via apt on Debian/Ubuntu**
32+
```yaml
33+
- name: "Setup: Elide"
34+
uses: elide-dev/setup-elide@v4
35+
with:
36+
installer: apt
37+
```
38+
39+
**Install via shell script (uses GitHub Releases for faster downloads in GHA)**
40+
```yaml
41+
- name: "Setup: Elide"
42+
uses: elide-dev/setup-elide@v4
43+
with:
44+
installer: shell
45+
```
46+
47+
**Install via PKG on macOS**
48+
```yaml
49+
- name: "Setup: Elide"
50+
uses: elide-dev/setup-elide@v4
51+
with:
52+
installer: pkg
53+
```
54+
55+
**Install without adding to PATH**
2056
```yaml
21-
- name: "Setup: Elide"
22-
uses: elide-dev/setup-elide@v2
23-
with:
24-
version: 1.0.0-beta1 # any tag from the `elide-dev/releases` repo; omit for latest
57+
- name: "Setup: Elide"
58+
uses: elide-dev/setup-elide@v4
59+
with:
60+
export_path: false
2561
```
2662

27-
**Install Elide but don't add it to the `PATH`**
63+
**Use outputs in subsequent steps**
2864
```yaml
29-
- name: "Setup: Elide"
30-
uses: elide-dev/setup-elide@v2
31-
with:
32-
export_path: false
65+
- name: "Setup: Elide"
66+
id: setup-elide
67+
uses: elide-dev/setup-elide@v4
68+
69+
- name: "Check"
70+
run: |
71+
echo "Installed: ${{ steps.setup-elide.outputs.version }}"
72+
echo "Path: ${{ steps.setup-elide.outputs.path }}"
73+
echo "Cached: ${{ steps.setup-elide.outputs.cached }}"
74+
echo "Installer: ${{ steps.setup-elide.outputs.installer }}"
3375
```
3476

35-
## Options
77+
## Inputs
3678

37-
The full suite of available options are below.
79+
| Input | Type | Default | Description |
80+
|---|---|---|---|
81+
| `version` | `string` | `latest` | Version to install, or `latest` for the newest release |
82+
| `channel` | `string` | `nightly` | Release channel: `nightly`, `preview`, or `release` |
83+
| `installer` | `string` | `archive` | Installation method (see [Installers](#installers) below) |
84+
| `os` | `string` | _(auto)_ | Target OS override |
85+
| `arch` | `string` | _(auto)_ | Target architecture override |
86+
| `install_path` | `string` | _(conventional)_ | Custom install directory |
87+
| `force` | `boolean` | `false` | Force installation even if Elide is already installed |
88+
| `export_path` | `boolean` | `true` | Add Elide to the `PATH` |
89+
| `no_cache` | `boolean` | `false` | Disable the GitHub Actions tool cache |
90+
| `telemetry` | `boolean` | `true` | Enable anonymous error telemetry ([details](#telemetry)) |
91+
| `token` | `string` | `${{ github.token }}` | GitHub token for API requests |
92+
| `custom_url` | `string` | | Custom download URL (overrides all other download logic) |
93+
| `version_tag` | `string` | | Version tag to use with a custom download URL |
3894

39-
| Option | Type | Default | Description |
40-
| ------------- | ------------ | ------------------------- | -------------------------------------------- |
41-
| `version` | `string` | `latest` | Version to install; defaults to `latest` |
42-
| `os` | `string` | (Current) | OS to target; defaults to current platform |
43-
| `arch` | `string` | (Current) | Arch to target; defaults to current platform |
44-
| `force` | `boolean` | `false` | Force installation over existing binary |
45-
| `prewarm` | `boolean` | `true` | Warm up the runtime after installing |
46-
| `token` | `string` | `${{ env.GITHUB_TOKEN }}` | GitHub token to use for fetching assets |
47-
| `export_path` | `boolean` | `true` | Whether to install Elide onto the `PATH` |
95+
## Outputs
4896

49-
**Options for `os`** (support varies)
50-
- `darwin`, `mac`, `macos`
51-
- `windows`, `win32`
52-
- `linux`
97+
| Output | Description |
98+
|---|---|
99+
| `path` | Path to the installed Elide binary |
100+
| `version` | Installed version string |
101+
| `cached` | `true` if the installation was served from the tool cache |
102+
| `installer` | The effective installer method that was used |
53103

54-
**Options for `arch`** (support varies)
55-
- `amd64`, `x64`, `x86_64`
56-
- `arm64`, `aarch64`
104+
## Installers
57105

58-
**Full configuration sample with defaults**
106+
The `installer` input controls how Elide is installed. The default (`archive`) downloads a prebuilt archive from the Elide CDN and caches it using the GitHub Actions tool cache.
107+
108+
| Installer | Platforms | Description |
109+
|---|---|---|
110+
| `archive` | All | Download and extract a `.tgz`/`.txz`/`.zip` archive (default) |
111+
| `shell` | All | Run the official install script (`install.sh` or `install.ps1`) |
112+
| `apt` | Linux (Debian/Ubuntu) | Install via the Elide apt repository |
113+
| `rpm` | Linux (RHEL/Fedora) | Install via `.rpm` package |
114+
| `pkg` | macOS | Install via `.pkg` installer |
115+
| `msi` | Windows | Install via `.msi` installer |
116+
117+
If you choose an installer that doesn't match your platform (e.g., `msi` on Linux), the action will warn and fall back to `archive`.
118+
119+
## Supported Platforms
120+
121+
| Platform | Architectures |
122+
|---|---|
123+
| Linux | `amd64`, `aarch64` |
124+
| macOS | `amd64`, `aarch64` |
125+
| Windows | `amd64` |
126+
127+
**OS aliases:** `darwin`, `mac`, `macos`, `windows`, `win`, `win32`, `linux`
128+
**Arch aliases:** `amd64`, `x64`, `x86_64`, `aarch64`, `arm64`
129+
130+
## Caching
131+
132+
The `archive` installer uses the [GitHub Actions tool cache][4] to avoid re-downloading on subsequent runs. Cache keys are scoped by version and architecture. Set `no_cache: true` to disable caching.
133+
134+
## Telemetry
135+
136+
This action sends anonymous error telemetry to help the Elide team detect and fix issues at scale. **No secrets, tokens, environment variables, or personally identifiable information are ever transmitted.** Only the error message (scrubbed of sensitive values), stack trace, and action configuration (installer, os, arch, channel, version) are sent.
137+
138+
To opt out:
59139
```yaml
60-
- name: "Setup: Elide"
61-
uses: elide-dev/setup-elide@v1
62-
with:
63-
version: latest
64-
os: linux
65-
arch: amd64
66-
force: false
67-
prewarm: true
68-
export_path: true
140+
- uses: elide-dev/setup-elide@v4
141+
with:
142+
telemetry: false
69143
```
70144

71-
> [!IMPORTANT]
72-
> Elide supports Linux on amd64 and macOS on amd64/aarch64 at this time. Windows and Linux/aarch64 support are forthcoming.
145+
## GitHub Integration
146+
147+
This action uses GitHub Actions features to provide a polished CI experience:
148+
149+
- **Grouped log output** -- Installation phases are wrapped in collapsible log groups
150+
- **Job summary** -- A summary table is written to the Actions Summary tab showing version, platform, installer, timing, and cache status
151+
- **Annotations** -- Errors and warnings appear as titled annotations in the Actions UI
152+
- **Rich outputs** -- Downstream steps can branch on `cached`, `installer`, `version`, and `path`
73153

74154
## What is Elide?
75155

76-
Elide is a new runtime and framework designed for the polyglot era. Mix and match languages including JavaScript, Python, Ruby, and JVM, with the ability to share objects between them. It's fast: Elide can execute Python at up to 3x the speed of CPython, Ruby at up to 22x vs. CRuby, and JavaScript at up to 75x the speed of Node. Elide already beats Node, Deno, and Bun under benchmark.
156+
Elide is a new runtime and framework designed for the polyglot era. Mix and match languages including JavaScript, Python, Ruby, and JVM, with the ability to share objects between them. It's fast: Elide can execute Python at up to 3x the speed of CPython, Ruby at up to 22x vs. CRuby, and JavaScript at up to 75x the speed of Node.
77157

78158
- **Visit [elide.dev][1]**, our website, which runs on Elide
79159
- **Watch the [launch video][2]** for demos, benchmarks, and a full feature tour
80160
- **Join the devs on [Discord][3]**, we are always open to new ideas and feedback
81161

162+
## License
163+
164+
[MIT](.github/LICENSE)
165+
82166
[0]: https://github.com/features/actions
83167
[1]: https://elide.dev
84168
[2]: https://www.youtube.com/watch?v=Txl9ryfbCw4
85169
[3]: https://elide.dev/discord
170+
[4]: https://github.com/actions/toolkit/tree/main/packages/tool-cache

0 commit comments

Comments
 (0)