tjh.dev
nixpkgs mirror (for testing)
github.com/NixOS/nixpkgs
nix
1# Tree-sitter Grammars
2
3Use [grammar-sources.nix](grammar-sources.nix) to define tree-sitter grammar sources.
4
5Tree-sitter grammars follow a common form for compatibility with the [`tree-sitter` CLI](https://tree-sitter.github.io/tree-sitter/cli/index.html).
6This uniformity enables consistent packaging through shared tooling.
7
8## Adding a Grammar
9
10To declare a new package, map the language name to a set of metadata required for the build.
11At a minimum, this must include the `version` and `src`.
12
13You may use a shorthand [flakeref](https://nix.dev/manual/nix/2.24/command-ref/new-cli/nix3-flake#url-like-syntax) style `url` and `hash` for concise declarations.
14If the hash is not yet known, use a [fake hash placeholder](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-fetchers-updating-source-hashes).
15
16```nix
17{
18 latex = {
19 version = "0.42.0";
20 url = "github:vandelay-industries/tree-sitter-latex";
21 hash = "";
22 };
23}
24```
25
26This will expand to an element in `pkgs.tree-sitter.grammars` at build time:
27
28```nix
29{
30 tree-sitter-latex = {
31 language = "latex";
32 version = "0.42.0";
33 src = fetchFromGitHub {
34 owner = "vandelay-industries";
35 repo = "tree-sitter-latex";
36 ref = "v0.42.0";
37 hash = "";
38 };
39 };
40}
41```
42
43Each entry is passed to [buildGrammar](../build-grammar.nix), which in turn populates `pkgs.tree-sitter-grammars`.
44
45Attempt to build the new grammar: `nix-build -A tree-sitter-grammars.tree-sitter-latex`.
46This will fail due to the invalid hash.
47Review the downloaded source, then update the source definition with the printed source `hash`.
48
49## Pinning Grammar Sources
50
51To pin to a specific ref, append this to the source `url` to override the default version tag.
52
53```nix
54{
55 latex = {
56 version = "0.42.0";
57 url = "github:vandelay-industries/tree-sitter-latex/ccfd77db0ed799b6c22c214fe9d2937f47bc8b34";
58 hash = "";
59 };
60}
61```
62
63This may be either a commit hash or tag.
64
65## Supported sources
66
67The `url` field supports the following prefixes:
68
69- `github:` → uses `fetchFromGitHub`
70- `gitlab:` → uses `fetchFromGitLab`
71- `sourcehut:` → uses `fetchFromSourcehut`
72
73To use [other fetchers](https://nixos.org/manual/nixpkgs/unstable/#chap-pkgs-fetchers), specify the `src` attribute directly:
74
75```nix
76{
77 foolang = {
78 version = "0.42.0";
79 src = fetchtorrent {
80 config = {
81 peer-limit-global = 100;
82 };
83 url = "magnet:?xt=urn:btih:dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c";
84 hash = "";
85 };
86 };
87}
88```
89
90## Modifying Build Behaviour
91
92Additional attributes in the grammar definition are forwarded to `buildGrammar`, and then to `mkDerivation`.
93This includes build-related flags and metadata.
94
95```nix
96{
97 foolang = {
98 version = "1729.0.0";
99 url = "sourcehut:~example/tree-sitter-foolang";
100 hash = "";
101 generate = true;
102 meta = {
103 license = lib.licenses.mit;
104 maintainers = with lib.maintainers; [
105 kimburgess
106 ];
107 };
108 };
109}
110```
111
112## Updating
113
114All grammar sources have a default update script defined.
115To manually trigger an update of a specific grammar definition:
116
117```shell
118nix-shell maintainers/scripts/update.nix --argstr package tree-sitter-grammars.tree-sitter-${name}
119```
120
121Or, to update all grammars:
122
123```shell
124nix-shell maintainers/scripts/update.nix --argstr path tree-sitter-grammars --argstr keep-going true
125```
126