This is the home of the Holochain Rust libraries, being rewritten from Go into Rust, and extended.

Code Status: Rust version is currently Pre-Alpha. Not for production use. The code has not yet undergone a security audit. We expect to destructively restructure code APIs and data chains until Beta. Prototype go version was unveiled at our first hackathon (March 2017), with go version Alpha 0 released October 2017. Alpha 1 was released May 2018. We expect a developer pre-release of this Rust re-write in mid October 2018.

This holochain-rust repository implements three distinct yet overlapping aspects of the Holochain framework.

1. The core Holochain functionality that executes applications
2. A wrapper used to instantiate, manage, and run applications
3. A library and syntax for use in Rust based development of Zomes within applications

Let's elaborate on these three aspects.

The core folder contains the code that implements the core functionality of Holochain. It is the aspect that takes in an application DNA, and an agent, and securely runs peer-to-peer applications by exposing the API functions to Zomes. It draws on other top level definitions and functions such as dna, cas_implementations, agent, and core_types.

The first aspect only implements the logic for the execution of a single application. Meanwhile, there is a strong need to be able to load and instantiate multiple applications, and possibly even multiple instances of the same application. The core_api folder contains the code that implements this capability. Even then, this code must be employed within some other context to actually run it. Such a thing is called a Holochain "container".

A container is a Holochain utility or service that manages and runs Holochain applications. The first such containers are the GUI driven holosqape and the CLI driven hcshell container for test running.

To implement a Rust based container, one could use the Rust crate exposed in core_api. To implement a container in a C based language, the core_api_c_binding code could be used, such as HoloSqape does.

Holochain applications have been designed to consist at the low-level of WebAssembly (WASM) running in a virtual machine environment. However, most languages will be easiest to use with some stub code to connect into the WASM runtime environment, because of some constraints with WASM. That is the main reason why a "Developer Kit" for a language exists. It is a library, and a syntax, for writing Zome code in that language.

hdk-rust is a solid reference implementation of this, that enables Zomes to be written in the Rust language (the same, somewhat confusingly, as Holochain Core).

Within this repository, some aspects cross over between core and hdk-rust, such as core_types, since they get stored into WASM memory in core, and then loaded from WASM memory, within hdk-rust. Related, wasm_utils is used on both sides to actually perform the storing, and loading, of values into and from WASM memory.

Any language that compiles to WASM and can serialize/deserialize JSON data can be available as an option for programmers to write Holochain applications.

An HDK for Assemblyscript is under experimental development at hdk-assemblyscript.

We expect many more languages to be added by the community, and there is even an article on how to write a kit for a new language.

There is a work-in-progress book of documentation being written about holochain-rust. See the published version at the associated GitHub Pages for this repo, https://holochain.github.io/holochain-rust. See instructions for how to contribute to the book at doc/holochain_101/src/how_to_contribute.md.

Please note that this repository, with its installation instructions, is not useful to install if you fall into one of the following two categories:

If you are developing Holochain applications, you will want to instead install both:

• the hc command line tool
• the hcshell test runner These will help create and test Holochain DNA packages suitable for running in a Holochain service. You may also wish to look into the hdk-rust folder within this repository, to read on about the use of the HDK for Zome development.

If you are a Holochain end-user, either you will install DNA packages into a Holochain hApp's service like HoloSqape, or your application will come with them built in.

The following instructions are for Holochain Core & HDK Developers Only

There are two approaches to building and testing Holochain, using make or using docker:

If you are running on ubuntu or macOS, and you have make installed, you can do local development by simply typing:

make which will:

1. install (or update to) the correct version of rust
2. build all the rust libraries from the source code in this repository.

However, we mostly use docker because it's easier to count on things working the expected way across platforms.

The docker folder contains scripts to build and run docker images.

Run:

. docker/run-test

There is a linter/formatter enforcing code style.

Run:

. docker/run-fmt

The continuous integration (CI) suite executes the same . docker/run-test command that developers are encouraged to run.

What happens if I need to change that environment? E.g. what if I need a new system library dependency installed?

• Step 1 - Add the dependency to docker/Dockerfile.ubuntu

RUN apt-get update && apt-get install --yes\
  # ... snip ...
  my-new-lib-here

• Step 2 - Build it

. docker/build-ubuntu

• Step 3 - Test it out

. docker/run-test

• Step 4 - Wait a minute! The CI environment is still using the old Dockerfile!

If your changes do not break the current environment, you can submit a separate Pull Request first, and once it is merged, the CI environment should be up-to-date for your code change Pull Request.

Otherwise, you will need to speak to an admin who can force merge your full changes after testing locally.

Note there is an article written on how to build Holochain for Android, read it here.

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.

In adding significant changes and new features to Holochain, we follow a specific test-driven development protocol:

1. Start by creating a branch in the app-spec-rust repository which demonstrates an actual implementation of the use of the new feature in the sample application that lives in that repository, including tests that would pass if the feature were actually implemented here in the holochain-rust repo.
2. Create a pull request on that branch for the development team to talk about and discuss the suggested change. The PR triggers Continuous Integration tests which will initially fail, because they try and run the proposed changes against the develop branch of this holochain-rust repo.
3. Do any development necessary in the holochain-rust repo to implement the feature demonstrated in app-spec-rust
4. Finally, when the feature is fully implemented, the CI tests should turn green on app-spec-rust and the branch can be merged. This merge in app-spec-rust of the feature branch completes the test-driven development loop.

In this way app-spec-rust works as a living specification with example app to build against.

Some helpful links:

• View our Kanban on Waffle
• Chat with us on our Chat Server or Gitter

Current Throughput graph:

Copyright (C) 2018, Holochain Trust

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

Note: We are considering other 'looser' licensing options (like MIT license) but at this stage are using GPL while we're getting the matter sorted out. See this article for some of our thinking on licensing for distributed application frameworks.