README

Luthier: automated builds
=========================

Luthier will automate the fetching and building of something, deciding
when to keep the results and notify developers.

It has been used successfully to make simple CI/CD pipelines.

Motivations:

* Lightweight: usable for personal projects
* 'Unix-like' feel
* Don't force use of specific UIDs, GIDs etc.; leave up to the user
* 'Silent on success', low noise
* Good defaults
* Use with any version control, not just Git
* Choose your own build environment, eg. default environment, or docker

The 'build' step can mean anything you want; compile, test, deploy.


Installation
------------

The default is to install to /usr/local:

  $ make install    # as root


Setting up
----------

Create a 'builds' directory to use as scratch/workspace:

  $ mkdir mywork

In that directory, a script defines a set of actions;

  $ vi builds/luthier.sh

Take a look at the "example" directory for what these functions are
and why they exist.


Running
-------

This command will run the most recent automated build, and notify
where necessary:

  $ luthier --verbose --builds mywork build

It's designed to be run from crontab or non-interactive environment,
by being silent except on fatal errors; build errors are emailed
separately. This is the command to put in a crontab:

  $ luthier --builds /path/to/mywork build

Other useful commands are:

  $ luthier freshen     # force rebuild even if fingerprints match
  $ luthier list        # list current builds
  $ luthier purge       # purge old builds

The default path for builds is the current directory, so interactive
commands are easy to use; eg. if you want to see what's going on:

  $ cd /path/to/mywork
  $ luthier


Code
----

The code is Bash shell, developed on Linux with GNU utilities. In
general there is a leaning towards future portability and use of
Bash-specific features sparingly.


Example
-------

Viewing the list of builds:

  /project/builds$ luthier
  20210413.01 11:35 355592 complete => Tue 11:45 (joe)
  20210415.00 10:45 492843 complete
  20210415.01 11:15 35c9f3 fail
  20210415.02 12:30 7f62e4 fail
  20210415.03 16:17 a67293 complete => Thu 16:25 (mark)
  20210415.04 16:31 977517 complete
  20210415.05 17:10 0bfae7 complete
  20210415.06 17:15 f83087 complete
  20210415.07 17:40 300ba8 complete => Fri 09:18 (mark)
  20210416.01 11:50 bd65e1 complete

  Currently: complete at bd65e1