^ ^                 ^ ^
=(o.o)=  ~byakuren  =(o.o)=
  m m                 m m

Development Guide (flowlog.c)

This guide focuses on developing Flowlog in flowlog.c.

Build and run

make
./flowlog

Direct compilation is also supported:

cc -O2 -Wall -Wextra -pthread flowlog.c -lm -o flowlog

Test workflow

Run the regression suite and INRIA ISO suite from this directory:

make test
make test-inria

To ensure the bytecode VM (flowlog_engine=wamvm) runs the ISO suite without falling back to wam, run:

make test-inria-wamvm-vmonly

Directory layout

• flowlog.c — the entire runtime (single-file build)
• Makefile — minimal build rules for the binary
• tests/ — regressions and ISO suite runners
• README.md and *.md — user and developer documentation

In the full repository checkout, benchmark scripts live under ../bench/.

Adding or adjusting built-ins

Most ISO predicates are implemented as built-ins in the solver’s goal dispatcher.

Suggested workflow:

1. Add the predicate implementation in flowlog.c
2. Add a regression test under tests/
3. If applicable, add a reference comparison case (Trealla/Scryer) or extend the INRIA harness inputs
4. Run:
   • the regression tests
   • the INRIA ISO suite

Coding style and PR hygiene (single file)

Even though flowlog.c is a single file, it helps to keep structure consistent:

• Prefer clear section headers (parser, term representation, unification, solver, built-ins, parallel, REPL).
• Keep helper utilities (buffers, small vectors) near their first use or in a dedicated “support” section.
• Avoid “dead” code paths; keep unused experiments behind #if 0 only temporarily.
• Add tests first when fixing conformance or regressions.

Debugging

OR-par debug logs

Enable OR-par logging:

FLOWLOG_DEBUG_ORPAR=all FLOWLOG_DEBUG_ORPAR_LOG=orpar.log \
  ./flowlog program.pl -g "goal."

Profiling

For CPU-bound problems, perf (Linux) or pmcstat (FreeBSD) can help identify hot paths in:

• unification
• indexing candidate selection
• clause instantiation (standardize-apart)
• allocation

REPL terminal state

The REPL uses termios raw mode when running on a TTY. If a crash leaves your terminal in a bad state, run:

reset