Overview of wheels for chialisp distribution

chialisp_distribution.md

The load_clvm method has been duplicated in multiple places, each version with slightly different semantics and bugs. We present here a set of tiny python wheels that solve many problems with chialisp contracts including:

• distribution of libraries
• distribution of compiled .hex files
• automatic dynamic builds in development mode
• dependency analysis (on library include files)

runtime_builder

This wheel supports configuration files named dynamic_build.py by default that can be use in projects that require a non-python build step. These builds can be done at wheel build time or dynamically at runtime when the corresponding resource is built.

The dynamic_build.py files should be regular python files. Note that they will be executed at build time before your project is installed, which means these files cannot depend on your other modules in your project. T

To load built artifacts at runtime, use build_all_at_build_time, which takes a list of packages to look for dynamic_build.py files.

chialisp_builder

This wheel uses runtime_builder to allows users to build .clsp files into .hex files, either at wheel build time or at development-cycle time.

So you install this wheel, install your local wheel with the .clsp files in development mode (pip install -e), and you can iterate on the .clsp or .clib files, which will build the .hex file at runtime if necessary. Necessity is based on file date stamps, so if .hex is older than the corresponding .clsp file or any transitively included .clib file, the .hex file is rebuilt when load_program is called.

To use: install, create dynamic_build.py files in the same directory/module as the .clsp files, and use load_program (which usesfrom chialisp_loader to load the .hex files.

This is a build-time and develop-time dependency. Deployments should not include this wheel: chialisp_loader looks for presence of this library to determine if this is a final deployment or a development.

The dynamic_build.py file might look something like this:

import pathlib

from chia_stdlib import STABLE_INCLUDE_DIRECTORY

from chialisp_builder import ChialispBuild


PUZZLE_DIR = pathlib.Path(__file__).parent.resolve()

BUILD_ARGUMENTS = {
    puzzle_path.with_suffix(".hex").name: ChialispBuild([STABLE_INCLUDE_DIRECTORY])
    for puzzle_path in PUZZLE_DIR.glob("*.clsp")
}

chialisp_loader

This wheel exports load_program, which is used to load resources from wheels.

When load_program is called, it tries to import chialisp_builder. If it fails, it assumes this is running at deploy time: any .clsp files are ignored, and the corresponding program is loaded from the .hex file.

chialisp_stdlib

This wheel exports two sets of .clib files: "stable" and "nightly". These tracks are similar to the tracks in rust, where things in "stable" are more likely to prioritize backward-compatibility over ergonomics, so presumably have evolved to a place where there is agreement that ergonomics is optimal. Over time, libraries evolve in "nightly" and eventually move to "stable".

This module exports two values: STABLE_INCLUDE_DIRECTORY and NIGHTLY_INCLUDE_DIRECTORY, both of type pathlib.Path. You can feed these directories to chialisp_builder.ChialispBuild

chialisp_puzzles

This wheel provides .hex files for standard chia puzzle templates ("mods") and an api to load them as Program objects.