readme

Hi. This is the readme for a static site generator used by https://cazander.ca and https://froghat.ca.

This site generator is a Python program named fucko that makes a website from content written in reStructuredText. The site content, along with the Python code, is available online at https://git.sr.ht/~sqwishy/froghat.ca.

license

The site generator software (not the articles) is public domain under CC0 1.0 Universal (CC0 1.0).

The articles (not the site generator software) are copyleft under Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).

site generator

fucko is trash. I wrote it because I didn’t like Pelican (also trash). As it turns out, I don’t like Jinja either. My website uses Mako for templates. And ninja to generally get things done in the right order.

My website has fewer features than Pelican. That’s kinda the point. It’s not supposed to be a one-size-fits-all kinda thing. It’s just supposed to be fun to edit and extend for your own ambitions. ﾟ･✿ヾ╲(｡◕‿◕｡)╱✿･ﾟ So you can copy[1] it and change it to be its own thing without feeling obligated to merge to any kind of uPsTrEaM and spend your life arguing with a maintainer.

usage

(Optional) Create & use a virtual env (using the fish shell in this example) …

python -m venv .venv
. .venv/bin/activate.fish

Install the Python package (from the directory containing setup.py) with: python -m pip install -e .

The site generator builds one of two sites at a time, either cazander.ca or froghat.ca. Make a symbolic link from content to either directory.

ln -s $(printf 'froghat.ca\ncazander.ca' | shuf -n1) content

You can run it with fucko build, which should dump a bunch of output to /tmp/fucko. There’s also fucko serve which does the same thing but also serves the files with a simple http server and tries to do reload your web page on file changes.

fucko-fwd

Because the site generator was designed to use ninja, and how ninja works, new processes are created for individual build steps like reading each reStructuredText document or for rendering each HTML file from a mako template.

A lot of time is spent starting the Python interpreter and importing modules.

So, instead of doing that, the build steps run a smol C program named fucko-fwd that connects to Python over a unix socket so that the main Python process can do everything and sometimes fork and finish build steps in another process.

That program is compiled as a build step automatically, but you need a C compiler (cc in your PATH).

Information about how this works follows.

how we forward fuckos

fucko-fwd is very simple.

  • fucko, the Python program, opens a TCP unix socket and starts ninja.

  • ninja runs fucko-fwd $args instead of python -m fucko $args for each build step.

  • fucko-fwd sends its stdin, stdout, stderr handles to the Python program, fucko, over the socket using SCM_RIGHTS.

  • fucko gets the process id of each fucko-fwd from getsockopt SO_PEERCRED and reads the command line arguments for each build step from /proc/pid/cmdline.

  • Temporarily using the file descriptors in place of its own stdin, stdout, and stderr, fucko runs the build step from those arguments.

  • When it’s done doing whatever thing, fucko sends the status code back to fucko-fwd over the connection and closes it.

  • fucko-fwd gets the status code and exits with it so that ninja sees the status code.

Wow, what a fucking convoluted thing to do.

todo

  • changing cfg.py doesn’t cause a rebuild when it should?

  • A caveat of fucko-fwd is that signals are not received by the job host. So if a job doesn’t complete because it hits a breakpoint or something, hitting CTRL-C terminates fucko-fwd but not the host at the other end of the socket. So they’ll remain at that breakpoint.

what nick thinks of my site generator

that’s cute

—nick