.Dd March 10, 2021
.Dt BOSUN 1
.Os
.Sh NAME
.Nm bosun
.Nd manage portage roles with stow
.Sh SYNOPSIS
.Nm
.Ic add
.Ar role ...
.Nm
.Ic flush
.Nm
.Op Ic list Op Ar type
.Nm
.Ic rebuild
.Op Ar role ...
.Nm
.Ic remove
.Ar role ...
.Sh DESCRIPTION
.Nm
is a program to add, remove, and list portage roles.
.Pp
A
.Dq role
is a directory comprised of a set of portage configuration files
pertaining to a specific service, usage, et cetera.
Roles are placed into
.Em /etc/portage/stow
or the directory pointed to by
.Ev BOSUN_DIR .
.Pp
.Nm
uses
.Xr stow 8
to build a full set of portage configuration files in
.Em /etc/portage .
It does so by creating symlinks in
.Em /etc/portage
that point back to the actual files in the role directories.
.Pp
The commands are as follows:
.Bl -tag -width Ds
.It Sy add Em role ...
Activates the given roles on the system.
.It Sy flush
Deactivates all active roles on the system.
.It Sy list Op Ar type
Lists roles of the given type.
If no type is given, list roles of the
.Dq active
type.
The types are as follows:
.Bl -tag -width Ds
.It Sy active
Lists roles that are active on the system.
.It Sy all
Lists all roles.
.It Sy available
Lists roles that are not active on the system.
.El
.It Sy rebuild Op Ar role ...
Deactivates the given roles and then activates them again.
This is used to incorporate files that have been added to an already
active role.
.Pp
If no roles are given, rebuild all active roles.
.It Sy remove Em role ...
Deactivates the given roles on the system.
.Pp
This command has two aliases,
.Sy del
and
.Sy delete .
.El
.Pp
If no command is given,
.Nm
will list active roles.
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev BOSUN_DIR
The base directory containing all portage roles.
See
.Sx FILES
for the default location if this is unset.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa /etc/portage/stow
The base directory containing all portage roles.
.El
.Sh EXAMPLES
The following directory structure under
.Pa /etc/portage/stow
describes a simple setup of bosun with three roles,
.Em service-mail ,
.Em app-tex ,
and
.Em group-musl .
.Bd -literal -offset indent
service-mail/package.accept_keywords/20-service-mail
service-mail/package.use/20-service-mail
app-tex/sets/tex
group-musl/package.accept_keywords/02-group-musl
group-musl/repos.conf/musl.conf
group-musl/patches/net-misc/openssh/disable-utmp-in-musl.patch
.Ed
.Pp
After activating
.Em group-musl
and
.Em service-mail ,
.Pa /etc/portage
will look something like this:
.Bd -literal -offset indent
package.accept_keywords/02-group-musl@
package.accept_keywords/20-service-mail@
package.use/20-service-mail@
patches/net-misc/openssh/disable-utmp-in-musl.patch@
repos.conf/musl.conf@
.Ed
.Pp
Here, each symbolic link points to the corresponding file in
.Pa /etc/portage/stow .
.Nm
transparently merged the given roles into one structure.
After removing
.Em group-musl
and activating
.Em app-tex ,
the directory will look like this:
.Bd -literal -offset indent
package.accept_keywords/20-service-mail@
package.use/20-service-mail@
sets/tex@
.Ed
.Pp
As roles are activated or removed, the role directory stays untouched; it is
merely the symbolic links that are added or removed.
This makes it suitable to manage
.Pa /etc/portage/stow
in
.Xr git 1 .
.Pp
Suppose we add another file to the
.Em service-mail
role in a new directory
.Pa package.use .
The role is already active, but since
.Nm
cannot know that it has been changed, we need to rebuild the symbolic links:
.Bd -literal -offset indent
bosun rebuild service-mail
.Ed
.Sh SEE ALSO
.Xr portage 5 ,
.Xr stow 8
.Sh AUTHORS
.An -nosplit
.Nm
was written by
.An Wolfgang Müller Aq Mt wolf@oriole.systems