Tiamat 8.0.0

Welcome to tiamat version 8.0.0’s release notes! This version of tiamat introduces pluggable backends. Tiamat supports a pyinstaller backend out of the box. This is the default and supported way to use tiamat. You can easily extend tiamat to use other backends. Here we will discuss how to extend tiamat with an alternative backend.

Pluggable Backends

Getting started

You can use a tool called pop-create to auto-generate the structure for your project.

# Create a new directory for your tiamat backend
$ mkdir tiamat-[my-backend]

# Move into that directory
$ cd tiamat-[my-backend]

# Install the pop-create project for initializing boilerplate code
$ pip install pop-create

# Run pop-create -- telling it that your project will vertically extend tiamat
$ pop-create -n tiamat-[my-backend] -tv -d builder tool

# Add tiamat to the requirements of your new project
$ echo "tiamat>=8.0.0" >> requirements/base.txt

# Create the directory where all of your plugin's code will reside (use underscores instead of dashes here)
$ mkdir tiamat_[my_backend]/builder/[my_backend].py

# Create a place to put your helper functions
$ mkdir tiamat_[my_backend]/tool/[my_backend]/init.py

All the files you could possibly need are now created

conf.py

Here we will discuss what goes into tiamat_my_backend/conf.py

This is how to add your own subcommand to tiamat that is aware of options specific to your backend.

# In this dictionary goes all the immutable values you want to show up under hub.OPT.tiamat
CONFIG = {
    # This option will become available to only your specific backend
    "my_option1": {"dyne": "tiamat", "subcommands": ["my-backend"]},
    # This option will become available to every subcommand
    "my_option2": {"dyne": "tiamat", "subcommands": ["_global_"]},
}

# This is how we make the main tiamat tool able to use our backend as a subcommand
# This is required and the "my-backend" must match with the name of your folder under the tiamat directory
SUBCOMMANDS = {"my-backend": {"dyne": "tiamat", "help": "my build backend for tiamat"}}

# Include keys from the CONFIG dictionary that you want to expose on the cli
# The values for these keys are a dictionaries that will be passed as kwargs to argparse.ArgumentParser.add_option
CLI_CONFIG = {
    # This option will become available to only your specific backend
    "my_option1": {"dyne": "tiamat", "subcommands": ["my-backend"]},
    # This option will become available to every subcommand
    "my_option2": {"dyne": "tiamat", "subcommands": ["_global_"]},
}

# This tells pop that "builder" is vertically extended through the folder called "builder" in your project root
# builder plugins are the backend of tiamat
DYNE = {"builder": ["builder"]}

builder/my_backend.py

def new(hub, *, my_option1, my_option2, **opts) -> dict[str, any]:
    """
    Collect all the arguments from the opts needed for a build.
    Here we can do more complex computation of defaults and bulletproofing.
    """
    return dict(
        my_option1=my_option1,
        my_option2=my_option2,
        directory=opts.directory,
    )


def run(hub, build_name: str):
    """
    Make the calls to perform the build process using the OPTs in "build_name"
    """
    # We can retrieve the sanitized using the build name
    opts = hub.tiamat.BUILDS[build_name]

    # A generic virtualenv plugin can be created within which to run the build
    hub.virtualenv.init.create(build_name)

    # Run the commands listed in the 'make' portion of the build config
    hub.tiamat.make.apply(build_name)

    # Helper functions can be called from hub.tool
    # This allows for organization of code so that everything doesn't need to be crammed into one giant file
    hub.tool.my_backend.helper_plugin.helper_function(build_name)


def clean(hub, build_name: str):
    """
    Clean up virtual environments and intermediate files after a build
    """

Usage

tiamat my-backend --my-option1="foo" --my-option2="bar"