Closed anshumanmohan closed 3 weeks ago
All these proposals sound great.
I am finally getting back to this, and am planning a bigger overhaul than previously outlined. There are actually two pages of documentation:
builder_example.py
and 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.
I propose to overhaul/extend 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.
Here's the syllabus:
with {component}.group("group_name") as group_handle:
syntaxthis
mux
, but by using a bunch of these handle-retrieving methods.<op>_use
, if_with
, and while_with
.I have pushed the beginnings of this new example. So far I have the following components:
adder
: Teaches how to add components, ports, cells. Shows how to define a group in the verbose manner. Shows dot notation to access ports. Shows the HI signal shorthand. Shows how to continuously output an answer. Shows how to access a port of a component that is under construction. abs_diff
: Shows off a higher-order construct that does reg := a-b
in one line of Python. Shows a more complicated control, with an if check. Uses a ge
check that is written in a verbose way, using a group and not a comb group. Shows how to create a comb group for an lt
check as a one-liner. Shows a higher-order if_with
construct in the control; this works with the one-liner lt
check by not unwrapping a tuple of cell and comb group.mux
: Shows a multi-component design. I have now pushed two further components:
map
: Covers 1d memory, items passed by reference, while loops, width inference, guarded assignments, and the higher-order helper incr
.main
: Covers external memories and invocations.I am close to done when it comes to new code, so I welcome your feedback on that! Please see #2002 for the code that I've been writing. In some cases I have annotated the syllabus above to ask for help or guidance.
After #1894 has landed, I'd like to take locks and revise the eDSL docs. Here is a non-exhaustive list:
get_cell
,get_group
, andget_component
can be pushed down to the tricks and tips section.<op>_use
,if_with
, andwhile_with
.