forked from lda/telodendria
Update porting documentation.
This commit is contained in:
parent
38565d4aa6
commit
3e4698bf72
1 changed files with 78 additions and 118 deletions
|
|
@ -1,4 +1,4 @@
|
|||
.Dd $Mdocdate: March 10 2023 $
|
||||
.Dd $Mdocdate: April 24 2023 $
|
||||
.Dt PORTING 7
|
||||
.Os Telodendria Project
|
||||
.Sh NAME
|
||||
|
|
@ -6,29 +6,32 @@
|
|||
.Nd Some guidelines for packaging Telodendria for your operating system.
|
||||
.Sh DESCRIPTION
|
||||
.Pp
|
||||
Telodendria is distributed at source code, and does not offer a convenient
|
||||
install process. This is intentional; the Telodendria project is primarily
|
||||
concerned with developing Telodendria itself, not packaging it for the
|
||||
hundreds of different operating systems and Linux distributions that exist.
|
||||
It is my firm belief that distributing an open source project is not the
|
||||
job of the open source developer; that's the reason software distributions
|
||||
exist, to collect and distribute software.
|
||||
Telodendria is distributed at source code, and does not offer a
|
||||
convenient install process. This is intentional; the Telodendria
|
||||
project is primarily concerned with developing Telodendria itself,
|
||||
not packaging it for the hundreds of different operating systems
|
||||
and Linux distributions that exist. It is my firm belief that
|
||||
distributing an open source project is not the job of the open
|
||||
source developer; that's the reason software distributions exist,
|
||||
to collect and distribute software.
|
||||
.Pp
|
||||
It would be impossible to single-handedly package Telodendria for every
|
||||
platform, because each platform has very different expectations for
|
||||
software. Even different Linux distributions have different conventions
|
||||
for where manual pages, binaries, and configuration files go.
|
||||
It would be impossible to single-handedly package Telodendria for
|
||||
every platform, because each platform has very different expectations
|
||||
for software. Even different Linux distributions have different
|
||||
conventions for where manual pages, binaries, and configuration
|
||||
files go.
|
||||
.Pp
|
||||
That being said, this page aims to assist those who want to package
|
||||
Telodendria for their operating system or software distribution.
|
||||
.Pp
|
||||
See
|
||||
.Xr td 1
|
||||
for instructions on how to build Telodendria. Only proceed with packaging
|
||||
Telodendria after you have successfully built it on your operating system.
|
||||
for instructions on how to build Telodendria. Only proceed with
|
||||
packaging Telodendria after you have successfully built it on your
|
||||
operating system.
|
||||
.Pp
|
||||
To package Telodendria, you should collect the following files, and figure
|
||||
out where they should be installed for your system:
|
||||
To package Telodendria, you should collect the following files, and
|
||||
figure out where they should be installed for your system:
|
||||
.Bl -bullet
|
||||
.It
|
||||
The telodendria server binary itself:
|
||||
|
|
@ -36,122 +39,79 @@ The telodendria server binary itself:
|
|||
.It
|
||||
All manual pages in the
|
||||
.Pa man/
|
||||
directory that are prefixed with "telodendria". These are the user documentation
|
||||
pages. All pages that do not have the "telodendria" prefix are intended only
|
||||
for developers, and so do not need to be installed to the system.
|
||||
directory that are prefixed with "telodendria". These are the user
|
||||
documentation pages. All pages that do not have the "telodendria"
|
||||
prefix are intended only for developers, and so do not need to be
|
||||
installed to the system.
|
||||
.It
|
||||
An init script. People that wish to install Telodendria to their system
|
||||
expect it to be integrated enough that Telodendria can be easily started at
|
||||
boot, and otherwise managed by the system's daemon tools, be it systemd, or
|
||||
another init system. Consult your system's documentation for writing an
|
||||
init script. Do note that Telodendria does not fork itself to the background;
|
||||
the init script should do that. Also note that Telodendria responds to SIGINT,
|
||||
so a SIGINT should be sent to stop Telodendria instead of a SIGTERM or SIGKILL.
|
||||
An init script. People that wish to install Telodendria to their
|
||||
system expect it to be integrated enough that Telodendria can be
|
||||
easily started at boot, and otherwise managed by the system's daemon
|
||||
tools, be it systemd, or another init system. Consult your system's
|
||||
documentation for writing an init script. Do note that Telodendria
|
||||
does not fork itself to the background; the init script should do
|
||||
that. Note that the init script probably requires a few things:
|
||||
.Bl -bullet
|
||||
.It
|
||||
A sample
|
||||
.Pa telodendria.conf
|
||||
file. Whether this file is placed at the actual configuration file location,
|
||||
or a directory containing configuration file samples is entirely up to the
|
||||
packager. You can use or adapt any of the configuration files in
|
||||
A dedicated system user under which Telodendria should run.
|
||||
Telodendria can either be started as that user, or started as
|
||||
root and configured to automatically drop to that user.
|
||||
.It
|
||||
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/ ,
|
||||
or write your own specifically for your package.
|
||||
.El
|
||||
.Pp
|
||||
Once you have collected the files that need to be installed, make sure your
|
||||
package performs the following tasks on install:
|
||||
Once you have collected the files that need to be installed, make
|
||||
sure your package performs the following tasks on install:
|
||||
.Bl -bullet
|
||||
.It
|
||||
If necessary, depending on the config used, create a new system user for
|
||||
the Telodendria daemon to run as.
|
||||
If necessary, depending on the config used, create a new system
|
||||
user for the Telodendria daemon to run as.
|
||||
.It
|
||||
If conventional for your system, enable the Telodendria init script so
|
||||
that Telodendria is started on system boot.
|
||||
If conventional for your system, enable the Telodendria init script
|
||||
so that Telodendria is started on system boot.
|
||||
.It
|
||||
Insruct the user to carefully read the sample
|
||||
.Pa telodendria.conf
|
||||
as well as the
|
||||
.Xr telodendria.conf 5
|
||||
manual page before starting Telodendria.
|
||||
Insruct the user to carefully read the
|
||||
.Xr telodendria-setup 7 ,
|
||||
.Xr telodendria-admin 7 ,
|
||||
and
|
||||
.Xr telodendria-config 7
|
||||
manual pages before starting Telodendria.
|
||||
.El
|
||||
.Pp
|
||||
The goal of a package should be to get everything as ready-to-run as possible.
|
||||
The user should only have to change one or two default options in the configuration
|
||||
file before Telodendria can be started.
|
||||
The goal of a package should be to get everything as ready-to-run
|
||||
as possible. The user should be able to start Telodendria
|
||||
right away and begin configuring it.
|
||||
.Pp
|
||||
Remember to publicly document the setup of Telodendria on your platform so
|
||||
that users can easily get Telodendria running. If you're packaging Telodendria
|
||||
for a containerization system such as Docker, you can omit the things that
|
||||
containers typically do not have, such as the init script and man pages.
|
||||
Remember to publicly document the setup of Telodendria on your
|
||||
platform so that users can easily get things running. If you're
|
||||
packaging Telodendria for a containerization system such as Docker,
|
||||
you can omit the things that containers typically do not have, such
|
||||
as the init script and man pages.
|
||||
.Pp
|
||||
Also remember that your port should feel like it belongs on your target system.
|
||||
Follow all of your system's conventions when placing files on the filesystem,
|
||||
so your users know what to expect. The goal is not to have a unified experience
|
||||
across all operating systems, rather, you should cater to the opinions of your
|
||||
operating system. Telodendria is architected in such a way that it does not
|
||||
impose the developers opinions of where things should go.
|
||||
.Sh PORTS REPOSITORY
|
||||
.Pp
|
||||
The Telodendria project provides a
|
||||
.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.
|
||||
Also remember that your port should feel like it belongs on your
|
||||
target system. Follow all of your system's conventions when placing
|
||||
files on the filesystem, so your users know what to expect. The
|
||||
goal is not necessarily to have a unified experience across all
|
||||
operating systems, rather, you should cater to the opinions of
|
||||
your operating system. Telodendria is architected in such a way
|
||||
that it does not impose the developers opinions of where things
|
||||
should go, and since the configuration lives in the database,
|
||||
it is fairly self-contained.
|
||||
.Pp
|
||||
.Sh SEE ALSO
|
||||
.Xr telodendria-contributing 7 ,
|
||||
|
|
|
|||
Loading…
Reference in a new issue