Builder Library Reference, which presents a multi-component design as an example and then covers a number of topics.
Let us say that the things that these two pages cover are our "syllabus", and we won't drop anything from the syllabus without talking about it. As I mentioned above, neither of these pages discusses static stuff or the new higher-level constructors, so that stuff goes into the syllabus too.
This PR overhauls builder_example.py, such that the documentation of the builder library can mostly "just" be a discussion of the example program, and such that that discussion covers the syllabus.
I want to teach people using a runnable example because many of the builder's features (especially the "modern" higher-level constructors) can only be understood via code generation: a single line of Python generates quite a few lines of Calyx in different parts of the Calyx program. This is why just showing snippets of Python/Calyx is ineffective.
I want the example program to show most features, but I don't want to overwhelm the user with too much info at once. To this end, I'm going to split the builder example into a number of components. A component will have a small number of self-contained lessons.
There is also a simple "hello world" example that just introduces an adder component. This is documented separately and line-by-line. For the walkthrough proper, I still go in program order but I only stop to explain new concepts.
Here's the syllabus:
[x] Adding a component
[x] Adding input and output ports
[x] Adding registers
[x] Adding computational units like adders
[x] Adding a group using the with {component}.group("group_name") as group_handle: syntax
[x] Adding a group with a static delay -- outdated?
[x] Adding a combinational group, and what that is for
[x] Writing to ports using dot notation
[x] Width inference of constants
[x] Guarded assignments
[x] "Bare names" -- I need a motivating example
[x] Continuous assignments
[x] Accessing a component's ports while defining it using this
[x] Control operators: seq, par, if, while, invoke
[x] Building and emitting programs to Calyx
[x] Multi-component designs
[x] 1-d memories, and reading and writing to them
[x] Marking memories as external or "by reference"
[x] Retrieving handles to components, cells, groups by name -- will cover this entirely in the doc.
[x] Defining component attributes -- I need a motivating example.
[x] High and low signals, and using them
[x] Static timing -- will cover entirely in the doc. I'll just point out that the adder component has latency one, and show the Python code to generate the static annotation.
[x] Higher-level constructs, like <op>_use, if_with, and while_with.
This PR closes #1908.
There are two old pages of documentation:
builder_example.pyand also discusses a tiny made-up code snippet to show parallelism in the control section.Let us say that the things that these two pages cover are our "syllabus", and we won't drop anything from the syllabus without talking about it. As I mentioned above, neither of these pages discusses static stuff or the new higher-level constructors, so that stuff goes into the syllabus too.
This PR overhauls
builder_example.py, such that the documentation of the builder library can mostly "just" be a discussion of the example program, and such that that discussion covers the syllabus.I want to teach people using a runnable example because many of the builder's features (especially the "modern" higher-level constructors) can only be understood via code generation: a single line of Python generates quite a few lines of Calyx in different parts of the Calyx program. This is why just showing snippets of Python/Calyx is ineffective.
I want the example program to show most features, but I don't want to overwhelm the user with too much info at once. To this end, I'm going to split the builder example into a number of components. A component will have a small number of self-contained lessons.
There is also a simple "hello world" example that just introduces an adder component. This is documented separately and line-by-line. For the walkthrough proper, I still go in program order but I only stop to explain new concepts.
Here's the syllabus:
with {component}.group("group_name") as group_handle:syntaxthis<op>_use,if_with, andwhile_with.