Experience report: dry running the tutorial

[anshumanmohan]

This will be a thread of bugs I run into as I dry run the tutorial

---

(Rachit edits to create a checklist)

• [x] Ensure that the docker pull command works
• [ ] The flit command should not require ROOT_INSTALL. Investigate.
• [x] Update fud command to --create `global.root (this should not be needed once we release a new version of the images but fine to have for now)
• [x] Separate out compiler run commands into code blocks

[anshumanmohan]

The recommended Docker installation seems to be behind an installation wall. Is this just me?

$ docker pull ghcr.io/cucapra/calyx:0.2.0
Error response from daemon: Head "https://ghcr.io/v2/cucapra/calyx/manifests/0.2.0": denied: denied

The other thing that is pointed to elsewhere in the repo doesn't work for me either.

$ docker pull ghcr.io/cucapra/calyx:latest
Error response from daemon: Head "https://ghcr.io/v2/cucapra/calyx/manifests/latest": denied: denied

I'm proceeding by just building the docker using the Dockerfile, changing branch to master, and running git pull.

[anshumanmohan]

# flit -f fud/pyproject.toml install -s --deps production

does not work as written; it requires

export FLIT_ROOT_INSTALL=1

first.

[anshumanmohan]

fud config global.root /home/calyx

does not work as written; it requires

fud config --create global.root /home/calyx

[anshumanmohan]

We need to tell them to change directories from

/home/calyx/examples/tutorial/

to

/home/calyx/frontends/mrxl/

[anshumanmohan]

There's something a little brittle about the new fud that has a stage named calyx. If I run it from anywhere but the root, I get

=====STDERR=====
/bin/sh: 1: ./target/debug/calyx: not found

Just a missing step in fud configuration?

[EclecticGriffin]

Need to set the global.root flag in fud to the calyx repo directory. Either that or the compiler hasn't been built.

EDIT: fud seems to not be resolving local paths through the root directory

[anshumanmohan]

Thanks for the tip! I just retried rebuilding Calyx and configuring fud with the global.root flag. Still the same, sadly

[anshumanmohan]

The MrXL pedagogical stuff requires no running, obviously, and simulating MrXL programs fails thusly:

/home/calyx/frontends/mrxl# fud e --from mrxl test/sos.mrxl --to dat --through verilog -s mrxl.data test/sos.mrxl.data
[fud] ERROR: `./target/debug/calyx -l /home/calyx/ -b verilog' failed:
=====STDERR=====
/bin/sh: 1: ./target/debug/calyx: not found

=====STDOUT=====

Note that this won't work at all in master. To run this, I switched to the mrxl-input-dynamic branch, rebuilt the compiler, and ran fud check to ensure that I saw

stages.mrxl.exec:
 ✔ mrxl installed.

However, this works if I change to the root (still in the mrxl-input-dynamic branch) and run it. So the issue is not with @susan-garry's merge-pending input-dynamic work, but with Mother Calyx. Precisely this issue.

root@23c8369f8870:/home/calyx/frontends/mrxl# cd ../../
root@23c8369f8870:/home/calyx# fud e --from mrxl frontends/mrxl/test
/sos.mrxl --to dat --through verilog -s mrxl.data frontends/mrxl/tes
t/sos.mrxl.data
{
  "cycles": 46,
  "memories": {
    "avec_b0": [
      0,
      1,
      4,
      5
    ],
    "sos": [
      42
    ]
  }
}

[anshumanmohan]

Nit:

The getting started guide reads:

You can invoke the compiler in one of two ways:

cargo run -- --help # Rebuilds the compiler if the sources changed
./target/debug/calyx --help # Default debug build of the compiler

I think folks will 100% just copy-paste the block of code and thereby run both things. Those invocations should be in their own fenced code blocks, and maybe the meta info there should be in the main text, not a comment.

[rachitnigam]

Updated top-level comment to create a checklist

[rachitnigam]

@anshumanmohan some of the problems you ran into seem like they happen outside the docker container. Can you confirm this is the case? For example, if you're in the docker container, you shouldn't have to setup global.root or provide the absolute path for the calyx binary.

[anshumanmohan]

I tried to do it in the Docker you pointed to, but after that didn't work I did all this inside a built-from-Dockerfile docker container. So, not just inside Havarti. A docker, but not the release package docker.

It's entirely possible that the container you set up as a package works much better! Just gotta make sure it can be pulled

[anshumanmohan]

I'm proceeding by just building the docker using the Dockerfile, changing branch to master, and running git pull.

[rachitnigam]

I see. The curious thing is that if you used the Dockerfile to build the container, it should have configured things like global.root for you. For example, see: https://github.com/cucapra/calyx/blob/master/Dockerfile#L74

[rachitnigam]

Just to help me reproduce the errors you got, can you provide a step-by-step for me. For example:

1. On local machine, git checkout master && git pull
2. docker build . -t ghcr.io/cucapra/calyx
3. docker run ...
4. (within docker) ???

[anshumanmohan]

Right, I figured as much. In fact the built-from Dockerfile container is probably a close cousin of the released-as-package container. I dunno, I'm pretty sure I'm reporting accurately but of course I could have gotten lost among all the black screens. I can try again tomorrow but it would be nice if others dry-ran it too.

[anshumanmohan]

Sorry, I cannot tonight. I'm just on my phone haha. And I likely cannot get to it before the meeting tomorrow either

[rachitnigam]

Right, the released as package container is the dockerfile-built image so if your commands are failing, then I don't expect anything else to work either. The one cofounding factor could be this setup command we run when using fud for CI: https://github.com/cucapra/calyx/blob/master/.github/workflows/rust.yml#L19

[rachitnigam]

No worries! I'lll try to take a look at it today as well