README.md: refine language and clarify more
This commit is contained in:
parent
425f7894a4
commit
0ad4236bcb
57
README.md
57
README.md
@ -1,11 +1,13 @@
|
|||||||
# 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 [flakes][rfc] mechanism. Its aim is
|
NixOS configuration using the experimental [flakes][rfc] mechanism. Its aim is
|
||||||
to provide a generic template repository, to neatly separate concerns and allow
|
to provide a generic template repository which neatly separates concerns and
|
||||||
one to get up and running with NixOS faster. Flakes are still an experimental
|
allows one to get up and running with NixOS faster than ever.
|
||||||
feature, but once they finally get merged, even more will become possible,
|
|
||||||
including [nixops](https://nixos.org/nixops) support.
|
Flakes are still an experimental feature, but once they finally get merged,
|
||||||
|
even more will become possible, including [nixops](https://nixos.org/nixops)
|
||||||
|
support.
|
||||||
|
|
||||||
|
|
||||||
#### [Flake Talk][video]
|
#### [Flake Talk][video]
|
||||||
@ -28,7 +30,7 @@ nixos-generate-config --show-hardware-config > ./hosts/<new_host>.nix
|
|||||||
|
|
||||||
|
|
||||||
A basic `rebuild` command is included in the shell to replace
|
A basic `rebuild` command is included in the shell to replace
|
||||||
`nixos-rebuild` for now.
|
`nixos-rebuild` for now:
|
||||||
|
|
||||||
```
|
```
|
||||||
Usage: rebuild [host] {switch|boot|test}
|
Usage: rebuild [host] {switch|boot|test}
|
||||||
@ -46,12 +48,11 @@ below on how to structure your expressions. And be sure to update the
|
|||||||
[locale.nix](local/locale.nix) for your region.
|
[locale.nix](local/locale.nix) for your region.
|
||||||
|
|
||||||
You can always check out my personal branch
|
You can always check out my personal branch
|
||||||
[`nrdxp`](https://github.com/nrdxp/nixflk/tree/nrdxp), to get an idea of how to
|
[`nrdxp`](https://github.com/nrdxp/nixflk/tree/nrdxp), for concrete examples.
|
||||||
structure your work.
|
|
||||||
|
|
||||||
## Additional Capabilities
|
## Additional Capabilities
|
||||||
|
|
||||||
In addtion:
|
Making iso images:
|
||||||
```
|
```
|
||||||
rebuild iso
|
rebuild iso
|
||||||
```
|
```
|
||||||
@ -72,7 +73,7 @@ flake to allow for seemless sharing between configurations.
|
|||||||
# Contributing
|
# Contributing
|
||||||
|
|
||||||
The purpose of this repository is to provide a standardized template structure
|
The purpose of this repository is to provide a standardized template structure
|
||||||
for NixOS machine expressions, thus enabling simpler sharing and resue of nix
|
for NixOS machine expressions, thus enabling simpler sharing and reuse of nix
|
||||||
expressions.
|
expressions.
|
||||||
|
|
||||||
Say your friend and you are using this repository, each with your own unique
|
Say your friend and you are using this repository, each with your own unique
|
||||||
@ -83,14 +84,16 @@ entire system configurations your friend has defined!
|
|||||||
## 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
|
||||||
available NixOS configurations available in the `nixosConfigurations` flake
|
the `nixosConfigurations` flake output. See the
|
||||||
output. See the [`default.nix`](hosts/default.nix) for implementation details.
|
[`default.nix`](hosts/default.nix) for the implementation details.
|
||||||
|
|
||||||
## Profiles
|
## Profiles
|
||||||
More abstract configurations that can be reused by multiple machines should
|
More abstract configurations suitable for reuse by multiple machines should
|
||||||
go in the [profiles](profiles) directory. We make a distinction between a module
|
go in the [profiles](profiles) directory. A distinction is made between a module
|
||||||
and profile, in that a profile is simly a regular NixOS module, without any new
|
and profile, in that a profile is simly a regular NixOS module, without any new
|
||||||
option declarations.
|
option declarations. If you want to declare new
|
||||||
|
[options](https://nixos.org/nixos/manual/options.html), create an expression
|
||||||
|
under the [modules](modules) directory instead.
|
||||||
|
|
||||||
Every profile should have a `default.nix` to easily import it. You can also
|
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
|
stick things in the profile's subdirectory which are not automatically
|
||||||
@ -107,10 +110,16 @@ In addition, profiles can depend on other profiles. For example, 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 in its [`default.nix`](profiles/graphical/default.nix).
|
||||||
|
|
||||||
|
You can, optionally, choose to export your profiles via the flake output. If
|
||||||
|
you add an attribute to [profiles/default.nix](profiles/default.nix) named
|
||||||
|
\<your-profile>, then it will become available to other flakes via
|
||||||
|
`nixosModules.profiles.<your-profile>`.
|
||||||
|
|
||||||
## Users
|
## Users
|
||||||
User declaration belongs in the `users` directory. Everything related to
|
User declaration belongs in the `users` directory. Everything related to
|
||||||
your user should be declared here. For convenience, [home-manager][home-manager]
|
your user should be declared here. For convenience, [home-manager][home-manager]
|
||||||
is available automatically for home directory setup.
|
is available automatically for home directory setup and should only be used
|
||||||
|
from this directory.
|
||||||
|
|
||||||
## Secrets
|
## Secrets
|
||||||
Anything you wish to keep encrypted goes in the `secrets` directory, which is
|
Anything you wish to keep encrypted goes in the `secrets` directory, which is
|
||||||
@ -126,10 +135,10 @@ only be imported from the `users` directory.
|
|||||||
|
|
||||||
## Modules and Packages
|
## Modules and Packages
|
||||||
All [modules](modules/default.nix) and [pkgs](pkgs/default.nix) are available
|
All [modules](modules/default.nix) and [pkgs](pkgs/default.nix) are available
|
||||||
for every configuration automatically. Simply add a `*.nix` file to one of
|
for every configuration automatically. Simply add an expression to one of
|
||||||
these directories declaring your module or package, and update the
|
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
|
corresponding `default.nix` to point to it. Now you can use your new module or
|
||||||
install your new package as usual.
|
install your new package as usual from any profile.
|
||||||
|
|
||||||
Doing this will also add them to the flake's `nixosModules` or `overlays`
|
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.
|
outputs to import them easily into an external NixOS configuration as well.
|
||||||
@ -140,13 +149,13 @@ While much of your work in this template may be idiosyncratic in nature. Anythin
|
|||||||
that might be generally useful to the broader NixOS community can be synced to
|
that might be generally useful to the broader NixOS community can be synced to
|
||||||
the `template` branch to provide a host of useful NixOS configurations available
|
the `template` branch to provide a host of useful NixOS configurations available
|
||||||
"out of the box". If you wish to contribute such an expression please follow
|
"out of the box". If you wish to contribute such an expression please follow
|
||||||
the following guidelines.
|
these guidelines:
|
||||||
|
|
||||||
Be sure to format your code with [`nixpkgs-fmt`][nixpkgs-fmt] before
|
* format your code with [`nixpkgs-fmt`][nixpkgs-fmt]
|
||||||
opening a pull-request. The commit message follows the same semantics as
|
* The commit message follows the same semantics as [nixpkgs][nixpkgs].
|
||||||
[nixpkgs][nixpkgs]. You can use a `#` symbol to specify abiguities. For example,
|
* You can use a `#` symbol to specify abiguities. For example,
|
||||||
`develop#zsh: <rest of commit message>` would tell me that your updating the
|
`develop#zsh: <rest of commit message>` would tell me that your updating the
|
||||||
`zsh` configuration living under the `develop` profile.
|
`zsh` subprofile living under the `develop` profile.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user