How to build Holochain DNA

as of 2021-03-21

Important documentation

Steps

0. Install nix-shell

If you haven't yet, install the nix-shell.

Note that you don't need to do the nix-shell https://holochain.love step, since in this repository we provide an example default.nix file that provides the appropriate versions for the binaries that you will need.

Enter the nix-shell for this repository by running nix-shell . in this folder. This will take a long time in the first run.
- Verify everything is working fine with holochain -V and hc -V.

1. Write your Zomes

Each zome is a Rust crate. See zomes/whoami and zomes/foo for examples.

2. Build your Zomes into Wasm

When you want to (re)build your zomes into Wasm, simply run

CARGO_TARGET_DIR=target cargo build --release --target wasm32-unknown-unknown

and they will be available in target/wasm32-unknown-unknown/release/

3. Package your Wasms into a DNA file

Create a new dna workdir with hc dna init <DNA_FOLDER>.

This will create a dna.yaml in it with the necessary initial configuration.

Add your zomes to the dna.yaml file with references the *.wasm files you built in the previous step (see workdir/dna/dna.yaml for examples).
Run the following command to package your Wasms into a DNA file per your dna.yaml:

hc dna pack workdir/dna

This will produce a demo.dna file as a sibling of the workdir/dna directory.

4. Package your DNAs into a happ file

hApps (holochain apps) are bundled as aggregations of different DNAs.

Create a new happ workdir with hc app init <HAPP_FOLDER>.

This will create a happ.yaml in it with the necessary initial configuration.

Add the DNA bundle created in the previous step to the new happ.yaml file (see workdir/happ/happ.yaml for an example).
Run the following command to package your DNAs into a happ bundle per your happ.yaml:

hc app pack workdir/happ

This will produce a demo-happ.happ file as a sibling of the workdir/happ directory.

4. Testing

To run the tryorama tests, execute this commands:

cd tests
npm install
npm test

This will output something similar to this:

11:00:17 info:
☸☸☸ [[[CONDUCTOR c0]]]
☸ Conductor ready.
☸
11:00:17 [tryorama] info: Conductor 'c0' process spawning completed.
App Port spun up on port  46587
ok 1 should be strictly equal
11:00:20 [tryorama] info: conductor 'c0' exited with code null
FIXME: ignoring onLeave

1..1
# tests 1
# pass  1

# ok

You can look at tests/src/index.ts and have a look at the tests. You can also look at the tryorama documentation.

5. Running your happ

To run the happ bundle directly, execute this command replacing workdir/happ for the directory in which you have you *.happ file:

hc sandbox generate workdir/happ --run=8888

which should yield something similar to this:

hc-sandbox: Created config at /tmp/tmp.2Vg2Ml2jO6/io6SQmBmBRX3oBroT0YkG/conductor-config.yaml

Conductor ready.
hc-sandbox: Created ["/tmp/tmp.2Vg2Ml2jO6/io6SQmBmBRX3oBroT0YkG"]

Conductor ready.
hc-sandbox: Running conductor on admin port 45843
hc-sandbox: Attaching app port 8888
hc-sandbox: App port attached at 8888
hc-sandbox: Connected successfully to a running holochain

Now you'll have holochain waiting for a connection at port 8888. You can connect to it with a UI or any other process.

You can look at the documentation of hc sandbox to learn more on how to manage sandboxes.

Note: notice that hc sandbox and its derivates are at a prototype stage and subject to change.

Next steps

Here you have useful documentation for holochain core utilities:

Here you can find useful resources:

Holochain Gym: a step-by-step collection of exercises to get you started in holochain development.
Acorn: the most complete holochain application up-to-date, full-stack.
Holochain Open Dev: collection of small holochain modules.
RSM playtime: deep dive video series on holochain rsm.

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

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

harlantwood / holochain-dna-build-tutorial