{% extends "base.html" %}

{% block title %}Wiki{% endblock %}

{% block content %}
<div class="page-header">
    <h1>Buckos Wiki</h1>
</div>

<div class="wiki-layout">
    <aside class="wiki-sidebar">
        <h3>Documentation</h3>
        <ul>
            <li><a href="#overview">Overview</a></li>
            <li><a href="#architecture">Architecture</a></li>
            <li><a href="#package-manager">Package Manager</a></li>
            <li><a href="#init-system">Init System</a></li>
            <li><a href="#configuration">Configuration</a></li>
            <li><a href="#packages">Package Format</a></li>
            <li><a href="#use-flags">USE Flags</a></li>
            <li><a href="#contributing">Contributing</a></li>
        </ul>
    </aside>

    <div class="wiki-content">
        <section id="overview">
            <h2>Overview</h2>
            <p>Buckos (Greek for "iron") is a modern Linux distribution written entirely in Rust. It draws inspiration from Gentoo Linux, particularly its powerful Portage package management system, while providing a clean, modern implementation.</p>

            <h3>Design Goals</h3>
            <ul>
                <li><strong>Memory Safety:</strong> Leverage Rust's guarantees to eliminate entire classes of bugs</li>
                <li><strong>Performance:</strong> Compile-time optimizations and efficient runtime behavior</li>
                <li><strong>Simplicity:</strong> Clean, understandable codebase without legacy cruft</li>
                <li><strong>Flexibility:</strong> Source-based with fine-grained configuration options</li>
            </ul>
        </section>

        <section id="architecture">
            <h2>System Architecture</h2>
            <p>Buckos is organized as a Rust workspace with several specialized crates:</p>

            <table>
                <thead>
                    <tr>
                        <th>Crate</th>
                        <th>Purpose</th>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td><code>buckos-package</code></td>
                        <td>Package management, dependency resolution, and installation</td>
                    </tr>
                    <tr>
                        <td><code>buckos-boss</code></td>
                        <td>Init system (PID 1) and service management</td>
                    </tr>
                    <tr>
                        <td><code>buckos-config</code></td>
                        <td>System configuration parsing and management</td>
                    </tr>
                    <tr>
                        <td><code>buckos-model</code></td>
                        <td>Data structures for packages, dependencies, and metadata</td>
                    </tr>
                    <tr>
                        <td><code>buckos-assist</code></td>
                        <td>Help system and user documentation</td>
                    </tr>
                    <tr>
                        <td><code>buckos-tools</code></td>
                        <td>Utility functions and common tools</td>
                    </tr>
                    <tr>
                        <td><code>buckos-web</code></td>
                        <td>Website and documentation server</td>
                    </tr>
                </tbody>
            </table>
        </section>

        <section id="package-manager">
            <h2>Package Manager</h2>
            <p>The Buckos package manager is inspired by Gentoo's Portage and provides similar functionality:</p>

            <h3>Key Features</h3>
            <ul>
                <li><strong>Dependency Resolution:</strong> Advanced SAT-based dependency solving</li>
                <li><strong>USE Flags:</strong> Fine-grained control over package features</li>
                <li><strong>Slots:</strong> Multiple versions of packages installed simultaneously</li>
                <li><strong>Overlays:</strong> Custom package repositories</li>
                <li><strong>World Set:</strong> Track explicitly installed packages</li>
            </ul>

            <h3>Commands</h3>
            <pre><code># Emerge (install/update) packages
buckos-package emerge category/package

# Search packages
buckos-package search keyword

# Show package info
buckos-package info category/package

# Update world
buckos-package emerge --update --deep @world

# Unmerge (remove) packages
buckos-package unmerge category/package

# Dependency tree
buckos-package deptree category/package</code></pre>
        </section>

        <section id="init-system">
            <h2>Init System (boss)</h2>
            <p>The <code>boss</code> daemon serves as Buckos's init system, running as PID 1 and managing system services.</p>

            <h3>Features</h3>
            <ul>
                <li>Fast parallel service startup</li>
                <li>Dependency-based service ordering</li>
                <li>Simple service definition format</li>
                <li>Socket activation support</li>
                <li>Process supervision and restart</li>
            </ul>

            <h3>Service Files</h3>
            <p>Services are defined in <code>/etc/buckos/services/</code>:</p>
            <pre><code># /etc/buckos/services/nginx.toml
[service]
name = "nginx"
description = "NGINX HTTP Server"
command = "/usr/sbin/nginx"
type = "forking"

[dependencies]
after = ["network"]
wants = ["network"]</code></pre>
        </section>

        <section id="configuration">
            <h2>Configuration System</h2>
            <p>Buckos uses a layered configuration system:</p>

            <h3>Configuration Hierarchy</h3>
            <ol>
                <li><code>/etc/buckos/make.conf</code> - Main system configuration</li>
                <li><code>/etc/buckos/package.*/</code> - Per-package overrides</li>
                <li>Environment variables - Runtime overrides</li>
            </ol>

            <h3>make.conf Options</h3>
            <pre><code># Compiler flags
CFLAGS="-O2 -pipe -march=native"
CXXFLAGS="${CFLAGS}"

# Number of parallel jobs
MAKEOPTS="-j8"

# Global USE flags
USE="X wayland pulseaudio -systemd"

# Video cards
VIDEO_CARDS="amdgpu radeonsi"

# Input devices
INPUT_DEVICES="libinput"

# Language support
LINGUAS="en en_US"</code></pre>
        </section>

        <section id="packages">
            <h2>Package Format</h2>
            <p>Buckos packages follow a format similar to Gentoo ebuilds, but written in a TOML-based format:</p>

            <h3>Package Structure</h3>
            <pre><code># category/package/package-1.0.0.toml
[package]
name = "example"
version = "1.0.0"
slot = "0"
description = "An example package"
homepage = "https://example.com"
license = "MIT"

[source]
uri = "https://example.com/example-1.0.0.tar.gz"
checksum = "sha256:..."

[dependencies]
build = ["dev-util/cmake"]
runtime = ["sys-libs/glibc"]
optional = { feature = ["x11-libs/gtk"] }

[use_flags]
default = ["unicode"]
available = ["debug", "unicode", "feature"]</code></pre>
        </section>

        <section id="use-flags">
            <h2>USE Flags</h2>
            <p>USE flags control which features are enabled when building packages:</p>

            <h3>Common USE Flags</h3>
            <table>
                <thead>
                    <tr>
                        <th>Flag</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td><code>X</code></td>
                        <td>Enable X11 support</td>
                    </tr>
                    <tr>
                        <td><code>wayland</code></td>
                        <td>Enable Wayland support</td>
                    </tr>
                    <tr>
                        <td><code>gtk</code></td>
                        <td>Enable GTK+ toolkit support</td>
                    </tr>
                    <tr>
                        <td><code>qt5</code></td>
                        <td>Enable Qt5 toolkit support</td>
                    </tr>
                    <tr>
                        <td><code>systemd</code></td>
                        <td>Enable systemd support (off by default)</td>
                    </tr>
                    <tr>
                        <td><code>debug</code></td>
                        <td>Build with debug symbols</td>
                    </tr>
                    <tr>
                        <td><code>doc</code></td>
                        <td>Build and install documentation</td>
                    </tr>
                </tbody>
            </table>

            <h3>Setting USE Flags</h3>
            <pre><code># Global (in make.conf)
USE="X wayland gtk -systemd"

# Per-package (in /etc/buckos/package.use/custom)
www-client/firefox wayland geckodriver
media-video/mpv lua wayland</code></pre>
        </section>

        <section id="contributing">
            <h2>Contributing</h2>
            <p>We welcome contributions to Buckos! Here's how to get started:</p>

            <h3>Development Setup</h3>
            <pre><code># Clone the repository
git clone https://github.com/hodgesds/buckos.git
cd buckos

# Build in development mode
cargo build

# Run tests
cargo test

# Run clippy for linting
cargo clippy</code></pre>

            <h3>Contribution Guidelines</h3>
            <ul>
                <li>Follow Rust coding conventions</li>
                <li>Write tests for new functionality</li>
                <li>Update documentation as needed</li>
                <li>Keep commits focused and well-described</li>
                <li>Open issues for discussion before major changes</li>
            </ul>

            <h3>Areas for Contribution</h3>
            <ul>
                <li>Package definitions</li>
                <li>Documentation improvements</li>
                <li>Bug fixes and testing</li>
                <li>Performance optimizations</li>
                <li>New features and enhancements</li>
            </ul>

            <p>See our <a href="https://github.com/hodgesds/buckos">GitHub repository</a> for more information.</p>
        </section>
    </div>
</div>
{% endblock %}