Appendix E: FAQ and Troubleshooting

Frequently Asked Questions

General Questions

Q: Is Wyn production-ready?

A: Wyn 1.19 is stable for production use. The core language is solid, the compiler is reliable, and the standard library covers common use cases. That said, the ecosystem is young. You won't find libraries for everything yet.

Q: How fast is Wyn compared to [language]?

A: Roughly:

• 50-100x faster than Python
• Similar to Go (within 10-20%)
• Slightly slower than Rust (ARC overhead)
• Slightly slower than C (ARC overhead)

Actual performance depends on your workload. Measure your specific use case.

Q: Does Wyn have a package manager?

A: Yes - wyn pkg. Dependencies are git repos (no central registry):

wyn pkg add sqlite       # bare names resolve to github.com/wynlang/<name>
wyn pkg install          # install everything from wyn.lock / wyn.toml

Q: Can I call C code from Wyn?

A: Yes - wyn bind <header.h> generates FFI bindings. Wyn can also generate libraries for other languages:

wyn init mylib --lib c       # C shared library
wyn init mylib --lib python  # Python extension
wyn init mylib --lib node    # Node.js addon

Q: Can I use Wyn for web development?

A: Yes. Wyn has HTTP servers, JSON, SQLite, templates, and deploy built in. See Chapter 15 and 17 for examples. Use wyn init myapp --api or wyn init myapp --web for project templates.

Q: Is Wyn object-oriented or functional?

A: Both. It has objects with methods (OOP) and supports higher-order functions, map/filter/reduce (FP). Use what fits your problem.

Q: Why not just use Rust?

A: Rust is more complex. Wyn trades some of Rust's guarantees for simplicity. If you need maximum performance and control, use Rust. If you want something easier to learn and use, try Wyn.

Q: Why not just use Go?

A: Go is great. Wyn is similar but with stronger type safety, pattern matching, and method-first syntax. Try both, see which you prefer.

Q: Can I contribute to Wyn?

A: Yes! The project is open source. Check the GitHub repository for contribution guidelines.

Installation Issues

Q: wyn: command not found

A: The compiler isn't in your PATH. Either:

# Add to PATH
export PATH="/path/to/wyn:$PATH"

# Or use full path
/path/to/wyn program.wyn

Q: Compilation fails with "No C compiler found"

A: Wyn uses a bundled TCC compiler by default - this error means TCC is missing from your install. Reinstall Wyn:

curl -fsSL https://wynlang.com/install.sh | sh

Or install a system C compiler as fallback:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

Q: permission denied when running compiled program

A: Make it executable:

chmod +x program.wyn.out
./program.wyn.out

Compilation Errors

Q: No main function found

A: Every program needs a main function:

fn main() -> int {
    // Your code here
    return 0
}

Q: Type mismatch: expected int, got string

A: You're using the wrong type. Check your function signatures and variable types. The error message shows where the mismatch is.

Q: Undefined variable: x

A: You're using a variable before declaring it, or it's out of scope. Declare it with var or const before use.

Q: Cannot modify const variable

A: Variables declared with const can't be reassigned. Use var if you need to modify it:

var mutable = 10
mutable = 20  // OK

const immutable = 10
// immutable = 20  // Error

Q: Module not found: module_name

A: The import path is wrong, or the module doesn't exist. Check:

• File exists at the expected path
• Import path matches directory structure
• File has .wyn extension

Q: Circular dependency detected

A: Two modules import each other. Refactor to break the cycle:

• Extract shared code to a third module
• Redesign module boundaries

Runtime Errors

Q: Program crashes with "index out of bounds"

A: You're accessing an array index that doesn't exist:

var arr = [1, 2, 3]
// arr[5]  // Crash - only indices 0-2 exist

// Check bounds first
if (i < arr.len()) {
    var value = arr[i]
}

Q: Program crashes with "null pointer"

A: You're accessing a value that doesn't exist. Use Option and check:

var maybe_value = find_user(id)
match maybe_value {
    some(user) => use_user(user),
    none => handle_not_found()
}

Q: Program hangs forever

A: Likely an infinite loop or deadlock:

• Check loop conditions
• Check channel operations (send/receive might block)
• Add timeouts to blocking operations

Q: "Too many open files" error

A: You're holding too many resources open at once - sockets, database handles, spawned processes. Close what you open (ch.close(), Db.close(db), Http.close_client(fd)) and prefer File.read/File.write, which open and close the file for you.

Performance Issues

Q: My program is slow

A: Build with optimizations, then profile with the system tools (Wyn binaries are ordinary native executables):

wyn build program.wyn --release
sample ./program 5                    # macOS quick profile (while it runs)
perf record ./program && perf report  # Linux

Common causes:

• Unnecessary allocations in loops
• Copying large structs
• O(n²) algorithms where O(n log n) would work
• Not using concurrency for I/O-bound tasks

Q: Memory usage keeps growing

A: Possible memory leak. Check for:

• Reference cycles (ARC does not collect cycles - break them manually)
• Accumulating data in collections
• Not clearing caches

Profile memory with the system tools (Wyn binaries are ordinary executables):

wyn build program.wyn
/usr/bin/time -l ./program          # macOS peak RSS (-v on Linux)
leaks --atExit -- ./program         # macOS allocation analysis
valgrind --tool=massif ./program    # Linux

Q: Compilation is slow

A: Dev builds are already incremental - wyn run skips recompilation when the binary is newer than the source. For the fastest compiles:

wyn build program.wyn --fast   # skip optimizations
wyn build-runtime              # precompile the runtime once

Concurrency Issues

Q: Race condition / unpredictable results

A: You're sharing mutable state between tasks. Don't do that. Communicate through channels instead:

fn send_one(ch: int) -> int {
    ch.send(1)
    return 0
}

fn main() -> int {
    var ch = channel(2)
    var f1 = spawn send_one(ch)
    var f2 = spawn send_one(ch)
    var sum = ch.recv() + ch.recv()
    println(sum)
    await f1
    await f2
    return 0
}

Q: Deadlock - program hangs

A: Tasks are waiting for each other. Common causes:

• Sending on unbuffered channel with no receiver
• Receiving on channel with no sender
• Circular wait (A waits for B, B waits for A)

Solution: Use buffered channels or redesign communication pattern.

Q: "Channel closed" error

A: You're sending on a closed channel. Check if channel is closed before sending, or redesign to avoid closing while senders are active.

Error Handling

Q: How do I handle multiple errors?

A: Use the ? operator to propagate:

fn process() -> ResultInt {
    var data = read_data("data.txt")?
    var parsed = parse_data(data)?
    var result = compute(parsed)?
    return Ok(result)
}

Q: How do I convert Option to Result?

A:

fn option_to_result(opt: OptionInt) -> ResultInt {
    match opt {
        some(value) => return Ok(value),
        none => return Err("No value")
    }
}

Q: How do I ignore an error?

A: Don't. Handle it properly. If you really must, call the function as a bare statement and discard the result:

risky_operation()  // Result ignored

But this is bad practice. At minimum, log the error.

Best Practices

Q: Should I use var or const?

A: Default to const. Only use var when you need to mutate.

Q: When should I use generics?

A: When you're writing code that works with any type (containers, algorithms, utilities). Don't over-generalize.

Q: How do I organize large projects?

A: By feature, usually:

project/
├── users/
│   ├── model.wyn
│   ├── service.wyn
│   └── repository.wyn
├── orders/
│   └── ...
└── main.wyn

Q: How do I handle configuration?

A: Load from JSON file with fallback to defaults:

fn load_config() -> Config {
    if not File.exists("config.json") {
        return default_config()
    }
    var contents = File.read("config.json")
    var json = Json.parse(contents)
    return Config { port: json.get("port").to_int() }
}

Q: How do I structure tests?

A: Create *_test.wyn files alongside source files. Each test is a function that returns 0 for pass, 1 for fail.

Common Mistakes

Q: Why doesn't this work?

var x = some_function()
print(x.field)  // Error

A: some_function() returns Option<T> or Result<T, E>. You need to unwrap it:

var result = some_function()
match result {
    ok(value) => print(value.field),
    err(e) => print("Error: " + e)
}

Q: Why doesn't this work?

fn add(a, b) {  // Error: missing types
    return a + b
}

A: Function parameters need types:

fn add(a: int, b: int) -> int {
    return a + b
}

Getting Help

Q: Where can I get help?

A:

• Read this book (you're doing it!)
• Check the official documentation
• Search GitHub issues
• Ask on the community forum
• Join the Discord/Slack

Q: How do I report a bug?

A:

1. Check if it's already reported
2. Create a minimal reproduction
3. Open a GitHub issue with:
   • Wyn version (wyn --version)
   • Operating system
   • Code that reproduces the bug
   • Expected vs actual behavior

Q: How do I request a feature?

A: Open a GitHub issue with:

• Clear description of the feature
• Use cases (why you need it)
• Examples of how it would work
• Comparison with other languages (if applicable)

Troubleshooting Checklist

When something doesn't work:

1. Read the error message carefully - It usually tells you what's wrong
2. Check the line number - Errors are reported where detected, might be earlier
3. Verify types - Most errors are type mismatches
4. Check scope - Is the variable in scope?
5. Handle errors - Are you ignoring Result/Option?
6. Simplify - Remove code until it works, then add back
7. Search - Someone else probably had this problem
8. Ask - Community is helpful

Quick Fixes

Problem	Solution
Command not found	Add to PATH
Type mismatch	Check function signatures
Undefined variable	Declare before use
Module not found	Check import path
Index out of bounds	Check array length
Infinite loop	Check loop condition
Memory leak	Profile and fix
Race condition	Use channels, not shared state
Deadlock	Redesign communication
Slow compilation	Use --fast and wyn build-runtime

Still Stuck?

If you've tried everything:

1. Create a minimal reproduction
2. Check GitHub issues
3. Ask on the forum
4. Join the community chat

Include:

• Wyn version
• Operating system
• Complete error message
• Minimal code that reproduces the issue

The community is friendly and helpful. Don't hesitate to ask.

---

For language reference, see Appendix A. For tooling setup, see Appendix D.