b12f/os
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

README.md: refine language and clarify more

Browse source
This commit is contained in:
Timothy DeHerrera 2020-01-03 20:23:13 -07:00
parent 425f7894a4
commit 0ad4236bcb
No known key found for this signature in database
GPG key ID: 8985725DB5B0C122
1 changed files with 34 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
README.md
View file

@ -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.