Unnamed repository; edit this file 'description' to name the repository.
Diffstat (limited to 'book/src/install.md')
| -rw-r--r-- | book/src/install.md | 175 |
1 files changed, 159 insertions, 16 deletions
diff --git a/book/src/install.md b/book/src/install.md index 021feceb..44f13584 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -1,24 +1,167 @@ -# Installing Helix +# Installation -The typical way to install Helix is via [your operating system's package manager](./package-managers.md). +We provide pre-built binaries on the [GitHub Releases page](https://github.com/helix-editor/helix/releases). -Note that: +[](https://repology.org/project/helix/versions) -- To get the latest nightly version of Helix, you need to - [build from source](./building-from-source.md). +## OSX -- To take full advantage of Helix, install the language servers for your - preferred programming languages. See the - [wiki](https://github.com/helix-editor/helix/wiki/Language-Server-Configurations) - for instructions. +Helix is available in homebrew-core: -## Pre-built binaries +``` +brew install helix +``` -Download pre-built binaries from the [GitHub Releases page](https://github.com/helix-editor/helix/releases). -The tarball contents include an `hx` binary and a `runtime` directory. -To set up Helix: +## Linux -1. Add the `hx` binary to your system's `$PATH` to allow it to be used from the command line. -2. Copy the `runtime` directory to a location that `hx` searches for runtime files. A typical location on Linux/macOS is `~/.config/helix/runtime`. +### NixOS -To see the runtime directories that `hx` searches, run `hx --health`. If necessary, you can override the default runtime location by setting the `HELIX_RUNTIME` environment variable. +A [flake](https://nixos.wiki/wiki/Flakes) containing the package is available in +the project root. The flake can also be used to spin up a reproducible development +shell for working on Helix with `nix develop`. + +Flake outputs are cached for each push to master using +[Cachix](https://www.cachix.org/). The flake is configured to +automatically make use of this cache assuming the user accepts +the new settings on first use. + +If you are using a version of Nix without flakes enabled you can +[install Cachix cli](https://docs.cachix.org/installation); `cachix use helix` will +configure Nix to use cached outputs when possible. + +### Arch Linux + +Releases are available in the `community` repository. + +A [helix-git](https://aur.archlinux.org/packages/helix-git/) package is also available on the AUR, which builds the master branch. + +### Fedora Linux + +You can install the COPR package for Helix via + +``` +sudo dnf copr enable varlad/helix +sudo dnf install helix +``` + +### Void Linux + +``` +sudo xbps-install helix +``` + +## Windows + +Helix can be installed using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/) +or [MSYS2](https://msys2.org/). + +**Scoop:** + +``` +scoop install helix +``` + +**Chocolatey:** + +``` +choco install helix +``` + +**MSYS2:** + +``` +pacman -S mingw-w64-i686-helix +``` + +or + +``` +pacman -S mingw-w64-x86_64-helix +``` + +or + +``` +pacman -S mingw-w64-ucrt-x86_64-helix +``` + +## Build from source + +``` +git clone https://github.com/helix-editor/helix +cd helix +cargo install --path helix-term +``` + +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:** + +```powershell +New-Item -ItemType SymbolicLink -Target "runtime" -Path "$Env:AppData\helix\runtime" +``` + +**Cmd:** + +```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`, +> 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](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html), including Gnome and KDE, copy the provided `.desktop` file to the correct folder: + +```bash +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`: + +```bash +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 +``` + +Please note: there is no icon for Helix yet, so the system default will be used. + +## Finishing up the installation + +To make sure everything is set up as expected you should finally run the helix healthcheck via + +``` +hx --health +``` + +For more information on the information displayed in the health check results refer to [Healthcheck](https://github.com/helix-editor/helix/wiki/Healthcheck). + +### 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). + +### Installing language servers + +Language servers can optionally be installed if you want their features (auto-complete, diagnostics etc.). +Follow the [instructions on the wiki page](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers) to add your language servers of choice. |