Getting Started

Getting Started with LightOS

This guide will help you get LightOS running on your development machine and create your first application.

Prerequisites

C++20 compiler: GCC 10+, Clang 12+, or MSVC 2019+
CMake: Version 3.20 or later
Git: For cloning the repository
Optional: ARM GCC toolchain for target builds
Optional: RISC-V GCC toolchain for RISC-V targets

Installation

1. Clone the Repository

git clone https://github.com/jiangintel-ux/lightOS.git
cd lightOS

2. Build for Host Testing

# Configure
cmake -B build -DCMAKE_BUILD_TYPE=Debug

# Build
cmake --build build -j

# Run tests
./build/lightos_unit_tests

You should see all 1122 tests pass.

3. Build for ARM Target

# Configure for ARM Cortex-R52
cmake -B build-arm \
    -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi-gcc.cmake \
    -DLIGHTOS_TARGET_ARCH=cortex-r52

# Build
cmake --build build-arm -j

4. Build for RISC-V Target

# Configure for RISC-V RV64
cmake -B build-rv64 \
    -DCMAKE_TOOLCHAIN_FILE=cmake/riscv64-unknown-elf-gcc.cmake \
    -DLIGHTOS_TARGET_ARCH=rv64gc

# Build
cmake --build build-rv64 -j

Your First Application

Create a simple multi-threaded application:

// main.cpp
#include <lightos/kernel.hpp>
#include <lightos/thread.hpp>
#include <lightos/mutex.hpp>

using namespace lightos;

// Shared resource
mutex print_lock;
int counter = 0;

// Worker thread function
void worker(void* arg) {
    int id = reinterpret_cast<intptr_t>(arg);

    for (int i = 0; i < 5; i++) {
        {
            scoped_lock lock(print_lock);
            counter++;
            // In production: use proper logging
        }
        thread::sleep(milliseconds(100));
    }
}

int main() {
    // Initialize kernel
    kernel::init();

    // Create worker threads
    thread worker1("Worker1", priority::normal, worker, (void*)1);
    thread worker2("Worker2", priority::normal, worker, (void*)2);

    // Start threads
    worker1.start();
    worker2.start();

    // Wait for completion
    worker1.join();
    worker2.join();

    // counter should be 10
    return 0;
}

Build and run:

cmake --build build --target my_app
./build/my_app

Project Structure

lightOS/
├── include/
│   └── lightos/           # Public headers
│       ├── kernel.hpp     # Kernel initialization
│       ├── thread.hpp     # Thread management
│       ├── mutex.hpp      # Mutex primitives
│       ├── semaphore.hpp  # Semaphore primitives
│       ├── queue.hpp      # Message queues
│       └── timer.hpp      # Timer services
├── src/
│   ├── kernel/            # Kernel implementation
│   └── arch/              # Architecture-specific code
├── tests/
│   └── unit/              # Unit tests
├── examples/              # Example applications
└── cmake/                 # CMake toolchain files

Configuration Options

LightOS can be configured via CMake options:

Option	Default	Description
`LIGHTOS_TARGET_ARCH`	`host`	Target architecture
`LIGHTOS_MAX_THREADS`	`32`	Maximum thread count
`LIGHTOS_MAX_PRIORITY`	`32`	Priority levels
`LIGHTOS_TICK_RATE_HZ`	`1000`	System tick rate
`LIGHTOS_HEAP_SIZE`	`65536`	Heap size (bytes)
`LIGHTOS_AUTOSAR_ENABLED`	`OFF`	Enable AUTOSAR features

Example:

cmake -B build \
    -DLIGHTOS_MAX_THREADS=16 \
    -DLIGHTOS_TICK_RATE_HZ=10000

Next Steps

Threading Guide - Deep dive into thread management
Synchronization - Mutex, semaphore, queues
Memory Management - Static and dynamic allocation
Architecture Guides - Platform-specific details
Examples - More code examples

Need Help?

FAQ - Common questions
GitHub Issues - Bug reports
Contact Us - Sales and support