README.md
1# Panopticum
2
3Panopticum is a tool to perform some operations on FreeBSD ports for every `OPTIONS` combination possible.
4
5Currently supported commands are:
6
7- `panopticum deps` produces a combined list of build- and run-depends.
8- `panopticum plist` generates a correct **pkg-plist** file.
9
10Since 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.
11
12## deps command
13
14The `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`.
15
16Usage: `panopticum deps PORT`, where `PORT` can be either port origin or an absolute/relevant path to the port.
17
18## plist command
19
20The `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.
21
22This 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%%`.
23
24## Restarting failing builds
25
26When 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 `/tmp/panopticum.state` along with a error log `/tmp/panopticum_err.log`. Once the port is fixed to build failing combinations correctly, the `panopticum plist` command can be restarted with `-s /tmp/panopticum.state` argument. This will make Panopticum to only rebuild combinations that were failing in the previous run, saving your time and CPU cycles.
27
28## Additional options
29
30Each 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.
31
32## Development
33The 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.
34
35The canonical upstream repository is [FOSS Heptapod instance](https://foss.heptapod.net/bsdutils/panopticum).
36