Skip to content

Home

Jump to bottom
jgabaut edited this page Sep 7, 2024 · 10 revisions

amboso

A build tool wrapping make, with some git integration, powered by bash.

Table of Contents

The anvil project

This project started as a simple "batch job" runner, and it's stayed pretty much the same.

Since the start, I was not going for a perfect implementation, but rather an explorative search of what I felt was useful ideas. Thus, I wanted to keep the idea of a "second implementation" in mind when picking the name.

I decided to name the bash implementation amboso since it both means "anvil" in esperanto and kinda sounds like "I'm bozo".

Having its roots in a plain bash script, the overall complexity was going to be inevitably constricted by the underlying implementation.

Once this has been established, we can try to define the anvil interface if it were to be fruitful improving upon it.

The first goal of the tool was being able to automate this pseudo-command chain:

git checkout MY_TAG; my_conf; my_rebuild; mv MY_BIN MY_DIR/; git switch -

Which will be referred to as the core command chain (or CCC) from now on.

In other words, build git tags for a project by relegating the needed arguments for the checkout-build-move-switchback to a script. Aaaand also the whole build logic to make. This was done both for simplicity (not having to implement my own subset of make or similar to start off) and to allow the usage of this tool with a wider number of project, given the popularity of make itself.

The MY_TAG argument could be just be expected as a command line argument, but since there was already a need for some file where needed arguments for the CCC would be stored, a list of all tool-expected tags was to be included with the build file.

This means that some git tags for a project can be ignored completely by the tool, if they are not in the build file.

So the core idea is: you have a C project that has a make target to build (and the target command chain doesn't create unignored files, more on this later) and you add a small file holding the needed arguments for the CCC.

The tool supports some flags to pass specific parameters to the CCC, when ie. you want to change the arguments to the my_conf call, or the name of MY_DIR.

The user should not be encumbered by any more setup than this, but unfortunately, up until recently my implementations were expecting a static directory tree to be present while performing an all-tags build (that is, to build all tags, the tool expected a pre-made MY_DIR/vX.Y.Z/ dir, but at some point this was changed so that the base directory should be created when not found.

This expectation is bad since it requires the user project to respect some .gitignore settings in order to really use the tool. More on this later.

Prerequisites

This implementation, just like the Rust one, has some dependencies.

Namely, it needs:

  • bash, >=4.0 (I've only tested with >=5.x)
  • gawk should be your awk symlink. If your awk is not gawk and you want to keep it that way, you can just install gawk for your platform and not symlink it.
  • bc
  • autotools to work with projects supporting autotools

Basic usage

The basic usage of the tools is:

$ ./anvil -b <MY_TAG>

And the expected result is for the target binary to be ready at MY_DIR/vMY_TAG/.

The stego.lock file

This file is used by anvil to get information about a project.

It uses a format loosely based on TOML:

[anvil]
kern = "amboso-C"
[build]
bin = "hello_world"
[versions]
"0.1.0" = "Foo"

The available keys are:

  • For scope anvil:

    • kern: name of the anvil mode used by the project.
    • version: version of anvil used by the project.

  • For scope build:

    • source: name for source file. Only used by the single-file build mode.
    • bin: name for target binary. Only one target binary is permitted.
    • makevers: first tag including a ready Makefile.
    • automakevers: first tag including a Makefile.am and a configure.ac, needed by autotools to generate a Makefile.
    • tests: name of the directory for tests.

  • For scope tests:

    • testsdir: name of the directory for "success" tests, expected inside tests (from build scope).
    • errortestsdir: name of the directory for "error" tests, expected inside tests (from build scope).

  • For scope versions:

    • Each key represents a supported anvil tag.

  • The tool also checks for a global config file at $HOME/.anvil/anvil.toml

    • Primarily useful to set a specific anvil version/kern you may want to use as default, without resorting to command aliasing.

Subcommands

Options

Environment

  • O <stegodir>: Set directory used to host the stego.lock file. Default: working directory, BIN_DIR
  • D <dir>: Set directory used to host the tagged versions. Default: ./bin
  • K <testsdir>: Set directory used to host the tests.
  • S <sourcename>: Set filename used for source, for single-file mode.
  • E <execname>: Set filename used for target binary.
  • M <minmaketag>: Set min tag using make mode.
  • Y <time>: Set start time for anvil.

Mode

  • T: Run a test
  • t: Run all tests
  • B: Run in base mode
  • g: Run in git mode (default)
  • x <file>: Run in stego parser mode

Operations

  • b: Build
  • d: Delete
  • r: Run
  • i: Init
  • p: Purge
  • G: Generate C header with some info for the project
  • F: Forced, ignores ready target binaries when building
  • X: Ignore git check, ignores the git status when not clean

Output settings

  • h: Print usage help and quit.
  • H: Print paged usage help and quit.
  • v: Print current anvil version and quit.
  • W: Print warranty info and quit.
  • l: List all tags for current mode.
    • With x: lint passed stego file
  • L: List all tags.
    • With x: report full lex
  • s: Silent, no output.
  • q: Quiet, less output.
  • w: Watch, prints timing for operations.
  • P: Plain, turns off colored output.
  • J: Journaled, logs all output to ./anvil_log.txt.
  • V <level>: Verbose, sets verbose level.

Compatibility settings

  • e: Extensions, turns off extensions to 2.0.0.
  • a: Anvil version, to specify behaviour for patches to 2.0.0.
  • k: Anvil kern, to specify the anvil mode to use.

Planned extensions

  • Add support for more project types
    • At the moment, the strong link with autotools for the ambosoC kern could be relaxed to allow for a simple script entryname.
    • A new "custom" kern could be added, intended to be a single process call expected to do the build, named explicitly by a new anvil key in the stego.lock.
  • The current toml parsing is very naive and should be replaced by a proper parsing utility.
  • The Rust implementation (invil) is shipping with a work-in-progress python kern support, leveraging pyproject.toml from the wanted Python package.
    • To implement this support, the current toml parsing module must be replaced by a proper one.
  • Rename config file to stego.toml and have the corresponding stego.lock be a file edited by the script itself
    • This may benefit from a proper toml parsing module, if such module also supports file editing
Clone this wiki locally