# Porteur

Porteur automates the creation of FreeBSD ports directly from Git repositories.
It bridges the gap between source code and the FreeBSD ports framework with
generating ready-to-build ports that work seamlessly with `poudriere` and
native `make` tooling.


## Concepts

### Ports Trees
A ports tree is a collection of ports similar to how FreeBSD defines it. It
only contains the ports and can be used as an overlay in the ports tooling
of FreeBSD. Porteur can manage multiple ports trees and defaults to the
`default` tree.

### Template
A template defines all the files that the resulting FreeBSD port should contain.
It is used to avoid repetitive port file definitions and uses variables to make
these files usable by multiple ports.

All templates must be defined in the directory `$PREFIX/etc/porteur/tmpl`.

### Port
A port in porteur is basically a reference to a Git repository and a template.
From such a port porteur creates a FreeBSD port which is ready to use with
`poudriere` or `make`.

The Git repository is used to create the distfile that will be referenced in
the Makefile. Porteur manages a local clone of this repository and bundles the
source code of the branch that is configured.

The template defines the contents of the resulting FreeBSD port. Each variable
used in the template must be defined by the port in order to render correctly.


## Quickstart

1. Create a template in `$PREFIX/etc/porteur/tmpl`.
2. Create a new port: `porteur port add my-app`
3. Define the variables the referenced template needs: `porteur port vars --edit my-app`
4. Trigger the first rendering of the port: `porteur port update my-app`
5. Use the port with the FreeBSD ports tooling.

For more information see `porteur --help`.