Skip to main content

Getting Started

Set up the Ora development environment and try the current implementation.

🚧 EXPERIMENTAL PROJECT: Ora is NOT ready for production use. This guide is for experimenting with the current implementation and understanding the development progress.

Prerequisites​

  • Zig 0.14.1 or later
  • CMake (for Solidity library integration)
  • Git (for submodules)
  • Basic familiarity with smart contracts (helpful but not required)

Installation​

Clone and Build​

# Clone the repository
git clone https://github.com/oralang/Ora.git
cd Ora

# Initialize submodules (required for Solidity integration)
git submodule update --init --recursive

# Build the compiler
zig build

# Run tests to verify installation
zig build test

Verify Installation​

Test that Ora is working correctly:

# Check the compiler help
./zig-out/bin/ora --help

# Run a simple compilation test
./zig-out/bin/ora examples/core/simple_parser_test.ora

Current Implementation Status​

What Works Now​

  • ✅ Basic contract compilation
  • ✅ Yul code generation
  • ✅ EVM bytecode output
  • ✅ Simple storage operations
  • ✅ Function definitions and calls

What's In Development​

  • 🚧 Formal verification system
  • 🚧 Advanced error handling
  • 🚧 Memory safety guarantees
  • 🚧 Standard library functions

Try Your First Contract​

Let's explore the current implementation with a simple storage contract.

Create a Test Contract​

Create a file simple_test.ora:

contract SimpleStorage {
    storage var value: u256;
    
    pub fn set(new_value: u256) {
        value = new_value;
    }
    
    pub fn get() -> u256 {
        return value;
    }
}

Compile the Contract​

# Compile to Yul (intermediate representation)
./zig-out/bin/ora simple_test.ora

# The compiler will output Yul code that can be further compiled to EVM bytecode

Exploring Examples​

The repository contains working examples that demonstrate current capabilities:

Core Examples​

  • examples/core/simple_parser_test.ora - Basic parsing demonstration
  • examples/core/control_flow_test.ora - Control flow structures
  • examples/tokens/simple_token.ora - Token contract patterns

Advanced Examples (Experimental)​

  • examples/advanced/formal_verification_test.ora - Formal verification syntax (in development)
  • examples/advanced/error_union_demo.ora - Error handling patterns (in development)

Run Example Tests​

# Test core functionality
./scripts/test-examples-simple.sh

# Run all example tests (some may fail - this is expected)
./scripts/test-examples.sh

Understanding the Output​

When you compile an Ora contract, you'll see:

  1. Lexical Analysis: Token stream from source code
  2. Syntax Analysis: Abstract syntax tree (AST)
  3. Semantic Analysis: Type checking and validation
  4. HIR Generation: High-level intermediate representation
  5. Yul Output: Ethereum's intermediate language
  6. Bytecode: Final EVM bytecode (if successful)

Development Workflow​

  1. Start with existing examples - Understand current capabilities
  2. Make small modifications - Test incremental changes
  3. Expect compilation errors - Many features are still being implemented
  4. Report interesting findings - Help improve the language

Common Issues​

  • Syntax errors: Language syntax is still evolving
  • Compilation failures: Some features are not yet implemented
  • Runtime errors: Limited testing of generated bytecode
  • Missing features: Advanced functionality is in development

Next Steps​

If You Want to Explore Further​

  1. Study the examples - See examples/ for working code patterns
  2. Read the specifications - Check docs/specifications/ for technical details
  3. Try modifications - Experiment with syntax variations
  4. Review the source - Understand the compiler implementation

If You Want to Contribute​

  1. Report bugs - File issues for unexpected behavior
  2. Suggest improvements - Discuss language design decisions
  3. Submit examples - Share interesting contract patterns
  4. Help with documentation - Improve this notebook

Development Environment Tips​

IDE Setup​

  • Use any text editor with basic syntax highlighting
  • Zig language server provides some support for the compiler code
  • No dedicated Ora language support yet

Debugging​

  • Use zig build test to run compiler tests
  • Check zig-out/bin/ora --help for compiler options
  • Review generated Yul code for understanding compilation process

Building from Source​

# Clean build
zig build clean
zig build

# Debug build with more information
zig build -Doptimize=Debug

# Release build for performance
zig build -Doptimize=ReleaseFast

Limitations and Warnings​

Current Limitations​

  • No standard library yet
  • Limited error messages
  • Incomplete type system
  • No formal verification implementation
  • Minimal testing framework

Safety Warnings​

  • Do not use for production contracts
  • Generated bytecode is experimental
  • Language syntax will change
  • No security audits performed
  • API is unstable

This guide reflects the current state of development. Check the repository for the latest updates.