Contributing Guide

​

About Dryft

• Stack-based concatenative programming - Programs compose functions that transform a data stack
• Pure and impure function distinction - Explicit separation between functions (pure) and actions (impure)
• Linear types - Stack-based resource management with linear type tracking
• Optional type inference - Full type inference with optional annotations
• Simple extensible syntax - Minimal keywords with clear semantics

​

Project Structure

src/
├── backends/          # Code generation backends
│   ├── c99/          # C99 transpiler backend
│   └── x86/          # x86-64 assembly backend (in development)
├── targets/           # Build profiles for different platforms
│   ├── gcc.toml      # GCC/C99 build configuration
│   └── elf.toml      # Native x86-64 ELF configuration
├── frontend.rs        # Single-pass compiler frontend
├── backends.rs        # Backend trait and selection
├── state.rs           # Compiler state and types
└── main.rs            # CLI entry point

doc/
├── how_to_add_a_backend.md    # Backend development guide
└── build_graph.md              # Compilation pipeline diagram

native/
└── stdc/              # C standard library bindings

​

Development Setup

git clone https://github.com/your-repo/dryft.git
cd dryft

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# GCC (most Linux distributions)
sudo apt install gcc

# NASM assembler
sudo apt install nasm

cargo build --release

cargo test

​

Ways to Contribute

​

1. Add Language Features

• src/frontend.rs - Add token handling in handle_token()
• src/backends.rs - Add method to the Backend trait
• Each backend - Implement the new method
• src/state.rs - Add types or state if needed

• Structs and composite types
• Module system improvements
• Pattern matching
• More control flow constructs
• Compile-time evaluation

​

2. Create a New Backend

• LLVM IR - Unlock powerful optimizations
• WebAssembly - Run Dryft in browsers
• ARM assembly - Target embedded systems
• JVM bytecode - Integrate with Java ecosystem
• Other languages - Python, JavaScript, Go, etc.

​

3. Improve Existing Backends

• Variables (create, read, write)
• Control flow (loops, conditionals)
• Comparisons and logic operations
• String support

• Better stack management
• Inline small functions
• Optimize away unnecessary push/pop sequences

​

4. Standard Library

• File I/O operations
• Network sockets
• String manipulation
• Data structures (lists, maps, etc.)
• Math functions
• System calls

​

5. Tooling

• Syntax highlighting - VSCode, Vim, Emacs, etc.
• LSP server - IDE integration
• Formatter - Code formatting tool
• Debugger - Interactive debugging support
• Package manager - Dependency management
• REPL - Interactive interpreter

​

6. Documentation

• Tutorial for beginners
• Language reference
• Standard library documentation
• Example programs
• Video tutorials
• Blog posts about Dryft

​

7. Testing

• Write test programs in .dry
• Add unit tests for compiler components
• Integration tests for build pipeline
• Fuzzing for compiler robustness
• Benchmark suite for performance tracking

​

Contribution Workflow

# Fork the repo on GitHub, then:
git clone https://github.com/YOUR-USERNAME/dryft.git
cd dryft
git checkout -b feature/your-feature-name

# Run all tests
cargo test

# Test with example programs
cargo run -- examples/fizzbuzz.dry

# Check formatting
cargo fmt --check

# Run linter
cargo clippy

git add .
git commit -m "Add feature: your feature description"
git push origin feature/your-feature-name

​

Code Style Guidelines

​

Rust Code

• Follow standard Rust style (cargo fmt)
• Use meaningful variable names
• Add comments for complex logic
• Prefer explicit types in public APIs
• Keep functions focused and small
• Use Rust idioms (iterators, ? operator, etc.)

​

Dryft Code

• Use descriptive function names
• Separate functions and actions clearly
• Add comments explaining stack effects: # ( in -- out )
• Keep functions small and composable
• Use proper indentation for nested blocks

​

Documentation

• Write clear, concise explanations
• Include code examples
• Link to related sections
• Keep language simple and accessible

​

Backend Development Guidelines

1. Start simple - Get basic arithmetic and functions working first
2. Study C99 backend - It’s the reference implementation
3. Use todo!() - For unimplemented features, don’t leave stubs empty
4. Test incrementally - Test each feature as you implement it
5. Document limitations - Be clear about what’s not supported yet
6. Add build profile - Create a TOML file in src/targets/

​

Compiler Architecture Notes

• Single-pass compilation - Tokens are processed immediately, no AST
• Stack-based - The compiler tracks stack state and types
• Type checking - Each operation validates input types and pushes output types
• Definition stack - Tracks nested contexts (function, loop, conditional, etc.)
• Backend abstraction - Frontend is backend-agnostic

​

Testing Guidelines

​

Unit Tests

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_feature() {
        // Test code
    }
}

​

Integration Tests

​

Test Coverage

• Happy path (normal usage)
• Edge cases (empty input, boundary values)
• Error cases (invalid syntax, type errors)
• Interactions (how features work together)

​

Communication

• GitHub Issues - Bug reports, feature requests, questions
• Pull Requests - Code review and discussion
• Discussions - General questions and ideas

​

License

/*
 * Copyright (C) 2025 Filip Chovanec
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

​

Getting Help

1. Check existing documentation and issues
2. Look at similar code in the codebase
3. Ask in GitHub Discussions
4. Open an issue with your question

​

Code of Conduct

​

Recognition

• Release notes
• Contributors list
• Project documentation