helix - Unnamed repository; edit this file 'description' to name the repository.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164


Building from source

Configuring Helix's runtime files
Linux and macOS
Windows
Multiple runtime directories
Note to packagers
Validating the installation
Configure the desktop shortcut

Requirements:
Clone the Helix GitHub repository into a directory of your choice. The
examples in this documentation assume installation into either ~/src/ on
Linux and macOS, or %userprofile%\src\ on Windows.

The Rust toolchain
The Git version control system
A C++14 compatible compiler to build the tree-sitter grammars, for example GCC or Clang

If you are using the musl-libc standard library instead of glibc the following environment variable must be set during the build to ensure tree-sitter grammars can be loaded correctly:
RUSTFLAGS="-C target-feature=-crt-static"


Clone the repository:

sh
   git clone https://github.com/helix-editor/helix
   cd helix

Compile from source:

sh
   cargo install --path helix-term --locked
This command will create the hx executable and construct the tree-sitter
   grammars in the local runtime folder.

💡 If you do not want to fetch or build grammars, set an environment variable HELIX_DISABLE_AUTO_GRAMMAR_BUILD
💡 Tree-sitter grammars can be fetched and compiled if not pre-packaged. Fetch
grammars with hx --grammar fetch and compile them with
hx --grammar build. This will install them in
the runtime directory within the user's helix config directory (more
details below).

Configuring Helix's runtime files
Linux and macOS
The runtime directory is one below the Helix source, so either export a
HELIX_RUNTIME environment variable to point to that directory and add it to
your ~/.bashrc or equivalent:
export HELIX_RUNTIME=~/src/helix/runtime


Or, create a symbolic link:
ln -Ts $PWD/runtime ~/.config/helix/runtime


If the above command fails to create a symbolic link because the file exists either move ~/.config/helix/runtime to a new location or delete it, then run the symlink command above again.
Windows
Either set the HELIX_RUNTIME environment variable to point to the runtime files using the Windows setting (search for
Edit environment variables for your account) or use the setx command in
Cmd:
setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime"


💡 %userprofile% resolves to your user directory like
C:\Users\Your-Name\ for example.

Or, create a symlink in %appdata%\helix\ that links to the source code directory:


Method
Command


PowerShell
New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"


Cmd
cd %appdata%\helix 
 mklink /D runtime "%userprofile%\src\helix\runtime"


💡 On Windows, creating a symbolic link may require running PowerShell or
Cmd as an administrator.

Multiple runtime directories
When Helix finds multiple runtime directories it will search through them for files in the
following order:

runtime/ sibling directory to $CARGO_MANIFEST_DIR directory (this is intended for
  developing and testing helix only).
runtime/ subdirectory of OS-dependent helix user config directory.
$HELIX_RUNTIME
Distribution-specific fallback directory (set at compile time—not run time—
   with the HELIX_DEFAULT_RUNTIME environment variable)
runtime/ subdirectory of path to Helix executable.

This order also sets the priority for selecting which file will be used if multiple runtime
directories have files with the same name.
Note to packagers
If you are making a package of Helix for end users, to provide a good out of
the box experience, you should set the HELIX_DEFAULT_RUNTIME environment
variable at build time (before invoking cargo build) to a directory which
will store the final runtime files after installation. For example, say you want
to package the runtime into /usr/lib/helix/runtime. The rough steps a build
script could follow are:

export HELIX_DEFAULT_RUNTIME=/usr/lib/helix/runtime
cargo build --profile opt --locked --path helix-term
cp -r runtime $BUILD_DIR/usr/lib/helix/
cp target/opt/hx $BUILD_DIR/usr/bin/hx

This way the resulting hx binary will always look for its runtime directory in
/usr/lib/helix/runtime if the user has no custom runtime in ~/.config/helix
or HELIX_RUNTIME.
Validating the installation
To make sure everything is set up as expected you should run the Helix health
check:
hx --health


For more information on the health check results refer to
Health check.
Configure the desktop shortcut
If your desktop environment supports the
XDG desktop menu
you can configure Helix to show up in the application menu by copying the
provided .desktop and icon files to their correct folders:
cp contrib/Helix.desktop ~/.local/share/applications
cp contrib/helix.png ~/.icons # or ~/.local/share/icons


It is recommended to convert the links in the .desktop file to absolute paths to avoid potential problems:
sed -i -e "s|Exec=hx %F|Exec=$(readlink -f ~/.cargo/bin/hx) %F|g" \
  -e "s|Icon=helix|Icon=$(readlink -f ~/.icons/helix.png)|g" ~/.local/share/applications/Helix.desktop


To use another terminal than the system default, you can modify the .desktop
file. For example, to use kitty:
sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop
sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop