4.4 KiB
Builders
tzk.builders
Builders are small executable chunks that can be linked together to form a useful build process. Products are built by applying builders in sequence. Please see the existing products
dictionary and associated comments in the config file <Configuring tzk>
for how these are specified.
Builders included with tzk
You can use the following builders in your configuration file out of the box:
check_for_kill_phrases
compile_html_file
export_public_tiddlers
new_output_folder
publish_wiki_to_github
replace_private_people
require_branch
require_clean_working_tree
save_attachments_externally
say_hi
set_tiddler_values
shell
Builder helper functions
These helper functions, also defined in tzk.builders
, are intended for use with any custom builders you create.
tzk.builders::info
tzk.builders::stop
tzk.builders::tzk_builder
Custom builders
If the existing builders don't cover something you're hoping to do to build a product, you can write your own directly within your config file.
As an example, let's suppose that we want to publish our wiki to an S3 bucket fronted by CloudFront on Amazon Web Services. We can work with AWS using the aws
CLI, if we've set that up on our computer. We first write a builder function in our tzk_config.py
, anywhere above the products
dictionary:
import subprocess
@builders.tzk_builder
def publish_to_aws(target_uri: str, cloudfront_distribution_id: str):
= Path(builders.build_state['public_wiki_folder']) / "output"
source_folder # Sync the output folder to S3, deleting any files that have been removed.
"aws", "s3", "sync", "--delete", source_folder, target_uri))
subprocess.call((# Clear the CDN cache so the new version is available immediately.
"aws", "cloudfront", "create-invalidation",
subprocess.call(("--distribution-id", cloudfront_distribution_id, "--paths", "/*"))
builders.build_state
is a dictionary that is preserved across all build steps. The new_output_folder()
builder populates this public_wiki_folder
attribute early in the default build process, so that it contains the path to the temporary wiki that build steps happen within.
Then we add a call to this builder within the list for this product, with whatever parameters we like:
= {
products 'public': [
[...]=True),
builders.compile_html_file(externalize_attachments"s3://my_target_uri", "MY_DISTRIBUTION_ID"),
publish_to_aws(
], }
Since we've parameterized this builder, we can easily use it multiple times if we want, for instance within different products. Note that we say just publish_to_aws
, not builders.publish_to_aws
, since this builder is located directly within the config file rather than in the external tzk.builders
module that comes with tzk.
Shell commands
If a builder seems like overkill for your use case, you can also run simple shell commands using the shell()
builder.
Our AWS example would look like this:
= {
products 'public': [
[...]=True,
builders.compile_html_file(externalize_attachments="output/public_site/"),
output_folder"aws s3 sync --delete output/public_site s3://my_target_uri"),
builders.shell("aws cloudfront create-invalidation --distribution-id MY_DISTRIBUTION_ID --paths '/*'"),
builders.shell(
], }
Notice the need to include quotes within the string in builders.shell
; the same quoting rules as when running shell commands directly apply. Also notice that we had to access the compiled HTML file from output/public_site
, since we can no longer use the build_state
dictionary. Paths are relative to the private wiki's root directory (the directory containing the tiddlywiki.info
file) while builders are running.