Holochain

License:

This repository contains the core Holochain libraries and binaries.

This is the most recent and well maintained version of Holochain with a refactored state model (you may see references to it as Holochain RSM).

Code Status

This code is in alpha. It is not for production use. The code is guaranteed NOT secure.

We will be frequently and heavily restructuring code APIs and data chains until Beta.

We are currently only supporting Linux at this time. You may or may not be able to successfully build and run Holochain on macOS or Windows. We will definitely be rolling out support for these OSes in the future, but in the meantime please use Linux for development!

Making the Holochain binaries available in your shell

There are a number of contexts and purposes you might be running in which yield different ways to access binaries.

Using nix-shell on a local clone

Assuming you have installed the nix shell:

nix-shell --argstr flavor happDev

This nix-shell flavor installs wrapper binaries for holochain and hc that will automatically compile and run the binaries. This is very useful if you are tracking changes in the holochain repo because when you check out a new rev, running holochain will compile automatically to the version at that rev.

Building with a pre-installed cargo

Another way to install the holochain and hc binaries (if the previous didn't work) is by using rust

Install Rust

Install holochain binaries:

cargo install --path crates/holochain
cargo install --path crates/hc

be sure to add $HOME/.cargo/bin to your PATH to be able to run the installed binaries

Usage

$ holochain --help
USAGE:
    holochain [FLAGS] [OPTIONS]

FLAGS:
    -h, --help           Prints help information
    -i, --interactive    Receive helpful prompts to create missing files and directories,
                             useful when running a conductor for the first time
    -V, --version        Prints version information

OPTIONS:
    -c, --config-path <config-path>
            Path to a YAML file containing conductor configuration

Running holochain requires a config file. You can generate one in the default configuration file locations using interactive mode:

$ holochain -i
There is no conductor config YAML file at the path specified (/home/eric/.config/holochain/conductor-config.yml)
Would you like to create a default config file at this location? [Y/n]
Y
Conductor config written.
There is no database set at the path specified (/home/eric/.local/share/holochain/databases)
Would you like to create one now? [Y/n]
Y
Database created.
Conductor ready.

As well as creating the config file this process also instantiates the database. If you provide a config file on first run with just the -c flag holochain will also initialize the environment even if not in interactive mode.

Documentation for Application Developers

Environment for Development on this Project

Assuming you have installed the nix shell:

git clone git@github.com:holochain/holochain.git
cd holochain
nix-shell
hc-merge-test

This will compile holochain and run all the tests.

If you get an error while running nix-shell about ngrok having an unfree license, you can fix that by running,

mkdir -p ~/.config/nixpkgs/
echo "{ allowUnfree = true; }" >> ~/.config/nixpkgs/config.nix

We have an all-in-one development environment including (among other things):

The correct version and sane environment variables of cargo/rust
Node for working with tryorama
Scaffolding, build and deployment scripts
Prebuilt binaries of core for various operating systems (soon)
Shared libs such as libsodium

It is called Holonix and you should use it.

It has plenty of documentation and functionality and can be used across Windows, Mac, and Linux. (Although Holochain itself currently only supports Linux.) It is based on the development tools provided by NixOS.

It is suitable for use in hackathons and 'serious' development for a long-term, production grade development team.

If you want to maintain your own development environment then we can only offer rough advice, because anything we say today could be out of date tomorrow:

Use a recent stable version of rust
Use node 12x+ for clientside work
Install any relevant shared libs like libsodium
Write your own scaffolding, build and development tools
Plan for dependency management as we ship new binaries

Advanced nix-shell usage

Custom rust version

The shell function in this repository takes a rustVersion argument that works in the following way:

$ nix-shell --arg rustVersion '{ track = "nightly"; version = "2021-07-01"; }' --run "rustc --version"
Using /home/steveej/src/holo/holochain as target prefix...
rustc 1.55.0-nightly (868c702d0 2021-06-30)

Additional Documentation

Build the holochain docs:

cargo doc --manifest-path=crates/holochain/Cargo.toml --open

Contribute

Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our contributing guidelines for our general practices and protocols on participating in the community, as well as specific expectations around things like code formatting, testing practices, continuous integration, etc.

Connect with us on our forum

License

This program is free software: you can redistribute it and/or modify it under the terms of the license provided in the LICENSE file (CAL-1.0). This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

mhuesch / holochain