README.md: elaborate on project structure
Provide details for contribution and bootstrapping.
This commit is contained in:
Timothy DeHerrera
parent
ed94fa013d
commit
a1a2a2c7e2
98
README.md
98
README.md
|
|
@ -1,35 +1,87 @@
|
||||||
# Introduction
|
# Introduction
|
||||||
|
|
||||||
This project is under construction as a rewrite of my [legacy][old]
|
This project is under construction as a rewrite of my [legacy][old]
|
||||||
NixOS configuration, using the [experimental][rfc] _flakes_ mechanism.
|
NixOS configuration, using the experimental [flakes][rfc] mechanism.
|
||||||
|
|
||||||
|
|
||||||
#### [Flake Talk][video]
|
#### [Flake Talk][video]
|
||||||
|
|
||||||
|
# Usage
|
||||||
|
Enter a nix-shell either manually or automatically using [direnv][direnv]. This
|
||||||
|
will set up the exerimental nix features that need to be available to use
|
||||||
|
[flakes][pr]. A basic `rebuild` command is included in the shell to replace
|
||||||
|
`nixos-rebuild` for now.
|
||||||
|
|
||||||
|
```
|
||||||
|
Usage: rebuild [host] {switch|boot|test}
|
||||||
## [setup][pr]:
|
|
||||||
```nix
|
|
||||||
{
|
|
||||||
|
|
||||||
nix.package = nixFlakes;
|
|
||||||
|
|
||||||
nix.extraOptions = ''
|
|
||||||
experimental-features = nix-command flakes
|
|
||||||
'';
|
|
||||||
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### sans [NixOS][nixos]:
|
You can specify one of the host configurations from the [hosts](hosts)
|
||||||
```
|
directory. If omitted, it will default to your systems current hostname.
|
||||||
# nix-env -f '<nixpkgs>' -iA nixFlakes
|
|
||||||
|
|
||||||
# echo "experimental-features = nix-command flakes" >> /etc/nix/nix.conf
|
In addtion:
|
||||||
|
```
|
||||||
|
rebuild iso
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Will make a minimal and bootable iso image of the [niximg](hosts/niximg.nix)
|
||||||
|
configuration. You can customize the image by editing this file.
|
||||||
|
|
||||||
|
You can also install the packages declared in [pkgs](pkgs) without needing
|
||||||
|
to install NixOS. For example:
|
||||||
|
```
|
||||||
|
# from top-level
|
||||||
|
nix profile install ".#packages.x86_64-linux.purs"
|
||||||
|
```
|
||||||
|
|
||||||
|
# Contributing
|
||||||
|
|
||||||
|
The purpose of this repository is to allow for simpler modularity and
|
||||||
|
maintainability than was achieved in a previous effort. Flakes, along with a
|
||||||
|
standardized structure, make this simple.
|
||||||
|
|
||||||
|
## Hosts
|
||||||
|
Distributions for particular machines should be stored in the [hosts](hosts)
|
||||||
|
directory. Every file in this directory will be added automatically to the
|
||||||
|
available NixOS configurations available in the `nixosConfigurations` flake
|
||||||
|
output. See the [`default.nix`](hosts/default.nix) for implementation details.
|
||||||
|
|
||||||
|
## Profiles
|
||||||
|
More abstract configurations that can be reused by multiple machines should
|
||||||
|
go in the [profiles](profiles) directory. It's structure is pretty straight
|
||||||
|
forward. Just have a look to get an idea. Every profile should have a
|
||||||
|
`default.nix` to easily import it. You can also stick things in the profile's
|
||||||
|
subdirectory which are not automatically imported by its `default.nix` but are
|
||||||
|
meant to be manually imported from a host (useful for less common, or
|
||||||
|
specialized configurations).
|
||||||
|
|
||||||
|
In addition, profiles can depend on other profiles. For example, The
|
||||||
|
[graphical](profiles/graphical) profile depends on [develop](profiles/develop)
|
||||||
|
simply by importing it in its [`default.nix`](profiles/graphical/default.nix).
|
||||||
|
|
||||||
|
## Users
|
||||||
|
User declaration belongs in the [users](users) directory. Everything related to
|
||||||
|
your user should be declared here. For convenience, [home-manager][home-manager]
|
||||||
|
is available automatically for home directory setup.
|
||||||
|
|
||||||
|
## Modules and Packages
|
||||||
|
All [modules](modules/default.nix) and [pkgs](pkgs/default.nix) are available
|
||||||
|
for every configuration automatically. Simply add a `*.nix` file to one of
|
||||||
|
these directories declaring your module or package, and update the
|
||||||
|
corresponding `default.nix` to point to it. Now you can use your new module or
|
||||||
|
install your new package as usual.
|
||||||
|
|
||||||
|
Doing this will also add them to the flake's `nixosModules` or `overlays`
|
||||||
|
outputs to import them easily into an external NixOS configuration as well.
|
||||||
|
|
||||||
|
## Pull Requests
|
||||||
|
|
||||||
|
If you'd like to add a package, module, profile or host configuration please
|
||||||
|
be sure to format your code with [`nixpkgs-fmt`][nixpkgs-fmt] before
|
||||||
|
opening a pull-request. The commit message follows the same semantics as
|
||||||
|
[nixpkgs][nixpkgs]. You can use a `#` symbol to specify abiguities. For example,
|
||||||
|
`develop#zsh: <rest of commit message>` would tell me that your updating the
|
||||||
|
`zsh` configuration living under the `develop` profile.
|
||||||
|
|
||||||
|
|
||||||
# License
|
# License
|
||||||
|
|
@ -43,8 +95,12 @@ included here, which may be derivative works of the packages to
|
||||||
which they apply. The aforementioned artifacts are all covered by the
|
which they apply. The aforementioned artifacts are all covered by the
|
||||||
licenses of the respective packages.
|
licenses of the respective packages.
|
||||||
|
|
||||||
[rfc]: https://github.com/tweag/rfcs/blob/flakes/rfcs/0049-flakes.md
|
[direnv]: https://direnv.net
|
||||||
[pr]: https://github.com/NixOS/nixpkgs/pull/68897
|
[home-manager]: https://github.com/nrdxp/home-manager
|
||||||
[video]: https://www.youtube.com/watch?v=UeBX7Ide5a0
|
|
||||||
[NixOS]: https://nixos.org
|
[NixOS]: https://nixos.org
|
||||||
|
[nixpkgs-fmt]: https://github.com/nix-community/nixpkgs-fmt
|
||||||
|
[nixpkgs]: https://github.com/NixOS/nixpkgs
|
||||||
[old]: https://github.com/nrdxp/nixos
|
[old]: https://github.com/nrdxp/nixos
|
||||||
|
[pr]: https://github.com/NixOS/nixpkgs/pull/68897
|
||||||
|
[rfc]: https://github.com/tweag/rfcs/blob/flakes/rfcs/0049-flakes.md
|
||||||
|
[video]: https://www.youtube.com/watch?v=UeBX7Ide5a0
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue