Run the tutorials

The experimental SDK holds the compiler, simfabric-sdk, which runs the Cerebras SDK simulator, and every tutorial this site publishes. To get it, download the experimental SDK. Everything is in one directory, called <sdk> on this site:

Directory	Holds
<sdk>/bin	the programs: carbide, paint, milink, weight, miset, miget, binseq, elfmi, mielf, midump, meminsp, portrait, pipeline, simfabric-sdk and tungsten-tutorials
<sdk>/share/build	the make rules every tutorial and application builds with
<sdk>/share/tutorial	the tutorial, and the applications in projects/
<sdk>/share/tungsten/docs	the language and tool references
<sdk>/share/tungsten/syntax_highlight, <sdk>/share/paint/syntax_highlight	the editor support

tungsten-tutorials sets up what it needs itself. To run make by hand, set up the shell first:

export PATH=<sdk>/bin:$PATH
export FLUTEMK=<sdk>/share/build/flute.mk TESTMK=<sdk>/share/build/test.mk
export SIMFABRIC=simfabric-sdk

Run every tutorial

tungsten-tutorials copies the tutorials to a new directory under the current one, builds and simulates every test there, and prints a scorecard:

tungsten-tutorials --list           # the tutorials it runs
tungsten-tutorials -f main-1        # lessons 1 to 3 first
tungsten-tutorials                  # every tutorial

Run it from a directory you can write.

Options

Option	Meaning
-d, --dir DIR	run in DIR, which must not exist
-f, --filter PATTERN	only tutorials whose path matches the regular expression PATTERN; quote it, e.g. -f '0[1-3]-'
-t, --timeout 30m	per-test timeout
-l, --list	list the tutorials and exit
--help	these options

Examples

These examples work in copies of the SDK's tutorial, <sdk>/share/tutorial, in a shell set up as above. Each block starts in a directory you can write and returns there:

# One tutorial by hand: build, simulate, compare.
cp -r <sdk>/share/tutorial/main-1-one-pe .
cd main-1-one-pe/01-hello-wafer
make TEST=tutorial
cat test-tutorial/make-log                  # the commands make ran, and their output
cd ../..

On this site: Tutorial I – Single-PE Programming.

# Read a result by name.
cd main-1-one-pe/01-hello-wafer/test-tutorial
make -f ../Makefile VPATH=.. TEST=tutorial bench.map bench-sim.core
miget image=bench-sim.core map=bench.map symbol=a decimal
cd ../../..

# A new kernel, from a tutorial: edit add.w (kernel), bench.paint (layout),
# ref.py (expected result) and test.rc (tests), then run it. After each
# later edit, run make clean first: make reuses an existing test-tutorial/.
cp -r <sdk>/share/tutorial/main-1-one-pe/01-hello-wafer mykernel
cd mykernel
make TEST=tutorial
cd ..

On this site: Lesson 1 — Hello, wafer!.

# A run of lessons 1 to 3, and its scorecard.
tungsten-tutorials -f main-1 --dir main-1-run
cat main-1-run/SCORECARD.md

After a full run, SCORECARD.md in the run directory lists every test and groups the failures by reason; each test's complete log is <tutorial>/test-<name>/make-log.

Common problems

Symptom	Fix
already exists; choose a new --dir	the run directory must be new
Permission denied writing the run	run from a directory you can write
Portrait: bind ...: Address already in use	another program has the port; pass port=N