rsconstruct.toml

# rsconstruct build configuration for this repository.

[build]
# src_dirs entries name directories; "." (the whole tree) is a config error
reject_dot_src_dirs = true

# ─── analyzers ───────────────────────────────────────────────────────────────

[analyzer.tera]

[analyzer.python]

# ─── templating ──────────────────────────────────────────────────────────────

[processor.generator.tera]
# out/drivers holds the build-generated driver templates (see the
# driver-generation section below); nothing under it is committed.
src_dirs = ["tera.templates", "out/drivers"]

[processor.checker.ruff]
src_dirs = ["scripts", "config", "tests"]


[processor.checker.pyrefly]
src_dirs = ["scripts", "config", "tests"]

# golden tests pinning the driver generator (tests/test_drivers.py)
[processor.checker.pytest]
src_dirs = ["tests"]

# ─── shell ───────────────────────────────────────────────────────────────────

[processor.checker.ishellcheck]
src_dirs = ["scripts", "docs", "config"]

# ─── lua ─────────────────────────────────────────────────────────────────────

[processor.checker.iluacheck]
src_dirs = ["config"]

# ─── toml / yaml / json ──────────────────────────────────────────────────────

[processor.checker.taplo]
src_files = [".rumdl.toml", "pyproject.toml", "rsconstruct.toml"]

# ─── derived song metadata ───────────────────────────────────────────────────

# One out/derived/<book>/<song>.ly.toml per song, derived from the TOML
# front matter of src/<book>/<song>.ly.tera. The driver templates
# load these via load_toml, so this must run before the tera renders —
# the exact output-path match gives rsconstruct that ordering. Without
# this step a cold checkout cannot render any song or book.
[processor.generator.generic.derive_metadata]
command = "python"
args = ["-m", "scripts.derive_metadata"]
src_dirs = ["src"]
src_extensions = [".tera"]
src_exclude_dirs = ["src/include"]
output_dir = "out/derived"
output_extension = "toml"
dep_inputs = ["scripts/derive_metadata.py", "scripts/drivers.py"]

# ─── driver templates ────────────────────────────────────────────────────────

# tera cannot include dynamic paths, so every output needs its own driver
# template wrapping the song file(s); scripts/drivers.py generates them
# from the weave master (src/include/common.ly.weave) so that git holds
# exactly ONE file per song. A song driver depends on the song's derived
# metadata toml (drivers depend only on front matter, not the tune body),
# which both orders derivation before the driver and, transitively,
# before the tera render that load_toml's it — cold builds work in one
# pass via rsconstruct's virtual-file discovery loop. The output path
# nests out/tera/src under out/drivers so the tera processor (src_dirs
# includes out/drivers) renders each driver to the out/tera path the
# books and opt-in song processors expect.
[processor.generator.generic.song_drivers]
command = "python"
args = ["-m", "scripts.drivers", "songs"]
src_dirs = ["out/derived"]
src_extensions = [".toml"]
output_dir = "out/drivers/out/tera/src"
output_extension = "tera"
dep_inputs = ["scripts/drivers.py", "src/include/common.ly.weave"]

# One driver per book, splicing all of the book's songs; the glob over
# the derived tomls grows across discovery passes, so the product picks
# up every song even on a cold build.
[processor.explicit.generic.openbook_driver]
command = "python"
args = ["-m", "scripts.drivers", "book"]
inputs = ["src/include/common.ly.weave", "scripts/drivers.py"]
input_globs = ["out/derived/openbook/**/*.ly.toml"]
output_files = ["out/drivers/out/tera/books/openbook.ly.tera"]

[processor.explicit.generic.israeli_driver]
command = "python"
args = ["-m", "scripts.drivers", "book"]
inputs = ["src/include/common.ly.weave", "scripts/drivers.py"]
input_globs = ["out/derived/israeli/**/*.ly.toml"]
output_files = ["out/drivers/out/tera/books/israeli.ly.tera"]

[processor.explicit.generic.drumming_driver]
command = "python"
args = ["-m", "scripts.drivers", "book"]
inputs = ["src/include/common.ly.weave", "scripts/drivers.py"]
input_globs = ["out/derived/drumming/**/*.ly.toml"]
output_files = ["out/drivers/out/tera/books/drumming.ly.tera"]

[processor.explicit.generic.rockbook_driver]
command = "python"
args = ["-m", "scripts.drivers", "book"]
inputs = ["src/include/common.ly.weave", "scripts/drivers.py"]
input_globs = ["out/derived/rockbook/**/*.ly.toml"]
output_files = ["out/drivers/out/tera/books/rockbook.ly.tera"]

[processor.explicit.generic.guitar_album_driver]
command = "python"
args = ["-m", "scripts.drivers", "book"]
inputs = ["src/include/common.ly.weave", "scripts/drivers.py"]
input_globs = ["out/derived/guitar_album/**/*.ly.toml"]
output_files = ["out/drivers/out/tera/books/guitar_album.ly.tera"]

# ─── books ───────────────────────────────────────────────────────────────────

# Compile the tera-rendered book sources with lilypond. Each book is one
# explicit product whose .ly input is a tera-processor output, so rsconstruct
# orders tera before lilypond automatically and rebuilds a book only when its
# rendered source changes.
[processor.explicit.generic.openbook]
command = "python"
args = ["-m", "scripts.wrapper_lilypond_explicit"]
inputs = ["out/tera/books/openbook.ly"]
required_tools = ["lilypond"]
output_files = ["out/tera/books/openbook.pdf", "out/tera/books/openbook.ps"]

# forScore index.csv for the openbook PDF (issue #121): one bookmark per tune
# when imported into the forScore iPad app. Page numbers are read from the
# book's rendered table of contents by scripts.gen_index_csv.
[processor.explicit.generic.openbook_index_csv]
command = "python"
args = ["-m", "scripts.gen_index_csv"]
inputs = ["out/tera/books/openbook.pdf"]
output_files = ["out/tera/books/openbook.csv"]

# Embedded PDF bookmarks for the openbook PDF (issue #121 follow-up): the
# same tune list as the index.csv, written directly into the PDF as outline
# entries so forScore (and every other PDF reader) picks up the table of
# contents natively, no CSV import needed. This is the step that publishes
# openbook.pdf to the website: it reads the engraved PDF and writes the
# bookmarked copy straight into docs/output, which is why pages_books_pdf
# below skips openbook.pdf (one producer per output file).
[processor.explicit.generic.openbook_pdf_bookmarks]
command = "python"
args = ["-m", "scripts.embed_pdf_bookmarks"]
inputs = ["out/tera/books/openbook.pdf"]
output_files = ["docs/output/openbook.pdf"]

[processor.explicit.generic.israeli]
command = "python"
args = ["-m", "scripts.wrapper_lilypond_explicit"]
inputs = ["out/tera/books/israeli.ly"]
required_tools = ["lilypond"]
output_files = ["out/tera/books/israeli.pdf", "out/tera/books/israeli.ps"]

[processor.explicit.generic.drumming]
command = "python"
args = ["-m", "scripts.wrapper_lilypond_explicit"]
inputs = ["out/tera/books/drumming.ly"]
required_tools = ["lilypond"]
output_files = ["out/tera/books/drumming.pdf", "out/tera/books/drumming.ps"]

[processor.explicit.generic.rockbook]
command = "python"
args = ["-m", "scripts.wrapper_lilypond_explicit"]
inputs = ["out/tera/books/rockbook.ly"]
required_tools = ["lilypond"]
output_files = ["out/tera/books/rockbook.pdf", "out/tera/books/rockbook.ps"]

[processor.explicit.generic.guitar_album]
command = "python"
args = ["-m", "scripts.wrapper_lilypond_explicit"]
inputs = ["out/tera/books/guitar_album.ly"]
required_tools = ["lilypond"]
output_files = ["out/tera/books/guitar_album.pdf", "out/tera/books/guitar_album.ps"]

# ─── github pages ────────────────────────────────────────────────────────────

# The website is the docs/ tree as built: the tera-rendered
# docs/index.html and the freshly engraved books copied to docs/output/
# below — index.html links them as output/<book>.{pdf,ps,ly} and the
# browser's native PDF viewer displays them. CI uploads this directory
# as the Pages artifact; docs/output and docs/index.html are generated,
# not committed.
[pages]
dir = "docs"

# copy the engraved books into the website tree, one product per file
[processor.generator.generic.pages_books_pdf]
command = "cp"
src_dirs = ["out/tera/books"]
src_extensions = [".pdf"]
# openbook.pdf is published by openbook_pdf_bookmarks instead, which copies
# it with the table of contents embedded. Copying it here too would make two
# processors produce docs/output/openbook.pdf.
src_exclude_files = ["openbook.pdf"]
output_dir = "docs/output"
output_extension = "pdf"
batch = false

[processor.generator.generic.pages_books_ps]
command = "cp"
src_dirs = ["out/tera/books"]
src_extensions = [".ps"]
output_dir = "docs/output"
output_extension = "ps"
batch = false

[processor.generator.generic.pages_books_ly]
command = "cp"
src_dirs = ["out/tera/books"]
src_extensions = [".ly"]
output_dir = "docs/output"
output_extension = "ly"
batch = false

# publish the forScore index.csv to the site so it can be downloaded from
# the gh-pages site alongside the PDFs
[processor.generator.generic.pages_books_csv]
command = "cp"
src_dirs = ["out/tera/books"]
src_extensions = [".csv"]
output_dir = "docs/output"
output_extension = "csv"
batch = false

# ─── external dependencies ───────────────────────────────────────────────────

# lilypond engraves the books: the stanzas that run it name it in
# required_tools, so `rsconstruct tool install project` installs the release
# rsconstruct.lock pins. The rest is installed by `rsconstruct tool install
# machine`.
[dependencies]
# poppler-utils provides pdfinfo/pdftotext, used by scripts.gen_index_csv to
# read tune page numbers out of the built PDF's table of contents.
system = ["tidy", "poppler-utils"]

# ─── opt-in targets (disabled by default) ────────────────────────────────────

# Migrated from the Makefile targets that were not part of `make all`.
# Each stanza ships with enabled = false; activate one for a single build
# from the command line without touching this file:
#
#   rsconstruct build --iset explicit.check_all.enabled=true
#   rsconstruct build --iset generator.songs_pdf.enabled=true
#
# The per-song and audio processors scan generated trees (out/tera/src,
# out/songs/midi), so they discover work only once a prior build has
# produced those files: run a plain `rsconstruct build` first.

# source-convention checks on the song sources; part of the default
# build since 2026-09-01, when its findings were all fixed
[processor.explicit.generic.check_all]
command = "python"
args = ["-m", "scripts.check_all"]
inputs = ["scripts/check_all.py"]
input_globs = ["src/**/*.ly.tera"]
output_files = ["out/checks/check_all.stamp"]

# End-to-end smoke test: engrave the single demo song
# (src/test/demo.ly.tera → its generated driver → its rendered .ly → pdf+ps).
# It exercises every stage the real books go through, so a plain
# `rsconstruct build` catches LilyPond breakage without waiting for the
# 200-tune full engrave — which is the point on CI. The tera render of
# out/tera/src/test/demo.ly is picked up automatically as the input dep.
[processor.explicit.generic.demo_smoke]
command = "python"
args = ["-m", "scripts.wrapper_lilypond_explicit"]
inputs = ["out/tera/src/test/demo.ly"]
required_tools = ["lilypond"]
# lilypond also writes the midi, since demo.ly has a \midi block.
output_files = ["out/smoke/demo.pdf", "out/smoke/demo.ps", "out/smoke/demo.midi"]

# validate the generated website index page (part of the default build)
[processor.checker.itidy]
src_dirs = ["docs"]

# per-song engraving (DO_PDF / DO_PS / DO_MIDI): one product per rendered song
[processor.generator.generic.songs_pdf]
enabled = false
command = "python"
args = ["-m", "scripts.wrapper_lilypond_song"]
src_dirs = ["out/tera/src"]
src_extensions = [".ly"]
output_dir = "out/songs/pdf"
output_extension = "pdf"
dep_inputs = ["scripts/wrapper_lilypond_song.py"]
required_tools = ["lilypond"]
batch = false

[processor.generator.generic.songs_ps]
enabled = false
command = "python"
args = ["-m", "scripts.wrapper_lilypond_song"]
src_dirs = ["out/tera/src"]
src_extensions = [".ly"]
output_dir = "out/songs/ps"
output_extension = "ps"
dep_inputs = ["scripts/wrapper_lilypond_song.py"]
required_tools = ["lilypond"]
batch = false

[processor.generator.generic.songs_midi]
enabled = false
command = "python"
args = ["-m", "scripts.wrapper_lilypond_song"]
src_dirs = ["out/tera/src"]
src_extensions = [".ly"]
output_dir = "out/songs/midi"
output_extension = "midi"
dep_inputs = ["scripts/wrapper_lilypond_song.py"]
required_tools = ["lilypond"]
batch = false

# audio rendering (DO_WAV / DO_OGG / DO_MP3): consumes the songs_midi outputs
[processor.generator.generic.midi2wav]
enabled = false
command = "python"
args = ["-m", "scripts.wrapper_midi_audio"]
src_dirs = ["out/songs/midi"]
src_extensions = [".midi"]
output_dir = "out/songs/wav"
output_extension = "wav"
dep_inputs = ["scripts/wrapper_midi_audio.py"]
required_tools = ["timidity"]
batch = false

[processor.generator.generic.midi2ogg]
enabled = false
command = "python"
args = ["-m", "scripts.wrapper_midi_audio"]
src_dirs = ["out/songs/midi"]
src_extensions = [".midi"]
output_dir = "out/songs/ogg"
output_extension = "ogg"
dep_inputs = ["scripts/wrapper_midi_audio.py"]
required_tools = ["timidity"]
batch = false

[processor.generator.generic.midi2mp3]
enabled = false
command = "python"
args = ["-m", "scripts.wrapper_midi_audio"]
src_dirs = ["out/songs/midi"]
src_extensions = [".midi"]
output_dir = "out/songs/mp3"
output_extension = "mp3"
dep_inputs = ["scripts/wrapper_midi_audio.py"]
required_tools = ["timidity", "lame"]
batch = false

# `make real_books_archive.gi`: fetch the scanned real-books reference archive
[processor.explicit.generic.real_books]
enabled = false
command = "python"
args = ["-m", "scripts.download_real_books"]
inputs = ["scripts/download_real_books.py"]
output_files = ["out/real_books/real_books.stamp"]

# lint the GitHub Actions workflow files with actionlint
[processor.checker.iactionlint]
src_dirs = [".github/workflows"]

# ─── markdown ────────────────────────────────────────────────────────────────

[processor.checker.rumdl]
src_files = ["README.md"]