jimzah/Telodendria
1
0
Fork 0
forked from Telodendria/Telodendria
Code Pull requests Activity

Update porting documentation.

Browse source
This commit is contained in:
Jordan Bancino 2023-04-24 22:24:32 +00:00
parent 38565d4aa6
commit 3e4698bf72
1 changed files with 78 additions and 118 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

196
man/man7/porting.7
View file

@ -1,4 +1,4 @@
.Dd $Mdocdate: March 10 2023 $ .Dd $Mdocdate: April 24 2023 $
.Dt PORTING 7 .Dt PORTING 7
.Os Telodendria Project .Os Telodendria Project
.Sh NAME .Sh NAME
@ -6,29 +6,32 @@
.Nd Some guidelines for packaging Telodendria for your operating system. .Nd Some guidelines for packaging Telodendria for your operating system.
.Sh DESCRIPTION .Sh DESCRIPTION
.Pp .Pp
Telodendria is distributed at source code, and does not offer a convenient Telodendria is distributed at source code, and does not offer a
install process. This is intentional; the Telodendria project is primarily convenient install process. This is intentional; the Telodendria
concerned with developing Telodendria itself, not packaging it for the project is primarily concerned with developing Telodendria itself,
hundreds of different operating systems and Linux distributions that exist. not packaging it for the hundreds of different operating systems
It is my firm belief that distributing an open source project is not the and Linux distributions that exist. It is my firm belief that
job of the open source developer; that's the reason software distributions distributing an open source project is not the job of the open
exist, to collect and distribute software. source developer; that's the reason software distributions exist,
to collect and distribute software.
.Pp .Pp
It would be impossible to single-handedly package Telodendria for every It would be impossible to single-handedly package Telodendria for
platform, because each platform has very different expectations for every platform, because each platform has very different expectations
software. Even different Linux distributions have different conventions for software. Even different Linux distributions have different
for where manual pages, binaries, and configuration files go. conventions for where manual pages, binaries, and configuration
files go.
.Pp .Pp
That being said, this page aims to assist those who want to package That being said, this page aims to assist those who want to package
Telodendria for their operating system or software distribution. Telodendria for their operating system or software distribution.
.Pp .Pp
See See
.Xr td 1 .Xr td 1
for instructions on how to build Telodendria. Only proceed with packaging for instructions on how to build Telodendria. Only proceed with
Telodendria after you have successfully built it on your operating system. packaging Telodendria after you have successfully built it on your
operating system.
.Pp .Pp
To package Telodendria, you should collect the following files, and figure To package Telodendria, you should collect the following files, and
out where they should be installed for your system: figure out where they should be installed for your system:
.Bl -bullet .Bl -bullet
.It .It
The telodendria server binary itself: The telodendria server binary itself:
@ -36,122 +39,79 @@ The telodendria server binary itself:
.It .It
All manual pages in the All manual pages in the
.Pa man/ .Pa man/
directory that are prefixed with "telodendria". These are the user documentation directory that are prefixed with "telodendria". These are the user
pages. All pages that do not have the "telodendria" prefix are intended only documentation pages. All pages that do not have the "telodendria"
for developers, and so do not need to be installed to the system. prefix are intended only for developers, and so do not need to be
installed to the system.
.It .It
An init script. People that wish to install Telodendria to their system An init script. People that wish to install Telodendria to their
expect it to be integrated enough that Telodendria can be easily started at system expect it to be integrated enough that Telodendria can be
boot, and otherwise managed by the system's daemon tools, be it systemd, or easily started at boot, and otherwise managed by the system's daemon
another init system. Consult your system's documentation for writing an tools, be it systemd, or another init system. Consult your system's
init script. Do note that Telodendria does not fork itself to the background; documentation for writing an init script. Do note that Telodendria
the init script should do that. Also note that Telodendria responds to SIGINT, does not fork itself to the background; the init script should do
so a SIGINT should be sent to stop Telodendria instead of a SIGTERM or SIGKILL. that. Note that the init script probably requires a few things:
.Bl -bullet
.It .It
A sample A dedicated system user under which Telodendria should run.
.Pa telodendria.conf Telodendria can either be started as that user, or started as
file. Whether this file is placed at the actual configuration file location, root and configured to automatically drop to that user.
or a directory containing configuration file samples is entirely up to the .It
packager. You can use or adapt any of the configuration files in A default data directory, in which all Telodendria data, including
the configuration and logs, will be stored. A good default on
Unix-like system is probably
.Pa /var/telodendria .
.El
.El
.Pp
Optionally, it may be helpful to provide these as well:
.Bl -bullet
.It
A sample Telodendria configuration. This should be placed in the
examples directory on your
system, if such a directory exists. You can use or adapt any of the
configuration files in
.Pa contrib/ , .Pa contrib/ ,
or write your own specifically for your package. or write your own specifically for your package.
.El .El
.Pp .Pp
Once you have collected the files that need to be installed, make sure your Once you have collected the files that need to be installed, make
package performs the following tasks on install: sure your package performs the following tasks on install:
.Bl -bullet .Bl -bullet
.It .It
If necessary, depending on the config used, create a new system user for If necessary, depending on the config used, create a new system
the Telodendria daemon to run as. user for the Telodendria daemon to run as.
.It .It
If conventional for your system, enable the Telodendria init script so If conventional for your system, enable the Telodendria init script
that Telodendria is started on system boot. so that Telodendria is started on system boot.
.It .It
Insruct the user to carefully read the sample Insruct the user to carefully read the
.Pa telodendria.conf .Xr telodendria-setup 7 ,
as well as the .Xr telodendria-admin 7 ,
.Xr telodendria.conf 5 and
manual page before starting Telodendria. .Xr telodendria-config 7
manual pages before starting Telodendria.
.El .El
.Pp .Pp
The goal of a package should be to get everything as ready-to-run as possible. The goal of a package should be to get everything as ready-to-run
The user should only have to change one or two default options in the configuration as possible. The user should be able to start Telodendria
file before Telodendria can be started. right away and begin configuring it.
.Pp .Pp
Remember to publicly document the setup of Telodendria on your platform so Remember to publicly document the setup of Telodendria on your
that users can easily get Telodendria running. If you're packaging Telodendria platform so that users can easily get things running. If you're
for a containerization system such as Docker, you can omit the things that packaging Telodendria for a containerization system such as Docker,
containers typically do not have, such as the init script and man pages. you can omit the things that containers typically do not have, such
as the init script and man pages.
.Pp .Pp
Also remember that your port should feel like it belongs on your target system. Also remember that your port should feel like it belongs on your
Follow all of your system's conventions when placing files on the filesystem, target system. Follow all of your system's conventions when placing
so your users know what to expect. The goal is not to have a unified experience files on the filesystem, so your users know what to expect. The
across all operating systems, rather, you should cater to the opinions of your goal is not necessarily to have a unified experience across all
operating system. Telodendria is architected in such a way that it does not operating systems, rather, you should cater to the opinions of
impose the developers opinions of where things should go. your operating system. Telodendria is architected in such a way
.Sh PORTS REPOSITORY that it does not impose the developers opinions of where things
.Pp should go, and since the configuration lives in the database,
The Telodendria project provides a it is fairly self-contained.
.Pa Telodendria-Ports
repository that is intended to serve as the official staging environment for
ports and packages of Telodendria to various operating systems. You can
most likely take inspiration from the files stored in this repository, or even
straight up copy and modify files for your own port if you'd like.
Telodendria-Ports is a convenient resource for new porters. You can grab
a copy of the ports repository like this:
.Bd -literal -offset indent
$ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria-Ports
.Ed
.Pp
(It is assumed that you have read
.Xr telodendria-contributing 7 ,
so you already have the proper tools for getting the ports repository.)
.Pp
The repository is structured in such a way that each operating system or
software distribution has a directory. For example, the OpenBSD port has an
.Pa OpenBSD/
directory. If you make a HaikuOS port, then make a
.Pa HaikuOS/
directory.
.Pp
The structure of the operating system directories themselves is really defined
by the conventions of the packaging system you're working with. There's no standard
structure, as each system does things differently. Just use the directory as a
working space that stores all the files your packaging system needs to build
a package for Telodendria.
.Pp
The exact procedure for interacting with this repository is also defined by how
your packaging system works. For OpenBSD, one is required to copy the
.Pa OpenBSD/
directory to
.Pa /usr/ports/net/telodendria ,
and then copy files back and forth when modifications are made. You may be able
to get away with building your package in place, without having to copy files
anywhere. Otherwise, you can try symlinking directories, but OpenBSD ports did
not like this at all.
.Pp
Submitting your port files to Telodendria-Ports is by no means required,
but it may be helpful to have a public record that you're working on a port,
and it's definitely helpful to have a consolidated list of all the ports out
there, making it much easier to determine whether or not a given platform
has a port, especially if you're unfamilier with that platform's port system.
If you are capable of managing your port entirely within your packaging system,
then go for it! I just wanted a staging environment that I have commit access to
for my ports, allowing me to prototype and test my port before submitting it
to the actual ports tree.
.Pp
It is important to note that I only maintain the OpenBSD port, because that's
the operating system I use. But, notice that I follow my own rules; nothing
inherently OpenBSD-specific, besides a few optional files in
.Pa contrib/ ,
actually exists in the main repository. All operating-system specific files,
such as init scripts and the like, should go to Telodendria-Ports. It's also
important to note that the files placed in Telodendria-Ports are not automatically
assumed to be official builds. The developer that committed the files to
Telodendria-Ports will most likely also have to get them submitted upstream,
because I'm not going to go to all these upstream packagers with the port files
here, I'll only do that with ports I officially maintain, which is the
OpenBSD port.
.Pp .Pp
.Sh SEE ALSO .Sh SEE ALSO
.Xr telodendria-contributing 7 , .Xr telodendria-contributing 7 ,