TD(1) General Commands Manual TD(1)

td — Telodendria build script and patch generation instructions.

td [recipe]

Telodendria uses a custom build script called td. The td script is not only a build script, however. It does all kinds of cool things like format the source code, and generate patch files. td is the only supported way to develop Telodendria.

I opted to write a custom build script instead of just writing a Makefile because I felt that there is really no way to make a truly portable Makefile that could do everything I wanted, with the flexibility I wanted. I was doing a lot of research on the differences between the GNU and BSD versions, and I felt it just wasn't worth trying to reconsile the two when I could write a small and relatively robust POSIX shell script that would run on both GNU and BSD systems without any problems. I also think that shell scripts are a lot easier to read than complex Makefiles. They're easier to follow because they're not so cryptic.

The td script is fairly intuitive. It operates somewhat like make(1) in that it has recipes that you specify on the command line. To start using it, just run the following command in the Telodendria source directory:

$ . tools/env.sh

You will have to run the above command every time you start a new terminal session, as nothing is persisted to your system. I believe in non-invasive, fully self-contained tooling, so it is up to you to hook the Telodendria tools into your environment as you see fit if you want them to persist.

If you're going to be submitting patches, you should also configure a .env file in the project directory root, which td will include automatically for you. See FILES and ENVIRONMENT.

Telodendria is designed to be light enough that it can be built from source on just about any operating system. It only requires an ANSI C compiler and a standard POSIX environment. To build the Telodendria binary, run td with no arguments, or with the build recipe. This will produce build/telodendria, which you can then install to your system and run as a daemon.

A complete list of recipes is below. Note that you can run multiple recipes with a single invocation of td, but recipes are run unconditionally; that is, even if a recipe fails, all the following recipes are still executed.

docs
Build the code documentation files. While a good portion of the documentation is written by hand and maintained in the man/ directory, a substantial amount of documentation is stored in the C header files that define Telodendria's APIs. This recipe runs hdoc(1) on each header to generate man pages for them. The man pages are place in a directory that's already in your man path.
build
Build the source code and generate the output binary. This is the default recipe, which means it runs if no other recipes are specified. This recipe is incremental; it only rebuilds sources that have been modifed since the last build, making subsequent builds faster.
run
Run the built binary with the data directory of data/ in the current directory. This recipe is used for quick testing during development. It is the recommended way to run Telodendria in a production environment; it should only be used for development.
clean
Remove the build/ directory. The build recipe does not place anything outside of build/, so you can usually just delete that directory and get the same effect.
license
Update the copyright comments in every C source and header file using the contents of the LICENSE.txt file. This recipe will also add the license header to new headers and C sources that show up.
format
Format the code using the system's indent(1). This should be run before generating patch files, to ensure that the code follows the project conventions. Note that the provided .indent.pro assumes an OpenBSD indent, which may cause the GNU implementation to choke. In that case, don't send patch files with totally different formatting; just submit the patch as-is and they will get formatted before committing.
site
Deploy the Telodendria website by generating HTML files for the documentation, and copying them along with the front page to the specified web root. This is used to deploy the official website, but it could be used to deploy a local development site as necessary. See ENVIRONMENT.
release
Generate a release tarball, checksum and sign it, and push it to the web root. See the relevant environment variables below.
patch
Generate a formatted patch file. The Telodendria project isn't super picky about how patches look as long as they apply cleanly, but this recipe generates patches in the format we like them, and is therefore recommended. It makes patches easy to read. This recipe will use your configured editor to open your formatted patch so you can review and edit it as necessary before sending it off.
diff
Generate a temporary preview patch that is opened in the system pager. This can be used for quickly quickly previewing your changes and the patch file you'll be creating.

Any of the following environment variables are used in the build recipes. They can all be specified in your shell when invoking td, or they can be placed in a .env file. For most of these variables, if you would like to append or prepend to the default values, do so in the .env file, which is sourced after the defaults are set, allowing you to reference the default values in your new value.

The C compiler to use. This defaults to cc, which is usually a symlink to your system's preferred compiler. If for some reason you want to use a diferent compiler, do so with this environment variable.
When installing/uninstalling Telodendria, the systeme prefix to use. This defaults to /usr/local.
The compiler flags used to generate object files. td comes with reasonable defaults that shouldn't need to be changed in most scenarios, but if you do need to change the compiler flags, you can do so with this environment variable.
The compiler flags used to link the object files to create an output binary.
The common, well-known compilers support a number of extra flags that smaller, niche compilers probably will not. This variable holds those flags, so if you are compiling with a small, lesser known compiler, you can set this to an empty string to disable the extra flags.

td comes with reasonable defaults that shouldn't need to be changed in most scenarios, but if you need to change the linker flags, you do so with this environment variable.

Set the TLS implementation library to use for Telodendria's TLS support. Consult Tls(3) for a list of supported implementations. Implementations should be specified by name in all uppercase.
The name of the output binary. This defaults to build/telodendria.
Global preprocessor definitions to append to CFLAGS. This is just kept separate to keep things organized.
Header directories to make available. This is appended to CFLAGS, it is just kept separate to keep things organized.
If set to "1", append some debug flags to CFLAGS and whipe out any LDFLAGS that awould cause the output binary to be optimized in any way. This also depends "-debug" to PROG.
This variable does make its way into the output binary, but it is primarily used for generating and publishing releases. This variable affects the recipe.
The web root where the Telodendria website lives. This is where the site is pushed to, and where generated releases go.
This variable restricts the files that td operates on when generating patches or diffs. If you only want to generate a diff or patch for a certain file, directory, or collection of files and directories, set this variable to those files and directories, separated by a space. You can mix files and directories as necessary.
Your Matrix ID in standard format. This is used when generating patches, so that you can be assigned credit for your patches, as well as be contacted about your patches. td will automatically deduce this from your system, but it will most likely get it wrong. Please make sure you are reachable at this ID.
The display name you want to appear on your patches. This should probably match your Matrix display name, although it doesn't necessarily have to. td will deduce this from your system, and if you set it up properly, you may not even have to set this variable. If td gets it wrong, this allows you to override your display name.
Your preferred editor for writing patch file descriptions. This can be a GUI or terminal editor. If unset, this defaults to the system's vi(1) editor.
Your preferred pager for previewing patches. If left unset, this defaults to less(1).

.env
An environment file that contains lines in the form of VARIABLE=value with environment variables to set in the td script. See ENVIRONMENT. Note that td simply sources this file, which means that any shell code in it will be executed each time td is invoked.

td unconditionally exits with code 0, even if errors occurred. Furthermore, recipes are run unconditionally, regardless of whether or not any recipes before have failed.

April 29, 2023 Telodendria Project