The Day Tree-sitter Killed Portability

2026-02-19T00:00:00+00:00
Same Emacs 29.2. Same config file.
It worked perfectly on macOS.
I copied it to Windows. Tree-sitter died.</p>
treesit-load-language-error: Cannot load language rust</span></span>
ABI version mismatch (library: 15, runtime: 14)</span></span></code></pre>
I checked.

macOS build: (treesit-library-abi-version)</code> → 15</strong>

Windows build: (treesit-library-abi-version)</code> → 14</strong></p>
That's when I realized.

The 10-year assumption of "portable init.el" had just collapsed.</p>

Act 1: The Migration Nightmare</h2>
The First Wall: "Grammar not found"</h3>
I had spent weeks perfecting my Emacs setup on macOS. Same version. Same packages. Same config file. I copied it to my Windows machine.</p>
I opened a Rust file.</p>
Cannot find tree-sitter grammar for rust</span></span></code></pre>
"Just not installed yet."

I ran M-x treesit-install-language-grammar</code>.

Entered the repository URL.</p>
treesit-install-language-grammar: Cannot find a C compiler</span></span></code></pre>The MSYS2 Swamp</h3>
I Googled. Every article gave the same answer.</p>
"Install MSYS2"</strong></p>

Download: 3.5GB</strong></li>
Install time: 30 minutes</li>
PATH configuration</li>
Restart Emacs</li>
</ul>
I tried again.</p>
Error: cc1.exe not found</span></span></code></pre>
Another search.</p>
"You need mingw-w64-x86_64-gcc</code>"</p>
Installed via pacman.

Another restart.</p>
Finally, compilation succeeded.</p>
The Gateway to ABI Hell</h3>
I opened a Rust file.</p>
treesit-load-language-error: Cannot load language rust</span></span>
ABI version mismatch (library: 15, runtime: 14)</span></span></code></pre>
"What is this?"</p>
I checked.

Windows build of Emacs 29.2 supports ABI 14</strong> at most.

macOS build of the same Emacs 29.2 supports ABI 15</strong>.</p>
Same version number. Different capabilities.</strong></p>
In that moment, I realized the "portable config file" had been a lie.</p>

Act 2: Four Circles of Hell</h2>
Hell 1: Platform-Dependent ABI Fragmentation</h3>
Same Emacs 29.2, but:</p>

macOS: ABI 15 supported</li>
Windows: ABI 14 only</li>
Linux (distribution-dependent): 13, 14, 15 mixed</li>
</ul>
Grammar settings in init.el won't work on another machine.

Because Emacs capabilities vary by build conditions</strong>.</p>
Hell 2: Crashes Even When ABI Matches</h3>
"Fine, I'll just use ABI 14 grammars."</p>
I installed the latest rust grammar on macOS.

ABI check: 14</strong>

Emacs support: 15</strong></p>
"Perfect."</p>
I opened a file.</p>
Emacs crashed. Segfault. No error message.</strong></p>
I searched.

Buried in a GitHub issue:</p>

"ABI 14 has internal breaking changes between tree-sitter 0.20.x and 0.21.x"</p>
</blockquote>
Same version number. Different internals.</strong></p>
Which commit actually works with my Emacs?

Trial and error is the only way.</p>
Hell 3: The Windows "3.5GB Tax"</h3>
To get a few kilobytes of syntax highlighting:</p>

MSYS2: 3.5GB</li>
mingw-w64-toolchain: hundreds of MB</li>
PATH conflicts</li>
Build error debugging</li>
</ul>
Polluting the OS just to get a .so file.</strong></p>
Hell 4: Configuration Fragmentation</h3>
I want to add Rust.</p>
;; 1. Define repository</span></span>
(</span>add-to-list</span> '</span>treesit-language-source-alist</span></span>
             '(</span>rust </span>"https://github.com/tree-sitter/tree-sitter-rust"</span>))</span></span>
</span>
;; 2. Install (manual execution)</span></span>
;; M-x treesit-install-language-grammar</span></span>
</span>
;; 3. Bind major mode</span></span>
(</span>add-to-list</span> '</span>major-mode-remap-alist</span> '(</span>rust-mode</span> .</span> rust-ts-mode</span>))</span></span>
</span>
;; 4. Bind file extension</span></span>
(</span>add-to-list</span> '</span>auto-mode-alist</span> '(</span>"\\.rs\\'"</span> .</span> rust-ts-mode</span>))</span></span></code></pre>
I want to add TypeScript.

Repeat the same process.</p>
Python, YAML, Markdown...</p>
Settings are now scattered across 4 places in init.el.

When I want to remove a language, I don't know where to delete.</p>
This is maintenance hell.</strong></p>

Act 3: The Obsession Begins</h2>
I spent 6 hours fighting MSYS2.

I manually traversed Git history to find compatible commits.

On the third night, I decided.</p>
"Never again."</strong></p>
I'll hijack Emacs's internal functions if I have to.

I'll brute-force scan Git repositories if I have to.</p>
This isn't a "convenient tool."

This is infrastructure born from obsession.</strong></p>

The Solution: treesit-env.el</h2>
I built four weapons.</p>
Weapon 1: Brute-Force Git History Search</h3>
"I don't know which commit works."

Then try them all.</strong></p>
(</span>while</span> (</span>and</span> (</span>></span> current-abi abi-max</span>) (</span><</span> attempt limit</span>))</span></span>
  ;; Deepen history by 10 commits at a time</span></span>
  (</span>call-process</span> "git"</span> nil nil nil</span> "fetch" "--deepen" "10"</span>)</span></span>
  </span></span>
  (</span>dolist</span> (</span>commit new-commits</span>)</span></span>
    (</span>with-temp-buffer</span></span>
      ;; Read file without checkout</span></span>
      (</span>call-process</span> "git"</span> nil</span> t</span> nil</span> "show"</span> </span></span>
                    (</span>format</span> "%s:src/parser.c"</span> commit</span>))</span></span>
      </span></span>
      ;; Parse LANGUAGE_VERSION with regex</span></span>
      (</span>goto-char</span> (</span>point-min</span>))</span></span>
      (</span>when</span> (</span>re-search-forward</span> "LANGUAGE_VERSION[ </span>\</span>t]+\\([0-9]+\\)"</span> nil</span> t</span>)</span></span>
        (</span>setq current-abi </span>(</span>string-to-number</span> (</span>match-string</span> 1</span>))))</span></span>
      </span></span>
      ;; Checkout immediately when compatible</span></span>
      (</span>when</span> (</span><=</span> current-abi abi-max</span>)</span></span>
        (</span>call-process</span> "git"</span> nil nil nil</span> "checkout"</span> commit</span>)</span></span>
        (</span>throw</span> '</span>found commit</span>)))))</span></span></code></pre>
How it works:</strong></p>

Dig into history with git fetch --deepen</code></li>
Read files directly with git show COMMIT:src/parser.c</code> (no checkout needed)</li>
Extract LANGUAGE_VERSION</code> via regex</li>
Stop the moment ABI is within limits</li>
</ol>
It's slow. Network-heavy.

But it never fails.</strong></p>
Weapon 2: Compiler Hijacking</h3>
"MSYS2 is too heavy."

Use Zig. A single 200MB binary.</strong></p>
"But Emacs expects gcc."

Then lie to it.</strong></p>
(</span>cl-letf*</span> (((</span>symbol-function</span> '</span>executable-find</span>)</span></span>
            (</span>lambda</span> (</span>command</span>)</span></span>
              ;; Looking for "gcc"? → Return Zig instead</span></span>
              (</span>let</span> ((</span>base </span>(</span>file-name-sans-extension</span> </span></span>
                          (</span>file-name-nondirectory</span> command</span>))))</span></span>
                (</span>cond</span> ((</span>member</span> base </span>'(</span>"cc" "gcc" "clang"</span>))</span></span>
                       (</span>car</span> treesit-env-compiler-cc</span>))</span></span>
                      ((</span>member</span> base </span>'(</span>"c++" "g++"</span>))</span></span>
                       (</span>car</span> treesit-env-compiler-c++</span>))</span></span>
                      (</span>t</span> (</span>funcall</span> old-exec-find command</span>))))))</span></span>
           </span></span>
           ((</span>symbol-function</span> '</span>call-process</span>)</span></span>
            (</span>lambda</span> (</span>program</span> &rest</span> args</span>)</span></span>
              ;; Missing .o files during linking? → Auto-inject them</span></span>
              (</span>when</span> (</span>and</span> (</span>member</span> "-shared"</span> args</span>)</span></span>
                         (</span>not</span> (</span>cl-some</span> (</span>lambda</span> (</span>a</span>)</span> </span></span>
                                        (</span>string-match-p</span> "\\.o$"</span> a</span>))</span> </span></span>
                                      args</span>)))</span></span>
                (</span>setq args </span>(</span>append</span> args </span></span>
                                  (</span>directory-files</span> "."</span> nil</span> "\\.o$"</span>))))</span></span>
              (</span>apply</span> old-call-process program args</span>))))</span></span></code></pre>
What's happening:</strong></p>
Emacs believes "gcc exists."

I decided to return Zig.</p>
Emacs expects ".o files as arguments."

I decided to scan the directory and inject them.</p>
This isn't a "hack." It's obsession.</strong></p>
Weapon 3: Declarative Configuration</h3>
"Settings are scattered."

Centralize them.</strong></p>
(</span>treesit-env rust</span></span>
  :</span>vc</span> "tree-sitter/tree-sitter-rust"</span></span>
  :</span>mode</span> "\\.rs\\'"</span></span>
  :</span>revision auto</span>)</span>  ;; Auto-search Git history</span></span></code></pre>
That's it.</p>

Repository definition</li>
Installation</li>
Mode binding</li>
ABI compatibility search</li>
</ul>
Everything is automatic.</strong></p>
Weapon 4: Recipe Dump</h3>
"Someone should maintain the canonical recipes."

No. Let the community share them.</strong></p>
M-x treesit-env-dump-recipes</span></span></code></pre>
This outputs your working configuration in recipe format.

Paste it in a Gist. Post it in a forum.</p>
No centralized maintainer needed.</strong></p>

Usage</h2>
Basic Setup</h3>
(</span>use-package</span> treesit-env</span></span>
  :</span>vc</span> (</span>:</span>url</span> "https://github.com/cottontailia/treesit-env"</span>)</span></span>
  :</span>custom</span></span>
  (</span>treesit-env-default-revision-auto t</span>)</span>  ;; Auto ABI search</span></span>
  (</span>treesit-env-abi-max </span>14</span>)</span>               ;; Force ABI 14 or lower</span></span>
  </span></span>
  :</span>config</span></span>
  ;; Use Zig on Windows</span></span>
  (</span>when</span> (</span>eq</span> system-type </span>'</span>windows-nt</span>)</span></span>
    (</span>setq treesit-env-compiler-cc </span>'(</span>"zig" "cc" "-O3"</span>))</span></span>
    (</span>setq treesit-env-compiler-c++ </span>'(</span>"zig" "c++" "-O3"</span>)))</span></span>
  </span></span>
  ;; Activate languages</span></span>
  (</span>treesit-env rust python typescript</span>))</span></span></code></pre>Pattern Collection</h3>
;; Pattern 1: Official repository (short form)</span></span>
(</span>treesit-env rust</span>)</span>  ;; → tree-sitter/tree-sitter-rust</span></span>
</span>
;; Pattern 2: tree-sitter-grammars org</span></span>
(</span>treesit-env markdown </span>:</span>vc grammars</span>)</span></span>
</span>
;; Pattern 3: Custom repository</span></span>
(</span>treesit-env python </span>:</span>vc</span> "user/custom-python-grammar"</span>)</span></span>
</span>
;; Pattern 4: Auto ABI search</span></span>
(</span>treesit-env go </span>:</span>revision auto</span>)</span></span>
</span>
;; Pattern 5: Fixed revision (fastest)</span></span>
(</span>treesit-env rust </span>:</span>revision</span> "v0.20.4"</span>)</span></span>
</span>
;; Pattern 6: Auto dependency resolution</span></span>
(</span>treesit-env tsx </span>:</span>deps typescript</span>)</span></span>
</span>
;; Pattern 7: Monorepo</span></span>
(</span>treesit-env typescript </span></span>
  :</span>vc</span> "tree-sitter/tree-sitter-typescript"</span></span>
  :</span>src-path</span> "typescript/src"</span>)</span></span>
</span>
;; Pattern 8: Multiple extensions</span></span>
(</span>treesit-env javascript </span></span>
  :</span>mode</span> "\\.js\\'" "\\.mjs\\'" "\\.cjs\\'"</span>)</span></span></code></pre>

Recipe Definition and Sharing</h3>
Complete examples: see treesit-env-recipe-placeholder.el</code> in the repository.

Warning</strong>: It's a "placeholder"—minimal recipes, no maintenance promise.</p>
;; Define recipes with treesit-env-recipes macro</span></span>
(</span>defconst</span> my-recipes</span></span>
  (</span>treesit-env-recipes</span></span>
   (</span>rust </span>:</span>vc</span> "tree-sitter/tree-sitter-rust"</span> :</span>revision</span> "v0.20.4"</span>)</span></span>
   (</span>python </span>:</span>vc grammars </span>:</span>mode</span> "\\.py\\'"</span>)</span></span>
   (</span>typescript </span>:</span>deps tsx </span>:</span>src-path</span> "typescript/src"</span>)))</span></span>
</span>
;; Import with treesit-env-source</span></span>
(</span>treesit-env-source my-recipes</span>)</span></span>
</span>
;; M-x treesit-env-dump-recipes outputs in this format too</span></span></code></pre>
Copy someone's success. Share yours.

Decentralized ecosystem.</strong></p>

Under the Hood: Technical Deep Dive</h2>
Why Read parser.c Directly?</h3>
Tree-sitter maintainers don't care about Emacs.

They race forward toward the latest library (ABI 15).</p>
Version info in GitHub READMEs is unreliable.

Tags can't be trusted.</p>
The only truth is the source code.</strong></p>
At the top of src/parser.c</code>:</p>
#define</span> LANGUAGE_VERSION</span> 14</span></span></code></pre>
Read this.

Only this tells you "Is this commit really ABI 14?"</p>
The Madness of Zig Hijacking</h3>
Emacs's build system is stubborn.</p>
It expects specific compiler names (gcc</code>, g++</code>).

It expects specific argument orders.

It expects specific file naming conventions.</p>
Zig doesn't satisfy these.</p>
So when Emacs "calls gcc," I run Zig instead</strong> behind the scenes.</p>
;; Emacs's perspective</span></span>
(</span>call-process</span> "gcc"</span> nil</span> t</span> nil</span> "-shared" "-o" "rust.so" "parser.c"</span>)</span></span>
</span>
;; Actual execution</span></span>
(</span>call-process</span> "zig"</span> nil</span> t</span> nil</span> "cc" "-O3" "-shared" "-o" "rust.so" "parser.c" "parser.o" "scanner.o"</span>)</span></span></code></pre>
Those .o</code> files at the end? I injected them.

Because Zig's linker requires explicit file lists.</p>
Emacs knows nothing. It just sees "build succeeded."</strong></p>
Recursive Dependency Resolution</h3>
tsx depends on typescript.

C depends on cpp (sometimes).</p>
Users don't know this. They don't need to.</p>
(</span>defvar</span> treesit-env--installing-stack</span> nil</span>)</span></span>
</span>
(</span>defun</span> treesit-env--execute-install</span> (</span>recipe</span>)</span></span>
  (</span>let</span> ((</span>lang </span>(</span>plist-get</span> recipe </span>:</span>lang</span>))</span></span>
        (</span>deps </span>(</span>plist-get</span> recipe </span>:</span>deps</span>)))</span></span>
    </span></span>
    ;; Detect circular dependencies</span></span>
    (</span>when</span> (</span>memq</span> lang treesit-env--installing-stack</span>)</span></span>
      (</span>error</span> "Circular dependency detected: %s"</span> lang</span>))</span></span>
    </span></span>
    ;; Install dependencies first</span></span>
    (</span>push</span> lang treesit-env--installing-stack</span>)</span></span>
    (</span>dolist</span> (</span>dep deps</span>)</span></span>
      (</span>unless</span> (</span>treesit-language-available-p dep</span>)</span></span>
        (</span>treesit-env--execute-install </span>(</span>get-recipe dep</span>))))</span></span>
    (</span>pop</span> treesit-env--installing-stack</span>)</span></span>
    </span></span>
    ;; Install the language itself</span></span>
    (</span>treesit-env--compile recipe</span>)))</span></span></code></pre>
Simple. Reliable.</p>
Users never think about dependencies.</strong></p>

Philosophy: Why CC0?</h2>
This tool was born from personal rage.</p>

6 hours fighting MSYS2</li>
Manual Git history traversal</li>
Config files that won't work across 3 machines</li>
</ul>
This isn't "innovative algorithm."

It's plumbing work</strong> to make unstable Tree-sitter infrastructure usable.</p>
That's why I chose CC0 (Public Domain).</p>
I don't seek stars or contributors.

I just wanted an environment that works the same way on any machine</strong>.</p>
Why I Won't Maintain Recipes</h3>
I don't want to be a "URL maintainer."

I want to write code.</p>
That's why I created treesit-env-dump-recipes</code>.</p>
You can export your working config.

Paste it in a Gist. Post it on Reddit. Copy it to someone's blog.</p>
Let the community self-organize.</strong></p>
Centralized databases are fragile.

Distributed knowledge is resilient.</p>

Conclusion</h2>
If you've ever:</p>

Been lost after seeing "ABI mismatch"</li>
Regretted installing MSYS2</li>
Despaired when your config broke on another machine</li>
Manually traversed Git history to find working commits</li>
</ul>
This tool is for you.</strong></p>
This isn't a perfect solution.

Someday, when Emacs and Tree-sitter mature, tools like this won't be needed.</p>
But today, you're suffering.</p>
So I'm releasing this infrastructure born from obsession.</p>

GitHub</strong>: https://github.com/cottontailia/treesit-env</a>

License</strong>: CC0 (Public Domain)</p>
cottontailia.io

The Day Tree-sitter Killed Portability

Act 1: The Migration Nightmare</h2>

Act 2: Four Circles of Hell</h2>

The Solution: treesit-env.el</h2> I built four weapons.</p>

Usage</h2>

Under the Hood: Technical Deep Dive</h2>

The Solution: treesit-env.el</h2>
I built four weapons.</p>
