178 lines
4.5 KiB
Markdown
178 lines
4.5 KiB
Markdown
# FeDIY
|
|
|
|
FeDIY provides a reproducible Rust development environment using Nix flakes and the fenix toolchain.
|
|
Nix is optional for contributors: if you use it, `nix develop` gives you the exact tools this repository expects without needing to install them globally. If you do not use Nix, you can still work with the standard Rust toolchain.
|
|
|
|
## Quick Start
|
|
|
|
```sh
|
|
nix develop
|
|
# or with direnv:
|
|
direnv allow
|
|
```
|
|
|
|
### Automatic Environment Setup
|
|
|
|
When you enter the devShell (via `direnv allow` or `nix develop`), the following happens automatically:
|
|
|
|
✓ **Git Repository**: Initializes `.git` if not present
|
|
✓ **Welcome Banner**: Displays available tools and quick commands
|
|
|
|
No manual setup needed! Just start coding.
|
|
|
|
## First Steps
|
|
|
|
```sh
|
|
nix develop
|
|
cargo build
|
|
cargo test
|
|
```
|
|
|
|
If you want a quick overview of what the shell provides, run:
|
|
|
|
```sh
|
|
nix run .#dev-helper
|
|
```
|
|
|
|
## Flatpak Packaging
|
|
|
|
This project supports building Flatpak packages for the FeDIY application.
|
|
|
|
### Build Flatpak Package
|
|
|
|
1. Run:
|
|
|
|
```bash
|
|
make flatpak-build
|
|
```
|
|
|
|
This will use the manifest at `flatpak/app.flatpak.json` to build a Flatpak bundle in the `build-flatpak/` directory.
|
|
|
|
### Customize Manifest
|
|
|
|
Edit `flatpak/app.flatpak.json` to update app ID, runtime, build commands, or sources as needed for your project.
|
|
|
|
### Install/Run Flatpak Locally
|
|
|
|
You can install and run the built Flatpak locally:
|
|
|
|
```bash
|
|
flatpak install --user build-flatpak/com.moturpin.fediy.flatpak
|
|
flatpak run com.moturpin.fediy
|
|
```
|
|
|
|
## Included Tools
|
|
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| **cargo** | Rust package manager and build system |
|
|
| **rustc** | Rust compiler |
|
|
| **clippy** | Rust linter for catching common mistakes |
|
|
| **rustfmt** | Rust code formatter |
|
|
| **rust-analyzer** | Language server for IDE integration |
|
|
| **rust-src** | Rust source code (for tools like rust-analyzer) |
|
|
| **cargo-deny** | Audit dependencies for advisories and license policy |
|
|
| **cargo-edit** | Add/remove/upgrade Cargo dependencies from the CLI |
|
|
| **cargo-watch** | Auto-rebuild on file changes |
|
|
| **flatpak-builder** | Build Flatpak distribution packages |
|
|
| **psql / postgresql** | Local PostgreSQL development and inspection |
|
|
| **gettext** | Localization and translation workflow support |
|
|
| **chromium / playwright** | Browser-based UI and accessibility checks |
|
|
| **podman / podman-compose / buildah** | Linux-only OCI/container tooling |
|
|
| **pre-commit** | Run pre-commit hooks |
|
|
|
|
## Testing & Development Features
|
|
|
|
Build and testing tools:
|
|
|
|
- **cargo test** - Run unit and integration tests
|
|
- **cargo clippy** - Lint code for common issues
|
|
- **cargo fmt** - Format code consistently with rustfmt
|
|
|
|
**Example usage:**
|
|
|
|
```bash
|
|
# Run tests
|
|
cargo test
|
|
|
|
# Check code with clippy
|
|
cargo clippy
|
|
|
|
# Format code
|
|
cargo fmt
|
|
|
|
# Watch and rebuild on changes
|
|
cargo watch -x build
|
|
|
|
# Build a Flatpak
|
|
make flatpak-build
|
|
```
|
|
|
|
## Project Layout
|
|
|
|
```
|
|
Cargo.toml
|
|
Cargo.lock
|
|
docs/
|
|
adrs/ # Architecture decision records
|
|
contracts/ # API and behavior contracts (planning artifacts)
|
|
extensions/ # Extension model planning and examples
|
|
OPEN_QUESTIONS.md
|
|
ROADMAP.md
|
|
ARCHITECTURE.md
|
|
schemas/
|
|
project-core/ # Core project schema artifacts
|
|
extensions/ # Domain-specific extension schema artifacts
|
|
src/
|
|
└── main.rs (or lib.rs)
|
|
tests/
|
|
Makefile
|
|
.envrc
|
|
flake.nix
|
|
```
|
|
|
|
## Legacy Usage
|
|
|
|
If you do not use flakes, run:
|
|
|
|
```sh
|
|
nix-shell
|
|
```
|
|
|
|
## Project Metadata
|
|
|
|
See project.toml for example metadata.
|
|
|
|
## Planning Documentation
|
|
|
|
- [Planning docs index](docs/README.md)
|
|
- [Roadmap](docs/ROADMAP.md)
|
|
- [Architecture baseline](docs/ARCHITECTURE.md)
|
|
- [Development workflow (TDD/BDD + GitHub Flow)](docs/WORKFLOW.md)
|
|
- [Open questions and clarification plan](docs/OPEN_QUESTIONS.md)
|
|
|
|
## Helper Tools
|
|
|
|
- **`nix run .#dev-helper`** - Display tool versions and availability, grouped by task
|
|
- **`cargo build`** - Build the project
|
|
- **`cargo check`** - Quick syntax check without building
|
|
- **`cargo doc --open`** - Generate and view documentation
|
|
|
|
## Packaging for nixpkgs
|
|
|
|
This project is structured for packaging in nixpkgs:
|
|
|
|
- All sources in `src/`
|
|
- `flake.nix` provides a devShell and package outputs
|
|
- Add a `default.nix` or package expression as needed for nixpkgs
|
|
|
|
See [nixpkgs Rust packaging docs](https://nixos.org/manual/nixpkgs/stable/#rust) for more details.
|
|
|
|
## Customization
|
|
|
|
Edit `flake.nix` to:
|
|
|
|
- Add additional Rust targets via `rustup target add [target]`
|
|
- Include additional cargo plugins
|
|
- Add board-specific tools (e.g., stm32cube, nrfjprog)
|