feed-gipeda

A kitchen-sink tool to run gipeda on a list of repositories after having run a benchmark script on each (repo, commit) pair that is yet to be benchmarked.

This will take all the necessary steps to update and deploy a gipeda-based site. Think Travis CI for benchmarks.

Use this when you host a variety of repositories and want to display performance data about them. Although the defaults are biased towards Haskell projects using cabal/stack, the script to run on each new commit can be configured.

I think I could use this but I haven't understood a word

This is a high-level example setup of how to use it:

Below there is a detailed visualization of the FRP layer (of the master node):

Without any special flags, feed-gipeda will enter the build once mode (and then exit).

feed-gipeda extracts repositories to watch from a *.yaml file (c.f. Config file). For each remote repository, a unique but human-readable directory (<base-name>-<hash-of-URI>) is created, under which a mirror repository resides in the repository/ folder.

Every commit for which gipeda requests a benchmark (e.g. because there is no *.csv result file in site/out/results) causes a benchmark script to be run. The concrete example above uses cloben for that (it's also the default), but any other benchmark script which expects to be executed in the project folder and which writes its CSV output to stdout should do.

Either after a benchmark finishes or a repository was fetched, gipeda is executed for both new commits to benchmark and for producing the website to be deployed via rsync to a remote location (--deploy-to flag).

--watch mode

When gipeda requests no more benchmarks, feed-gipeda exits.

This can be changed via the --watch=SECONDS option. If specified, feed-gipeda will enter a daemon mode and not exit if there is temporary nothing to benchmark. Instead, it will watch for changes to the config file (handle updates to the watched repository list) and refetch all currently watched repositories every SECONDS seconds.

--check mode

With the --check flag supplied, feed-gipeda will check the config file (c.f. Config file, --config) for syntax errors and report them as an error. It will successfully exit when it can find none.

How to get it to run

The following steps should get you all Haskell dependencies (using cabal in a similar way):

$ stack install cloben gipeda feed-gipeda

You will also need to install the system dependencies for gipeda (sorry, fellow Windows users!), as well as there must be rsync and ssh available on the path, if you choose to --deploy-to some location.

Using cloben is of course optional, but the simplest option for benchmarking (if you want to benchmark cabal-conformant Haskell repositories).

By now, $ feed-gipeda --help should spit out maybe more up-to-date documentation than this README and you can read about supplying custom paths to various files such as the configuration file. For the sake of the example, we will use the default location, which is at ~/.feed-gipeda/feed-gipeda.yaml. Put this into that file:

repositories:
- https://github.com/sgraf812/benchmark-test

In --watch mode, that file would be watched for changes, so you can make it part of a git repository (like I did here) and fetch updates as part of a cron job.

Alternatively, you can run feed-gipeda in the default mode (build once) any time you need updates.

Now find yourself a quiet little tmp folder and run

$ feed-gipeda --help
...
$ feed-gipeda --deploy-to=some/local/path/if/you/want

For some more usage examples, see the Cookbook section.

Config file

Contains the list of repositories to watch encoded in a YAML file. Is supplied via the --config option, which defaults to ~/.feed-gipeda/feed-gipeda.yaml (resp. %APPDATA%/Roaming/.feed-gipeda/feed-gipeda.yaml on Windows).

For an example, see https://github.com/sgraf812/.feed-gipeda or the example 2 line file above. The file must contain a top-level repositories mapping to a list of repository URIs.

Cookbook

• feed-gipeda
  Enter default mode (Exit when done). Read config from the default location (system-specific, see --config option under --help), act as both a master and a slave node.
• feed-gipeda --watch=5
  Enter watch mode. Watch for changes to config and re-fetch repositories every 5 seconds. Read config from the default location, act as both master and slave node
• feed-gipeda --check --config=~/.feed-gipeda/feed-gipeda.yaml
  Enter check mode. Check the specified config file for syntax errors. Useful in a CI setting.
• feed-gipeda --master=12345
  Enter default mode. Dispatch benchmark requests on registered slave nodes, don't work on them in this process.
• feed-gipeda --slave=12346:127.0.0.1:12345
  Enter slave-only mode, listen on 127.0.0.1:12346. Periodically try to register at the master node located at 127.0.0.1:12345 which requests you to do benchmarks.
• feed-gipeda --deploy-to=deploymentDir/
  Enter default mode. Deploy changes via rsync to the local deploymentDir