83 lines
2.7 KiB
Markdown
83 lines
2.7 KiB
Markdown
## ⚙️ Development Setup
|
|
|
|
`ember-tune` is a standard Cargo project. You will need a recent Rust toolchain and common build utilities.
|
|
|
|
**Prerequisites:**
|
|
- `rustup`
|
|
- `build-essential` (or equivalent for your distribution)
|
|
- `libudev-dev`
|
|
|
|
```bash
|
|
# 1. Clone the repository
|
|
git clone https://gitea.com/narl/ember-tune.git
|
|
cd ember-tune
|
|
|
|
# 2. Build the release binary
|
|
cargo build --release
|
|
|
|
# 3. Run the test suite (safe, uses a virtual environment)
|
|
# This requires no special permissions and does not touch your hardware.
|
|
cargo test
|
|
```
|
|
|
|
**Running:**
|
|
Due to its direct hardware access, `ember-tune` requires root privileges.
|
|
|
|
```bash
|
|
# Run a full benchmark and generate optimized configs
|
|
sudo ./target/release/ember-tune
|
|
|
|
# Run a mock benchmark for UI/logic testing
|
|
sudo ./target/release/ember-tune --mock
|
|
```
|
|
|
|
---
|
|
|
|
## 🤝 Contributing Quirk Data (`hardware_db.toml`)
|
|
|
|
**This is the most impactful way to contribute.** `ember-tune`'s strength comes from its `assets/hardware_db.toml`, which encodes community knowledge about how to manage specific laptops. If your hardware isn't working perfectly, you can likely fix it by adding a new entry here.
|
|
|
|
The database is composed of four key sections: `conflicts`, `ecosystems`, `quirks`, and `discovery`.
|
|
|
|
### A. Reporting a Service Conflict
|
|
If a background service on your system interferes with `ember-tune`, add it to `[[conflicts]]`.
|
|
|
|
**Example:** Adding `laptop-mode-tools`.
|
|
```toml
|
|
[[conflicts]]
|
|
id = "laptop_mode_conflict"
|
|
services = ["laptop-mode.service"]
|
|
contention = "Multiple - I/O schedulers, Power limits"
|
|
severity = "Medium"
|
|
fix_action = "SuspendService" # Orchestrator will stop/start this service
|
|
help_text = "laptop-mode-tools can override power-related sysfs settings."
|
|
```
|
|
|
|
### B. Adding a New Hardware Ecosystem
|
|
If your laptop manufacturer (e.g., Razer) has a unique fan control tool or ACPI platform profile path, define it in `[ecosystems]`.
|
|
|
|
**Example:** A hypothetical "Razer" ecosystem.
|
|
```toml
|
|
[ecosystems.razer]
|
|
vendor_regex = "Razer"
|
|
# Path to the sysfs node that controls performance profiles
|
|
profiles_path = "/sys/bus/platform/drivers/razer_acpi/power_mode"
|
|
# Map human-readable names to the values the driver expects
|
|
policy_map = { Balanced = 0, Boost = 1, Silent = 2 }
|
|
```
|
|
|
|
### C. Defining a Model-Specific Quirk
|
|
If a specific laptop model has a bug (like a stuck sensor or incorrect fan reporting), define a `[[quirks]]` entry.
|
|
|
|
**Example:** A laptop whose fans report 0 RPM even when spinning.
|
|
```toml
|
|
[[quirks]]
|
|
model_regex = "HP Envy 15-ep.*"
|
|
id = "hp_fan_stuck_sensor"
|
|
issue = "Fan sensor reports 0 RPM when active."
|
|
# The 'action' tells the SAL to use a different method for fan detection.
|
|
action = "UseThermalVelocityFallback"
|
|
```
|
|
|
|
After adding your changes, run the test suite and then submit a Pull Request!
|