Skip to content
Snippets Groups Projects
README.md 2.54 KiB
Newer Older
Gleb Popov's avatar
Gleb Popov committed
# Panopticum

Panopticum is a tool to perform some operations on FreeBSD ports for every `OPTIONS` combination possible.

Currently supported commands are:

- `panopticum deps` produces a combined list of build- and run-depends.
Gleb Popov's avatar
Gleb Popov committed
- `panopticum plist` generates a correct **pkg-plist** file.
Gleb Popov's avatar
Gleb Popov committed

Since options may affect other options, the problems `panopticum` tries to solve scale poorly. For a port with 8 possibly dependent options it'd require to test 2^8 option combinations.

## deps command

Gleb Popov's avatar
Gleb Popov committed
The `panopticum deps` command is supposed to be used for figuring out every dependency the port might require. It essetially runs `make build-depends-list run-depends-list` for every `OPTIONS` combination and then combines the output. The resulting list can be fed to `poudriere bulk` to prepare Poudriere cache for running `panopticum plist`.
Gleb Popov's avatar
Gleb Popov committed

Usage: `panopticum deps PORT`, where `PORT` can be either port origin or an absolute/relevant path to the port.

Gleb Popov's avatar
Gleb Popov committed
## plist command
Gleb Popov's avatar
Gleb Popov committed

The `panopticum plist` command builds a port for every `OPTIONS` combination inside a Poudriere jail, then produce a **pkg-plist** with `make makeplist`, and finally combine them into a single file. All entries in the resulting **pkg-plist** are annotated with `%%OPT_FOO%%` tags if needed.
Gleb Popov's avatar
Gleb Popov committed

This command employs [Quine-McCluskey algorithm](https://en.wikipedia.org/wiki/Quine-McCluskey_algorithm) to compute inter-dependencies between options, and thus is able to handle even complex cases like `%%OPT1%%%%NOOPT2%%%%OPT3_OR_OPT4%%`.

## Restarting failing builds

Gleb Popov's avatar
Gleb Popov committed
When running `plist` command some combination of port options may cause the build to fail. In this case Panopticum will proceed building other combinations, but instead of generating a combined plist will generate a **build state** file `panopticum.state` along with a error log `panopticum_err.log`. Once the port is fixed to build failing combinations correctly, the `panopticum plist` command can be restarted with `-s /path/to/panopticum.state` argument. This will make Panopticum to only rebuild combinations that were failing in the previous run, saving your time and CPU cycles.
Gleb Popov's avatar
Gleb Popov committed
## Additional options

Each command accepts Poudriere-style arguments `-j` and `-p` to set jail name and Ports tree to operate on. These arguments are required for the `plist` command.
Gleb Popov's avatar
Gleb Popov committed

## Development
The project uses [Haskell Stack](https://www.freshports.org/devel/stack) as a build tool. Use `stack build` to compile it and `stack test` to run the test suite.

The canonical upstream repository is [FOSS Heptapod instance](https://foss.heptapod.net/bsdutils/panopticum).