forked from Telodendria/Telodendria
Move man pages into a proper man directory
This commit is contained in:
parent
cfcef45c00
commit
2d6b80a26e
12 changed files with 1231 additions and 27 deletions
20
TODO.txt
20
TODO.txt
|
@ -75,7 +75,6 @@ Phase 4:
|
|||
[ ] Create an OpenBSD package and get it submitted to ports
|
||||
[ ] Add relayd examples to contrib/
|
||||
[ ] Create a command line tool to manage Telodendria
|
||||
[ ] Configuration file generation
|
||||
[ ] User management
|
||||
[ ] Room management
|
||||
[ ] Migrate from Synapse or Dendrite, whichever is more mainstream by the time we get here
|
||||
|
@ -100,7 +99,24 @@ Documentation
|
|||
[x] Convert documentation to man pages
|
||||
[x] Clean up dark mode in man page CSS (links)
|
||||
[x] Synopsis table should not be styled
|
||||
[ ] Internal API docs
|
||||
[x] Make available on MANPATH in tools/env.sh
|
||||
[~] Internal API docs
|
||||
[x] Array
|
||||
[x] Base64
|
||||
[ ] CanonicalJson
|
||||
[ ] Config
|
||||
[ ] Constants
|
||||
[ ] HashMap
|
||||
[ ] Http
|
||||
[ ] HttpServer
|
||||
[ ] Json
|
||||
[ ] Log
|
||||
[ ] Matrix
|
||||
[ ] NonPosix
|
||||
[ ] Queue
|
||||
[ ] Routes
|
||||
[ ] TelodendriaConfig
|
||||
[ ] Util
|
||||
|
||||
[ ] Add onboarding documentation
|
||||
[ ] Building from source
|
||||
|
|
1
man/.cvsignore
Normal file
1
man/.cvsignore
Normal file
|
@ -0,0 +1 @@
|
|||
mandoc.db
|
114
man/man3/Array.3
Normal file
114
man/man3/Array.3
Normal file
|
@ -0,0 +1,114 @@
|
|||
.Dd $Mdocdate: September 30 2022 $
|
||||
.Dt ARRAY 3
|
||||
.Os Telodendria Project
|
||||
.Sh NAME
|
||||
.Nm Array
|
||||
.Nd A simple dynamic array data structure.
|
||||
.Sh SYNOPSIS
|
||||
.In Array.h
|
||||
.Ft Array *
|
||||
.Fn ArrayCreate "void"
|
||||
.Ft void
|
||||
.Fn ArrayFree "Array *"
|
||||
.Ft int
|
||||
.Fn ArrayTrim "Array *"
|
||||
.Ft size_t
|
||||
.Fn ArraySize "Array *"
|
||||
.Ft void *
|
||||
.Fn ArrayGet "Array *" "size_t"
|
||||
.Ft int
|
||||
.Fn ArrayInsert "Array *" "void *" "size_t"
|
||||
.Ft int
|
||||
.Fn ArrayAdd "Array *" "void *"
|
||||
.Ft void *
|
||||
.Fn ArrayDelete "Array *" "size_t"
|
||||
.Ft void
|
||||
.Fn ArraySort "Array *" "int (*) (void *, void *)"
|
||||
.Sh DESCRIPTION
|
||||
These functions implement a simple array data structure that
|
||||
is automatically resized as necessary when new values are added.
|
||||
This implementation does not actually store the values of the
|
||||
items in it; it only stores pointers to the data. As such, you will
|
||||
still have to manually maintain all your data. The advantage of this
|
||||
is that these functions don't have to copy data, and thus don't care
|
||||
how big the data is. Furthermore, arbitrary data can be stored in the
|
||||
array.
|
||||
.Pp
|
||||
This array implementation is optimized for storage space and appending.
|
||||
Deletions are expensive in that all the items of the list above a deletion
|
||||
are moved down to fill the hole where the deletion occurred. Insertions are
|
||||
also expensive in that all the elements above the given index must be shifted
|
||||
up to make room for the new element.
|
||||
.Pp
|
||||
Due to these design choices, this array implementation is best suited to
|
||||
linear writing, and then linear or random reading.
|
||||
.Pp
|
||||
These functions operate on an array structure which is opaque to the
|
||||
caller.
|
||||
.Pp
|
||||
.Fn ArrayCreate
|
||||
and
|
||||
.Fn ArrayFree
|
||||
allocate and deallocate an array, respectively.
|
||||
Note that
|
||||
.Fn ArrayFree
|
||||
does not free any of the values stored in the array; it is the caller's
|
||||
job to manage the memory for each item. Typically, the caller would
|
||||
iterate over all the items in the array and free them before freeing
|
||||
the array.
|
||||
.Fn ArrayTrim
|
||||
reduces the amount of unused memory by calling
|
||||
.Xr realloc 3
|
||||
on the internal structure to perfectly fit the elements in the array. It
|
||||
is intended to be used by functions that return relatively read-only arrays
|
||||
that will be long-lived.
|
||||
.Pp
|
||||
.Fn ArrayInsert
|
||||
and
|
||||
.Fn ArrayDelete
|
||||
are the main functions used to modify the array.
|
||||
.Fn ArrayAdd
|
||||
is a convenience method that simply appends a value to the end of the
|
||||
array. It uses
|
||||
.Fn ArrayInsert .
|
||||
The array can also be sorted by using
|
||||
.Fn ArraySort ,
|
||||
which takes a pointer to a function that compares elements. The function
|
||||
should take two
|
||||
.Dv void
|
||||
pointers as parameters, and return an integer. The return value indicates
|
||||
to the algorithm how the elements relate to each other. A return value of
|
||||
0 indicates the elements are identical. A return value greater than 0
|
||||
indicates that the first item is "bigger" than the second item and should
|
||||
thus appear after it in the array, and a value less than zero indicates
|
||||
the opposite: the second element should appear after the first in the array.
|
||||
.Pp
|
||||
.Fn ArrayGet
|
||||
is used to get the element at the specified index.
|
||||
.Sh RETURN VALUES
|
||||
.Fn ArrayCreate
|
||||
returns a pointer on the heap to a newly allocated array structure, or
|
||||
.Dv NULL
|
||||
if the allocation fails.
|
||||
.Pp
|
||||
.Fn ArrayGet
|
||||
and
|
||||
.Fn ArrayDelete
|
||||
return pointers to values that were put into the array, or
|
||||
.Dv NULL
|
||||
if the provided array is
|
||||
.Dv NULL
|
||||
or the provided index was out of bounds.
|
||||
.Fn ArrayDelete
|
||||
returns the element at the specified index after removing it so that
|
||||
it can be properly handled by the caller.
|
||||
.Pp
|
||||
.Fn ArrayTrim ,
|
||||
.Fn ArrayInsert ,
|
||||
and
|
||||
.Fn ArrayAdd
|
||||
return a boolean value indicating their status. They return a value of zero
|
||||
on failure, and a non-zero value on success.
|
||||
.Sh SEE ALSO
|
||||
.Xr HashMap 3 ,
|
||||
.Xr Queue 3
|
81
man/man3/Base64.3
Normal file
81
man/man3/Base64.3
Normal file
|
@ -0,0 +1,81 @@
|
|||
.Dd $Mdocdate: September 30 2022 $
|
||||
.Dt BASE64 3
|
||||
.Os Telodendria Project
|
||||
.Sh NAME
|
||||
.Nm Base64
|
||||
.Nd A simple base64 encoder/decoder with "unpadded base64" support.
|
||||
.Sh SYNOPSIS
|
||||
.In Base64.h
|
||||
.Ft size_t
|
||||
.Fn Base64EncodedSize "size_t"
|
||||
.Ft size_t
|
||||
.Fn Base64DecodedSize "const char *" "size_t"
|
||||
.Ft char *
|
||||
.Fn Base64Encode "const char *" "size_t"
|
||||
.Ft char *
|
||||
.Fn Base64Decode "const char *" "size_t"
|
||||
.Ft void
|
||||
.Fn Base64Unpad "char *" "size_t"
|
||||
.Ft int
|
||||
.Fn Base64Pad "char **" "size_t"
|
||||
.Sh DESCRIPTION
|
||||
This is an efficient yet simple base64 encoding and decoding
|
||||
library that supports regular base64, as well as the Matrix
|
||||
specification's extension to base64, called "unpadded base64."
|
||||
.Nm provides the ability to convert between the two, instead of
|
||||
just implementing "unpadded base64."
|
||||
.Pp
|
||||
.Fn Base64EncodedSize
|
||||
and
|
||||
.Fn Base64DecodedSize
|
||||
compute the amount of characters needed to store an encoded or
|
||||
decoded message, respectively. Both functions take the size of
|
||||
the message being encoded or decoded, but
|
||||
.Fn Base64DecodedSize
|
||||
also takes a pointer to an encoded string, because a few bytes of
|
||||
the string need to be read in order to compute the size.
|
||||
.Pp
|
||||
.Fn Base64Encode
|
||||
and
|
||||
.Fn Base64Decode
|
||||
do the actual work of encoding and decoding base64 data. They both
|
||||
take a string and its length.
|
||||
.Pp
|
||||
.Fn Base64Unpad
|
||||
and
|
||||
.Fn Base64Pad
|
||||
are used to implement Matrix unpadded base64.
|
||||
.Fn Base64Unpad
|
||||
takes a valid base64 string and strips off the trailing equal signs,
|
||||
as per the specification.
|
||||
.Fn Base64Pad
|
||||
does the opposite; it takes an unpadded base64 input string, and pads
|
||||
it with equal signs as necessary, so that it can be properly decoded
|
||||
with
|
||||
.Fn Base64Decode
|
||||
if necessary. However, the Matrix specification envisons unpadded base64
|
||||
as opaque; that is, once it's encoded, it never needs to be decoded.
|
||||
In practice, a homeserver might need to decode an unpadded base64 string.
|
||||
.Sh RETURN VALUES
|
||||
.Fn Base64EncodedSize
|
||||
and
|
||||
.Fn Base64DecodedSize
|
||||
simply return unsigned integers representing a number of bytes generated
|
||||
from a simple computation.
|
||||
.Pp
|
||||
.Fn Base64Encode
|
||||
and
|
||||
.Fn Base64Decode
|
||||
return pointers to new strings, allocated on the heap, or
|
||||
.Dv NULL
|
||||
if a heap allocation fails. These pointers must be
|
||||
.Xr free 3 -ed
|
||||
at some point when they are no longer needed.
|
||||
.Pp
|
||||
.Fn Base64Unpad
|
||||
modifies the passed string in-place. It thus has no return value, because
|
||||
it cannot fail. If the passed pointer is invalid, the behavior is undefined.
|
||||
.Fn Base64Pad
|
||||
returns a boolean value indicating whether the pad operation was successful.
|
||||
In practice, this function will only fail if a bigger string is necessary, but
|
||||
could not be automatically allocated on the heap.
|
190
man/man5/telodendria.conf.5
Normal file
190
man/man5/telodendria.conf.5
Normal file
|
@ -0,0 +1,190 @@
|
|||
.Dd $Mdocdate: September 30 2022 $
|
||||
.Dt TELODENDRIA.CONF 5
|
||||
.Os Telodendria Project
|
||||
.Sh NAME
|
||||
.Nm telodendria.conf
|
||||
.Nd Configuration file for Telodendria
|
||||
.Sh DESCRIPTION
|
||||
.Nm
|
||||
is the configuration file for the Telodendria homeserver,
|
||||
.Xr telodendria 8 .
|
||||
Telodendria is designed to be extremely configurable. As such,
|
||||
it has a fairly extensive configuration file. The configuration
|
||||
file can be passed to the Telodendria binary with the
|
||||
.Sy -f
|
||||
option, and is typically located at
|
||||
.Pa /etc/telodendria.conf
|
||||
.sp
|
||||
.Nm
|
||||
uses OpenBSD-style syntax, though it is a little more rigid in its
|
||||
parser. All values must be surrounded by quotes, and each directive
|
||||
must be ended with a semicolon.
|
||||
.Sh MACROS
|
||||
Macros can be defined that will later be expanded in context.
|
||||
Macro names must start with a letter, digit, or underscore, and may
|
||||
contain only those characters. Macros are not expanded inside quotes.
|
||||
.sp
|
||||
For example:
|
||||
.Bd -literal -offset indent
|
||||
macro1 = "value1";
|
||||
directive $macro1;
|
||||
.Ed
|
||||
.Sh GLOBAL OPTIONS
|
||||
Here are the settings that can be set globally:
|
||||
.Bl -tag -width Ds
|
||||
.It Ic listen Ar port
|
||||
The port to listen on. Telodendria will bind to all interfaces, but it
|
||||
is recommended to configure your firewall so that it only listens on
|
||||
localhost, and then configure a reverse proxy such as
|
||||
.Xr relayd 8
|
||||
in front of it, because Telodendria does not implement TLS. Note that
|
||||
Telodendria doesn't provide multiple ports for the various services it
|
||||
offers. ALl APIs are made available over the same port, so care should
|
||||
be taken in
|
||||
.Xr relayd.conf 5
|
||||
to ensure that only the public Matrix API paths are made available over
|
||||
the internet.
|
||||
.Ar port
|
||||
should be a decimal port number. This directive is entirely optional. If
|
||||
it is omitted, then Telodendria will listen on port 8008 by default.
|
||||
.It Ic server-name Ar name
|
||||
Configure the domain name of your homeserver. Note that Matrix servers
|
||||
cannot be migrated to other domains, so once this is set, it should never
|
||||
change unless you want unexpected things to happen, or you want to start
|
||||
over.
|
||||
.Ar name
|
||||
should be a DNS name that can be publically resolved. This directive
|
||||
is required.
|
||||
.It Ic base-url Ar url
|
||||
Set the server's base URL.
|
||||
.Ar url
|
||||
should be a valid URL, complete with the protocol. It does not need to
|
||||
be the same as the server name; in fact, it is common for a subdomain of
|
||||
the server name to be the base URL for the Matrix homeserver.
|
||||
.Pp
|
||||
This URL is the URL at which Matrix clients will connect to the server,
|
||||
and is thus served as a part of the
|
||||
.Pa .well-known
|
||||
manifest.
|
||||
.Pp
|
||||
This directive is optional. If it is not specified, it is automatically
|
||||
deduced from the server name.
|
||||
.It Ic identity-server Ar url
|
||||
The identity server that clients should use to perform identity lookups.
|
||||
.Pp
|
||||
.Ar url
|
||||
follows the same rules as
|
||||
.Ic base-url .
|
||||
.Pp
|
||||
This directive is optional. If it is not specified, it is automatically
|
||||
set to be the same as the base URL.
|
||||
.It Ic chroot Ar directory
|
||||
Change the root directory to the specified directory as soon as possible.
|
||||
Note that all other paths and files specified in
|
||||
.Nm
|
||||
must be accessible relative from this directory. This directive only
|
||||
takes effect if Telodendria is running as root. If it isn't, then a
|
||||
warning is printed to the log, and no
|
||||
.Xr chroot 2
|
||||
call is made. In that case, Telodendria will still change into the
|
||||
specified directory, so that the other paths referenced can be made
|
||||
relative to this one. This directive is required. It is expected that
|
||||
the homeserver data and logs will be stored in a subdirectory of this one.
|
||||
.It Ic id Ar uid Ar gid
|
||||
The effective UNIX user and group to drop to after binding to the socket
|
||||
and changing the filesystem root. This only works if Telodendria is
|
||||
running as the root user, and is used as a security mechanism. If Telodendria
|
||||
is started as a non-priviledged user, then a warning is printed to the log
|
||||
if that user does not match what's specified here. This directive is
|
||||
required, even if Telodendria is unable to switch to the given user and
|
||||
group. It should be used as a sanity check to make sure the permissions are
|
||||
working properly.
|
||||
.It Ic data-dir Ar directory
|
||||
The data directory into which Telodendria will write all user and event
|
||||
information. Telodendria doesn't use a database like other Matrix homeserver
|
||||
implementations; it uses a flat-file directory structure, similar to how an
|
||||
SMTP server uses Maildirs to deliver email. This directive is required.
|
||||
.Ar directory
|
||||
should be a path relative to the
|
||||
.Ic chroot
|
||||
directory. Don't depend on the
|
||||
.Ic chroot
|
||||
option working, because there may be legitimate cases when Telodendria will
|
||||
not be started as root, thus causing the chroot to fail.
|
||||
.It Ic federation Ar true|false
|
||||
Whether to enable federation with other Matrix homeservers or not. Matrix is
|
||||
by its very nature a federated protocol, but if you just want to run your
|
||||
own internal chat server with no contact with the outside, then you can use
|
||||
this option to disable federation. It is highly recommended to set this to
|
||||
.Ar true ,
|
||||
however, if you wish to be able to communicate with users on other Matrix
|
||||
servers. This directive is required.
|
||||
.It Ic registration Ar true|false
|
||||
Whether or not to enable new user registration or not. For security and anti-spam
|
||||
reasons, you can set this to
|
||||
.Ar false .
|
||||
If you do, you can still add users via the administrator API. In an ideal world,
|
||||
everyone would run their own homeserver, so no public registration would ever
|
||||
be required. Unfortunately, not everyone has the means to run their own homeserver,
|
||||
especially because of the fact that public IPv4 addresses are becoming increasingly
|
||||
harder to come by. If you would like to provide a service to those that are unable
|
||||
to run their own homeserver, you can aset this to
|
||||
.Ar true ,
|
||||
which will allow anyone to create an account. Telodendria should be capable of handling
|
||||
a large amount of users without difficulty or security issues. This directive is
|
||||
required.
|
||||
.It Ic log Ar file|stdout
|
||||
The log configuration. Telodendria uses its own logging facility, which can output to
|
||||
either standard output or a file. A number of child directives can be added to this
|
||||
directive to customize the log output:
|
||||
.Bl -tag -width Ds
|
||||
.It Ic level Ar error|warning|task|message|debug
|
||||
The level of messages to log at. Each level shows all the levels above it. For
|
||||
example, setting the level to
|
||||
.Ar error
|
||||
will show only errors, while setting the level to
|
||||
.Ar warning
|
||||
will show warnings and errors.
|
||||
.Ar task
|
||||
shows tasks, warnings, and errors, and so on. The
|
||||
.Ar debug
|
||||
level shows all messages.
|
||||
.It Ic timestampFormat Ar format|none|default
|
||||
If you want to customize the timestamp format shown in the log, or disable it
|
||||
altogether, you can do so via this option. Acceptable values are
|
||||
.Ar none ,
|
||||
.Ar default ,
|
||||
or a formatter string as described by your system's
|
||||
.Xr strftime 3 .
|
||||
.It Ic color Ar true|false
|
||||
Whether or not to enable colored output on TTYs. Note that ANSI color sequences
|
||||
will not be written to a log file, only a real terminal, so this option only
|
||||
applies if the log is being written to a standard output which is connected to
|
||||
a terminal.
|
||||
.El
|
||||
.It Ic threads Ar count
|
||||
How many worker threads to spin up to handle requests. This should generally be
|
||||
less than the total CPU core count, to prevent overloading the system. The most
|
||||
efficient number of threads ultimately depends on the configuration of the
|
||||
machine running Telodendria, so you may just have to play around with different
|
||||
values here to see which gives the best performance.
|
||||
.El
|
||||
.Sh FILES
|
||||
.Bl -tag -width Ds
|
||||
.It Pa /etc/telodendria.conf
|
||||
The default
|
||||
.Xr telodendria 8
|
||||
configuration file.
|
||||
.It Pa /var/telodendria
|
||||
The recommended chroot directory.
|
||||
.El
|
||||
.Sh EXAMPLES
|
||||
Please consult the default
|
||||
.Nm
|
||||
that ships with Telodendria for a complete example. If you installed Telodendria
|
||||
as a package, then the example should be located at the default location. If you
|
||||
are building from source, you can find the default config in the
|
||||
.Pa contrib/
|
||||
directory.
|
||||
.Sh SEE ALSO
|
||||
.Xr telodendria 8
|
252
man/man7/contributing.7
Normal file
252
man/man7/contributing.7
Normal file
|
@ -0,0 +1,252 @@
|
|||
.Dd $Mdocdate: September 30 2022 $
|
||||
.Dt CONTRIBUTING 7
|
||||
.Os Telodendria Project
|
||||
.Sh NAME
|
||||
.Nm contributing
|
||||
.Nd Guide to contributing to Telodendria
|
||||
.Sh DESCRIPTION
|
||||
Telodendria is an open source project. As such, it welcomes
|
||||
contributions. There are many ways you can contribute, and any
|
||||
way you can is greatly appreciated. This page contains some of
|
||||
the ways you can help out.
|
||||
.Sh REPORTING ISSUES
|
||||
Please reach out to the Matrix rooms mentioned at the top of
|
||||
.Xr telodendria 7 .
|
||||
All issue tracking takes place in those rooms. Start by reaching
|
||||
out to the general room, and if you think there's a legitimate
|
||||
problem with Telodendria itself, then stick the issue in the
|
||||
issues room, where it can be discussed further. Issues usually
|
||||
remain in the Matrix rooms, but severe enough issues may be put
|
||||
in a
|
||||
.Pa TODO
|
||||
file in the
|
||||
.Xr cvs 1
|
||||
repository so that they don't get lost.
|
||||
.Sh DEVELOPING
|
||||
The primary language used to write Telodendria code is ANSI C.
|
||||
Other languages you'll find in the Telodendria repository include
|
||||
shell scripts,
|
||||
.Xr mdoc 7 ,
|
||||
and a little bit of HTML and CSS. If you have any experience with
|
||||
any of these languages, your contributions are valuable! Please follow
|
||||
the guidelines on this page to ensure the contribution workflow goes
|
||||
as smoothly as possible.
|
||||
.Ss Getting the Code
|
||||
If you'd like to hack on Telodendria, you'll need the following tools
|
||||
in addition to a C compiler and POSIX shell:
|
||||
.Bl -tag
|
||||
.It Xr cvs 1
|
||||
For checking out and updating your local copy of the source code.
|
||||
.It Xr indent 1
|
||||
For formatting your code before generating patches.
|
||||
.It Xr patch 1
|
||||
For applying patches to your local copy of the source code.
|
||||
.El
|
||||
.sp
|
||||
All of these tools are built into OpenBSD. While you don't have to
|
||||
use OpenBSD to develop Telodendria, it may make the process a bit
|
||||
easier. In fact, these tools where chosen precisely because they
|
||||
were built into my operating system of choice.
|
||||
.sp
|
||||
You can download an official release tarball from the website if
|
||||
you would really like, but the preferred way to get the source
|
||||
code for development is to check it out from CVS. This makes generating
|
||||
patches a lot easier.
|
||||
.Bd -literal -offset indent
|
||||
$ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria
|
||||
$ cd Telodendria
|
||||
.Ed
|
||||
.sp
|
||||
If you already checked out the code previously, make sure you update
|
||||
your local copy before you start developing:
|
||||
.Bd -literal -offset indent
|
||||
$ cvs -q update -dP
|
||||
.Ed
|
||||
.sp
|
||||
You should now have the latest source code. Follow the
|
||||
.Sx CODE STYLE
|
||||
as you make your changes. If the
|
||||
.Xr cvs 1
|
||||
command fails with a "Connection refused" error message, try setting
|
||||
the
|
||||
.Ev CVS_RSH
|
||||
environment variable to "ssh", like this:
|
||||
.Bd -literal -offset indent
|
||||
$ export CVS_RSH=ssh
|
||||
.Ed
|
||||
.sp
|
||||
Then run the checkout command again. Some versions of CVS on some
|
||||
systems don't use SSH to checkout by default, so if yours doesn't,
|
||||
you might want to put the above line into your shell init script.
|
||||
.Ss Submitting Patches
|
||||
Telodendria aims at remaining as minimal as possible. This doesn't just
|
||||
mean minimal code, it also means a minimal development process, which is
|
||||
why Telodendria doesn't use GitHub, GitLab, or even SourceHut. Instead,
|
||||
the contribution workflow operates on submitting patch files to a public
|
||||
Matrix room, sort of like the OpenBSD project operates on patch files
|
||||
sent to a public mailing list.
|
||||
.sp
|
||||
If you're not used to manually creating and submitting patches instead of
|
||||
just 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's repository, and then making a pull request for it. Once you have
|
||||
made your changes in your local copy of the code, and you've configured your
|
||||
environment properly as noted in the manual for
|
||||
.Xr td 8 ,
|
||||
just run the patch recipe:
|
||||
.Bd -literal -offset indent
|
||||
$ td patch
|
||||
.Ed
|
||||
.sp
|
||||
This will automatically generate a patch file for all your changes, and then
|
||||
open it in your preferred editor. You can also generate a patch file for only
|
||||
certain files and directories. To do that, set
|
||||
.Ev PATCHSET ,
|
||||
like this:
|
||||
.Bd -literal -offset indent
|
||||
# Only write a patch for README.txt and the files in docs/
|
||||
$ PATCHSET="README.txt docs/" td patch
|
||||
.Ed
|
||||
.sp
|
||||
As you'll notice, the top of the patch file should have some email-style
|
||||
headers that look like this:
|
||||
.Bd -literal -offset indent
|
||||
From: Jordan Bancino <@jordan:bancino.net>
|
||||
Date: Fri Jul 29 03:21:21 PM EDT 2022
|
||||
Subject: Document Patch Procedure
|
||||
.Ed
|
||||
.sp
|
||||
As much information should be filled out for you, such as the date. An
|
||||
attempt to fill out the From header was also made by
|
||||
.Xr td 8 ,
|
||||
but the information there can be modifed as necessary. Consult the manual
|
||||
for
|
||||
.Xr td 8
|
||||
for more details. The Subject should very briefly describe what the patch
|
||||
is about.
|
||||
.sp
|
||||
You'll also notice these lines in the patch:
|
||||
.Bd -literal -offset indent
|
||||
[ ] I have read the Telodendria Project development certificate of
|
||||
origin, and certify that I have permission to submit this patch
|
||||
under the conditions specified in it.
|
||||
.Ed
|
||||
.sp
|
||||
This is a checkbox that tells me whether or not you actually have the
|
||||
rights to submit your patch, and that once you submit your patch, your
|
||||
code is bound by the Telodendria project license, which you can and
|
||||
should view in
|
||||
.Xr telodendria 7 .
|
||||
The full text of the developer certificate of origin is as follows:
|
||||
.Bl -enum
|
||||
.It
|
||||
The contribution was created in whole or in part by me, and I have the right
|
||||
to submit it under the open source licenses of the Telodendria project; or
|
||||
.It
|
||||
The contribution is based upon a previous work that, to the best of my knowledge,
|
||||
is covered under an appropriate open source license and I have the right under
|
||||
that license to submit that work with modifications, whether created in whole
|
||||
or in part by me, under the Telodendria project license; or
|
||||
.It
|
||||
The contribution whas provided directly to me by some other person who certified
|
||||
(1), (2), or (3), and I have not modifed it.
|
||||
.It
|
||||
I understand and agree that this project and the contribution are made public
|
||||
and that a record of the contribution\(emincluding all personal information
|
||||
I submit with it\(emis maintained indefinitely and may be redistributed
|
||||
consistent with this project or the open source licenses involved.
|
||||
.El
|
||||
.sp
|
||||
If you agree to the above, fill in the square brackets with an 'x', and then after
|
||||
the headers, but before the checkbox, write a more thorough description of the
|
||||
patch and why it was created. Then, send the resulting patch file to the public
|
||||
Matrix room, as noted in
|
||||
.Xr telodendria 7 ,
|
||||
so it can be discussed and reviewed by the community.
|
||||
.sp
|
||||
Try to keep your patches on topic\(emmake one patch file per feature or bug fix
|
||||
being implemented. It is okay if your patches depend on previous patches, just
|
||||
indicate that in the patch description. Note that it may take a while for
|
||||
patches to be committed, and some patches may not be comitted at all. In either
|
||||
case, all sent patches are queued from the Matrix room into the public patch
|
||||
directory, so they can be referenced easier in the future. If you want to
|
||||
reference a submitted patch in a Matrix message, email, or other digital medium,
|
||||
it might be a good idea to link to it in the public patch directory.
|
||||
.sp
|
||||
The public patch directory works as follows: when you send your patch to the
|
||||
Matrix room, it is downloaded by Telodendria Bot and placed in the
|
||||
.Pa ingress/
|
||||
directory, named as the message ID. Then, it is assigned a patch ID and
|
||||
copied to the
|
||||
.Pa p/
|
||||
directory as just "%d.patch", where "%d" is obviously the patch ID. This is
|
||||
a permanent link that will always reference your patch. Then, your patch will
|
||||
be symlinked into the
|
||||
.Pa queue/
|
||||
directory. I have a script that automatically ingresses patches and queues them
|
||||
for me, and I use this to review patches. If your patch is accepted, the queue
|
||||
symlink will be moved to
|
||||
.Pa accepted/
|
||||
and the submitted patch will be committed to the official CVS repository.
|
||||
If your patch is rejected for some reason, its symlink will be moved to the
|
||||
.Pa rejected/
|
||||
directory. Regardless of the state of your patch, it will always remain
|
||||
permalinked in the
|
||||
.Pa p/
|
||||
directory, and when it is accepted or rejected, Telodendria Bot will send a
|
||||
message to the Matrix room.
|
||||
.sp
|
||||
You're always welcome to inquire about rejected patches, and request that they
|
||||
be reviewed again, or you can use them as a starting point for future patches.
|
||||
.sp
|
||||
The public patch directory is located at
|
||||
.Lk https://telodendria.io/patches/
|
||||
.Sh CODE STYLE
|
||||
In general, these are the conventions used by the code base. This guide
|
||||
may be slightly outdated or subject to change, but it should be a good
|
||||
start. The source code itself is always the absolute source of truth, so
|
||||
as long as you make your code look like the code surrounding it, you should
|
||||
be fine.
|
||||
.Bl -bullet
|
||||
.It
|
||||
All function, enumeration, structure, and header names are CamelCase. This
|
||||
is preferred to snake_case because it is more compact.
|
||||
.It
|
||||
All variable names are lowerCamelCase. This is preferred to snake_case
|
||||
because it is more compact.
|
||||
.It
|
||||
enumerations and structures are always typedef-ed to their same name. The
|
||||
typedef should occur in the public API header, and the actual declaration
|
||||
should live in the implementation file.
|
||||
.It
|
||||
A feature of the code base lives in a single C source file that has a
|
||||
matching header. The header file should only export public symbols;
|
||||
everything else in the C source should be static.
|
||||
.It
|
||||
Except where absolutely necessary, global variables are forbidden to
|
||||
prevent problems with threads and whatnot. Every variable a function
|
||||
needs should be passed to it either through a structure, or as a
|
||||
separate argument.
|
||||
.It
|
||||
Anywhere curly braces are optional, there still must be curly braces. This
|
||||
makes it easier to add on to the code later, and just makes things a bit
|
||||
less ambiguous.
|
||||
.El
|
||||
.sp
|
||||
As far as actually formatting the code goes, such as where to put brackets,
|
||||
and whether or not to use tabs or spaces, use
|
||||
.Xr indent 1
|
||||
to take care of all of that. The root of the CVS repository has a
|
||||
.Pa .indent.pro
|
||||
that should automatically be loaded by
|
||||
.Xr indent 1
|
||||
to set the correct rules. If you don't have a working
|
||||
.Xr indent 1 ,
|
||||
then just indicate in your patch that I should run my
|
||||
.Xr indent 1
|
||||
on the code after applying it. Although in reality, I'll likely
|
||||
run my own
|
||||
.Xr indent 1
|
||||
on the code anyway, just to make sure the spacing is consistent, if nothing
|
||||
else.
|
248
man/man7/telodendria.7
Normal file
248
man/man7/telodendria.7
Normal file
|
@ -0,0 +1,248 @@
|
|||
.Dd $Mdocdate: September 30 2022 $
|
||||
.Dt TELODENDRIA 7
|
||||
.Os Telodendria Project
|
||||
.Sh NAME
|
||||
.Nm Telodendria
|
||||
.Nd The terminal branches of an axon.
|
||||
.Sh DESCRIPTION
|
||||
.Nm
|
||||
is an open source Matrix homeserver written entirely from scratch in ANSI C.
|
||||
It is designed to be lightweight and simple, yet functional.
|
||||
.Pp
|
||||
.Sy Note:
|
||||
.Nm
|
||||
is under
|
||||
.Sy heavy
|
||||
development. Please see
|
||||
.Sx PROJECT STATUS .
|
||||
.Pp
|
||||
.Nm
|
||||
differentiates itself from the other Matrix homeserver
|
||||
implementations because it:
|
||||
.Bl -bullet
|
||||
.It
|
||||
Is written in C, a stable, low-level programming language with a
|
||||
long history, low build and runtime overhead, and wide compatibility.
|
||||
.It
|
||||
Is written with minimalism as a primary design goal. Whenever possible
|
||||
and practical, no third-party libraries are pulled into the source code.
|
||||
Everything
|
||||
.Nm
|
||||
needs is custom written. As a result,
|
||||
.Nm
|
||||
depends only on a standard C compiler and a POSIX C library to be built,
|
||||
both of which should come with any good Unix-style operating system already,
|
||||
which means you shouldn't have to install anything extra.
|
||||
.It
|
||||
Uses a flat-file directory structure to store data instead of a database.
|
||||
This has a number of advantages:
|
||||
.Bl -bullet
|
||||
.It
|
||||
It makes setup and maintenance much easier.
|
||||
.It
|
||||
It allows
|
||||
.Nm
|
||||
to run on systems with fewer resources.
|
||||
.El
|
||||
.It
|
||||
Is packaged as a single small, statically-linked and highly-optimized binary
|
||||
that can be run just about anywhere. It is designed to be extremely easy to
|
||||
set up and consume as few resources as possible.
|
||||
.It
|
||||
Is permissively licensed.
|
||||
.Nm
|
||||
is licensed under a modified MIT license, which imposes very few restrictions
|
||||
on what you can do with it.
|
||||
.El
|
||||
.Pp
|
||||
.Nm
|
||||
is on Matrix! Check out the official Matrix rooms:
|
||||
.Pp
|
||||
.TS
|
||||
box tab(;);
|
||||
l l.
|
||||
#telodendria:bancino.net;The public "space" room.
|
||||
#telodendria-releases:bancino.net;Get notified of new releases.
|
||||
#telodendria-general:bancino.net;General discussion and support.
|
||||
#telodendria-issues:bancino.net;Report bugs and issues.
|
||||
#telodendria-patches:bancino.net;Submit code patches to the project.
|
||||
.TE
|
||||
.Nm
|
||||
is designed to be fairly straightforward, but that doesn't mean there
|
||||
won't be hiccups along the way. If you're struggling to get
|
||||
.Nm
|
||||
up and running, you're more than welcome to reach out for support. Just
|
||||
hop into the appropriate Matrix rooms and talk to me!
|
||||
.Sh RATIONALE
|
||||
I want a lightweight Matrix homeserver designed specifically for OpenBSD,
|
||||
and other Unix-like operating systems. I want a homeserver that can be
|
||||
developed and compiled with built-in tools. I want it to function entirely
|
||||
on a base OS install without having to install any packages whatsoever. I've
|
||||
found that as far as these goals are concerned, the existing homeserver
|
||||
implementations fall short. This project aims to prove that Matrix homeservers
|
||||
can be lightweight and written in such a way that very few, if any, third-party
|
||||
libraries need to be pulled in.
|
||||
.Pp
|
||||
I also want to learn how Matrix works, and I want to understand the code I'm
|
||||
running on my server, which is why I'm writing every component from scratch,
|
||||
even the HTTP server and router.
|
||||
.Pp
|
||||
The advantage of using a flat-file database instead of a real database is that
|
||||
your data remains in a format that is incredibly easy to digest. Backups are
|
||||
incredibly easy as well\(emjust
|
||||
.Xr tar 1
|
||||
up the data directory and you're good to go.
|
||||
.Sh PROJECT GOALS
|
||||
The goals of this project are generally divided into user goals and developer
|
||||
goals, depending on who they impact the most. This isn't an exaustive list
|
||||
of the project's goals, but it is a list of things that I want to prioritize,
|
||||
because other server implementations lack them.
|
||||
.Pp
|
||||
The user goals are as follows:
|
||||
.Bl -bullet
|
||||
.It
|
||||
To implement the latest Matrix specification as fully and completely as possible.
|
||||
All features defined by the specification should eventually be present in
|
||||
.Nm .
|
||||
.It
|
||||
To be as privacy-friendly as possible.
|
||||
.Nm
|
||||
should not store any information it does not absolutely need to function as a
|
||||
Matrix homeserver. While
|
||||
.Nm
|
||||
strives to be feature-complete, it should not implement anything not explicitly
|
||||
defined in the Matrix specification.
|
||||
.It
|
||||
To be a production-ready Matrix server capable of working in constrained environments,
|
||||
such as embedded devices, cheap VPSs, or a peer-to-peer device.
|
||||
.Nm
|
||||
should also work on traditional setups as well, and be able to handle a decent
|
||||
amount of users. It should work well for personal Matrix homeservers that also
|
||||
host a few friends and/or family members.
|
||||
.It
|
||||
To be easier to get up and running, and yet also be more configurable than other
|
||||
Matrix homeserver implementations. The configuration file should be flexible,
|
||||
well-documented, and easy to understand and modify. An intuitive command-line
|
||||
tool for administrative tasks should also be available.
|
||||
.El
|
||||
.Pp
|
||||
The developer goals are as follows:
|
||||
.Bl -bullet
|
||||
.It
|
||||
To have as few build and runtime dependencies as possible. It should be possible
|
||||
to compile and run
|
||||
.Nm
|
||||
on any POSIX operating system right out of the box.
|
||||
.Nm
|
||||
should be fully statically-linked, so it can run under a
|
||||
.Xr chroot 3 .
|
||||
Furthermore, it should be possible to read all the documentation offline, and
|
||||
without any overly complicated tools. You'll notice that this documentation is
|
||||
a collection of
|
||||
.Xr man 1
|
||||
pages, not HTML or Markdown, to remove the dependency on a browser or Markdown
|
||||
parser. Any Unix-like system has a manual page viewer, which makes the
|
||||
documentation more accessible, even on remote systems that have no graphical
|
||||
interface to read the documentation. This ensures that you can read the
|
||||
documentation for the installed version of
|
||||
.Nm
|
||||
without having to go online.
|
||||
.It
|
||||
To have a simple yet elegant workflow, and not depend on any large or complex
|
||||
development tools such as code forges. The entire development workflow should
|
||||
be able to be successfully and efficiently completed on a base OpenBSD install.
|
||||
Of course, you don't have to use OpenBSD for development, but the point is that
|
||||
the workflow should require fairly standardized and simple tools.
|
||||
.It
|
||||
To write clean, elegant, well-tested, and well-documented code. The goal is to build
|
||||
a Matrix homeserver from the ground up, not just because I don't like the way existing
|
||||
homeservers are implemented, but also because I want to learn how Matrix works,
|
||||
make it more accessible, and potentially teach others a little bit along the way.
|
||||
.It
|
||||
To foster a welcoming community. Many big communities such as Linux and OpenBSD
|
||||
have hostile leaders.
|
||||
.Nm
|
||||
shouldn't have a hostile leader. I want to be as understanding as I can, and talk
|
||||
through issues politely and in a civil manner. If I'm failing in this way, don't
|
||||
be afraid to call me out!
|
||||
.El
|
||||
.Sh PROJECT STATUS
|
||||
Telodendria is a very ambitious project. There's a lot that needs to happen yet
|
||||
before it is usable. At the moment, there's nothing here that even remotely resembles
|
||||
a Matrix homeserver. I'm still getting off the ground and building a foundation.
|
||||
.Pp
|
||||
But just because there's nothing here yet doesn't mean you should go away! I could
|
||||
always use help, so you are more than welcome to help out if you want things to go
|
||||
quicker. Please see the
|
||||
.Xr contributing 7
|
||||
page for details on how you can get involved. The CVS repository has a file called
|
||||
.Pa TODO.txt ,
|
||||
which contains a checklist of what has been done so far, and what's on the radar
|
||||
to be done. You can take a look at it once you've checked out the source code.
|
||||
If you'd like to help out, feel free to grab an item on the list that's not done
|
||||
yet and start getting patches written. When you're done, enjoy the satisfaction
|
||||
of crossing the item off the list yourself.
|
||||
.Sh SEE ALSO
|
||||
.Xr telodendria 8 ,
|
||||
.Xr telodendria.conf 5 ,
|
||||
.Xr td 8
|
||||
.Sh STANDARDS
|
||||
The installed version of
|
||||
.Nm
|
||||
conforms to the latest Matrix specification available at the time
|
||||
of its release.
|
||||
.Sh HISTORY
|
||||
At this time,
|
||||
.Nm
|
||||
does not have any tagged releases because it is not yet functional
|
||||
as a Matrix homeserver. Please checkout out
|
||||
.Sx PROJECT STATUS
|
||||
to see where things are currently at. When
|
||||
.Nm
|
||||
is mature enough to have a change log, it will go in this section.
|
||||
.Sh AUTHORS
|
||||
.Nm
|
||||
was started by Jordan Bancino <@jordan:bancino.net>.
|
||||
Contributions to the code, website, documentation, or other
|
||||
components of
|
||||
.Nm
|
||||
were made by the following people:
|
||||
.Bl -bullet
|
||||
.It
|
||||
Jonah Evans <@jonah:bancino.net>
|
||||
.El
|
||||
.Sh LICENSE
|
||||
All of the code and documentation for
|
||||
.Nm
|
||||
is licensed under a modified MIT license. Please consult the
|
||||
.Pa LICENSE.txt
|
||||
file for the actual license text. The
|
||||
.Nm
|
||||
license text differs from the MIT license in the following ways:
|
||||
.Bl -bullet
|
||||
.It
|
||||
Where the MIT license states that the copyright notice and permission
|
||||
notice shall be included in all copies or
|
||||
.Pa substantial
|
||||
portions of the software, the
|
||||
.Nm
|
||||
license requires the copyright notice and permission notice be included
|
||||
with
|
||||
.Pa all
|
||||
portions, regardless of the size, of the software by omitting the word
|
||||
.Pa substantial .
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Nm
|
||||
logo, however, belongs solely to the
|
||||
.Nm
|
||||
project. It must only be used to represent the official
|
||||
.Nm
|
||||
project, and may only appear in official
|
||||
.Nm
|
||||
media. If
|
||||
.Nm
|
||||
is forked, the logo must be removed completely from the project, and
|
||||
optionally replaced with a different one. The logo may not be modified
|
||||
in any way or for any purpose.
|
238
man/man8/td.8
Normal file
238
man/man8/td.8
Normal file
|
@ -0,0 +1,238 @@
|
|||
.Dd $Mdocdate: September 30 2022 $
|
||||
.Dt TD 8
|
||||
.Os Telodendria Project
|
||||
.Sh NAME
|
||||
.Nm td
|
||||
.Nd Telodendria build script
|
||||
.Sh SYNOPSIS
|
||||
.Nm
|
||||
.Op recipe
|
||||
.Sh DESCRIPTION
|
||||
Telodendria uses a custom build script called
|
||||
.Nm .
|
||||
The
|
||||
.Nm
|
||||
script is not only a build script, however. It does all kinds of
|
||||
cool things like format the source code, and generate patch files.
|
||||
.Nm
|
||||
is the only supported way to develop Telodendria.
|
||||
.sp
|
||||
I opted to write a custom build script instead of just writing a
|
||||
.Pa Makefile
|
||||
because I felt that there is really no way to make a truly portable
|
||||
.Pa 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
|
||||
.Pa Makefiles.
|
||||
They're easier to follow because they're not so cryptic.
|
||||
.sp
|
||||
The
|
||||
.Nm
|
||||
script is fairly intuitive. It operates somewhat like
|
||||
.Xr 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:
|
||||
.Bd -literal -offset indent
|
||||
$ . tools/env.sh
|
||||
.Ed
|
||||
.sp
|
||||
.Sy Note:
|
||||
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.
|
||||
.sp
|
||||
If you're going to be submitting patches, you should also configure a
|
||||
.Pa .env
|
||||
file in the project directory root, which
|
||||
.Nm
|
||||
will include automatically for you. See
|
||||
.Em FILES
|
||||
and
|
||||
.Em ENVIRONMENT .
|
||||
.sp
|
||||
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
|
||||
.Nm
|
||||
with no arguments, or with the
|
||||
.Pa build
|
||||
recipe. This will produce
|
||||
.Pa build/telodendria ,
|
||||
which you can then install to your system and run as a daemon.
|
||||
.sp
|
||||
A complete list of recipes is below. Note that you can run multiple recipes
|
||||
with a single invocation of
|
||||
.Nm ,
|
||||
but recipes are run unconditionally; that is, even if a recipe fails, all the
|
||||
following recipes are still executed.
|
||||
.Bl -tag
|
||||
.It 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.
|
||||
.It run
|
||||
Run the build binary with the development configuration in the
|
||||
.Pa contrib/
|
||||
directory. This recipe is used for quick testing during development. It is
|
||||
.Sy not
|
||||
the recommended way to run Telodendria in a production environment; it should only
|
||||
be used for development.
|
||||
.It clean
|
||||
Remove the
|
||||
.Pa build/
|
||||
directory and any ephemeral files in the source tree, such as
|
||||
.Pa .orig
|
||||
files. The build recipe does not place anything outside of
|
||||
.Pa build/ ,
|
||||
so you can usually just delete that directory and get the same effect.
|
||||
.It format
|
||||
Make sure the source code copyright headers are up to date, and format the code
|
||||
using the system's
|
||||
.Xr indent 1 .
|
||||
This should be run before generating patch files, to ensure that the code follows
|
||||
the project conventions. Note that the provided
|
||||
.Pa .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.
|
||||
.It test
|
||||
Run all of the unit tests and report the results. It is highly recommended to
|
||||
ensure that all the tests pass before submitting a patch, because patches that
|
||||
break the tests are likely to be rejected.
|
||||
.It 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
|
||||
.Em ENVIRONMENT .
|
||||
.It release
|
||||
Generate a release tarball, checksum and sign it, and push it to the web root.
|
||||
See the relevant environment variables below.
|
||||
.It 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.
|
||||
.It 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.
|
||||
.El
|
||||
.sp
|
||||
.Sh ENVIRONMENT
|
||||
Any of the following environment variables are used in the build recipes.
|
||||
They can all be specified in your shell when invoking
|
||||
.Nm ,
|
||||
or they can be placed in a
|
||||
.Pa .env
|
||||
file. For most of these variables, if you would like to append or prepend
|
||||
to the default values, do so in the
|
||||
.Pa .env
|
||||
file, which is sourced after the defaults are set, allowing you to reference
|
||||
the default values in your new value.
|
||||
.Bl -tag
|
||||
.It Ev CC
|
||||
The C compiler to use. This defaults to
|
||||
.Pa 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.
|
||||
.It Ev CFLAGS
|
||||
The compiler flags used to generate object files.
|
||||
.Nm
|
||||
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.
|
||||
.It Ev LDFLAGS
|
||||
The compiler flags used to link the object files to create an output
|
||||
binary.
|
||||
.Nm
|
||||
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.
|
||||
.It Ev PROG
|
||||
The name of the output binary. This defaults to
|
||||
.Pa build/telodendria.
|
||||
.It Ev DEFINES
|
||||
Global preprocessor definitions to append to
|
||||
.Ev CFLAGS.
|
||||
This is just kept separate to keep things organized.
|
||||
.It Ev INCLUDES
|
||||
Header directories to make available. This is appended to
|
||||
.Ev CFLAGS,
|
||||
it is just kept separate to keep things organized.
|
||||
.It Ev DEBUG
|
||||
If set to "1", append some debug flags to
|
||||
.Ev CFLAGS
|
||||
and whipe out any
|
||||
.Ev LDFLAGS
|
||||
that awould cause the output binary to be optimized in any way. This also
|
||||
depends "-debug" to
|
||||
.Ev PROG .
|
||||
.It Ev TELODENDRIA_VERSION
|
||||
This variable does make its way into the output binary, but it is primarily
|
||||
used for generating and publishing releases. This variable affects the
|
||||
.Sy release
|
||||
recipe.
|
||||
.It Ev TELODENDRIA_PUB
|
||||
The web root where the Telodendria website lives. This is where the site
|
||||
is pushed to, and where generated releases go.
|
||||
.It Ev PATCHSET
|
||||
This variable restricts the files that
|
||||
.Nm
|
||||
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.
|
||||
.It Ev MXID
|
||||
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.
|
||||
.Nm
|
||||
will automatically deduce this from your system, but it will most
|
||||
likely get it wrong. Please make sure you are reachable at this ID.
|
||||
.It Ev DISPLAY_NAME
|
||||
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.
|
||||
.Nm
|
||||
will deduce this from your system, and if you set it up properly, you may
|
||||
not even have to set this variable. If
|
||||
.Nm
|
||||
gets it wrong, this allows you to override your display name.
|
||||
.It Ev EDITOR
|
||||
Your preferred editor for writing patch file descriptions. This can be a
|
||||
GUI or terminal editor. If unset, this defaults to the system's
|
||||
.Xr vi 1
|
||||
editor.
|
||||
.It Ev PAGER
|
||||
Your preferred pager for previewing patches. If left unset, this defaults
|
||||
to
|
||||
.Xr less 1 .
|
||||
.Sh FILES
|
||||
.Bl -tag
|
||||
.It Pa .env
|
||||
An environment file that contains lines in the form of
|
||||
.Pa VARIABLE=value
|
||||
with environment variables to set in the
|
||||
.Nm
|
||||
script. See
|
||||
.Em ENVIRONMENT .
|
||||
Note that
|
||||
.Nm
|
||||
simply sources this file, which means that any shell code in it will be
|
||||
executed each time
|
||||
.Nm
|
||||
is invoked.
|
||||
.Sh EXIT STATUS
|
||||
.Sh HISTORY
|
||||
.Sh CAVEATS
|
||||
.Sh BUGS
|
57
man/man8/telodendria.8
Normal file
57
man/man8/telodendria.8
Normal file
|
@ -0,0 +1,57 @@
|
|||
.Dd $Mdocdate: September 30 2022 $
|
||||
.Dt TELODENDRIA 8
|
||||
.Os Telodendria Project
|
||||
.Sh NAME
|
||||
.Nm telodendria
|
||||
.Nd Matrix homeserver daemon
|
||||
.Sh SYNOPSIS
|
||||
.Nm
|
||||
.Op Fl nVv
|
||||
.Op Fl f Ar file
|
||||
.Sh DESCRIPTION
|
||||
.Nm
|
||||
is a Matrix homeserver written entirely from scratch in ANSI C.
|
||||
It is designed to be lightweight and simple, yet functional.
|
||||
.sp
|
||||
The options are as follows:
|
||||
.Bl -tag -width Ds
|
||||
.It Fl f Ar file
|
||||
Specify an alternate configuration file. The default is
|
||||
.Pa /etc/telodendria.conf .
|
||||
.It Fl n
|
||||
Configtest mode. Only check the configuration file for validity.
|
||||
.It Fl V
|
||||
Only print the version information header.
|
||||
.It Fl v
|
||||
Verbose mode. This overrides the configuration file and sets the
|
||||
log level to
|
||||
.Em LOG_DEBUG
|
||||
.El
|
||||
.Sh ENVIRONMENT
|
||||
.Nm
|
||||
does not read any environment variables. All configuration should
|
||||
be done via the configuration file.
|
||||
.Sh FILES
|
||||
Just the configuration file and the data directory; see
|
||||
.Xr telodendria.conf 5
|
||||
for more details.
|
||||
.El
|
||||
.Sh EXIT STATUS
|
||||
.Nm
|
||||
exits with a non-0 exit code if the configuration file is invalid, or
|
||||
one or more required paths is inaccessible.
|
||||
.Nm
|
||||
will print an error to the log and then terminate abnormally.
|
||||
.Pp
|
||||
.Nm
|
||||
exits with a code of 0 if the configuration file is valid, all
|
||||
paths and files required are accessible, and the HTTP listener starts
|
||||
as intended. If
|
||||
.Nm
|
||||
is sent a signal that it catches after it begins servicing requests, it
|
||||
will still exit with a code of 0 after it safely shuts down, because
|
||||
the bootstrap process completed successfully, and by all accounts,
|
||||
it ran normally and exitted normally.
|
||||
.Sh SEE ALSO
|
||||
.Xr telodendria 7 ,
|
||||
.Xr telodendria.conf 5
|
|
@ -16,20 +16,20 @@
|
|||
<meta property="og:description"
|
||||
content="Telodendria, a Matrix homeserver written in ANSI C.">
|
||||
|
||||
<link rel="stylesheet" href="style.css">
|
||||
<link rel="stylesheet" href="/style.css">
|
||||
<link rel="icon" href="assets/Telodendria-196x196.png">
|
||||
|
||||
<title>Telodendria | A Matrix Homeserver written in ANSI C.</title>
|
||||
</head>
|
||||
<body>
|
||||
<img id="logo" src="assets/Telodendria-500x500.png" alt="Telodendria Logo"/>
|
||||
<img id="logo" src="/assets/Telodendria-500x500.png" alt="Telodendria Logo"/>
|
||||
<h1 id="telodendria">Telodendria</h1>
|
||||
<p>
|
||||
<b>Telodendria:</b> The terminal branches of an axon.
|
||||
</p>
|
||||
<div class="msg-error">
|
||||
<b><i>Note:</i></b> <b>Telodendria</b> is under <i>heavy</i> development.
|
||||
Please see the <a href="telodendria.7.html#PROJECT_STATUS">Project Status</a>.
|
||||
Please see the <a href="/man/man7/telodendria.7.html#PROJECT_STATUS">Project Status</a>.
|
||||
</div>
|
||||
<p>
|
||||
<b>Telodendria</b> is an open source Matrix homeserver implementation written from
|
||||
|
@ -159,7 +159,7 @@ Signify
|
|||
<tr>
|
||||
<td colspan="4" style="text-align: center;">
|
||||
No downloads here yet. See the
|
||||
<a href="telodendria.7.html#PROJECT_STATUS">Project Status</a> for more
|
||||
<a href="/man/man7/telodendria.7.html#PROJECT_STATUS">Project Status</a> for more
|
||||
information.
|
||||
</td>
|
||||
</tr>
|
||||
|
@ -175,23 +175,23 @@ on what <b>Telodendria</b> is, what its goals are, how to build the source,
|
|||
configure it, as well as contribute to the project. The <code>man</code>
|
||||
pages are also available online for convenience:
|
||||
</p>
|
||||
<ul>
|
||||
<li><a href="telodendria.7.html">telodendria(7)</a> - Introduction and project information, including licensing information</li>
|
||||
<li><a href="telodendria.8.html">telodendria(8)</a> - Command line usage</li>
|
||||
<li><a href="telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li>
|
||||
<li><a href="contributing.7.html">contributing(7)</a> - Contributing guide</li>
|
||||
<li><a href="td.8.html">td(8)</a> - Build script and patch instructions</li>
|
||||
</ul>
|
||||
<h2>Getting Support</h2>
|
||||
<b>Telodendria</b> is designed to be fairly straightforward, but that
|
||||
doesn't mean there won't be hiccups along the way. If you are struggling
|
||||
to get <b>Telodendria</b> up and running, you're more than welcome to
|
||||
reach out for support. Just join the
|
||||
<code>#telodendria-general:bancino.net</code> Matrix channel. Before
|
||||
you do though, make sure you're running the latest version of
|
||||
<b>Telodendria</b> and you've thoroughly read through all the
|
||||
relevant documentation.
|
||||
<p>
|
||||
User documentation:
|
||||
</p>
|
||||
<ul>
|
||||
<li><a href="/man/man7/telodendria.7.html">telodendria(7)</a> - Introduction and project information, including project status and licensing information</li>
|
||||
<li><a href="/man/man8/telodendria.8.html">telodendria(8)</a> - Command line usage</li>
|
||||
<li><a href="/man/man5/telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li>
|
||||
<li><a href="/man/man7/contributing.7.html">contributing(7)</a> - Contributing guide</li>
|
||||
<li><a href="/man/man8/td.8.html">td(8)</a> - Build script and patch instructions</li>
|
||||
</ul>
|
||||
<p>
|
||||
Developer documentation:
|
||||
</p>
|
||||
<ul>
|
||||
<li><a href="/man/man3/Array.3.html">Array(3)</a> - Dynamic array structure</li>
|
||||
<li><a href="/man/man3/Base64.3.html">Base64(3)</a> - Base64 encoder/decoder with unpadded support</li>
|
||||
</ul>
|
||||
<h2 id="resources">Resources</h2>
|
||||
<ul>
|
||||
<li><a target="_blank" href="/pub">Old <b>Telodendria</b> Versions</a></li>
|
||||
|
|
10
tools/bin/td
10
tools/bin/td
|
@ -164,13 +164,15 @@ recipe_site() {
|
|||
exit 1
|
||||
fi
|
||||
|
||||
# In the future, this might do more.
|
||||
cp -v site/* "$TELODENDRIA_PUB/"
|
||||
|
||||
find docs/ -name '*.[1-9]' | while IFS= read -r man; do
|
||||
find man/ -name '*.[1-9]' | while IFS= read -r man; do
|
||||
dir=$(dirname "$man")
|
||||
html=$(basename "$man")
|
||||
mandoc -Thtml -O style=style.css "$man" > "$TELODENDRIA_PUB/$html.html"
|
||||
echo "$man -> $TELODENDRIA_PUB/$html.html"
|
||||
|
||||
mkdir -p "$TELODENDRIA_PUB/$dir/"
|
||||
mandoc -Thtml -O style=/style.css "$man" > "$TELODENDRIA_PUB/$dir/$html.html"
|
||||
echo "$man -> $TELODENDRIA_PUB/$dir/$html.html"
|
||||
done
|
||||
}
|
||||
|
||||
|
|
|
@ -4,4 +4,9 @@ find tools/bin -type f | while IFS= read -r tool; do
|
|||
chmod +x "$tool"
|
||||
done
|
||||
|
||||
PATH="$(pwd)/tools/bin:$PATH"
|
||||
makewhatis "$(pwd)/man"
|
||||
|
||||
export PATH="$(pwd)/tools/bin:$PATH"
|
||||
export MANPATH="$(pwd)/man:$MANPATH"
|
||||
|
||||
PS1="(td) $PS1"
|
||||
|
|
Loading…
Reference in a new issue