# Atlas Framework

> The shared base of every Atlas app, with the Atlas.Ui QML controls, the icon fonts, the Rust crates for startup, settings, logging and system work, and the app template.

Atlas Framework is what every Atlas app is built on, so they all look and behave the same. AtlasOS installs it once and every app uses that copy. It runs on Qt 6.11 and KDE Frameworks 6 on Fedora 44.

## Which library to use

| You want to | Use |
|---|---|
| Build the app's interface: windows, pages, buttons, fields, lists, tables, dialogs, charts | [Atlas.Ui](https://atlasos.eterneon.net/framework/atlas-ui.md), the QML module (`import Atlas.Ui`) |
| Show an icon | [Symbols](https://atlasos.eterneon.net/framework/symbols.md): `Symbol { icon: Symbols.Home }` draws Material Symbols |
| Name the app, read its settings file, log to the journal | [atlas-framework-core](https://atlasos.eterneon.net/framework/atlas-framework-core.md) |
| Start a GUI app: app ID, one instance per session, crash hooks, the Atlas.Ui version check | [atlas-framework-ui](https://atlasos.eterneon.net/framework/atlas-framework-ui.md) |
| System work: crash reports, update history, bootc state, polkit checks, desktop notifications | [atlas-framework-system](https://atlasos.eterneon.net/framework/atlas-framework-system.md) |
| Flatpak updates | [atlas-framework-flatpak](https://atlasos.eterneon.net/framework/atlas-framework-flatpak.md) |
| Start a new app | [The app template](https://atlasos.eterneon.net/framework/template.md) |

A small app needs only Atlas.Ui and atlas-framework-ui, which brings in atlas-framework-core. Add the other crates only when the app does that kind of work.

## Getting started

1. Copy the [app template](https://atlasos.eterneon.net/framework/template.md) and rename it. It builds on its own: a Rust backend through CXX-Qt, a QML interface on Atlas.Ui, and one line of C++ that starts the app.
2. Build on Fedora 44 with the `atlas-ui` package installed. Atlas.Ui is a QML module next to Qt's own, so the app writes `import Atlas.Ui` and links nothing.
3. Build pages from [AtlasWindow](https://atlasos.eterneon.net/framework/atlas-ui/atlas-window.md), [AtlasPage](https://atlasos.eterneon.net/framework/atlas-ui/atlas-page.md) and the controls. Colours, spacing, fonts and motion come from [AtlasStyle](https://atlasos.eterneon.net/framework/atlas-ui/atlas-style.md), never hard-coded.
4. Run the framework's checks on the app (`tools/lint-app.sh` and `tools/check-app-names.sh` from the framework repository) in its CI.

```qml
import QtQuick
import Atlas.Ui

AtlasWindow {
    title: qsTr("Hello")
    width: 640
    height: 480
    visible: true

    AtlasPage {
        anchors.fill: parent
        title: qsTr("Hello")

        PrimaryButton {
            text: qsTr("Say hello")
            symbol: Symbols.WavingHand
            onClicked: console.log("hello")
        }
    }
}
```

## Versions

Atlas.Ui only ever adds API: a type, property, signal, function, enum value or symbol name is never renamed or removed in a later version. Each page says which version added it (`since`). An app declares the oldest Atlas.Ui it works with (`ui:` in `app!`), and at startup it refuses to run on an older one, with a plain message instead of a broken window.


## Libraries

- [Atlas.Ui](https://atlasos.eterneon.net/framework/atlas-ui.md): The QML module every Atlas app imports, with windows, pages, buttons, fields, lists, dialogs, charts and the style and services behind them; how to install it, check it and find a type.
- [Symbols](https://atlasos.eterneon.net/framework/symbols.md): Google's Material Symbols as fonts, drawn with the Symbol type and named by Symbols.Name: styles, filled and outline, size, colour and how to find a name.
- [atlas-framework-core](https://atlasos.eterneon.net/framework/atlas-framework-core.md): The small Rust crate every Atlas app uses, with app identity, the settings file, journal logging, os-release and a safe append helper, and no Qt or async runtime.
- [atlas-framework-ui](https://atlasos.eterneon.net/framework/atlas-framework-ui.md): The Rust crate that starts every Atlas GUI app, with the app! macro, the C functions main.cpp calls, one instance per session, journal logging, crash hooks and the Atlas.Ui version check.
- [atlas-framework-system](https://atlasos.eterneon.net/framework/atlas-framework-system.md): The Rust crate for Atlas system apps, with opt-in crash reports, AtlasOS state \(bootc status, boot history, update events\), polkit checks for root helpers and desktop notifications.
- [atlas-framework-flatpak](https://atlasos.eterneon.net/framework/atlas-framework-flatpak.md): The Rust crate for Flatpak updates through libflatpak, used by Atlas Updater and the future Atlas Store, with update listing, update runs and a check for newly requested permissions.
- [App template](https://atlasos.eterneon.net/framework/template.md): A minimal Atlas app to copy: a Kirigami window on Atlas.Ui, one Rust QObject exposed through CXX-Qt, built with CMake and Corrosion on the framework's crates.