build/README.md

+++
extra.pipeline = "forgebuild"
template = "project.html"
+++

# forgebuild

This repository contains the specification, translation strings, and tests for forgebuild, a system to check for updates on remote repositories and trigger some tasks accordingly.

If you are looking for a program you may use as an end user, check out [forge/build.rs](https://tildegit.org/forge/build.rs) (Rust) or [forge/build.sh](https://tildegit.org/forge/build.sh) (bash) instead.

## Specification

forgebuild is based on a specification which can be found in the [spec.md](spec.md) document. This document is versioned, and all forgebuild implementations should use it as a reference.

## Translations

This repository also contains translation files for the various forgebuild implementations. The reference translations are located in the `i18n/` folder, stored as JSON files using 2-letter codes for the language name, such as `en.json`.

In the future, some scripts may be added to convert those JSON files to different formats such as [GNU gettext](https://www.gnu.org/software/gettext/).

## Tests

This project contains the tests for validating your forgebuild implementation. These tests are written with the [bats](https://github.com/bats-core/bats-core/) testing framework, which runs anywhere bash does.

To run the tests, you can either use `test.sh` or run bats on the tests folder directly, like so:

```
$ # Requirements on Debian-based systems:
$ # sudo apt install bats git
$ git clone https://tildegit.org/forge/build
$ bats build/tests
 ✓ repository is cloned
 ✓ first run triggers task
 ✓ no update does not trigger task
 ✓ forced run triggers task
 ✓ update triggers task
 ✓ host-based settings are loaded
 ✓ unknown host uses default settings
 ✓ submodule is cloned
 ✓ first submodule run triggers task
 ✓ submodule update does not trigger task by default

10 tests, 0 failures
```

If you want to test an implementation of forgebuild that is not `forgebuild` in the $PATH, you can either pass its path as first argument to test.sh, or feed bats with that path in the `FORGEBUILD` environment variable:

```
$ test.sh /tmp/forgebuild.rb
$ # Is the same as
$ FORGEBUILD=/tmp/forgebuild.rb bats tests
```

Note: git and hg need to be configured in order to commit (require authorship). TODO: automate this, maybe?

# Tests TODO

- [x] basic function tests
- [x] configurable forgebuild path, so we can test different implementations
- [x] task settings (global/per-host settings)
- [x] multiple source backends (DVCS)
- [x] short/long flags for CLI
- [ ] PGP signatures