Reporting bugs

This page is for beta testers, whether you use the release archive or a clone of the repository. It says what to check first, what to put in a report, how to cut a program down to a small one that still shows the problem, and how to tell a bug from something PXX does not support yet.

Reports go to the project's issue tracker:

Placeholder: the address of the project's issue tracker goes here. Where it will be hosted has not been decided yet.

A program that compiles and quietly gives a wrong answer is the most valuable report you can send. A refusal with a clear message is usually already known; a wrong answer usually is not.

Check the known issues first

Look for your problem on these pages before you write it up:

If your problem is listed, a report is still useful when your program shows it in a shape the page does not mention, or when the workaround does not work for you. Say which entry you mean.

What to put in a report

  1. Which compiler you ran. Paste the output of:

    ./pxx --version

    Its build: line is the SHA-256 of the compiler binary that ./pxx runs (the first 12 digits of what sha256sum prints). The lines under it say where that binary came from: a release archive's release: and source:, or a clone's pin: and source:. A binary that no record names says local:. The compiler computes the hash itself, so it works the same in an archive and in a clone, and needs no git.

    If --version prints no build: line, your compiler is older than this feature. The v0.1.0-beta.1 archive is one of them. Paste this instead:

    ./pxx --where | head -1
sha256sum "$(./pxx --where | sed -n 's/^binary: *//p')"

  2. The exact command, with every flag. The ones that change the result most are --target= (the CPU, or an ESP chip name such as esp32c3), --platform=, --esp-profile=bare, -O0 to -O3, --threadsafe and --system-libs. Say whether you ran ./pxx or a compiler binary directly: ./pxx adds the library search paths, and the two can resolve an import differently.

  3. Where the program ran: natively on x86-64, under QEMU (tools/run_target.sh), under wasmtime, under Espressif's QEMU, or on a board. For a board, give the chip and the ESP-IDF version.

  4. The smallest source file that shows the problem, pasted in full. See the next section.

  5. What you expected, and what you got, both pasted as text. The best "expected" is another compiler's output for the same file: GCC's for C, Free Pascal's for Pascal, CPython's for Nil Python. For a compile error, paste the whole message.

  6. The output of ./pxx --doctor if the problem is about building at all: a missing tool, a target that does not run, or an ESP build.

Making a small reproducer

A report with a ten-line program gets fixed; a report that needs your whole project often waits. To cut a program down:

  1. Save the failing version and a script that shows the failure, such as a build and run whose output you compare with the expected output. Every cut below is judged by that script.
  2. Delete, then re-check. Remove a routine, a unit, a class or a block of statements, and run the script. If the problem is still there, keep the cut; if it went away, undo it and try something else.
  3. Replace inputs with constants. Replace files, command-line arguments and network data with literal values in the source.
  4. Inline what is left. Move the remaining pieces of other units or files into one file, if the problem survives that.
  5. Stop when nothing more can go. A good reproducer is one file, prints a value, and says in a comment what the value should be.

Two quick checks narrow a problem down, and are worth putting in the report:

Make sure the small program still fails for the same reason as the original. Cutting can move a program onto a different problem: if the message or the wrong value changed along the way, report the one you started with, or both.

Bug, or not supported yet?

Next