Input needed on re-write of instructions for installing from source, especially regarding Windows

[David-Else]

@jdrst @megumish @gdtroszak @NotAgentBilly @matan-h @the-mikedavis (I plucked you out of the commit history, hope you don't mind, everyone is very welcome to comment on this!)

I am working on improving the documentation by rewriting and refactoring it. However, I lack some domain knowledge, particularly for Windows.

The current instructions for installing from source are a mish-mash of different peoples input over time and are extremely hard to follow. I am trying to radically simplify them into clear easy to follow steps, but I might have gone too far. I also may have misunderstood something. Please can people compare the before and after and give me feedback?

• Is it correct that any modern Windows from Vista onwards can do symlinks? If so, we don't need to support legacy systems, can we drop the xcopying and stick to just symlinking? That massively simplifies things, see below.

CURRENT Docs

Build from source

git clone https://github.com/helix-editor/helix
cd helix
cargo install --path helix-term --locked

This will install the hx binary to $HOME/.cargo/bin and build tree-sitter grammars in ./runtime/grammars.

Helix also needs its runtime files so make sure to copy/symlink the runtime/ directory into the config directory (for example ~/.config/helix/runtime on Linux/macOS). This location can be overridden via the HELIX_RUNTIME environment variable.

OS	Command
Windows (Cmd)	xcopy /e /i runtime %AppData%\helix\runtime
Windows (PowerShell)	xcopy /e /i runtime $Env:AppData\helix\runtime
Linux / macOS	ln -s $PWD/runtime ~/.config/helix/runtime

Starting with Windows Vista you can also create symbolic links on Windows. Note that this requires elevated privileges - i.e. PowerShell or Cmd must be run as administrator.

PowerShell:

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

Cmd:

cd %appdata%\helix
mklink /D runtime "<helix-repo>\runtime"

The runtime location can be overridden via the HELIX_RUNTIME environment variable.

NOTE: if HELIX_RUNTIME is set prior to calling cargo install --path helix-term --locked, tree-sitter grammars will be built in $HELIX_RUNTIME/grammars.

If you plan on keeping the repo locally, an alternative to copying/symlinking runtime files is to set HELIX_RUNTIME=/path/to/helix/runtime (HELIX_RUNTIME=$PWD/runtime if you're in the helix repo directory).

To use Helix in desktop environments that supports XDG desktop menu, including Gnome and KDE, copy the provided .desktop file to the correct folder:

cp contrib/Helix.desktop ~/.local/share/applications

To use another terminal than the default, you will need to 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

NEW Docs (v2, updated 11th Jan)

Building from Source

1. Clone the repository:

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

2. Compile Helix:

cargo install --path helix-term --locked

This command installs the hx binary to ~/.cargo/bin and builds the tree-sitter grammars in ./runtime/grammars.

3. IMPORTANT: Configure Helix's runtime files

Helix looks by default in the config folder (~/.config/helix/ on Linux/macOS) to find your runtime/ folder, and without our intervention Helix will find nothing there. Misconfiguration is a common source of problems, so please pay careful attention to this section.

To allow Helix to access the runtime files, which are located in the .runtime/ directory of your source code folder, you will need to set the HELIX_RUNTIME environmental variable OR create a symlink of the runtime/ directory to your config folder.

• To set the HELIX_RUNTIME variable, use the HELIX_RUNTIME=/path/to/helix/runtime format. For example: HELIX_RUNTIME=/home/user-name/src/helix/runtime. Add this variable to your ~/.bashrc file or equivalent to persist it.

• To create a symlink, enter the appropriate command for your operating system:

OS	Command
Linux / macOS	ln -s $PWD/runtime ~/.config/helix/runtime
Windows (PowerShell)	New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime"
Windows (Cmd)	cd %appdata%\helix
	mklink /D runtime "<helix-repo>\runtime"

Note: On Windows creating a symbolic link requires elevated privileges - i.e. PowerShell or Cmd must be run as administrator.

4. 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 ~/.local/share/icons

To use another terminal than the system default (which is always gnome-terminal on Gnome), 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

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.

Building tree-sitter grammars

Tree-sitter grammars must be fetched and compiled if not pre-packaged. Fetch grammars with hx --grammar fetch (requires git) and compile them with hx --grammar build (requires a C++ compiler).

[archseer]

I would emphasize Enable Helix to find the runtime files and certain sections under it because users are trained to run cargo install then stop reading the instructions (which results in a ton of questions in the format of "why isn't my highlighting working")

you can find installation instructions for Rust

this part seems unnecessary for me, if the user doesn't know how to deal with Rust they'd probably have a better experience just using a package or the release binaries

Clone the Helix GitHub repository and navigate to it in your terminal:

Same here, "Clone the repository:" seems enough for me

Since the book already covers installation we can also remove that section from the README and leave a link to that page. Similar to how that's done in wezterm: https://github.com/wez/wezterm#installation

[archseer]

The way wezterm splits the guide by OS seems nice too: https://wezfurlong.org/wezterm/installation.html

[David-Else]

@archseer I have updated the Building from Source documentation (NEW Docs (v2, updated 11th Jan) above with your suggestions, and rewritten sections for even greater clarity.

I am pretty happy with it now, but I am no expert on setting up the runtime files, please let me know if there are any errors or anything that could be improved further.

I am still awaiting feedback on the Windows issues I raised in the original post.

I am unsure about the Building tree-sitter grammars section tacked on the end, it is out of place, why would anyone need to do this as an extra step? I don't know if we need this section, or if we do, why?

[CptPotato]

Is it correct that any modern Windows from Vista onwards can do symlinks?

I added the symlink hint for the Windows install instructions. My source for the Windows Vista or later requirement is Microsoft's windows developer blog:

The Windows’ NTFS file system has supported symlinks since Windows Vista.

^{https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/}

Since I've never used Windows Vista I can't confirm whether or not this actually is the case. On Windows 10 the symlink command works without issues for me.

It did however require elevated privileges on all Windows 10 machines I used, even though the blog says it shouldn't:

Starting with Windows 10 Insiders build 14972, symlinks can be created without needing to elevate the console as administrator.

[David-Else]

Thanks!

It did however require elevated privileges on all Windows 10 machines I used, even though the blog says it shouldn't:

I have changed the wording to may require elevated privileges.

In your opinion, does NEW Docs (v2, updated 11th Jan) in my original post fully explain how to install Helix from source on modern Windows? I did chop out a lot from the original documentation, but it seemed to be all relating to Windows 7 needing to use xcopy, Windows 7 support ended on January 14, 2020 - Microsoft Support

[CptPotato]

It seems fairly straight forward to me. Some small nits, though:

• there's a .runtime/ which I think was meant to be ./runtime/
• the may require elevated privileges change is not in the text above
• some of the wording in section 3. sounds a bit odd to me. But take this with a grain of salt, I'm not a native speaker

Besides that, there are a few MacOS/Linux specific paths like ~/.config which may be a bit confusing for Windows users that don't know Linux.

Maybe it's a good idea to split the Windows installation instructions into a separate page as @archseer hinted at?
For example, omitting Windows equivalents to the Linux paths may leave people confused. At the same time, having the text littered with (or '%appdata\helix' on Windows) breaks the flow and bloats the instructions, making them harder to follow. Having a separate page would help with this and allows us to have sections that are exclusive to a platform like the XDG desktop shortcuts.

I could also contribute to this if needed.

[David-Else]

@CptPotato Thanks!

some of the wording in section 3. sounds a bit odd to me.

You are right, I was not really happy with that section either and have re-written it.

The new third revision splits the Window and Linux/macOS sections. I don't think a whole new page is needed as they have some things in common, but I hope it will be much clearer now.

Please may I take you up on your offer of contribution? I am not sure what the directory names should be in Windows, I have left them as the Linux ones in the following revision, can you correct it? Also, please can you confirm it is correct overall and Windows users will be happy?

Here is the new version, and then the Markdown code following it. Can you paste in your resulting Markdown using four backticks? Then it keeps the syntax and can be copied.

Building from Source

1. Clone the repository:

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

2. Compile Helix:

cargo install --path helix-term --locked

This command will compile and install the hx binary, and builds the
tree-sitter grammars in the runtime directory.

3. Configure Helix's runtime files

IMPORTANT: The runtime files must be accessible to the newly created binary. They are
currently located in the source code runtime directory. To make them
accessible, you must follow the instructions for your operating system:

Linux and macOS

Either,

1. Set the HELIX_RUNTIME environmental variable on your system to tell Helix
   where to find the runtime files.

   Use the HELIX_RUNTIME=/path/to/helix/runtime format. For example:
   HELIX_RUNTIME=/home/user-name/src/helix/runtime. Add this variable to your
   ~/.bashrc file or equivalent to persist it.

Or,

2. Create a symlink in ~/.config/helix/ that links to the source code
   directory.

ln -s $PWD/runtime ~/.config/helix/runtime

And optionally:

3. 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 ~/.local/share/icons

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

Windows

Either,

1. Set the HELIX_RUNTIME environmental variable on your system to tell Helix
   where to find the runtime files.

   Use the HELIX_RUNTIME=/path/to/helix/runtime format. For example:
   HELIX_RUNTIME=/home/user-name/src/helix/runtime. Add this variable to your
   ~/.bashrc file or equivalent to persist it.

Or,

2. Create a symlink in ~/.config/helix/ that links to the source code
   directory.

Method	Command
PowerShell	New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime"
Cmd	cd %appdata%\helix
	mklink /D runtime "<helix-repo>\runtime"

Note: On Windows creating a symbolic link may require elevated privileges -
i.e. PowerShell or Cmd must be run as administrator.

## Building from Source

1. Clone the repository:

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

2. Compile Helix:

```sh
cargo install --path helix-term --locked
```

This command will compile and install the `hx` binary, and builds the
tree-sitter grammars in the `runtime` directory.

3. Configure Helix's runtime files

**IMPORTANT**:  The runtime files must be accessible to the newly created binary. They are
currently located in the source code `runtime` directory. To make them
accessible, you must follow the instructions for your operating system:

### Linux and macOS

Either,

1. Set the `HELIX_RUNTIME` environmental variable on your system to tell Helix
   where to find the runtime files.

   Use the `HELIX_RUNTIME=/path/to/helix/runtime` format. For example:
   `HELIX_RUNTIME=/home/user-name/src/helix/runtime`. Add this variable to your
   `~/.bashrc` file or equivalent to persist it.

Or,

2. Create a symlink in `~/.config/helix/` that links to the source code
   directory.

`ln -s $PWD/runtime ~/.config/helix/runtime`

And optionally:

3. Configure the Desktop Shortcut

If your desktop environment supports the
[XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html),
you can configure Helix to show up in the application menu by copying the
provided `.desktop` and icon files to their correct folders:

```sh
cp contrib/Helix.desktop ~/.local/share/applications
cp contrib/helix.png ~/.local/share/icons
```

To use another terminal than the system default, you can modify the `.desktop`
file. For example, to use `kitty`:

```sh
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
```

### Windows

Either,

1. Set the `HELIX_RUNTIME` environmental variable on your system to tell Helix
   where to find the runtime files.

   Use the `HELIX_RUNTIME=/path/to/helix/runtime` format. For example:
   `HELIX_RUNTIME=/home/user-name/src/helix/runtime`. Add this variable to your
   `~/.bashrc` file or equivalent to persist it.

Or,

2. Create a symlink in `~/.config/helix/` that links to the source code
   directory.

| Method     | Command                                                                                |
| ---------- | -------------------------------------------------------------------------------------- |
| PowerShell | `New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime"` |
| Cmd        | `cd %appdata%\helix`                                                                   |
|            | `mklink /D runtime "<helix-repo>\runtime"`                                             |

> Note: On Windows creating a symbolic link may require elevated privileges -
> i.e. PowerShell or Cmd must be run as administrator.

[gabydd]

should we also add why people need the runtime files, specifically that it provides support for highlighting and tree-sitter as well as the tutor (once the help stuff is done we can add that here as well)

[gdtroszak]

I think the main clarification that I made to the docs was that if HELIX_RUNTIME is set prior to calling cargo install --path helix-term --locked, the tree-sitter grammars will be built in HELIX_RUNTIME, not the relative runtime directory.

I think that could be captured by changing the last sentence of step 2 to something like:

"This command will compile and install the hx binary, and builds the tree-sitter grammars in the runtime directory OR HELIX_RUNTIME (see below) if set."

[David-Else]

Cheers! I came up with the following based on your input:

This command will create the 'hx' executable and construct the tree-sitter
grammars in the 'runtime' folder, or in the folder specified in 'HELIX_RUNTIME'
(as described below).