Skip to content

Latest commit

 

History

History
130 lines (102 loc) · 4.3 KB

CONTRIBUTING.md

File metadata and controls

130 lines (102 loc) · 4.3 KB
Raw

Contributing to Horust

Thanks for considering contributing to Horust!

Github Issue are a good place for getting started. You can also search the code for TODOs.

We should use issues to track things to do. Thus every PR should fix one or more issues. So even if you want to fix a TODO, please create an issue first. In this way it's easier to keep track of who's working on what.

Development environment

In order to start hacking on Horust, you will need to install Rust (1.42.0). By using rustup, you will also automatically install cargo and other needed tools.

You can run horust with debug logs by using:

HORUST_LOG=debug cargo run

Passing arguments to horust via cargo:

HORUST_LOG=debug cargo run -- --sample-service

Run Horust in single command mode:

HORUST_LOG=debug cargo run -- -- /bin/bash

For PRs:

Before almost every commit, you might want to check your fmt:

cargo fmt

Clippy for lints:

cargo clippy

And run tests:

cargo test

If you want to run integration tests only:

cargo test --package horust --test horust -- --exact

There is also a make file, at the moment used mainly for docker:

# build a container without the http feature:
make build-nofeature
# run the built image
make run
# print an help:
make help

Local development using a container

If you'd like to skip all the bells and whistles of setting up the project, you can get up and running quickly using an "All-In-One" Docker container. It's a wrapper around Horust that enables you to compile it and all of its dependencies, and then work off the container instead of compiling locally.

The Makefile contains a set of commands intended to scaffold an AIO container from scratch.

Just run make dargo COMMAND=X, where X is any valid cargo command, inside the project's root folder. If this is the first time you run the command, it will:

  1. Create a Docker image with a pre-determined working directory
  2. Run an (interactive / long-running) container off that image, with the local Horust project folder bind-mounted to the working directory
  3. Run cargo X inside the container

When the Makefile target finishes, you will have a running container on your machine that you can compile Horust in. That container allows you to take advantage of rustc's incremental compilation, without compiling locally.

If it's not the first time you run the command, it will just run cargo X inside the container.

If you'd like to go for maximum ergonomics, run the following command (swapping ~/.bashrc for ~/.zshrc or wherever you keep your shell stuff):

echo 'dargo(){ make dargo COMMAND=$1}' >> ~/.bashrc
source ~/.bashrc

This will now enable you to run dargo X instead of make dargo COMMAND=X, to get a more cargo-like feel while using the container. Try running dargo check to see how if feels!

Container-based development example

Just to make sure everything is clear, let's run a step-by-step mini tutorial on developing in container-based workflow "mode":

  1. Clone the repo to your local machine:
git clone https://github.com/FedericoPonzi/Horust.git`
cd Horust
  1. Make some changes to a source file.
  2. Run the following to create the AIO container and then test your changes:
make dargo COMMAND=test

Useful Links:

Just a small collection of useful links:

Random init systems:

Useful man pages:

  • man runlevel
  • man 8 init
  • man getty