BBeOS/docs/DEVELOPMENT_GUIDE.md

BBeOS Development Guide

Welcome to the BBeOS development guide! This document serves as the main entry point for developers working on the BlackBerry Classic Linux OS project.

🎯 Project Overview

BBeOS is a lightweight, secure, non-Android, Linux-based operating system for the BlackBerry Classic (Q20) that transforms this iconic device into a modern, privacy-focused smartphone.

Key Features

• Native Hardware Support: Boot on ARMv7 architecture with full hardware integration
• Security-First Design: Privacy-focused design with minimal attack surface
• Physical Interface Optimization: GUI designed for trackpad navigation and physical QWERTY keyboard
• Core Telephony: Complete phone functionality including calling, SMS, Wi-Fi, and GPS
• Open Source: Community-driven development with transparent codebase

📁 Project Structure

BBeOS/
├── docs/                    # Documentation
│   ├── phases/             # Phase-by-phase development docs
│   ├── guides/             # How-to guides and tutorials
│   └── api/                # API documentation and design docs
├── src/                    # Source code
│   ├── kernel/             # Kernel configuration and patches
│   ├── drivers/            # Hardware drivers
│   ├── ui/                 # User interface components
│   ├── telephony/          # Phone functionality
│   ├── apps/               # Core applications
│   ├── sdk/                # Development tools and SDK
│   └── packaging/          # System packaging and deployment
├── build/                  # Build artifacts
│   ├── kernel/             # Kernel builds
│   ├── rootfs/             # Root filesystem
│   └── images/             # Boot images
├── scripts/                # Build automation and tools
├── tests/                  # Test files and test automation
├── vendor/                 # Third-party code and dependencies
├── downloads/              # External downloads and sources
├── community/              # Community website and resources
└── research/               # Hardware research and analysis

🚀 Quick Start

Prerequisites

• Linux development environment (Ubuntu 20.04+ recommended)
• Cross-compilation toolchain for ARMv7
• QEMU for emulation testing
• Git for version control

Building the System

1. Clone the repository:

   git clone https://gitea.lab48.be/eliott/BBeOS.git
   cd BBeOS
   

2. Build the kernel:

   ./scripts/build-kernel.sh
   

3. Build the root filesystem:

   ./scripts/build-rootfs.sh
   

4. Create boot image:

   ./scripts/build-boot-image.sh
   

5. Test in emulation:

   ./scripts/emulate-simple.sh
   

📋 Development Phases

The project is organized into 7 development phases:

Phase 1: Research & Feasibility

• Hardware specification analysis
• Bootloader investigation
• Firmware extraction and analysis
• Documentation: docs/phases/PHASE_1_*.md

Phase 2: Bootstrapping

• Minimal Linux kernel boot
• Basic hardware access
• Development environment setup
• Documentation: docs/phases/PHASE_2_*.md

Phase 3: Hardware Support

• Device drivers development
• Input/output systems
• Display and audio support
• Documentation: docs/phases/PHASE_3_*.md

Phase 4: User Interface

• Wayland-based GUI
• Keyboard-centric navigation
• Core applications
• Documentation: docs/phases/PHASE_4_*.md

Phase 5: Telephony Stack

• Modem integration
• Call/SMS functionality
• Network connectivity
• Documentation: docs/phases/PHASE_5_*.md

Phase 6: Packaging & Updates

• System packaging
• Update mechanisms
• Security hardening
• Documentation: docs/phases/PHASE_6_*.md

Phase 7: Community & SDK

• Developer tools
• Application ecosystem
• Documentation
• Documentation: docs/phases/PHASE_7_*.md

🛠️ Development Workflow

Code Organization

• Source code goes in src/ directory
• Build artifacts are placed in build/ directory
• Scripts are in scripts/ directory
• Documentation is organized in docs/ subdirectories

Testing

• Unit tests in tests/ directory
• Hardware testing with scripts/hardware-test.sh
• Emulation testing with QEMU scripts
• Integration testing for full system

Building Components

Kernel

./scripts/build-kernel.sh          # Full kernel build
./scripts/build-kernel-minimal.sh  # Minimal kernel build

Root Filesystem

./scripts/build-rootfs.sh          # Build BusyBox rootfs

Drivers

./scripts/build-drivers.sh         # Build Q20-specific drivers

User Interface

./scripts/build-ui.sh              # Build UI components

Telephony

./scripts/build-telephony.sh       # Build telephony stack

Packaging

./scripts/build-packaging.sh       # Build system images

🧪 Testing and Emulation

QEMU Emulation

./scripts/emulate-simple.sh        # Simple QEMU demo
./scripts/emulate-bbeos.sh         # Full BBeOS emulation
./scripts/emulate-terminal.sh      # Terminal-based simulation

Hardware Testing

./scripts/hardware-test.sh         # Hardware component testing

📚 Documentation

Guides

• Emulation Guide: docs/guides/EMULATION_GUIDE.md
• Hardware Testing: docs/guides/hardware-testing-guide.md

API Documentation

• UI/UX Design: docs/api/UI_UX_DESIGN.md
• Security Analysis: docs/api/SECURITY_ANALYSIS.md

Phase Documentation

• Phase 1: docs/phases/PHASE_1_*.md
• Phase 2: docs/phases/PHASE_2_*.md
• Phase 3: docs/phases/PHASE_3_*.md
• Phase 4: docs/phases/PHASE_4_*.md
• Phase 5: docs/phases/PHASE_5_*.md
• Phase 6: docs/phases/PHASE_6_*.md
• Phase 7: docs/phases/PHASE_7_*.md

🔧 Configuration

Build Configuration

• Kernel config: src/kernel/msm8960-defconfig
• Device tree: vendor/kernel-source/arch/arm/boot/dts/qcom/

Environment Variables

• CROSS_COMPILE: ARM cross-compilation toolchain
• KERNEL_DIR: Kernel source directory
• BUILD_DIR: Build output directory

🤝 Contributing

Code Style

• Follow Linux kernel coding style for kernel code
• Use consistent indentation and naming conventions
• Add comments for complex logic
• Include error handling

Commit Messages

• Use descriptive commit messages
• Reference issue numbers when applicable
• Follow conventional commit format

Pull Requests

• Create feature branches for new development
• Include tests for new functionality
• Update documentation as needed
• Ensure all tests pass

🐛 Troubleshooting

Common Issues

1. Build failures: Check toolchain installation
2. Emulation issues: Verify QEMU installation
3. Hardware problems: Review device tree configuration

Getting Help

• Check the documentation in docs/
• Review phase-specific guides
• Test with emulation first
• Use hardware testing scripts

📄 License

BBeOS is open source software licensed under the GPL v3 License. See LICENSE file for details.

🔗 Resources

• Repository: https://gitea.lab48.be/eliott/BBeOS
• Community Website: community/website/index.html
• Hardware Specs: hardware/q20-specs.md
• Research: research/ directory

---

This guide is maintained by the BBeOS development team. For questions or contributions, please refer to the project repository.