2021-05-04 04:21:06 +03:00
[![MIT License ](https://img.shields.io/github/license/divnix/devos )][mit]
[![NixOS ](https://img.shields.io/badge/NixOS-unstable-blue.svg?style=flat&logo=NixOS&logoColor=white )](https://nixos.org)
2021-07-21 04:41:00 +03:00
[![Chat ](https://img.shields.io/badge/chat-join%20us-brightgreen.svg?style=flat&logo=matrix&logoColor=white )](https://matrix.to/#/#devos:nixos.org)
2021-05-04 04:21:06 +03:00
2023-08-08 21:10:48 +03:00
# DEPRECATION NOTICE
This project is no longer maintained and not recommended for any sort of use case. Please see https://github.com/divnix/digga/issues/503 for better alternatives and the reasons behind this decision.
-----
2021-08-04 19:18:23 +03:00
Digga — slangy German for "good friend" — is a flake utility library
2021-07-21 04:41:00 +03:00
that helps you declaratively craft and manage all three layers of your system
environment within a single [nix flakes][flakes] repository:
- development shells (via [`numtide/devshell`][devshell]),
- home environments (via [`nix-community/home-manager`][home-manager]), and
- host configurations (via [`NixOS/nixpkgs/nixos`][nixpkgs]).
This library is based on [flake-utils-plus][].
2021-05-04 04:21:06 +03:00
2022-02-26 23:05:53 +03:00
# Status: Beta
2022-11-08 17:06:32 +03:00
2022-02-26 23:05:53 +03:00
Although this project has already matured quite a bit, a fair amount of api polishing is still
expected. There are unstable versions (0._x_._x_) to help users keep track
of changes and progress.
2021-05-13 00:55:15 +03:00
# Usage
2022-11-08 17:06:32 +03:00
2021-07-21 04:41:00 +03:00
The best way to make use of library is with the [Official template][template].
2022-04-03 20:12:00 +03:00
Check out the [guide ](./doc/start/index.md ) to get up and running.
2022-02-26 23:05:53 +03:00
Also have a look at devos's [_flake.nix_ ](./examples/devos/flake.nix ).
2022-03-03 23:48:56 +03:00
If anything is not immediately discoverable via our [`mkFlake`][mk-flake], please file a bug report.
2022-02-26 23:05:53 +03:00
# Examples
2022-11-08 17:06:32 +03:00
2022-02-26 23:05:53 +03:00
Make sure to check out all the [examples ](./examples ) to see the different ways
to make use of the digga api.
## In the Wild
2022-11-08 17:06:32 +03:00
2022-02-26 23:05:53 +03:00
You can also see digga being actually used:
2021-07-21 04:41:00 +03:00
2022-11-08 17:06:32 +03:00
- @Pacman99: [Personal ](https://gitlab.com/coffeetables/lower ), [Server ](https://gitlab.com/coffeetables/myrdd )
- [@danielphan2003 ](https://github.com/danielphan2003/flk ) and make sure to also check out [devos-ext-lib ](https://github.com/divnix/devos-ext-lib )
- [PubSolarOS ](https://git.sr.ht/~b12f/pub-solar-os )
- @montchr: [Dotfield ](https://github.com/montchr/dotfield ) – including darwin configurations
- [@sweenu ](https://github.com/sweenu/nixfiles ): pc, server and RaspberryPi deployment in one repo
2021-07-21 04:41:00 +03:00
# Philosophy
2021-08-04 19:18:23 +03:00
In it's `lib.mkFlake` function, _Digga_ implements a well-specified API
2021-07-21 04:41:00 +03:00
interface comprising four API containers that allow you to:
1. configure **nixpkgs channels** including internal and external overlays,
2021-08-04 19:18:23 +03:00
2. define **NixOS hosts** including internal and external NixOS modules as well as
2021-07-21 04:41:00 +03:00
host defaults that apply to all hosts in the environment,
3. specify **user home environments** including internal and external home-manager
modules, and
4. setup & combine a series of **devshells** that you like to have available in
your projects.
## Modules, Profiles & Suites
2022-11-08 17:06:32 +03:00
2021-08-04 19:18:23 +03:00
For NixOS- & home-manager-modules, _Digga_ allows you to distinguish between
2021-07-21 04:41:00 +03:00
_modules_, _profiles_ and _suites_ .
- **Modules** are abstract configurations that, while holding the implementation, do not
2022-11-08 17:06:32 +03:00
set any system state.
2021-05-13 00:55:15 +03:00
2021-07-21 04:41:00 +03:00
- **Profiles** are concrete configurations that set system state within the profile domain.
- **Suites** are a composable, clean and discoverable mechanism for profile aggregation.
## Internal Art vs External Art
2022-11-08 17:06:32 +03:00
2021-09-18 16:44:59 +03:00
Overlays and modules can be defined internally coming from your repo or externally
2021-07-21 04:41:00 +03:00
coming from an upstream flake. This distinction serves the library to only export
your own work as the public flake output.
Downstream consumers of your flake can now more easily tell your art apart from
other upstream art.
2021-05-04 04:21:06 +03:00
2021-06-03 18:36:30 +03:00
# Contributing
2022-11-08 17:06:32 +03:00
2021-06-03 18:36:30 +03:00
We encourage contributions of any kind. The simplest way to get involved is to
2021-07-21 04:41:00 +03:00
join the [chat][] or report problems and ideas on the [issue thread][issues].
2021-06-03 18:36:30 +03:00
2021-07-21 04:41:00 +03:00
To craft well thought out APIs we need all the thoughts regarding new ideas.
Pull Requests are just as amazing.
2021-06-03 18:36:30 +03:00
2022-02-26 23:05:53 +03:00
# Why _flakes_?
2022-11-08 17:06:32 +03:00
Flakes are a part of an explicit push to improve [Nix's UX ](https://github.com/NixOS/nix/blob/master/doc/manual/src/contributing/cli-guideline.md ), and have become an integral part of that effort.
2022-02-26 23:05:53 +03:00
They also make [Nix expressions ](https://nixos.org/manual/nix/unstable/expressions/expression-syntax.html ) easier to distribute and reuse with convient [flake references ](https://github.com/NixOS/nix/blob/master/src/nix/flake.md#flake-references ) for building or using packages, modules, and whole systems.
# Shoulders
2022-11-08 17:06:32 +03:00
2022-02-26 23:05:53 +03:00
This work does not reinvent the wheel. It stands on the [shoulders of the
following giants][giants]:
## :onion: — like the layers of an onion
2022-11-08 17:06:32 +03:00
2022-02-28 08:53:36 +03:00
- [`gytis-ivaskevicius/flake-utils-plus` ](https://github.com/gytis-ivaskevicius/flake-utils-plus )
- [`numtide/flake-utils` ](https://github.com/numtide/flake-utils/ )
2021-07-21 04:41:00 +03:00
2022-02-26 23:05:53 +03:00
## :family: — like family
2022-11-08 17:06:32 +03:00
2022-02-28 08:53:36 +03:00
- [`numtide/devshell` ](https://github.com/numtide/devshell )
- [`serokell/deploy-rs` ](https://github.com/serokell/deploy-rs )
- [`berberman/nvfetcher` ](https://github.com/berberman/nvfetcher )
- [`NixOS/nixpkgs` ](https://github.com/NixOS/nixpkgs )
2022-02-26 23:05:53 +03:00
:heart:
### Inspiration & Art
2022-11-08 17:06:32 +03:00
2022-02-28 08:53:36 +03:00
- [hlissner/dotfiles ](https://github.com/hlissner/dotfiles )
2022-02-26 23:05:53 +03:00
- [nix-user-chroot ](https://github.com/nix-community/nix-user-chroot )
- [Nickel ](https://github.com/tweag/nickel )
- [Awesome Nix ](https://github.com/nix-community/awesome-nix )
- [devshell ](https://github.com/numtide/devshell )
# Divnix
2022-11-08 17:06:32 +03:00
2022-02-26 23:05:53 +03:00
The divnix org is an open space that spontaneously formed out of "the Nix".
It is really just a place where otherwise unrelated people work
together and get stuff done.
It's a place to stop "geeking out in isolation" (or within company boundaries).
A place to experiment, learn together, and iterate quickly on best practices.
That's what it is.
It might eventually become a non-profit if that's not too complicated or, if those
goals are sufficiently upstreamed into "the Nix", dissolved.
# License
2022-11-08 17:06:32 +03:00
2021-05-15 20:47:49 +03:00
Digga is licensed under the [MIT License][mit].
2022-03-03 23:48:56 +03:00
[mk-flake]: ./src/mkFlake
2021-11-26 15:09:55 +03:00
[chat]: https://matrix.to/#/#devos:matrix.org
2021-07-21 04:41:00 +03:00
[devshell]: https://github.com/numtide/devshell
[examples]: https://github.com/divnix/digga/tree/main/examples
2024-05-17 13:19:41 +03:00
[flakes]: https://wiki.nixos.org/wiki/Flakes
2021-07-21 04:41:00 +03:00
[flake-utils-plus]: https://github.com/gytis-ivaskevicius/flake-utils-plus
2022-05-16 17:09:10 +03:00
[giants]: https://en.wikipedia.org/wiki/Standing_on_the_shoulders_of_giants
2021-07-21 04:41:00 +03:00
[home-manager]: https://github.com/nix-community/home-manager
[issues]: https://github.com/divnix/digga/issues
[mit]: https://mit-license.org
[nix]: https://nixos.org/manual/nix/stable
[nixpkgs]: https://github.com/nixos/nixpkgs
2022-02-26 23:05:53 +03:00
[template]: ./examples/devos