executorch 0.1.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.executorch-version +1 -0
- data/CHANGELOG.md +24 -38
- data/README.md +143 -129
- data/ext/executorch/core/core.cpp +1131 -0
- data/ext/executorch/core/dtype.hpp +157 -0
- data/ext/executorch/core/module_core.hpp +165 -0
- data/ext/executorch/core/status.hpp +100 -0
- data/ext/executorch/core/tensor_core.hpp +73 -0
- data/ext/executorch/executorch.map +6 -0
- data/ext/executorch/extconf.rb +254 -173
- data/ext/executorch/rb_errors.cpp +117 -0
- data/ext/executorch/rb_executorch.cpp +69 -0
- data/ext/executorch/rb_internal.hpp +121 -0
- data/ext/executorch/rb_module.cpp +760 -0
- data/ext/executorch/rb_tensor.cpp +1281 -0
- data/lib/executorch/method_meta.rb +70 -0
- data/lib/executorch/module.rb +56 -0
- data/lib/executorch/sdk.rb +251 -0
- data/lib/executorch/tensor.rb +85 -0
- data/lib/executorch/version.rb +3 -1
- data/lib/executorch.rb +8 -204
- metadata +26 -23
- data/ext/executorch/executorch.cpp +0 -582
- data/ext/executorch/utils.h +0 -140
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 1f93c0ed8ee28b19d0bdc5c7ef7491624fd3aa1ed49d34ad5479505d076f9e1c
|
|
4
|
+
data.tar.gz: b0b41fa67de249d8796d53274d6d72a3c97e7d2627f78f198138e8fbc5ad1460
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 5f1c0924825678ffe2f6b701ad4888daada21a27cbdc95f540a3313be7a56fce51755b603dcc58b7f2dca4089d1602273a346fa637ba1bd2fc388c48235d5e0d
|
|
7
|
+
data.tar.gz: 7079e1771391b1934cc32c28c5fb0322cf60272f1643fb0c5b3263f9f3bb6f88e45b9cee310493472d48cab5564a26442e044a919f97c56f427c0ce03a504091
|
data/.executorch-version
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
1.6.0
|
data/CHANGELOG.md
CHANGED
|
@@ -2,46 +2,32 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
-
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
-
## [
|
|
8
|
+
## [1.0.0] - 2026-11-19
|
|
9
|
+
|
|
10
|
+
Complete from-scratch rewrite targeting ExecuTorch 1.6.0 and Ruby >= 3.2.
|
|
11
|
+
|
|
12
|
+
### Breaking Changes
|
|
13
|
+
|
|
14
|
+
- Replaced `Executorch::Model` with `Executorch::Module` (`Module.open`, `Module.from_bytes`, `#call`, `#forward`, `#execute`, `#meta`, `#load_method`, `#unload_method`, `#close`).
|
|
15
|
+
- Canonical tensor dtype symbols are now explicit-width (`:float32`, `:float64`, `:float16`, `:bfloat16`, `:uint8`, `:int8`, `:int16`, `:uint16`, `:int32`, `:uint32`, `:int64`, `:uint64`, `:bool`). Short aliases (`:float`, `:double`, `:int`, `:long`, etc.) remain accepted on input.
|
|
16
|
+
- Raised minimum Ruby version to `>= 3.2.0`.
|
|
17
|
+
- Removed `rice` dependency and leaked internal methods (`_original_to_a`, `Tensor.create`, `Tensor.from_array`, `NATIVE_VERSION`, `NativeError`).
|
|
9
18
|
|
|
10
19
|
### Added
|
|
11
20
|
|
|
12
|
-
- `
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- `
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
- `#flat_to_a` - Convert to flat Ruby array
|
|
26
|
-
- `#shape`, `#dim`, `#numel`, `#dtype` - Inspection methods
|
|
27
|
-
- Build configuration via `--with-executorch-dir` flag or `EXECUTORCH_DIR` environment variable
|
|
28
|
-
- `bundle config set --local build.executorch --with-executorch-dir=/path` (recommended)
|
|
29
|
-
- `EXECUTORCH_DIR=/path bundle install` (for CI)
|
|
30
|
-
- `EXECUTORCH_EXTRA_LIBS` for additional backend libraries
|
|
31
|
-
- Test models and export script
|
|
32
|
-
|
|
33
|
-
### Known Limitations
|
|
34
|
-
|
|
35
|
-
- Bool tensors (`:bool` dtype) not yet supported for creation
|
|
36
|
-
- No prebuilt binaries - requires ExecuTorch built from source
|
|
37
|
-
- macOS and Linux only (no Windows)
|
|
38
|
-
|
|
39
|
-
### Design Decisions
|
|
40
|
-
|
|
41
|
-
- Tensors are cloned when passed to inference methods for memory safety (slight performance overhead)
|
|
42
|
-
- dtype symbols use short names (`:int`, `:long`) rather than explicit sizes (`:int32`, `:int64`)
|
|
43
|
-
- EValue (ExecuTorch's internal tagged union) is not exposed; scalar outputs are auto-converted to Ruby types
|
|
44
|
-
|
|
45
|
-
## [Unreleased]
|
|
46
|
-
|
|
47
|
-
_No unreleased changes._
|
|
21
|
+
- Two-layer `noexcept` C++17 core beneath a direct Ruby C-API seam — eliminates `rb_raise` `longjmp`-past-destructor UB by construction.
|
|
22
|
+
- Strict symbol visibility (`-fvisibility=hidden` + ELF version script / macOS `-exported_symbol,_Init_executorch`) preventing ODR collisions with `torch.rb`, `onnxruntime-ruby`, or `ruby-vips`.
|
|
23
|
+
- GVL release (`rb_thread_call_without_gvl`) during module load, method load, and execution, paired with per-method thread-safety mutexes and `RB_GC_GUARD`.
|
|
24
|
+
- Native memory pressure reporting (`dsize` + `rb_gc_adjust_memory_usage`) and deterministic `#close` / block-form `Module.open`.
|
|
25
|
+
- Support for all 13 numeric/boolean dtypes, 0-D scalar tensors (`Tensor#item`), non-contiguous / `NHWC` `dim_order` normalization, value equality (`Tensor#==`), `Tensor.zeros`/`ones`/`full`, `Tensor.from_bytes`/`#to_bytes`, zero-copy `IO::Buffer` (`Tensor.from_buffer`/`#to_buffer`), pre-allocated `out:` output reuse, and optional `Numo::NArray`/`Torch::Tensor` adapters.
|
|
26
|
+
- `Module.open` defaults to `:mmap` (supporting `Pathname`, all `LoadMode`s, and external `.ptd` `data_files`), plus `Module.from_bytes` (`BufferDataLoader`) and `MethodMeta` / `TensorInfo` introspection.
|
|
27
|
+
- Runtime introspection (`Executorch.backends`, `.kernel_count`, `.num_threads`, `.num_threads=`, `.executorch_version`), PAL initialization (`runtime_init`), and thread-local PAL error log capture attached to typed `Executorch::Error` subclasses (`LoadError`, `MethodNotFoundError`, `OperatorMissingError`, `DelegateError`, `ShapeError`, `DTypeError`, `ExecutionError`, `MemoryError`, `ClosedError`).
|
|
28
|
+
- Precompiled platform gems (`x86_64-linux`, `aarch64-linux`, `arm64-darwin`) bundling the official ExecuTorch 1.6.0 shared SDK (XNNPACK, optimized & quantized kernels, CoreML/MLX on Apple Silicon) plus a pure-stdlib SHA-256-verified SDK fetcher for source installs — no Python, CMake, or Buck2 required at install or inference time.
|
|
29
|
+
- Deterministic `.pte`/`.ptd` test fixture export pipeline (`test/fixtures/export_fixtures.py`) and comprehensive correctness, ASan/UBSan, GC stress, concurrency, and adversarial safety test suites (0 skipped tests).
|
|
30
|
+
|
|
31
|
+
## [0.1.0] - 2025-11-16
|
|
32
|
+
|
|
33
|
+
Initial prototype release.
|
data/README.md
CHANGED
|
@@ -1,198 +1,212 @@
|
|
|
1
|
-
#
|
|
1
|
+
# executorch-ruby
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/benngarcia/executorch-ruby/actions/workflows/ci.yml)
|
|
4
|
+
[](https://rubygems.org/gems/executorch)
|
|
5
|
+
[](LICENSE.txt)
|
|
4
6
|
|
|
5
|
-
[ExecuTorch](https://pytorch.org/executorch/)
|
|
7
|
+
Native Ruby bindings for Meta's [ExecuTorch](https://pytorch.org/executorch/) runtime (`1.6.0`), built directly on the Ruby C API.
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
Run exported PyTorch models (`.pte` / `.ptd`) in Ruby with precompiled platform gems, GVL-free execution, zero-copy `IO::Buffer` tensors, and hardware delegates (XNNPACK, CoreML, MLX).
|
|
8
10
|
|
|
9
|
-
|
|
10
|
-
require "executorch"
|
|
11
|
+
## Installation
|
|
11
12
|
|
|
12
|
-
|
|
13
|
-
|
|
13
|
+
Add to your `Gemfile`:
|
|
14
|
+
|
|
15
|
+
```ruby
|
|
16
|
+
gem "executorch", "~> 1.0"
|
|
17
|
+
```
|
|
14
18
|
|
|
15
|
-
|
|
16
|
-
input = Executorch::Tensor.new([[1.0, 2.0, 3.0]])
|
|
19
|
+
Or install directly:
|
|
17
20
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
puts output.to_a # => [[3.0, 5.0, 7.0]]
|
|
21
|
+
```bash
|
|
22
|
+
gem install executorch
|
|
21
23
|
```
|
|
22
24
|
|
|
23
|
-
|
|
25
|
+
Requires **Ruby `>= 3.2`**.
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
### Supported platforms
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
| Platform | Precompiled Gem | Bundled Delegates & Kernels |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| `x86_64-linux` | Yes | XNNPACK, Optimized CPU, Quantized |
|
|
32
|
+
| `aarch64-linux` | Yes | XNNPACK (KleidiAI), Optimized CPU, Quantized, TorchAO |
|
|
33
|
+
| `arm64-darwin` | Yes | XNNPACK, CoreML, MLX, Optimized CPU, Quantized, TorchAO |
|
|
34
|
+
| Source (`ruby`) | Yes | Fetches the official ExecuTorch 1.6.0 C++ SDK (or uses `--with-executorch-dir`) |
|
|
28
35
|
|
|
29
|
-
|
|
36
|
+
## Quick Start
|
|
30
37
|
|
|
31
|
-
|
|
32
|
-
git clone https://github.com/pytorch/executorch.git
|
|
33
|
-
cd executorch
|
|
34
|
-
./install_requirements.sh
|
|
35
|
-
|
|
36
|
-
cmake -B cmake-out \
|
|
37
|
-
-DCMAKE_INSTALL_PREFIX=vendor/executorch \
|
|
38
|
-
-DEXECUTORCH_BUILD_EXTENSION_MODULE=ON \
|
|
39
|
-
-DEXECUTORCH_BUILD_EXTENSION_DATA_LOADER=ON \
|
|
40
|
-
-DEXECUTORCH_BUILD_EXTENSION_TENSOR=ON \
|
|
41
|
-
-DCMAKE_BUILD_TYPE=Release
|
|
42
|
-
|
|
43
|
-
cmake --build cmake-out -j4
|
|
44
|
-
cmake --install cmake-out
|
|
45
|
-
```
|
|
38
|
+
Export a PyTorch model to `.pte` using ExecuTorch:
|
|
46
39
|
|
|
47
|
-
|
|
40
|
+
```python
|
|
41
|
+
import torch
|
|
42
|
+
from executorch.backends.xnnpack.partition.xnnpack_partitioner import XnnpackPartitioner
|
|
43
|
+
from executorch.exir import to_edge_transform_and_lower
|
|
48
44
|
|
|
49
|
-
|
|
45
|
+
class AddMul(torch.nn.Module):
|
|
46
|
+
def forward(self, x):
|
|
47
|
+
return x * 2.0 + 1.0
|
|
50
48
|
|
|
51
|
-
|
|
52
|
-
|
|
49
|
+
example_input = (torch.tensor([[1.0, 2.0, 3.0]], dtype=torch.float32),)
|
|
50
|
+
exported = torch.export.export(AddMul().eval(), example_input)
|
|
51
|
+
et_program = to_edge_transform_and_lower(
|
|
52
|
+
exported, partitioner=[XnnpackPartitioner()]
|
|
53
|
+
).to_executorch()
|
|
54
|
+
|
|
55
|
+
with open("model.pte", "wb") as f:
|
|
56
|
+
et_program.write_to_file(f)
|
|
53
57
|
```
|
|
54
58
|
|
|
55
|
-
|
|
59
|
+
Load and run it in Ruby:
|
|
56
60
|
|
|
57
61
|
```ruby
|
|
58
|
-
|
|
59
|
-
```
|
|
62
|
+
require "executorch"
|
|
60
63
|
|
|
61
|
-
|
|
64
|
+
Executorch::Module.open("model.pte") do |mod|
|
|
65
|
+
meta = mod.meta(:forward)
|
|
66
|
+
p meta.backends # => ["XnnpackBackend"]
|
|
67
|
+
p meta.inputs # => [#<Executorch::TensorInfo dtype=:float32 shape=[1, 3] nbytes=12>]
|
|
62
68
|
|
|
63
|
-
|
|
64
|
-
|
|
69
|
+
input = Executorch::Tensor.new([[1.0, 2.0, 3.0]])
|
|
70
|
+
output = mod.call(input)
|
|
71
|
+
p output.to_a # => [[3.0, 5.0, 7.0]]
|
|
72
|
+
end
|
|
65
73
|
```
|
|
66
74
|
|
|
67
|
-
> **CI/CD:** Use the environment variable instead: `EXECUTORCH_DIR=/path/to/executorch bundle install`
|
|
68
|
-
|
|
69
75
|
## Usage
|
|
70
76
|
|
|
71
|
-
###
|
|
77
|
+
### Modules
|
|
72
78
|
|
|
73
|
-
|
|
79
|
+
`Executorch::Module.open` accepts a `String` or `Pathname`, defaults to `:mmap` loading (sharing read-only weight pages across forked Puma/Unicorn workers), and closes deterministically when given a block.
|
|
74
80
|
|
|
75
81
|
```ruby
|
|
76
|
-
#
|
|
77
|
-
|
|
78
|
-
|
|
82
|
+
# Load modes: :mmap (default), :file, :mmap_mlock, :mmap_mlock_ignore_errors, :mmap_madvise
|
|
83
|
+
mod = Executorch::Module.open(Pathname.new("model.pte"), load_mode: :mmap)
|
|
84
|
+
mod.load_method(:forward) # optional pre-warm before serving requests
|
|
85
|
+
out = mod.call(input)
|
|
86
|
+
mod.close
|
|
87
|
+
|
|
88
|
+
# Multi-method programs
|
|
89
|
+
Executorch::Module.open("autoencoder.pte") do |m|
|
|
90
|
+
z = m.execute(:encode, x).first
|
|
91
|
+
reconstructed = m.execute(:decode, z).first
|
|
92
|
+
end
|
|
93
|
+
|
|
94
|
+
# External .ptd weight files
|
|
95
|
+
Executorch::Module.open("model.pte", data_files: ["weights.ptd"]) do |m|
|
|
96
|
+
logits = m.call(tokens)
|
|
97
|
+
end
|
|
98
|
+
|
|
99
|
+
# Load directly from an in-memory String (e.g. S3 or ActiveStorage)
|
|
100
|
+
mod = Executorch::Module.from_bytes(pte_bytes)
|
|
101
|
+
mod.close
|
|
102
|
+
```
|
|
79
103
|
|
|
80
|
-
|
|
81
|
-
|
|
104
|
+
- `#call(*inputs, out: nil)` runs `"forward"` and returns the single output directly when there is one output, or an `Array` otherwise.
|
|
105
|
+
- `#forward(*inputs, out: nil)` and `#execute(name, *inputs, out: nil)` always return an `Array`.
|
|
106
|
+
- `#meta(name = :forward)` returns an `Executorch::MethodMeta` describing input/output shapes, dtypes, planned memory size, and lowered backends without loading the full method.
|
|
82
107
|
|
|
83
|
-
|
|
84
|
-
tensor.shape # => [2, 3]
|
|
85
|
-
tensor.dtype # => :float
|
|
86
|
-
tensor.to_a # => [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
|
|
87
|
-
```
|
|
108
|
+
### Tensors
|
|
88
109
|
|
|
89
|
-
|
|
110
|
+
Supported dtypes: `:float32`, `:float64`, `:float16`, `:bfloat16`, `:uint8`, `:int8`, `:int16`, `:uint16`, `:int32`, `:uint32`, `:int64`, `:uint64`, and `:bool`. Short aliases (`:float`, `:double`, `:half`, `:byte`, `:char`, `:short`, `:int`, `:long`) are accepted at construction.
|
|
90
111
|
|
|
91
112
|
```ruby
|
|
92
|
-
|
|
113
|
+
t = Executorch::Tensor.new([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
|
|
114
|
+
t.shape # => [2, 3]
|
|
115
|
+
t.dtype # => :float32
|
|
116
|
+
t.nbytes # => 24
|
|
117
|
+
t.to_a # => [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
|
|
118
|
+
|
|
119
|
+
# 0-D scalar tensors
|
|
120
|
+
scalar = Executorch::Tensor.new(42.5, dtype: :float32)
|
|
121
|
+
scalar.shape # => []
|
|
122
|
+
scalar.item # => 42.5
|
|
123
|
+
|
|
124
|
+
# Packed binary I/O & factories
|
|
125
|
+
raw = t.to_bytes
|
|
126
|
+
t2 = Executorch::Tensor.from_bytes(raw, shape: [2, 3], dtype: :float32)
|
|
127
|
+
t == t2 # => true
|
|
128
|
+
|
|
129
|
+
zeros = Executorch::Tensor.zeros([2, 3], dtype: :float32)
|
|
130
|
+
ones = Executorch::Tensor.ones([2, 3], dtype: :int64)
|
|
131
|
+
full = Executorch::Tensor.full([2, 3], 7, dtype: :uint8)
|
|
93
132
|
```
|
|
94
133
|
|
|
95
|
-
|
|
134
|
+
Optional adapters are provided for `Numo::NArray` (`Tensor.from_numo` / `Tensor#to_numo`) and `Torch::Tensor` (`Tensor.from_torch`).
|
|
135
|
+
|
|
136
|
+
### Zero-copy `IO::Buffer` and output reuse
|
|
96
137
|
|
|
97
|
-
|
|
138
|
+
Pass Ruby `IO::Buffer` instances directly into ExecuTorch without copying or allocating intermediate arrays. Pairing `Tensor.from_buffer` with `out:` writes inference outputs straight into a caller-owned buffer:
|
|
98
139
|
|
|
99
140
|
```ruby
|
|
100
|
-
|
|
141
|
+
in_buf = IO::Buffer.for([1.0, 2.0, 3.0].pack("f*"))
|
|
142
|
+
out_buf = IO::Buffer.new(12)
|
|
101
143
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
outputs = model.forward([input])
|
|
105
|
-
outputs = model.call([input])
|
|
144
|
+
input = Executorch::Tensor.from_buffer(in_buf, shape: [1, 3], dtype: :float32)
|
|
145
|
+
output = Executorch::Tensor.from_buffer(out_buf, shape: [1, 3], dtype: :float32)
|
|
106
146
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
147
|
+
Executorch::Module.open("model.pte") do |mod|
|
|
148
|
+
mod.call(input, out: output)
|
|
149
|
+
p out_buf.get_string.unpack("f*") # => [3.0, 5.0, 7.0]
|
|
150
|
+
end
|
|
110
151
|
```
|
|
111
152
|
|
|
112
|
-
|
|
153
|
+
### Concurrency, runtime introspection & errors
|
|
113
154
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
class MyModel(torch.nn.Module):
|
|
121
|
-
def forward(self, x):
|
|
122
|
-
return x * 2 + 1
|
|
123
|
-
|
|
124
|
-
model = MyModel()
|
|
125
|
-
example_input = torch.randn(1, 3)
|
|
126
|
-
|
|
127
|
-
exported = torch.export.export(model, (example_input,))
|
|
128
|
-
et_program = to_edge(exported).to_executorch()
|
|
129
|
-
|
|
130
|
-
with open("model.pte", "wb") as f:
|
|
131
|
-
et_program.write_to_file(f)
|
|
155
|
+
```ruby
|
|
156
|
+
Executorch.backends # => ["XnnpackBackend"]
|
|
157
|
+
Executorch.kernel_count # => 263
|
|
158
|
+
Executorch.num_threads # => 24
|
|
159
|
+
Executorch.num_threads = 2 # size the ExecuTorch threadpool for multi-worker servers
|
|
160
|
+
Executorch.executorch_version # => "1.6.0"
|
|
132
161
|
```
|
|
133
162
|
|
|
134
|
-
|
|
163
|
+
- **GVL release & thread safety:** Model loading and execution release the Ruby GVL (`rb_thread_call_without_gvl`). Calls on separate `Module` instances run in parallel across cores; concurrent calls to the same method on a shared `Module` serialize safely via a per-method mutex.
|
|
164
|
+
- **Typed errors:** Runtime failures inherit from `Executorch::Error < StandardError` (`LoadError`, `MethodNotFoundError`, `OperatorMissingError`, `DelegateError`, `ShapeError`, `DTypeError`, `ExecutionError`, `MemoryError`, `ClosedError`) and expose `#code` and `#pal_log`.
|
|
135
165
|
|
|
136
|
-
|
|
137
|
-
<summary><strong>"ExecuTorch installation not found"</strong></summary>
|
|
166
|
+
## Architecture
|
|
138
167
|
|
|
139
|
-
|
|
168
|
+
The native extension is written directly against the Ruby C API (no binding generator or runtime gem dependencies) in two layers:
|
|
140
169
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
```
|
|
145
|
-
</details>
|
|
170
|
+
- **`ext/executorch/core/`** — A `noexcept` C++17 core with zero Ruby headers. Handles ExecuTorch lifecycle, per-method locking, thread-local PAL log capture, overflow-checked shape math, and strided/`NHWC` layout normalization.
|
|
171
|
+
- **`ext/executorch/rb_*.cpp`** — A thin Ruby C-API layer managing `TypedData`, `dsize` + `rb_gc_adjust_memory_usage`, `GC.compact`-safe global roots, `rb_io_buffer_lock` around GVL-free execution, and single-pass C++ nested-array flattening. All C++ stack objects are destroyed before any Ruby exception is raised.
|
|
172
|
+
- **Symbol isolation:** Compiled with `-fvisibility=hidden` and a linker export map so only `Init_executorch` is exported, avoiding symbol collisions with `torch.rb`, `onnxruntime`, or `ruby-vips`.
|
|
146
173
|
|
|
147
|
-
|
|
148
|
-
<summary><strong>"module.h header not found"</strong></summary>
|
|
174
|
+
## Custom ExecuTorch builds
|
|
149
175
|
|
|
150
|
-
ExecuTorch
|
|
176
|
+
To compile against a local ExecuTorch installation instead of the default SDK:
|
|
151
177
|
|
|
152
178
|
```bash
|
|
153
|
-
|
|
154
|
-
-DEXECUTORCH_BUILD_EXTENSION_MODULE=ON \
|
|
155
|
-
-DEXECUTORCH_BUILD_EXTENSION_DATA_LOADER=ON \
|
|
156
|
-
-DEXECUTORCH_BUILD_EXTENSION_TENSOR=ON \
|
|
157
|
-
...
|
|
179
|
+
bundle config set --local build.executorch --with-executorch-dir=/absolute/path/to/executorch
|
|
158
180
|
```
|
|
159
|
-
</details>
|
|
160
|
-
|
|
161
|
-
<details>
|
|
162
|
-
<summary><strong>"undefined symbol" at runtime</strong></summary>
|
|
163
|
-
|
|
164
|
-
Try linking additional libraries:
|
|
165
181
|
|
|
166
|
-
|
|
167
|
-
EXECUTORCH_EXTRA_LIBS=portable_ops_lib,portable_kernels bundle exec rake compile
|
|
168
|
-
```
|
|
169
|
-
</details>
|
|
182
|
+
Or pass `EXECUTORCH_DIR=/absolute/path/to/executorch`. Set `EXECUTORCH_NO_DOWNLOAD=1` to disable automatic SDK fetching.
|
|
170
183
|
|
|
171
|
-
##
|
|
184
|
+
## Changelog
|
|
172
185
|
|
|
173
|
-
|
|
174
|
-
- [Changelog](CHANGELOG.md)
|
|
175
|
-
- [Report an Issue](https://github.com/benngarcia/executorch-ruby/issues)
|
|
186
|
+
See [CHANGELOG.md](CHANGELOG.md) for release notes and migration details.
|
|
176
187
|
|
|
177
188
|
## Development
|
|
178
189
|
|
|
179
190
|
```bash
|
|
180
|
-
git clone https://github.com/benngarcia/executorch-ruby.git
|
|
181
|
-
cd executorch-ruby
|
|
182
191
|
bundle install
|
|
183
|
-
bundle
|
|
184
|
-
bundle exec rake compile
|
|
185
|
-
bundle exec rake test
|
|
192
|
+
bundle exec rake sdk:fetch # Fetches verified ExecuTorch 1.6.0 C++ SDK into ~/.cache/executorch-ruby/
|
|
193
|
+
bundle exec rake compile # Compiles native C++17 extension
|
|
194
|
+
bundle exec rake fixtures:export # Exports deterministic .pte/.ptd test models via uv
|
|
195
|
+
bundle exec rake test # Runs full test suite
|
|
196
|
+
ruby bench/run_bench.rb # Runs local latency benchmarks
|
|
186
197
|
```
|
|
187
198
|
|
|
188
|
-
|
|
199
|
+
To run the suite under AddressSanitizer + UndefinedBehaviorSanitizer on Linux:
|
|
189
200
|
|
|
190
|
-
|
|
201
|
+
```bash
|
|
202
|
+
bundle exec rake clean
|
|
203
|
+
EXECUTORCH_SANITIZE=1 bundle exec rake compile
|
|
204
|
+
LD_PRELOAD="$(g++ -print-file-name=libasan.so):$(g++ -print-file-name=libubsan.so)" \
|
|
205
|
+
ASAN_OPTIONS=detect_leaks=0:use_sigaltstack=0:halt_on_error=1 \
|
|
206
|
+
UBSAN_OPTIONS=print_stacktrace=1:halt_on_error=1 \
|
|
207
|
+
bundle exec rake test
|
|
208
|
+
```
|
|
191
209
|
|
|
192
210
|
## License
|
|
193
211
|
|
|
194
212
|
Apache License 2.0. See [LICENSE.txt](LICENSE.txt).
|
|
195
|
-
|
|
196
|
-
## Acknowledgments
|
|
197
|
-
|
|
198
|
-
Built with [Rice](https://github.com/jasonroelofs/rice). Inspired by [onnxruntime-ruby](https://github.com/ankane/onnxruntime-ruby) and [torch.rb](https://github.com/ankane/torch.rb).
|