Some guidelines for packaging
Telodendria for your operating system.
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.
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.
That being said, this page aims to assist those who want to package Telodendria for their operating system or software distribution.
See td(8) for instructions on how to build Telodendria. Only proceed with packaging Telodendria after you have successfully built it on your operating system.
To package Telodendria, you should collect the following files, and figure out where they should be installed for your system:
- The telodendria server binary itself: build/telodendria
- All manual pages in the 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.
- 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.
- A sample 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 contrib/, or write your own specifically for your package.
Once you have collected the files that need to be installed, make sure your package performs the following tasks on install:
- If necessary, depending on the config used, create a new system user for the Telodendria daemon to run as.
- If conventional for your system, enable the Telodendria init script so that Telodendria is started on system boot.
- Insruct the user to carefully read the sample telodendria.conf as well as the telodendria.conf(5) manual page before starting Telodendria.
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.
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.
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.
The Telodendria project provides a 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:
$ cvs -d firstname.lastname@example.org:/cvs checkout -P Telodendria-Ports
(It is assumed that you have read telodendria-contributing(7), so you already have the proper tools for getting the ports repository.)
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 OpenBSD/ directory. If you make a HaikuOS port, then make a HaikuOS/ directory.
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.
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 OpenBSD/ directory to /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.
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.
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 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.
telodendria-contributing(7), td(8), telodendria(7)