Advanced installation guide, tips and tricks¶
This guide assumes that you’ve already followed the quick installation guide and want something more. It describes how to make it faster to get into the Holonix shell, explains how to install more or less stable versions of Holochain, and discusses why we use nix-shell in the first place.
Getting into Holonix faster and easier¶
You might find it tedious to try to remember the command that gets you back into the Holonix development shell.
nix-shell ~/.holonix/shellDrv isn’t that intuitive, and when you’re trying to open multiple terminals at a time for testing purposes it could get annoying.
To save keystrokes, add an alias to your shell config:
echo 'alias holonix=\'nix-shell ~/.holonix/shellDrv\' >> ~/.bashrc holonix
Close your terminal window, open it again, and you should be able to type
holonix from now on to get into the shell.
Using your favorite text editor or IDE¶
In most cases you can run your editor as normal. However, if you are using a text editor or integrated development environment (IDE) that needs to communicate with the Rust compiler for real-time syntax checks, then you should launch it from inside the nix-shell. This is because Holonix comes with its own version of Rust that might be different from what you may already have installed.
To do this, just open your editor from the command line while you are in the nix-shell (this example uses Vim):
nix-shell ~/.holonix/shellDrv cd my_project vim my_file.rs
Any time you want to get the latest version of the dev tools, you can follow the install procedure again and it’ll update you.
The faster and easier method¶
Once again, this is a hard command to remember, so you might want to add an alias for it as well:
Linux (or Windows 10 with WSL2)¶
echo 'alias holonix-update=\'$(nix-build https://holochain.love --no-link -A pkgs.holonix)/bin/holonix\'' >> ~/.bashrc holonix-update
echo 'alias holonix-update=\'HN_NOSUDO=true $(nix-build https://holochain.love --no-link -A pkgs.holonix)/bin/holonix\'' >> ~/.bashrc holonix-update
Staying up to date all the time¶
There’s a trick you can use to keep yourself up to date with the newest release of all the Holochain tools. It takes a bit longer whenever there’s something new, though, because it has to compile everything from source.
Every time you want to enter the Holonix development environment, use this command:
You usually don’t need to uninstall anything, because
nix-shell leaves your familiar user environment alone and makes all of its own changes disappear once you exit the shell. But it does keep binaries on your device. If you want to free up some space, run these commands:
rm -rf ~/.holonix nix-collect-garbage -d
If you want to uninstall Nix as well, run these commands (you might need root privileges for the first line):
rm -rf /nix rm ~/.nix-profile
Using a specific version of the development tools¶
Sometimes you might want to target a specific version of Holochain — for instance, when you’re working on an application that was compiled with an older version of the HDK that’s incompatible with the version of Holochain you have installed. This is where Nix really shines: you can set up an environment containing all the tools that target the older version while leaving your current installation alone. Simply find the release tag of the version of Holochain you’re looking for (we don’t yet have release tags, but that will change soon) and enter this command in your project’s working folder:
Note that Nix will have to compile all the binaries from source, so it’ll take a long time. You’ll also have to enter this same command every time you want that specific version (although it won’t have to recompile on next run).
Keeping everything local¶
If you find yourself needing to switch versions often, a faster method is to clone the Holochain repository, check out the release you want, and enter the nix shell from there:
git clone firstname.lastname@example.org:holochain/holochain.git cd holochain git checkout <tag> nix-shell
Once you’re in the shell, you can navigate to your project’s working folder. This way you have all the versions of Holochain available to you locally and don’t need to remember long URLs.
More info on Nix¶
We use the Nix/NixOS toolkit to build consistent development, testing, and deployment environments for Holochain Core and apps. It consists of two systems:
- NixOS, a tool for reliably building Linux-based systems from a set of configuration files (we use NixOS in our HoloPorts and automated testing VMs)
- Nix, a package manager that works on many OSes and uses the same configuration file format as NixOS
The main components of the tooling for Holochain development are:
- The Rust programming language
- Node.JS and npm
- Cryptographic libraries
- Common automations and scripts
It is important that these remain consistent, so you can get your work done without fighting package and compiler issues. And when it comes time to compile and distribute your application, it’s very important to have a deterministic build system so the same DNA source code always results in the same hash.
The main Nix tool used in Holochain development workflows is
nix-shell, a managed Bash shell that overlays a new environment and set of tools on top of your existing environment.
The full suite of Nix tooling is broad and deep. There’s even a dedicated programming language. Learn more with the NixOS Wiki or the Pills Tutorial. The community IRC chat at
#nixos on freenode is active and helpful.
While working on Holochain, you will usually have an active
nix-shell to run commands. This shell overlays Holochain-specific configuration on top of your existing shell—environment variables, Rust toolchains, binaries, libraries, and development tools—giving you a consistent development environment to build Holochain apps. All this setup will be cleaned up automatically when you close the shell.
If you want to re-enter the shell to do more work, or create multiple terminals to work in, you’ll need to re-enter the
nix-shell. The packages are built and cached locally on your machine, so they will not be rebuilt the next time you enter the shell. You do need to get the package configuration files from somewhere, though. If you use our quick install guide or the Holochain repo cloning method, they’re cached on your machine, but the ‘staying up to date all the time’ and ‘using a specific version’ methods require an internet connection every time you want to enter the shell.