README.md: further refinements

This commit is contained in:
Timothy DeHerrera 2020-01-05 18:26:09 -07:00
parent 9670fa4b0f
commit 97c87299de
No known key found for this signature in database
GPG key ID: 8985725DB5B0C122

View file

@ -21,8 +21,8 @@ git checkout -b $new_branch template
nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix
# wrapper for `nix build` bypassing `nixos-rebuild` # `rebuild` wrapper for `nix build` bypassing `nixos-rebuild`
# Usage: rebuild [([host] {switch|boot|test|dry-activate})|iso] # Usage: rebuild [host] {switch|boot|test|dry-activate}
# You can specify any of the host configurations living in the ./hosts # You can specify any of the host configurations living in the ./hosts
# directory. If omitted, it will default to your systems current hostname. # directory. If omitted, it will default to your systems current hostname.
@ -32,7 +32,7 @@ rebuild $new_host switch
And now you should be ready to start writing your nix configuration or import And now you should be ready to start writing your nix configuration or import
your current one. Review [structure](#structure) below on how to build your your current one. Review the [structure](#structure) below on how to build your
layout. And be sure to update the [locale.nix](local/locale.nix) for your layout. And be sure to update the [locale.nix](local/locale.nix) for your
region. region.
@ -49,7 +49,7 @@ rebuild iso
nix profile install ".#packages.x86_64-linux.myPackage" nix profile install ".#packages.x86_64-linux.myPackage"
``` ```
this flake exports overlays and modules as well: this flake exports multiple outputs for use in other flakes:
```nix ```nix
# external flake.nix # external flake.nix
{ {
@ -58,6 +58,8 @@ this flake exports overlays and modules as well:
outputs = { self, nixpkgs, nixflk }: { outputs = { self, nixpkgs, nixflk }: {
nixosConfigurations.newConfig = nixflk.nixosConfigurations.someConfig;
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem { nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
system = "x86_64-linux"; system = "x86_64-linux";
modules = [ modules = [
@ -74,40 +76,42 @@ this flake exports overlays and modules as well:
The structure is here to keep things simple and clean. Anything sufficiently The structure is here to keep things simple and clean. Anything sufficiently
generic can ultimately be exported for use in other flakes without getting generic can ultimately be exported for use in other flakes without getting
tied up in user concerns. An additional bonus of is the ability to trivially tied up in user concerns. As an added bonus, one can now trivially swap or
swap or combine [profiles](#profiles). combine [profiles](#profiles), creating a custom config in mere moments.
## Hosts ## Hosts
Distributions for particular machines should be stored in the [hosts](hosts) Distributions for particular machines should be stored in the [hosts](hosts)
directory. Every file in this directory will be added automatically to the directory. Every file in this directory will be added automatically to the
the `nixosConfigurations` flake output and thus deployable. See the the `nixosConfigurations` flake output and thus becomes deployable. See the
[`default.nix`](hosts/default.nix) for the implementation details. [`default.nix`](hosts/default.nix) for the implementation details.
## Profiles ## Profiles
More abstract expressions suitable for reuse by deployments should live in the A profile is any directory under [profiles](profiles) containing a `default.nix`
[profiles](profiles) directory. A distinction is made between a module and defining a valid NixOS module, _with_ the added restriction that no new
profile, in that a profile is simply a regular NixOS module, without any _new_ delclarations to the `options` attribute are allowed (use [modules](modules)
option declarations. instead). Their purpose is to provide abstract expressions suitable for reuse by
multiple deployments. They are perhaps _the_ key concept in keeping this
repository matainable.
Every directory here is a profile and should have a `default.nix` to import it. Profiles can have subprofiles which are themselves just profiles that live under
Profiles can have subprofiles which are just subdirectories with a `default.nix`. another. There's no hard rule that everything in the folder must be imported by
There's no hard rule that everything in the folder must be imported by its its `default.nix`, so you can also store relevant code that is useful but not
`default.nix` so you can also store relevant configurations that may not be used wanted by default in, say, an `alt.nix`. Importantly, every subdirectory in a
as often and just import them directly from a [host](#hosts) when needed. profile should be independent of its parent.
Importantly, every subdirectory in a profile should be independently importable.
For example, a zsh directory lives under [profiles/develop](profiles/develop/zsh). For example, a zsh directory lives under [profiles/develop](profiles/develop/zsh).
It's written in a generic way to allow in to be imported without the entire It's self contained to allow inclusion without the whole of
[develop](profiles/develop) if one so wished. This provides a wonderful level of [develop](profiles/develop) if one so wished. This provides a wonderful level of
granularity. granularity and control. Put simply: take the best, leave the rest.
In addition, profiles can depend on other profiles. For example, The In addition, profiles can depend on other profiles. For instance, the
[graphical](profiles/graphical) profile depends on [develop](profiles/develop) [graphical](profiles/graphical) profile depends on [develop](profiles/develop)
simply by importing it in its [`default.nix`](profiles/graphical/default.nix). simply by importing it. This is to ensure my terminal configuration is always
available from within a graphical session.
You can, optionally, choose to export your profiles via the flake output. If Optionally, you may choose to export your profiles via the flake output. If
you add it to the list in [profiles/default.nix](profiles/default.nix), then it you include it in the list defined in [profiles/default.nix](profiles/default.nix),
will become available to other flakes via `nixosModules.profiles.<filename>`. it will be available to other flakes via `nixosModules.profiles`.
## Users ## Users
User declaration belongs in the `users` directory. Everything related to User declaration belongs in the `users` directory. Everything related to
@ -125,17 +129,19 @@ if your not familiar. The filter is already set up to encrypt everything in this
folder by default. folder by default.
To keep [profiles](profiles) reusable across configurations, secrets should To keep [profiles](profiles) reusable across configurations, secrets should
only be imported from the `users` directory. only be imported from the `users` or [`hosts`](hosts) directory.
## Modules and Packages ## Modules and Packages
All [modules](modules/default.nix) and [pkgs](pkgs/default.nix) are available All expressions in both [modules/defualt.nix](modules/default.nix) and
for every configuration automatically. Simply add an expression to one of [pkgs/default.nix](pkgs/default.nix) are available globally, anywhere else in the
these directories declaring your module or package, and update the repo. They are additionally included in the `nixosModules` or `overlays` flake
corresponding `default.nix` to point to it. Now you can use your new module or outputs. Packages can manually be added to [flake.nix](flake.nix) for inclusion
install your new package as usual from any profile. in the `packages` output as well.
Doing this will also add them to the flake's `nixosModules` or `overlays` The directory structure is identical to nixpkgs to provide a kind of staging area
outputs to import them easily into an external NixOS configuration as well. for any modules or packages we might be wanting to merge there later. If your not
familiar or can't be bothered, simply dropping a valid nix file and pointing the
`default.nix` to it, is all that's really required.
# License # License