Eliott
73fb76098e
Some checks failed
CI / markdown-lint (push) Failing after 14s
- Reorganized directory structure following open source best practices - Created src/ directory for all source code components - Moved build artifacts to build/ subdirectories - Organized documentation into phases/, guides/, and api/ subdirectories - Moved third-party code to vendor/ directory - Moved downloads to downloads/ directory - Updated all build scripts to reference new directory structure - Created comprehensive PROJECT_STRUCTURE.md documentation - Added DEVELOPMENT_GUIDE.md as main entry point - Improved separation of concerns and maintainability - Follows standard open source project conventions
281 lines
13 KiB
Markdown
281 lines
13 KiB
Markdown
# BBeOS Project Structure
|
|
|
|
This document provides a comprehensive overview of the BBeOS project structure and organization.
|
|
|
|
## 📁 Directory Layout
|
|
|
|
```
|
|
BBeOS/
|
|
├── 📚 docs/ # Documentation
|
|
│ ├── 📋 phases/ # Phase-by-phase development docs
|
|
│ │ ├── PHASE_1_*.md # Research & Feasibility
|
|
│ │ ├── PHASE_2_*.md # Bootstrapping
|
|
│ │ ├── PHASE_3_*.md # Hardware Support
|
|
│ │ ├── PHASE_4_*.md # User Interface
|
|
│ │ ├── PHASE_5_*.md # Telephony Stack
|
|
│ │ ├── PHASE_6_*.md # Packaging & Updates
|
|
│ │ └── PHASE_7_*.md # Community & SDK
|
|
│ ├── 📖 guides/ # How-to guides and tutorials
|
|
│ │ ├── EMULATION_GUIDE.md # QEMU emulation guide
|
|
│ │ └── hardware-testing-guide.md # Hardware testing guide
|
|
│ ├── 🔧 api/ # API documentation and design docs
|
|
│ │ ├── UI_UX_DESIGN.md # UI/UX design specifications
|
|
│ │ └── SECURITY_ANALYSIS.md # Security analysis and recommendations
|
|
│ └── DEVELOPMENT_GUIDE.md # Main development guide
|
|
│
|
|
├── 💻 src/ # Source code
|
|
│ ├── 🖥️ kernel/ # Kernel configuration and patches
|
|
│ │ └── msm8960-defconfig # MSM8960 kernel configuration
|
|
│ ├── 🔌 drivers/ # Hardware drivers
|
|
│ │ ├── display/ # Display drivers
|
|
│ │ │ └── q20-panel.c # Q20 LCD panel driver
|
|
│ │ ├── input/ # Input device drivers
|
|
│ │ │ └── q20-keyboard.c # Q20 keyboard driver
|
|
│ │ └── Makefile # Driver build configuration
|
|
│ ├── 🖼️ ui/ # User interface components
|
|
│ │ ├── compositor/ # Wayland compositor
|
|
│ │ │ └── q20-compositor.c # Q20-specific compositor
|
|
│ │ ├── applications/ # UI applications
|
|
│ │ │ └── home-screen.c # Home screen application
|
|
│ │ └── Makefile # UI build configuration
|
|
│ ├── 📞 telephony/ # Phone functionality
|
|
│ │ ├── modem/ # Modem drivers
|
|
│ │ │ └── q20-modem.c # MDM9615 modem driver
|
|
│ │ ├── voice/ # Voice call management
|
|
│ │ │ └── q20-voice.c # Voice call driver
|
|
│ │ ├── sms/ # SMS management
|
|
│ │ │ └── q20-sms.c # SMS driver
|
|
│ │ └── Makefile # Telephony build configuration
|
|
│ ├── 📱 apps/ # Core applications
|
|
│ │ ├── core/ # Core system apps
|
|
│ │ │ ├── calculator.c # Calculator application
|
|
│ │ │ └── text-editor.c # Text editor application
|
|
│ │ └── Makefile # Application build configuration
|
|
│ ├── 🛠️ sdk/ # Development tools and SDK
|
|
│ │ └── tools/ # SDK tools
|
|
│ │ └── bbeos-sdk.c # BBeOS SDK main tool
|
|
│ └── 📦 packaging/ # System packaging and deployment
|
|
│ ├── system/ # System image creation
|
|
│ │ └── image-builder.c # System image builder
|
|
│ ├── security/ # Security components
|
|
│ │ └── secure-boot.c # Secure boot implementation
|
|
│ ├── updates/ # Update system
|
|
│ │ └── ota-updater.c # OTA update system
|
|
│ └── Makefile # Packaging build configuration
|
|
│
|
|
├── 🔨 build/ # Build artifacts
|
|
│ ├── 🖥️ kernel/ # Kernel builds
|
|
│ │ ├── zImage # Kernel image
|
|
│ │ ├── *.dtb # Device tree blobs
|
|
│ │ └── modules/ # Kernel modules
|
|
│ ├── 📁 rootfs/ # Root filesystem
|
|
│ │ ├── bin/ # Binary files
|
|
│ │ ├── etc/ # Configuration files
|
|
│ │ ├── lib/ # Library files
|
|
│ │ └── init # Init script
|
|
│ ├── 🖼️ images/ # Boot images
|
|
│ │ ├── bbeos-boot.img # Bootable system image
|
|
│ │ ├── initramfs.img # Initial RAM filesystem
|
|
│ │ └── recovery.img # Recovery image
|
|
│ ├── 🖼️ ui/ # UI build artifacts
|
|
│ │ ├── compositor/ # Compiled compositor
|
|
│ │ ├── applications/ # Compiled applications
|
|
│ │ └── assets/ # UI assets
|
|
│ └── 📦 boot-unpacked/ # Unpacked boot components
|
|
│
|
|
├── 🔧 scripts/ # Build automation and tools
|
|
│ ├── build-kernel.sh # Full kernel build script
|
|
│ ├── build-kernel-minimal.sh # Minimal kernel build script
|
|
│ ├── build-rootfs.sh # Root filesystem build script
|
|
│ ├── build-boot-image.sh # Boot image creation script
|
|
│ ├── build-drivers.sh # Driver build script
|
|
│ ├── build-ui.sh # UI build script
|
|
│ ├── build-telephony.sh # Telephony build script
|
|
│ ├── build-packaging.sh # Packaging build script
|
|
│ ├── emulate-simple.sh # Simple QEMU emulation
|
|
│ ├── emulate-bbeos.sh # Full BBeOS emulation
|
|
│ ├── emulate-terminal.sh # Terminal-based simulation
|
|
│ ├── hardware-test.sh # Hardware testing script
|
|
│ ├── flash-boot.sh # Device flashing script
|
|
│ ├── test-qemu.sh # QEMU testing script
|
|
│ └── test-qemu-compatible.sh # Compatible QEMU testing
|
|
│
|
|
├── 🧪 tests/ # Test files and test automation
|
|
│ ├── unit/ # Unit tests
|
|
│ ├── integration/ # Integration tests
|
|
│ └── hardware/ # Hardware tests
|
|
│
|
|
├── 📦 vendor/ # Third-party code and dependencies
|
|
│ └── kernel-source/ # Linux kernel source
|
|
│ ├── arch/arm/boot/dts/qcom/ # Qualcomm device trees
|
|
│ └── ... # Other kernel files
|
|
│
|
|
├── 📥 downloads/ # External downloads and sources
|
|
│ ├── busybox-1.36.1/ # BusyBox source
|
|
│ ├── busybox-1.36.1.tar.bz2 # BusyBox archive
|
|
│ └── ... # Other downloads
|
|
│
|
|
├── 🌐 community/ # Community website and resources
|
|
│ └── website/ # Community website
|
|
│ └── index.html # Main website page
|
|
│
|
|
├── 🔬 research/ # Hardware research and analysis
|
|
│ ├── q20-hardware-research.md # Q20 hardware research
|
|
│ ├── bootloader-analysis.md # Bootloader analysis
|
|
│ ├── driver-compatibility.md # Driver compatibility research
|
|
│ └── q20-specs.md # Q20 specifications
|
|
│
|
|
├── 📋 .gitea/ # Gitea configuration
|
|
│ └── workflows/ # CI/CD workflows
|
|
│ └── ci.yml # Continuous integration
|
|
│
|
|
├── 📄 Configuration Files
|
|
│ ├── README.md # Project overview
|
|
│ ├── QUICK_START.md # Quick start guide
|
|
│ ├── PROJECT_STRUCTURE.md # This file
|
|
│ ├── .gitignore # Git ignore rules
|
|
│ ├── config.yaml # Gitea runner configuration
|
|
│ └── bbeos-runner.service # Systemd service file
|
|
│
|
|
└── 🏗️ hardware/ # Hardware specifications
|
|
└── q20-specs.md # BlackBerry Classic Q20 specs
|
|
```
|
|
|
|
## 🎯 Organization Principles
|
|
|
|
### **1. Separation of Concerns**
|
|
- **Source code** (`src/`) is separate from **build artifacts** (`build/`)
|
|
- **Documentation** (`docs/`) is organized by type and purpose
|
|
- **Scripts** (`scripts/`) handle automation and tooling
|
|
- **Third-party code** (`vendor/`) is isolated from project code
|
|
|
|
### **2. Build System Organization**
|
|
- **Build artifacts** are placed in `build/` subdirectories
|
|
- **Downloads** are stored in `downloads/` directory
|
|
- **Scripts** reference the new directory structure
|
|
- **Clean separation** between source and build files
|
|
|
|
### **3. Documentation Structure**
|
|
- **Phase documentation** in `docs/phases/`
|
|
- **How-to guides** in `docs/guides/`
|
|
- **API documentation** in `docs/api/`
|
|
- **Main development guide** at `docs/DEVELOPMENT_GUIDE.md`
|
|
|
|
### **4. Source Code Organization**
|
|
- **Kernel components** in `src/kernel/`
|
|
- **Hardware drivers** in `src/drivers/`
|
|
- **User interface** in `src/ui/`
|
|
- **Telephony stack** in `src/telephony/`
|
|
- **Applications** in `src/apps/`
|
|
- **Development tools** in `src/sdk/`
|
|
- **Packaging tools** in `src/packaging/`
|
|
|
|
## 🔄 Build Workflow
|
|
|
|
### **1. Kernel Build**
|
|
```bash
|
|
./scripts/build-kernel.sh # Full kernel build
|
|
./scripts/build-kernel-minimal.sh # Minimal kernel build
|
|
```
|
|
- **Source**: `vendor/kernel-source/`
|
|
- **Output**: `build/kernel/`
|
|
|
|
### **2. Root Filesystem**
|
|
```bash
|
|
./scripts/build-rootfs.sh # Build BusyBox rootfs
|
|
```
|
|
- **Source**: `downloads/busybox-*/`
|
|
- **Output**: `build/rootfs/`
|
|
|
|
### **3. System Components**
|
|
```bash
|
|
./scripts/build-drivers.sh # Build hardware drivers
|
|
./scripts/build-ui.sh # Build UI components
|
|
./scripts/build-telephony.sh # Build telephony stack
|
|
./scripts/build-packaging.sh # Build system images
|
|
```
|
|
- **Source**: `src/*/`
|
|
- **Output**: `build/*/`
|
|
|
|
### **4. System Integration**
|
|
```bash
|
|
./scripts/build-boot-image.sh # Create bootable image
|
|
```
|
|
- **Input**: `build/kernel/`, `build/rootfs/`
|
|
- **Output**: `build/images/`
|
|
|
|
## 🧪 Testing and Emulation
|
|
|
|
### **Emulation Options**
|
|
```bash
|
|
./scripts/emulate-simple.sh # Simple QEMU demo
|
|
./scripts/emulate-bbeos.sh # Full BBeOS emulation
|
|
./scripts/emulate-terminal.sh # Terminal-based simulation
|
|
```
|
|
|
|
### **Hardware Testing**
|
|
```bash
|
|
./scripts/hardware-test.sh # Hardware component testing
|
|
```
|
|
|
|
## 📚 Documentation Access
|
|
|
|
### **Main Guides**
|
|
- **Development Guide**: `docs/DEVELOPMENT_GUIDE.md`
|
|
- **Project Structure**: `PROJECT_STRUCTURE.md` (this file)
|
|
- **Quick Start**: `QUICK_START.md`
|
|
|
|
### **Phase Documentation**
|
|
- **Phase 1**: `docs/phases/PHASE_1_*.md` - Research & Feasibility
|
|
- **Phase 2**: `docs/phases/PHASE_2_*.md` - Bootstrapping
|
|
- **Phase 3**: `docs/phases/PHASE_3_*.md` - Hardware Support
|
|
- **Phase 4**: `docs/phases/PHASE_4_*.md` - User Interface
|
|
- **Phase 5**: `docs/phases/PHASE_5_*.md` - Telephony Stack
|
|
- **Phase 6**: `docs/phases/PHASE_6_*.md` - Packaging & Updates
|
|
- **Phase 7**: `docs/phases/PHASE_7_*.md` - Community & SDK
|
|
|
|
### **How-to Guides**
|
|
- **Emulation**: `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`
|
|
|
|
## 🔧 Configuration
|
|
|
|
### **Build Configuration**
|
|
- **Kernel config**: `src/kernel/msm8960-defconfig`
|
|
- **Device tree**: `vendor/kernel-source/arch/arm/boot/dts/qcom/`
|
|
- **Build artifacts**: `build/` directory structure
|
|
|
|
### **Environment Variables**
|
|
- `CROSS_COMPILE`: ARM cross-compilation toolchain
|
|
- `KERNEL_DIR`: Kernel source directory (`vendor/kernel-source`)
|
|
- `BUILD_DIR`: Build output directory (`build/`)
|
|
|
|
## 🎯 Benefits of This Structure
|
|
|
|
### **1. Maintainability**
|
|
- **Clear separation** between source, build, and documentation
|
|
- **Consistent naming** conventions throughout
|
|
- **Modular organization** for easy navigation
|
|
|
|
### **2. Scalability**
|
|
- **Extensible structure** for new components
|
|
- **Standard directories** for common project needs
|
|
- **Build system** that scales with project growth
|
|
|
|
### **3. Developer Experience**
|
|
- **Intuitive navigation** through logical organization
|
|
- **Comprehensive documentation** at every level
|
|
- **Clear build workflows** with dedicated scripts
|
|
|
|
### **4. Open Source Best Practices**
|
|
- **Standard directory layout** following open source conventions
|
|
- **Proper separation** of concerns
|
|
- **Comprehensive documentation** structure
|
|
|
|
---
|
|
|
|
*This structure is designed to support the development of a complete operating system while maintaining clarity and organization for developers and contributors.* |