From 45ac8e0cbc1c8a21c6b942ab665513c5e043ccb5 Mon Sep 17 00:00:00 2001 From: Tobias Pflug Date: Thu, 14 May 2020 12:53:01 +0200 Subject: [PATCH] README.md: info about runHydra/foreman Add sections about using `runHydra` and `foreman` --- README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/README.md b/README.md index c4a40de9..113254b7 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,7 @@ Make sure **State** at the top of the page is set to "_Enabled_" and click on "_ ### Building Hydra You can build Hydra via `nix-build` using the provided [default.nix](./default.nix): + ``` $ nix-build ``` @@ -84,6 +85,44 @@ $ configurePhase # NOTE: not ./configure $ make ``` +### Development Workflow + +When working on new features or bug fixes you want to be able to run Hydra from your working copy. There are +two ways to do this. One is better for interactive development and provides faster feedback cycles, the other +is more convenient for a single test run of Hydra from the working copy (suiteable for PR reviews). + +#### Using runHydra + +Hydra can be built and executed using the `runHydra` shell: + +``` +$ nix-shell default.nix -A runHydra +``` + +This will spawn a shell that starts hydra-server, hydra-queue-runner, hydra-evaluator and postgres using [foreman](https://github.com/ddollar/foreman). +In order to not collide with potentially existing installations running on default ports hydra and postgres are running on custom ports: + +- hydra-server: 63333 +- postgresql: 64444 + +**Note**: In some cases you may want to skip test execution. You can do so by passing `doCheck false`: + +``` +$ nix-shell default.nix -A runHydra --arg doCheck false +``` + +#### Using foreman + +When you are actively working on the code, you need fast feedback cycles and thus want incremental builds. Instead of using +`runHydra` you can just run `foreman start` directly in the normal `nix-shell` environment: + +``` +$ nix-shell +$ # hack hack +$ make +$ foreman start +``` + ### JSON API You can also interface with Hydra through a JSON API. The API is defined in [hydra-api.yaml](./hydra-api.yaml) and you can test and explore via the [swagger editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/NixOS/hydra/master/hydra-api.yaml)