Community & Contributing

SUB is open source (MIT License) and welcomes contributions of all kinds — bug reports, documentation, new features, and new backends. This guide covers everything you need to get started.

How to Contribute

There are many ways to contribute, regardless of your experience level:

Report bugs — Found something wrong? Open an issue.
Improve documentation — Typos, unclear explanations, missing examples. All welcome.
Add examples — Share interesting programs you've written in SUB.
Fix bugs — Look for issues labeled good first issue to get started.
Add features — Discuss your idea in an issue first, then submit a PR.
Add a backend — See Adding New Backends below.
Package SUB — Help with packaging for new platforms or distros.

Building from Source

The build process is simple — one command, no dependencies beyond a C compiler.

# Clone the repository
git clone https://github.com/subhobhai943/sub-lang.git
cd sub-lang

# Build all three tools (subi, subc, sub)
make

# Run the test suite
make test

# Install locally
sudo make install

Requirements

C compiler — GCC or Clang
GNU Make — make (or gmake on FreeBSD)
Git — for cloning the repository

That's it. No build system generators, no package managers, no configuration.

Tip: Set CC=clang or CC=gcc to choose your compiler. Set PREFIX to change the install location.

Running Tests

SUB ships with a comprehensive conformance test suite that verifies every backend produces identical output.

# Run all tests
make test

# Run only interpreter tests
make test-interp

# Run only transpiler tests
make test-transpile

How the conformance suite works

Each test is a .sb program in the tests/ directory
The program is run through subi (the interpreter) to capture reference output
The same program is transpiled to each target language and run
Outputs are diffed — any difference is a test failure

This ensures that all 13 backends agree with the interpreter on every program.

Note: When adding a new feature, always add a conformance test. This is how we guarantee cross-backend consistency.

Adding New Backends

Adding a new transpilation target is the most impactful contribution you can make. Here's the process:

1. Understand the AST

All backends walk the same AST. The node types are defined in src/ast.h. Each node has a type tag and type-specific fields. Your backend needs a walk function that handles every node type.

2. Create the backend file

Add a new file src/codegen_<target>.c following the pattern of existing backends. The key functions are:

codegen_<target>_init() — initialize state
codegen_<target>_emit(ast) — walk the AST and emit output
codegen_<target>_finish() — finalize and write output

3. Register the target

Add your target to the dispatch table in src/main.c so sub program.sb <your-target> works.

4. Add conformance tests

Add your backend to the CI test matrix. Every existing test program must pass through your backend.

5. Update documentation

Add your target to the transpilation docs and the type mapping table.

Project Structure

sub-lang/
├── src/               # C source code
│   ├── main.c         # Entry point, tool dispatch
│   ├── lexer.c/h      # Tokenizer
│   ├── parser.c/h     # AST builder
│   ├── interpreter.c  # subi — direct AST interpreter
│   ├── codegen_*.c    # One file per transpilation target
│   ├── codegen_infer.c # Type inference
│   ├── elf_emit.c     # ELF64 binary writer (subc)
│   └── stdlib_*.c     # Standard library runtime
├── stdlib/            # Standard library (.sb files)
│   ├── math.sb
│   ├── arrays.sb
│   ├── strings.sb
│   └── ...
├── tests/             # Conformance test suite
├── packaging/         # Platform packages (deb, rpm, arch, etc.)
├── installer/         # Universal install script
├── Makefile
└── README.md

Code of Conduct

We are committed to providing a friendly, safe, and welcoming environment for all, regardless of level of experience, gender identity, sexual orientation, disability, neurotype, ethnicity, religion, or similar personal characteristic.

Be respectful and inclusive in all interactions.
Give constructive feedback — critique code, not people.
Assume good intent. Ask clarifying questions before reacting.
Don't engage in personal attacks, trolling, or harassment.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project maintainer at GitHub. All complaints will be reviewed and investigated.

Reporting Issues

Use GitHub Issues to report bugs, request features, or ask questions.

Before reporting

Check if the issue already exists (search open and closed issues).
Make sure you're using the latest version of SUB.
Try to reproduce the issue with a minimal example.

Writing a good bug report

Title — a short, descriptive summary
Steps to reproduce — the exact commands and code
Expected behavior — what should happen
Actual behavior — what actually happens
Environment — OS, SUB version, compiler version

Security issues: Do not report security vulnerabilities in public issues. See the Security Policy for the responsible disclosure process.

Getting Help

GitHub Discussions — ask questions, share ideas
GitHub Issues — report bugs and request features
Getting Started — if you're new to SUB