From 5da3b9f9839d2acbbd362db5ab49ecd7b9d08482 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 29 Jul 2022 17:09:34 -0400 Subject: [PATCH] Begin documenting the build script. --- site/index.html | 72 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 10 deletions(-) diff --git a/site/index.html b/site/index.html index eb9c2cd..fdfaf60 100644 --- a/site/index.html +++ b/site/index.html @@ -598,7 +598,57 @@ I'll likely run my indent(1) on the code anyway though, just to make sure the spacing is consistent, if nothing else.

The Build Script

- +

+Telodendria uses a custom build script called td, +for Telodendria developer. The td 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 build Telodendria. +

+

+I opted to write a custom build script instead of just using +make, because I felt that there is really no way to make +a truly portable Makefile that could do everything I +need. I was doing a lot of research on the differences between the +GNU and BSD versions of make, and I felt it just wasn't +worth it when I could write a small POSIX script that would run on +both GNU systems and BSD systems without a fuss. I also wanted a way +to automate more than just building code. I wanted a system +versatile enough that I could define arbitrary recipes to do whatever +I want. I didn't want to be limited by the Makefile +syntax. +

+

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

+
+$ . contrib/td-env.sh +
+

+Note: You will have to run the above command every time you +start a new terminal session, as nothing is persisted. +

+

+If you're going to be submitting patches, you should also configure +a .env file, which td will include +automatically for you. For the best experience, you'll want at +least these values: +

+
+MXID=@your:matrix-id.net +DISPLAY_NAME="Your Display Name" +EDITOR=gedit # Or whatever your preferred editor is. +
+

+If you don't provide these values, td will deduce them +from your environment. It uses your system username and hostname to +create the MXID, and reads the password database to +get your configured display name. It also uses vi as +the default editor, which may not be suitable for all developers. +

Submitting Patches

Telodendria aims at remaining as minimal as possible. This doesn't @@ -614,35 +664,37 @@ opening a "pull request," you should be pleased to hear that submitting patches is fairly easy to do if you've got the CVS sources checked out. In fact, I find it easier than having to make a GitHub account, forking a project repository, and then making a pull request for it. Once you -have made your changes in your local copy of the code, just run the +have made your changes in your local copy of the code, and you've +configured your environment using the instructions in +The Build Script, just run the patch recipe:

-$ sh make.sh patch +$ td patch

-This will automatically generate the patch file from all your changes, +This will automatically generate a patch file for all your changes, and then open it in your default editor. You can set the EDITOR variable to your preferred editor if the default doesn't work for you. Either set it in your environment via your preferred means, or set it like this:

-$ EDITOR=gedit sh make.sh patch +$ EDITOR=gedit td patch

You can also generate a patch for only certain files and directories. -To do that, set PATCH, like this: +To do that, set PATCHSET, like this:

# Only write a patch for README.txt and the files in site/ -$ PATCH="README.txt site/" sh make.sh patch +$ PATCHSET="README.txt site/" td patch

-You can of course specify both PATCH and +You can of course specify both PATCHSET and EDITOR at the same time, if you want. But at that point, -it might make more sense to just set them in .env or in -your system environment. +it might make more sense to just EDITOR in your +.env or in your system environment.

As you'll notice, the top of the patch file should have some email-style