Reporting bugs

Reporting bugs

PJA checks everything it writes, so a bug usually shows as a refusal, a file taken "as bytes" that should not have been, a .pja that does not extract, or a run that ends with "This is a bug in PJA". Any of those is worth an issue. This page says how to make one that can be acted on, and what it does and does not send.

The short way

pja report photo.jpg -o report.txt

That writes a plain-text report and prints a link. Open the link: it is a new issue with the report already pasted in. Add the command you ran, what it printed and what you expected, and submit. A report too long for a link keeps its start and its end, with a line in place of the rest (pja report says so before the link): paste the whole report.txt into the issue as well.

No file to blame? pja report alone gives the part about PJA and the machine.

What a report contains

• PJA: version, the commit it was built from, the build date, the FreePascal version, the C compiler, the target.
• The machine: the system and its version, the processor's name, the SIMD features PJA uses (SSE4.1, AVX2), the path it runs (plain, sse41, avx2), how many processors, how many threads.
• The command line, with every path cut to the file's name.
• The file: its size and BLAKE3-128 hash, what PJA does with it (takes it: stream version 7, ..., as bytes: BadRst@1670, refuses it: ...), and its structure: each marker with its place and length, the frame (coding, precision, size, sampling), each scan, restarts, DNL, what follows the image, JPEGs inside it, the MPF index; for a .pja, the container and the stream inside.

What it does not contain

• No image: not a pixel, not a coefficient.
• No metadata contents: EXIF (camera, dates, GPS), XMP, ICC profiles and comments are counted in bytes and nothing else (Exif 1818 B, XMP 0 B, ...; contents not shown). An APP segment is named only by its standard identifier (Exif, ICC_PROFILE, MPF...).
• No folders: your user name or directory layout never appears.

Read the report before sending it: it is plain text.

Sharing the file

Most bugs need the file itself, but only you decide that:

pja report --with-file photo.jpg -o report.txt

puts a copy of the file beside the report as pja-report-photo.jpg, ready to drag into the issue. GitHub takes .jpg files as they are; zip a .jls, .mpo or .pja first. If the file is private, say so in the issue: the structure in the report is often enough, and a maintainer may ask for a file that shows the same problem.

Before reporting

• pja selftest compresses and extracts the samples built into the binary on every SIMD path the machine has (pja selftest --cpu=sse41: that path alone). If it fails, that alone is the bug: report it with pja report.
• pja --cpu=plain a photo.jpg takes the plain path. A problem that goes away with it, and not with --cpu=sse41 or --cpu=avx2, narrows things down a lot: say which.
• pja info photo.jpg shows what the report will say about the file.
• pja t *.pja checks .pja files without writing anything.

Exit codes

code	meaning
0	everything went through
1	a file failed (not taken, damaged, unreadable, unwritable)
2	the command line was wrong
3	a bug in PJA: please report it

Speed problems

pja bench photo.jpg times compressing (with and without the verification) and extracting, with where the time goes, and prints the machine's details: paste it into the issue. --stats on a, x or t gives the same breakdown for a real run.