Skip to content

Latest commit

 

History

History
122 lines (89 loc) · 4.06 KB

README.md

File metadata and controls

122 lines (89 loc) · 4.06 KB

OG Loc

Open Graph image generator for crates.io

Building

  1. Install Rust following the instructions on https://rustup.rs.
  2. Install the Fira Sans font on your machine: https://fonts.google.com/specimen/Fira+Sans (a later version might include the fonts in the binray itself)
  3. Run cargo build for a debug build, or cargo build --release for an optimized build

Running

OG Loc gets its data from Crates.io database dumps, which are loaded in a set of hash maps each time the application starts. First, you'll need the latest Crates.io database dump, which you can fetch from https://static.crates.io/db-dump.tar.gz.

Using wget:

wget https://static.crates.io/db-dump.tar.gz

OG Loc can either perform a a one-shot image generation, do a bulk job or run as a HTTP server.

$ cargo run -q -- --help
Usage: og-loc [OPTIONS] <COMMAND>

Commands:
  serve     Run the server
  one-shot  Do a single conversion
  bulk      Do a bulk conversion
  help      Print this message or the help of the given subcommand(s)

Options:
  -d, --db-dump-path <DB_DUMP_PATH>  The path of the database dump [env: DB_DUMP_PATH=] [default: ./db-dump.tar.gz]
  -h, --help                         Print help

One shot

To run generate a single Open Graph image for a crate, use the one-shot subcommand:

$ cargo run -q -- one-shot --help
Do a single conversion

Usage: og-loc one-shot --name <NAME> --out <OUT_PATH>

Options:
  -n, --name <NAME>     The name of the crate [env: NAME=]
  -o, --out <OUT_PATH>  The path to the PNG output file [env: OUT_PATH=]
  -h, --help            Print help

For instance, to get an image for the knien crate at version 0.0.8, run

# Unoptimized build
cargo run -- one-shot --name knien --out knien-og.png
# Optimized build, significantly improves performance
cargo run --release -- one-shot --name knien --out knien-og.png

Result:

image

Bulk job

To run a bulk job for a number of crates, use the bulk subcommand:

$ cargo run -q -- bulk --help
Do a bulk conversion

Usage: og-loc bulk [OPTIONS] --in <INPUT> --out <OUT_FOLDER>

Options:
  -f, --force             Force overwrite the output [env: FORCE=]
  -i, --in <INPUT>        Input specifier. Either a comma-separated list of crate names, a path to a file containing a newline-separated list of crate names, or `-`, indicating stdin. Will first attempt to match input with `-`, then parse it as a comma-separated list of crate names, and then fall back to a path, only failing if an empty value is passed [env: INPUT=]
  -o, --out <OUT_FOLDER>  The path of the folder to which the PNGs should be written [env: OUT_FOLDER=]
  -h, --help              Print help

For instance, to generate a number of images for line break separated crate names specified in test.txt, and write them to the out folder, run

# Unoptimized build
cargo run -- bulk --in test.txt -o test
# Optimized build, significantly improves performance
cargo run --release -- bulk -in test.txt -out test

Server

To run the OG Loc server, use the serve subcommand:

$ cargo run -q -- serve --help
Run the server

Usage: og-loc serve [OPTIONS]

Options:
  -a, --addr <ADDR>  The socket address to listen on [env: ADDR=] [default: 127.0.0.1:3000]
  -h, --help         Print help

For instance, to serve locally from port 3000, run

# Unoptimized build
cargo run -- serve --addr 0.0.0.0:3000
# Optimized build, significantly improves performance
cargo run --reelase -- serve --addr 0.0.0.0:3000

Open your browser, and navigate to http://localhost:3000/og/<CRATE_NAME> For instance, to get an image for the knien crate, navigate to http://localhost:3000/og/knien

Internals

OG Loc uses the awesome Typst typesetting system internally to render the PNG images from a Jinja2 template that gets filled with information from crates.io. The HTTP server is implented using Axum, and the Crates.io database is loaded using db_dump.