Install the Holochain Developer Tools¶
This guide will get you set up with the latest Holochain developer environment on macOS, Linux, and Windows. Right now Holochain is alpha quality and things are moving fast. Expect our APIs and SDKs to change and even break your app if you’re keeping up with the latest changes. If you like tinkering, read our advanced guide.
Hardware Requirements¶
- 4GB+ RAM (16GB+ recommended)
- 4+ CPU (6+ CPU recommended)
- 30GB+ available disk space
- Internet connection
Verify Nix installation¶
After installing Nix, close the terminal and open a new one.
Check that Nix is correctly installed:
nix-shell --version
You should see something like:
nix-shell (Nix) 2.6.0
If you’d like to know more about Nix and why we use it, you can find more information here.
Configure Cachix to use pre-built binaries of Holochain¶
Now that you have installed Nix, you can install and run a development shell that contains all the prerequisites, including the correct Rust and Nodejs versions and the Holochain tools. This shell won’t interfere with your current system configuration.
To significantly speed up the load times for the next step you can make use of our Cachix instance. If you don’t use Cachix, nix-shells will take around 20-30 min for every version of Holochain, depending on your machine’s specifications, because it needs to compile the Holochain binaries.
Run the following commands to set up the cache:
nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-21.11.tar.gz -p cachix --run "cachix use holochain-ci"
Using the Holochain dev tools¶
You can use the Holochain dev tools in two ways, either by creating a nix file which specifies the Holochain version or by using a URL that points to the most recent release. Usually Holochain projects define a specific Holochain version that they’re running on and compatible with, just like Rust crates or NPM packages are included in a project with a particular version. If you want play around with Holochain and the dev tools, you can use the URL with an ad-hoc nix-shell.
Ad-hoc nix-shells with a current version of Holochain dev tools¶
Use this one-liner to load Holonix:
nix-shell https://holochain.love
Once this is finished, you’ll be in the Holonix shell with all the developer tools at your disposal. You will see a new bash prompt that looks like:
[nix-shell:~]$
Test that you have Holochain by running:
holochain --version
You should see something like this:
holochain 0.0.124
Once you exit
the shell you’ll be back to your usual system shell, with all Holochain-specific bits cleaned up.
You can re-enter the Holonix shell with the same command you used initially:
nix-shell https://holochain.love
It will always keep you up to date with the newest stable version of Holochain and the dev tools.
Using Holochain with a pinned Holochain version¶
Holochain is currently in rapid development, which means newer versions introduce new features and breaking changes. This means that it’s likely that the version that you get with nix-shell https://holochain.love
won’t always work with existing hApp repositories or even breaks a hApp you were working on.
To solve this, hApp projects can use Nix to pin a compatible Holochain version. The project needs to have a default.nix
file in the root folder of the repository. Don’t run this from inside the nix-shell
provided by https://holochain.love. Instead, simply navigate to the project’s root folder where the default.nix
file needs to be and run:
nix-shell
This command looks for a default.nix
file in the current folder and will create the specified environment.
Initialize a project for easy Holochain version upgrades¶
If you want to automatically upgrade your project to the most recent version of Holochain, you need to initalize a tool called niv
for your project.
nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-21.11.tar.gz -p niv --run "niv init && niv drop nixpkgs && niv drop niv && niv add -b main holochain/holonix"
⚠️ Run in x86_64 mode on Apple silicon machines ⚠️
Executing this command creates a new folder named nix
with 2 files that niv
needs to retrieve the revision of the latest Holonix version.
Next you need to add a default.nix
file as a Nix configuration of your development environment, including Holochain as a dependency.
This is a minimal default.nix
file with a specific version of Holochain:
let holonixPath = (import ./nix/sources.nix).holonix; # points to the current state of the Holochain repository holonix = import (holonixPath) { holochainVersionId = "v0_0_124"; # specifies the Holochain version }; nixpkgs = holonix.pkgs; in nixpkgs.mkShell { inputsFrom = [ holonix.main ]; packages = with nixpkgs; [ niv # any additional packages needed for this project, e. g. Nodejs ]; }
Now you can enter the Nix shell with your development environment by running the command nix-shell
. Once it’s finished you have the Holochain commands at your disposal.
niv initializes and updates to the latest revision of the Holonix repository. As every revision contains configurations for several previous versions of Holochain, you need to explicitly define the exact version of Holochain you want to use. In other words, niv does not set a Holochain version; it’s defined in
default.nix
.
Upgrading the Holochain version¶
⚠️ Run in x86_64 mode on Apple silicon machines ⚠️
When the time has come to upgrade your hApp to a newer version of Holochain, there are 3 steps to follow:
-
Update the Holonix revision using
niv
:nix-shell --run "niv update"
-
Run
hn-versions
to see which versions of Holochain are available:nix-shell --run "hn-versions"
-
Set the
holochainVersionId
accordingly:... holonix = import (holonixPath) { holochainVersionId = "v0_0_127"; }; ...
The next time you enter your hApp development environment using nix-shell
, the updated version of Holochain will be downloaded and made available in the resulting Nix shell.
Keep in mind that the Holonix repo includes Nix configurations for the last ~ 5 versions of Holochain. That means that if you keep updating its revision using
niv
, you will have to augment the Holochain version id indefault.nix
sooner or later too.
Holochain inspection commands¶
Built into Holochain and holonix are a few commands that give insight about versions of Holochain components.
hn-introspect
This command displays versioning information about Holochain’s main components as well as Rust and Cargo. The output looks like this:
List of applications and their version information v0_0_131 - hc-0.0.32-dev.0: https://github.com/holochain/holochain/tree/holochain-0.0.131 - holochain-0.0.131: https://github.com/holochain/holochain/tree/holochain-0.0.131 - kitsune-p2p-tx2-proxy-0.0.21: https://github.com/holochain/holochain/tree/holochain-0.0.131 - lair-keystore-0.0.9: https://github.com/holochain/lair/tree/v0.0.9 - rustc: rustc 1.58.1 (db9d1b20b 2022-01-20) - cargo fmt: rustfmt 1.4.38-stable (db9d1b20 2022-01-20) - cargo clippy: clippy 0.1.58 (db9d1b20 2022-01-20)
Another Holochain command that inspects the platform information and outputs the compatible HDK version is
holochain --build-info
A sample output of this command looks like this (JSON formmatted using jq
):
{ "git_info": null, "cargo_pkg_version": "0.0.131", "hdk_version_req": "0.0.126", "timestamp": "2022-04-10T05:55:04.525835Z", "hostname": "Mac-1649560170558.local", "host": "x86_64-apple-darwin", "target": "x86_64-apple-darwin", "rustc_version": "rustc 1.58.1 (db9d1b20b 2022-01-20)", "rustflags": "", "profile": "release" }
Advanced installation guide¶
Read through our advanced installation guide for tips and tricks on making your development environment easier to work with, or what to do in case you need to work offline.
Next Steps¶
- Read through the Holochain Core Concepts.
- Try building and running a sample hApp.
- Scaffold your own hApp using our RAD tool.
- Learn Holochain development interactively with community-created Learning Resources.
- Learn more about Rust in the Rust book.
- Take a look at the developer documentation.
- Join the discussion at the developers’ forum.