Quick Start

Last updated: May 21, 2019
Version: v0.0.16-alpha1

Overview

Welcome to the Quick Start guide for getting started with Holochain development. It will guide you through installation. Once you've got things installed, or regardless, read on into a tutorial, the Holochain guidebook, and the API Reference to get going!

Please note that previously the networking component "n3h" had to be installed separately. It will now be dowloaded and setup automatically by Holochain.

If you find an issue with the instructions, please open an issue on the GitHub repo for the documentation site.

If you believe you've found an issue with Holochain, please open an issue on the GitHub repo for Holochain Rust core.

If you need general assistance, post all the relevant details on StackOverflow then post a link to it in the developer community chat.

Development Tools Installation

If you wish to develop Holochain DNAs, you will want to install the Holochain developer command line tools.

Step One: Fetch and Setup the Dev Tools Binary

When you go to Github, look for one of the downloads that starts with "cli". Go to GitHub and download the appropriate release for your system.

Once you've downloaded it, unpack it, RENAME it "hc" and move the resulting folder to a directory on your computer where you'd like to keep these files long term. As a default, lets assume that it can be this folder called "hc", right under your $HOME or %USERPROFILE% (your user) directory. Now we will have to add this directory to your PATH variable, so that the binary becomes available within your command line. The instructions for this differ, depending on your platform. If you need help with this, read the relevant Help with PATHs section at the bottom of this page.

To confirm that you have them installed, try running the following command, which should result in it printing the version of the tools that you downloaded:

hc --version

Congratulations!

Note that you've installed the minimum necessary to start developing with Holochain. You have enough installed to generate a new Holochain project from scratch! To do additional things with it, you will need to make sure you have the additional dependencies mentioned below. Relevant feedback will also be given through the use of the commands, so don't be afraid to try things out.

Step Two: Getting Started

As a next step, try running the following command to familiarize with the tools:

hc help

To generate your first Holochain project folder, run:

hc init my_first_app

In the new "my_first_app" folder is the basic structure of a new Holochain project, congratulations! Open it up in a file browser or text editor to start to check it out.

To get started beyond this, you will need to jump ahead to the code generation prerequisite and follow those instructions, diving a layer deeper into Holochain development.

Once you've completed that, you will be able to generate a new "Zome", the basic module format for Holochain. To try it, make sure your terminal is set to the directory of "my_first_app" and then run:

hc generate zomes/my_zome

This will add some starter code into the "zomes/my_zome" sub folder, which you can open up in a text editor and start checking out! That's the quick start. To go further, you may want to check out a tutorial, and the Guidebook.

To read about the rest of the commands, and how to get started using them, check out the README for the "hc" command line tools.

Prerequisite for Packaging and Generating

If you are generating new Zomes, developing new code, or wish to "package" code that someone else wrote, you will need to install Rust. To "package" the code means to compile or build all the source code into WebAssembly from its native language, and then aggregate it into a Holochain "DNA" file. This can be read about further in the Guidebook.

Commands that invoke the Rust dependencies include hc generate, hc test, hc run --package, and hc package. Use of any of these commands will require Rust to be installed. Other commands can be run without the installation of Rust.

The recommended way to write Holochain applications is to use the "Holochain Development Kit" (HDK).

The HDK allows generation of low level web assembly (WASM) code with convenience functions written in the high level Rust language.

In the future there will be HDKs written to a variety of languages, but for now you will need to install and maybe learn some Rust.

We are using a "nightly" release of the Rust langauge.
The Rust community moves very quickly so we "pin" to a specific version to ensure a relatively stable working environment.
Only the pinned nightly version of Rust is compatible with Holochain

For installation follow:

Add WebAssembly Support

Since Holochain code needs to be in WebAssembly, the Rust compilation "target" for WebAssembly is required. This just means that the Rust toolchain knows how to compile Rust code to WebAssembly. You will likely need to restart your terminal, or open a new one, before being able to run the following command. In a terminal, run:

rustup target add wasm32-unknown-unknown

Prerequisite for Testing

End-to-end testing of Holochain apps is done in Javascript executed by Nodejs. The command to run these tests is hc test.
If you want to use hc test you will need to have nodejs installed.

Holochain supports nodejs versions in the 8, 10, and 11 ranges

To check the currently installed node version run:

node -v

If you don't have a supported nodejs version you can find installation instructions at https://nodejs.org.

Production Tools Installation

If you wish to have a way to run Holochain apps, beyond the simple way available in the development tools, you can do that with the Holochain Conductor, which is capable of mounting configuration files that start up Holochain DNA instances.

Step One

When you go to Github, look for one of the downloads that starts with "conductor". Go to GitHub and download the appropriate release for your system.

Once you've downloaded it, unpack it, RENAME it "holochain" and move the resulting folder to a directory on your computer where you'd like to keep these files long term. As a default, lets assume that it can be this folder called "holochain", right under your $HOME or %USERPROFILE% (your user) directory. Now we will have to add this directory to your PATH variable, so that the binary becomes available within your command line. The instructions for this differ, depending on your platform. If you need help with this, read the relevant Help with PATHs section at the bottom of this page.

Step Two

To confirm that you have the Holochain Conductor installed, try running the following command:

holochain --version

To read about the Conductor, and how to get started using it, check out this section of the Guidebook.

Help With PATHs