makiolaj
f5052f3fa9
The first public build. CHANGELOG's Unreleased section is rewritten as user-facing notes, since it becomes the beta's release notes. The README gains an install section, and the store short description fits Play's 80 characters.
96 lines
4.4 KiB
Markdown
96 lines
4.4 KiB
Markdown
<div align="center">
|
|
|
|
<h1>Clockula</h1>
|
|
|
|
<p><strong>A modern Material 3 Expressive clock app for Android.</strong><br>
|
|
Alarms, timers, stopwatch and world clock. Open standards, no account required.</p>
|
|
|
|
<a href="https://codeberg.org/jlmakiola/clockula/actions"><img src="https://codeberg.org/jlmakiola/clockula/actions/workflows/ci.yaml/badge.svg?branch=main" alt="CI"></a>
|
|
<img src="https://img.shields.io/badge/Android-10%2B-3DDC84?logo=android&logoColor=white" alt="Android 10+">
|
|
<img src="https://img.shields.io/badge/Kotlin-Compose-7F52FF?logo=kotlin&logoColor=white" alt="Kotlin + Compose">
|
|
<img src="https://img.shields.io/badge/Material%203-Expressive-4285F4" alt="Material 3 Expressive">
|
|
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="MIT License"></a>
|
|
|
|
<p>
|
|
<a href="https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://codeberg.org/jlmakiola/clockula"><img src="https://github.com/ImranR98/Obtainium/blob/main/assets/graphics/badge_obtainium.png?raw=true" alt="Get it on Obtainium" height="56"></a>
|
|
</p>
|
|
|
|
</div>
|
|
|
|
Clockula is the clock sibling to [Calendula](https://codeberg.org/jlmakiola/calendula)
|
|
(calendar) and [Agendula](https://codeberg.org/jlmakiola/agendula) (tasks). The
|
|
name follows theirs: *clock*, given Calendula's `-ula` ending. A Calendula flower
|
|
head is botanically a cluster of many small *florets*, so the three apps are
|
|
florets of one bloom. They also share one library, [floret-kit](https://codeberg.org/jlmakiola/floret-kit).
|
|
|
|
> 🧪 **Beta.** Clockula 1.0.0 is in beta: feature-complete, and being tested
|
|
> before the stable release. See [Install](#install) to try it.
|
|
|
|
## The honest difference from its siblings
|
|
|
|
Calendula is a pure front-end over Android's `CalendarContract`. Agendula speaks
|
|
the dmfs `TaskContract`. Both put a good interface on a standard someone else
|
|
already maintains.
|
|
|
|
There is no open provider behind a clock. Alarms, timers and laps are
|
|
Clockula's own data, so Clockula is the first app in the family to own its
|
|
storage, and does so by design. The first section of
|
|
[`docs/PLAN.md`](docs/PLAN.md) sets out what takes the place of a shared
|
|
standard, and it comes down to three things:
|
|
|
|
- Clockula speaks Android's standard alarm contract. It implements
|
|
`android.provider.AlarmClock` in full, so your assistant and your automation
|
|
apps can set alarms and timers in it exactly as they would in any stock clock,
|
|
and the system status bar and lock screen show its next alarm.
|
|
- World clocks are IANA time zones, not a bespoke city list that goes stale.
|
|
- Your data exports to a documented, versioned JSON file whenever you want
|
|
it, because data you can't take with you isn't really yours.
|
|
|
|
## Alarms that actually ring
|
|
|
|
An alarm app is only worth having if you can trust it, so Clockula treats reliability
|
|
as the main feature. Alarms are scheduled as real alarm clocks (doze-exempt and
|
|
visible to the system) and re-resolved against your current time
|
|
zone whenever anything moves underneath them, so DST and travel don't silently
|
|
shift them.
|
|
|
|
When something on your device *would* stop an alarm ringing, Clockula tells you
|
|
which setting it is and takes you there, instead of failing quietly at 7am.
|
|
|
|
## Install
|
|
|
|
Betas are published as pre-releases on
|
|
[Codeberg](https://codeberg.org/jlmakiola/clockula/releases), with the signed
|
|
APK and a `.sha256` checksum attached. Download the APK there, or add
|
|
`https://codeberg.org/jlmakiola/clockula` to
|
|
[Obtainium](https://github.com/ImranR98/Obtainium) and switch on *Include
|
|
prereleases* for it so it finds the beta. A beta updates in place to later betas
|
|
and to the stable release.
|
|
|
|
From the stable 1.0.0 on, every release also goes to the self-hosted F-Droid
|
|
repository that serves Calendula and Agendula.
|
|
|
|
## Documentation
|
|
|
|
Start with [`docs/`](docs/): [`PLAN.md`](docs/PLAN.md) is the spec and the
|
|
reasoning, [`ROADMAP.md`](docs/ROADMAP.md) is the status,
|
|
[`ARCHITECTURE.md`](docs/ARCHITECTURE.md) is how the code is put together, and
|
|
[`RELEASING.md`](docs/RELEASING.md) is the release runbook.
|
|
|
|
## Building
|
|
|
|
```sh
|
|
git clone --recurse-submodules https://codeberg.org/jlmakiola/clockula.git
|
|
cd clockula
|
|
./gradlew assembleDebug
|
|
```
|
|
|
|
floret-kit is a submodule built from source as a Gradle composite build, so
|
|
`--recurse-submodules` is not optional. The included build needs to find the
|
|
Android SDK on its own: either export `ANDROID_HOME`, or drop a `sdk.dir=…` line
|
|
in a (gitignored) `floret-kit/local.properties`.
|
|
|
|
## Licence
|
|
|
|
MIT. See [`LICENSE`](LICENSE).
|