Compile LaTeX elsewhere
README.md

texci #

Compile LaTeX elsewhere. Can be thrown into a Makefile for interactive use, or run automatically as by e.g. a cron(8) job. You could think of it as a dead-simple CI for LaTeX only.

Why #

texlive is gigantic and takes forever to update. The packages are split in awful, contrived ways. Markup that compiles in one environment will complain about missing font or .sty files in another. I just want to install and maintain a toolchain in one place.

This script makes that possible.

Tips #

Try texci -h for built-in documentation.

Remote setup #

Create a user named texci with a home directory it can write in. Cannot be a no-login user.

Create an .ssh folder in the texci user's home directory. Only the texci user should be able to read or write in it. Within that, create an authorized_keys file with all relevant public keys. If you've configured sshd(8) to look elsewhere for authorized keys, I trust you know what to do.

Generate host keys, if necessary. I trust you either use a distro that does this for you, or you know what to do.

Lastly, log in to this server at least once interactively. You do need to get the host's public key added to known_hosts.

What if I want a more complicated setup {with split users,with custom login shells,etc}? #

There is nothing stopping you. There is also no helping you.

Local setup #

Create a key pair with texci -write-keys. If you do anything unusual with these key files, I trust you know what to do next.

Create a default configuration file with texci -write-config. Delete any lines that don't seem relevant. Populate at least Name and Host.

What if I want a more complicated setup {that compiles other formats as well,that dispatches across build servers,etc}? #

Use CLI flags instead of the configuration file. If you can't make that work, you either don't know what you're doing, or you need to take your witchcraft elsewhere.

Validating the whole setup #

First try running each of:

  • texci -check-config
  • texci -check-private-key
  • texci -check-host
  • texci -dry-run

Consider also passing -verbose, or at least -log-level=debug.

What about security? #

That's on you.

I committed a configuration file that revealed a publicly-reachable hostname and now I'm being DDoSed? #

Not a question, and see above.

Using the IncludeList configuration option (or the -include flag) #

Okay, here's a quick primer on rsync(1) file marking. It starts with a list of all files. Directives are parsed sequentially. As exclude directives are reached, files are dropped from the list. If a file was previously marked as included (by an include directive), it is not dropped.

But directories are different. The recursive mode of rsync(1) is only recursive of the main directory by default. Which is to say, unless a directory is named on an directive, the files in it are not even on the initial list.

The configurations of texci are passed directly to rsync(1). So consider a working directory like:

$ ls -R
.:
bar  baz.txt  foo/

./foo:
ham  spam.txt

To copy all *.txt files in either the main directory or the foo subdirectory, try IncludeList="{foo,*.txt}". To include all subdirectories (i.e., any nesting level below the main one) try IncludeList="{*/,*.txt}".