DOCSEARCHbyAlgolia
Submit Docs

Redox OS Build System

repository·master·Indexed 12 days ago

https://github.com/redox-os/redox

A microkernel-based, open-source operating system written in Rust. This documentation covers the central build system, including instructions for building via Podman, running in virtual machines or on real hardware, and using target-specific wrappers like pkg-config and llvm-config for aarch64, i586, i686, riscv64, and x86_64.

Tokens
9.4K
Snippets
27
Records
49
Agent score
97%

What's inside Redox OS

  1. Explore the Redox OS Ecosystem

    master

    Redox is a microkernel-based operating system written in Rust. The ecosystem is composed of several key repositories that provide the kernel, essential system components, drivers, and user-space utilities. Key components include:

    • Kernel: The core microkernel.
    • Base: Essential system components and drivers.
    • RedoxFS: The default filesystem.
    • relibc: A C POSIX library written in Rust.
    • Ion: The default shell.
    • Orbital: The display server and window manager.
    • pkgutils: The current package manager.

  2. Understand Redox OS hardware limitations

    master

    The following hardware limitations currently apply to all systems running Redox OS:

    • ACPI: Support is incomplete; some functionality is hardcoded in the kernel.
    • Connectivity: Wi-Fi and Bluetooth are not yet supported.
    • Graphics: Only Intel GPUs are supported. Other vendors must rely on BIOS VESA or UEFI GOP.
    • Peripherals: I2C devices are not supported (use PS/2 or USB instead).
    • USB: Support varies by model; use input devices with standardized controls for best compatibility.
    • Booting: Automatic OS discovery is not yet implemented in the bootloader.

  3. Run Redox in a Virtual Machine or on Real Hardware

    master

    Redox OS can be deployed in different environments. Use the following resources to learn how to set up your environment:

    • Virtual Machine: Instructions for running Redox in a VM can be found here.
    • Real Hardware: Instructions for running Redox on physical hardware can be found here.

  4. Request permission to use the Redox OS trademark

    master

    For any trademark use cases not covered by the standard policy, or to request permission for marketing, merchandising, or official software status, contact the Redox OS nonprofit via email.

    trademark@redox-os.org

  5. Guidelines for using the Redox OS trademark and logo

    master

    The Redox OS trademark includes the name "Redox OS", the Redox OS logo, and associated symbols. Use is governed by the following rules:

    Permissible Use

    • Community Projects: May use the trademark to refer to the operating system, provided it is not misleading and does not imply endorsement by the Redox OS nonprofit.
    • Educational/Informational Use: May use the trademark in books, websites, and articles to refer to the OS.
    • Marketing/Promotional Use: Partners and affiliates require prior written consent from the Redox OS nonprofit.

    Prohibited Use

    • Misrepresentation: Do not imply false association, endorsement, or sponsorship from the Redox OS nonprofit.
    • Modification: Do not alter or modify the trademark or logo, or incorporate it into another logo without written permission.
    • Merchandising: Commercial use on merchandise (e.g., T-shirts, mugs) requires explicit authorization.

    Logo Usage

    • Use the logo exactly as provided; do not change colors, proportions, or design.
    • Maintain sufficient clear space around the logo to ensure legibility.
    • Identify the Redox OS name using the ™ symbol.

  6. Use the hardware compatibility report template

    master

    When contributing a new hardware report to the compatibility table, use the following Markdown template. Ensure the Redox Image Date follows the ISO 8601 format.

    New reports should be ordered alphabetically by Vendor, and then independently alphabetically by Model within each vendor group.

    |  |  |  |  |  |  |  |  |

  7. Report hardware compatibility for Redox OS

    master

    To help improve driver support and fix boot bugs, users are encouraged to report their hardware status.

    Reporting Customized Hardware

    • Desktops: Use Custom for the Vendor and include the motherboard and CPU vendor/model in the Model field.
    • Laptops: Only report if you have replaced the original CPU; include the new CPU vendor and model in the Model field.
    • Pro-tip: Add your pciutils log as a comment to the tracking issue to assist with device porting.

    Hardware Status Definitions

    • Recommended: The OS boots successfully with video, sound, PS/2 or USB input, Ethernet, terminal, and Orbital working.
    • Booting: The OS boots successfully but has issues or lacks certain hardware support (document these in the Report section).
    • Broken: The bootloader or system boot fails to work.

  10. Manage background package jobs with ExecutionManager

    master

    The ExecutionManager is responsible for spawning and tracking background tasks (jobs) that execute repo commands against specific package targets. It manages a collection of PackageJob instances and handles asynchronous status updates such as log streaming and job completion.

    Key Workflow

    1. Spawn a Job: Use spawn_job to initiate a command. This sets up a PTY (Pseudo-Terminal) to capture output, spawns log reader threads, and executes the command via the repo binary.
    2. Handle Updates: Listen for StatusUpdate messages via a channel. These updates are processed using handle_status_update to update job logs or set the final exit code.
    3. Job Lifecycle: Jobs are tracked in active_job_order. Successful jobs (exit code 0) can be automatically closed using close_job to clean up resources.
    // Conceptual usage of ExecutionManager
let mut manager = ExecutionManager::new();
let (status_tx, status_rx) = mpsc::channel();

// Spawn a job for a specific command and package targets
manager.spawn_job("build", vec![PackageName::from("my-pkg")], status_tx);

// In your event loop, handle updates
while let Ok(update) = status_rx.try_recv() {
    manager.handle_status_update(update);
}

  11. Run cookbook_redoxer with write-exec mode

    master

    When running the write-exec command, the tool can automatically configure directory paths if the COOKBOOK_STAGE environment variable is set.

    If COOKBOOK_STAGE is present, the tool injects the following arguments into the execution flow:

    • --root <COOKBOOK_STAGE>
    • --folder <COOKBOOK_STAGE>/root

    This allows the tool to operate within a specific staging directory for execution tasks.

    export COOKBOOK_STAGE=/path/to/stage
cookbook_redoxer write-exec

  12. How `repo` handles recipe rules (source vs binary)

    master

    The repo tool manages recipes using different "rules" that determine how a package is acquired and built:

    • source: The recipe is treated as a source-based build. The tool will fetch the source code and compile it.
    • binary: The recipe is treated as a pre-compiled binary. The tool will attempt to fetch a pre-built package.
    • local: Similar to source, but typically used for local development/testing.
    • ignore: The recipe is skipped during the operation.

    Rules can be overridden using the --set-rule=<rule> flag with the change-rule command, or by providing a --filesystem=<config_file> which uses an installer configuration to map package names to specific rules.