Cross-Platform Debugging

Systematic approach to debugging issues that only occur on Erlang OR JavaScript.

Quick Diagnosis

bash
1# Run on both targets to identify which fails
2just test-erlang
3just test-js

Common Causes

1. FFI Implementation Mismatch

Symptom: Different behavior between targets for the same function.

Check:

bash
1# Compare FFI implementations
2diff <(grep -A 20 "function_name" src/birch_ffi.erl) \
3     <(grep -A 20 "function_name" src/birch_ffi.mjs)

Common issues:

• Return type mismatch (tuples vs arrays)
• Error handling differences
• String encoding (UTF-8 handling)

2. Platform-Specific APIs

Symptom: Function works on one platform, undefined/error on other.

JavaScript-only APIs:

• process.stdout, process.stderr (Node.js)
• Deno.isatty() (Deno)
• console.log behavior varies by runtime

Erlang-only APIs:

• Process dictionary (erlang:put/get)
• OTP behaviors (gen_server, etc.)
• :logger integration

3. Async Behavior

Symptom: Race conditions or timing issues on JavaScript.

Check:

• Erlang is synchronous by default
• JavaScript may need await or callbacks
• Look for Promise handling in FFI

4. Type Coercion

Symptom: Unexpected values or type errors.

5. TTY/Terminal Detection

Symptom: Color output works on one platform.

Check:

gleam
1// In platform.gleam
2is_stdout_tty()  // Different implementation per platform

Debugging Steps

Step 1: Isolate the Failure

bash
1# Run specific test
2gleam test --target erlang -- --filter "test_name"
3gleam test --target javascript -- --filter "test_name"

Step 2: Add Debug Output

gleam
1// Temporary debug logging
2import gleam/io
3io.debug(value)  // Works on both targets

Step 3: Check FFI

1. Read src/birch/internal/platform.gleam for declarations
2. Compare src/birch_ffi.erl and src/birch_ffi.mjs
3. Look for behavioral differences

Step 4: Test JavaScript Runtimes

bash
1# Test on all JS runtimes
2just test-integration-node
3just test-integration-deno
4just test-integration-bun

Step 5: Check Runtime Detection

In birch_ffi.mjs, verify runtime detection:

javascript
1// Node.js
2typeof process !== 'undefined' && process.versions?.node
3
4// Deno
5typeof Deno !== 'undefined'
6
7// Bun
8typeof Bun !== 'undefined'
9
10// Browser
11typeof window !== 'undefined'

FFI Debugging Checklist

• Both implementations exist for the function
• Return types match Gleam declaration
• Error cases handled identically
• Edge cases (empty string, null, special chars) tested
• All JS runtimes have fallbacks (Node, Deno, Bun, browser)

Quick Fixes