Skip to main content

Setup

This section explains how to get Hydroflow running, either for development or usage, even if you are not familiar with Rust development.

Installing Rust​

First you will need to install Rust. We recommend the conventional installation method, rustup, which allows you to easily manage and update Rust versions.

Install Rust

The link in the previous line will take you to the Rust website that shows you how to install rustup and the Rust package manager cargo (and the internally-used rustc compiler). cargo is Rust's main development tool, used for building, running, and testing Rust code.

The following cargo commands will come in handy:

  • cargo check --all-targets - Checks the workspace for any compile-time errors.
  • cargo build --all-targets - Builds all projects/tests/benchmarks/examples in the workspace.
  • cargo clean - Cleans the build cache, sometimes needed if the build is acting up.
  • cargo test - Runs tests in the workspace.
  • cargo run -p hydroflow --example <example name> - Run an example program in hydroflow/examples.

To learn Rust see the official Learn Rust page. Here are some good resources:

In this book we will be using the Hydroflow template generator, which we recommend as a starting point for your Hydroflow projects. For this purpose you will need to install the cargo-generate tool:

cargo install cargo-generate

VS Code Setup​

We recommend using VS Code with the rust-analyzer extension (and NOT the Rust extension).

Setting up a Hydroflow Project​

The easiest way to get started with Hydroflow is to begin with a template project. Create a directory where you'd like to put that project, direct your terminal there and run:

cargo generate gh:hydro-project/hydroflow template/hydroflow

You will be prompted to name your project. The cargo generate command will create a subdirectory with the relevant files and folders.

cd into the generated folder, ensure the correct nightly version of rust is installed:

cd <my-project>
rustup update

As part of generating the project, the hydroflow library will be downloaded as a dependency. You can then open the project in VS Code or IDE of your choice, or you can simply build the template project with cargo build.

cargo build

This should return successfully.

The template provides a simple working example of a Hydroflow program. As a sort of "hello, world" of distributed systems, it implements an "echo server" that simply echoes back the messages you sent it; it also implements a client to test the server. We will replace the code in that example with our own, but it's a good idea to run it first to make sure everything is working.

note

We call a running Hydroflow binary a transducer.

Start by running a transducer for the server:

cargo run -- --role server
Listening on 127.0.0.1:<port>
Server live!

Take note of the server's port number, and in a separate terminal, start a client transducer:

cd <project name>
cargo run -- --role client --address 127.0.0.1:<port>
Listening on 127.0.0.1:<client_port>
Connecting to server at 127.0.0.1:<port>
Client live!

Now you can type strings in the client, which are sent to the server, echo'ed back, and printed at the client. E.g.:

Hello!
2023-06-01 00:19:53.906635 UTC: Got Echo { payload: "Hello!", ts: 2023-06-01T00:19:53.906123Z } from 127.0.0.1:61019

Alternative: Checking out the Hydroflow Repository​

This book will assume you are using the template project, but some Rust experts may want to get started with Hydroflow by cloning and working in the repository directly. You should fork the repository if you want to push your changes.

To clone the repo, run:

git clone [email protected]:hydro-project/hydroflow.git

Hydroflow requires nightly Rust, but the repo is already configured for it via rust-toolchain.toml.

You can then open the repo in VS Code or IDE of your choice. In VS Code, rust-analyzer will provide inline type and error messages, code completion, etc.

To work with the repository, it's best to start with an "example", found in the hydroflow/examples folder. The simplest example is the 'hello world' example; the simplest example with networking is the echo server.

The Hydroflow repository is set up as a workspace, i.e. a repo containing a bunch of separate packages, hydroflow is just the main one. So if you want to work in a proper separate cargo package, you can create one and add it into the root Cargo.toml, much like the provided template.