HowToDab

Managing a project with Dab

As an example we will use Dab to manage the development of dab itself.

Preparation

Firstly, make sure Dab is installed before we proceed.

Registering a repository

For Dab to know about your repository you first need to add it, lets do that now.

$ dab repo add dab https://github.com/Nekroze/dab.git

This will store the URL we have given the config and attempt to clone the repo to $DAB_REPO_PATH which defaults to $HOME/dab, in this case it may end up at ~/dab/dab unless that path already existed.

You can see the URL in the config by running:

$ dab config get repo/dab/url

Since dab is managing this repository now, should a patch get merged to master from elsewhere, I can check if there is an update to the repo available to get checked out like so:

$ dab repo list

If the repo has a cross beside it then the commit current checked out is not the origin/master commit. If there is a tick then we know it is up to date.

Creating an entrypoint

Entry point scripts can be used for just about anything, in this case we will use it to execute a script that will run tests for us, providing a simple interface instead of remembering perhaps long and complex commands and setup.

$ dab repo entrypoint create dab tests

Now in our Dab config there will be an executable script at ~/.config/dab/repo/dab/entrypoint/tests by default.

Lets edit it to contain the following:

#!/bin/sh
set -eu

./scripts/tagged_tests.sh 'not @ci'

Note that this is a full fledge posix shell script running within the dab image and able to receive arguments if desired.

Now we can execute this entrypoint whenever we want with:

$ dab repo entrypoint run dab tests

Grouping dependencies

Sometimes your project may need a service running or the entrypoint of repo to be run before it. This is there groups can help.

While the Dab project does not require it to test lest imagine it needed postgres running. We can setup a new group for testing our repos that first will bring up a postgres instance then run the test entrypoint for Dab.

$ dab group services alltest postgres
$ dab group repos alltest dab tests

Then to run them all in sequence we can execute:

$ dab group start alltest