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

docs: soft update (fix the most obvious drift)

Browse source
This commit is contained in:
David Arnold 2021-08-01 16:38:52 -05:00
parent f69737301f
commit 2fcb3605ee
No known key found for this signature in database
GPG key ID: AB15A6AF1101390D
22 changed files with 59 additions and 708 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/mdbook_docs.yml vendored
View file

@ -3,7 +3,7 @@ name: Deploy Docs to GitHub Pages
on:
push:
branches:
- core
- main
jobs:
deploy:

0
pkgs/bud/default.nix → bud/default.nix
View file

0
pkgs/bud/get.bash → bud/get.bash
View file

33
doc/CONTRIBUTING.md
View file

@ -1,25 +1,18 @@
# Pull Requests
All development is done in the `develop` branch. Only minor bug-fixes and release
PRs should target `master`.
If making a change to the template, or adding a feature, please be sure to update the
relevant docs. Each directory contains its own README.md, which will
automatically be pulled into the [mdbook](https://devos.divnix.com). The book is
rendered on every change, so the docs should always be up to date.
## TL;DR;
- **Target Branch**: `main`
- **Merge Policy**: [`bors`][bors] is alwyas right (→ `bors try`)
- **Docs**: every changeset is expected to contain doc updates
- **Commit Msg**: be a poet! Comprehensive and explanatory commit messages
should cover the motivation and use case in an easily understandable manner
even when read after a few months.
- **Test Driven Development**: please default to test driven development where possible.
We also use [BORS](https://bors.tech) to ensure that all pull requests pass the
test suite once at least one review is completed.
### Within the Devshell (`nix develop`)
- **Hooks**: please `git commit` within the devshell
- **Fail Early**: please run from within the devshell on your local machine:
- `nix flake check`
# Style
If you wish to contribute please follow these guidelines:
[bors]: https://bors.tech
* format your code with [`nixpkgs-fmt`][nixpkgs-fmt]. The default devshell
includes a pre-commit hook that does this for you.
* The commit message follows the same semantics as [nixpkgs][nixpkgs].
* You can use a `#` symbol to specify ambiguities. For example,
`develop#zsh: <rest of commit message>` would tell me that you're updating the
`zsh` subprofile living under the `develop` profile.
[nixpkgs-fmt]: https://github.com/nix-community/nixpkgs-fmt
[nixpkgs]: https://github.com/NixOS/nixpkgs

12
doc/SUMMARY.md
View file

@ -6,7 +6,6 @@
- [Bootstrapping](./start/bootstrapping.md)
- [From NixOS](./start/from-nixos.md)
- [Key Concepts](./concepts/index.md)
- [Extern](./concepts/extern.md)
- [Hosts](./concepts/hosts.md)
- [Overrides](./concepts/overrides.md)
- [Profiles](./concepts/profiles.md)
@ -17,17 +16,10 @@
- [Overlays](./outputs/overlays.md)
- [Packages](./outputs/pkgs.md)
- [Concerns]()
- [Lib](./lib.md)
- [Secrets](./secrets.md)
- [Tests](./tests.md)
- [Helper Script – `flk`](./flk/index.md)
- [up](./flk/up.md)
- [update](./flk/update.md)
- [get](./flk/get.md)
- [doi](./flk/doi.md)
- [iso](./flk/iso.md)
- [install](./flk/install.md)
- [home](./flk/home.md)
- [Helper Script – `bud`](./bud/index.md)
- [get](./bud/get.md)
- [Integrations](./integrations/index.md)
- [Cachix](./integrations/cachix.md)
- [Deploy RS](./integrations/deploy.md)

2
doc/flk/get.md → doc/bud/get.md
View file

@ -4,7 +4,7 @@ git history.
## Usage
```sh
flk get DEST-DIR
bud get DEST-DIR
```
If DEST-DIR is ommitted, it defaults to _./devos_.

24
doc/bud/index.md Normal file
View file

@ -0,0 +1,24 @@
# [`bud`][bud] command
The template incudes a convenient script for managing your system called [`bud`][bud].
It is a portable and highly composable system control tool that work anywhere on your host
or in the flake's devshell.
Although it comes with some predefined standard helpers,
it is very extensible and you are encouraged to write your own script snippets
to ease your workflows. An example is the bud module for a `get` command that
comes included with `devos`.
While writing scripts you can convenientely access smart environment variables
that can tell the current architecture, user or host name, among others, regardless
wether you invoke `bud` within the devshell or as the system-wide installed `bud`.
For details, please review the [bud repo][bud].
## Usage
```sh
bud help
```
[bud]: https://github.com/divnix/bud

42
doc/concepts/extern.md
View file

@ -1,42 +0,0 @@
# External Art
When you need to use a module, overlay, or pass a value from one of your inputs
to the rest of your NixOS configuration, you can make use of a couple arguments.
It is encouraged to add external art directly in your `flake.nix` so the file
represents a complete dependency overview of your flake.
## Overlays
External overlays can directly be added to a channel's `overlays` list.
flake.nix:
```nix
{
channels.nixos.overlays = [ inputs.agenix.overlay ];
}
```
Upon exporting overlays, these overlays will be automatically filtered out by inspecting the `inputs` argument.
## Modules
There is a dedicated `nixos.hostDefaults.externalModules` argument for external
modules.
flake.nix:
```nix
{
nixos.hostDefaults.externalModules = [ inputs.agenix.nixosModules.age ];
}
```
## Home Manager
Since there isn't a `hosts` concept for home-manager, externalModules is just a
top-level argument in the `home` namespace.
flake.nix:
```nix
{
home.externalModules = [ doom-emacs = doom-emacs.hmModule ];
}
```
> ##### Note:
> To avoid declaring "external" modules separately, which is obvious since they come from `inputs`, the optimal solution would be to automatically export modules that were created in
> your flake. But this is not possible due to NixOS/nix#4740.

10
doc/concepts/index.md
View file

@ -1,4 +1,10 @@
# Key Concepts
There are few idioms unique to DevOS. This section is dedicated to helping you
understand them.
Key concepts are derived from [digga][digga]. Please refer to its
[docs][digga-docs] for more details.
This section is dedicated to helping you develop a more hands on
understanding of them them.
[digga-docs]: https://digga.divnix.com
[digga]: https://github.com/divnix/digga

6
doc/concepts/users.md
View file

@ -1,3 +1,8 @@
> ##### _Note:_
> This section and its semantics need a conceptiual rework.
> Since recently [portable home configurations][portableuser]
> that are not bound to any specific host are a thing.
# Users
Users are a special case of [profiles](profiles.md) that define system
@ -69,3 +74,4 @@ nix build "github:divnix/devos#homeConfigurations.nixos@NixOS.home.activationPac
[home-manager]: https://nix-community.github.io/home-manager
[modules-list]: https://github.com/divnix/devos/tree/core/users/modules/module-list.nix
[portableuser]: https://digga.divnix.com/api-reference-home.html#homeusers

10
doc/flk/doi.md
View file

@ -1,10 +0,0 @@
# DigitalOcean
Now you can [create a droplet](https://cloud.digitalocean.com/droplets/new) using your custom image.
Making a DigitalOcean compatible image for `hosts/NixOS.nix` is as simple as:
```sh
flk doi NixOS
```
This works for any file matching `hosts/*.nix` excluding `default.nix`.

8
doc/flk/home.md
View file

@ -1,8 +0,0 @@
# home
The `home` subcommand is for using your home-manager configurations outside of
NixOS, providing an awesome mechanism for keeping your environments
synchronized, even when using other systems.
## Usage
The [users](../concepts/users.md#external-usage) page contains a good usage
example.

20
doc/flk/index.md
View file

@ -1,20 +0,0 @@
# flk command
The devshell for the project incudes a convenient script for managing your
system called `flk`. Each of the following chapters is a reference for one of
its subcommands.
## Rebuild
Without any of the subcommands, `flk` acts as a convenient shortcut for
`nixos-rebuild`:
```sh
flk NixOS build
```
Will build _hosts/NixOS.nix_. You can change out `build` for `switch`, `test`,
etc. Any additional arguments are passed through to the call to
`nixos-rebuild`.
## Usage
```sh
flk help
```

12
doc/flk/install.md
View file

@ -1,12 +0,0 @@
# install
The `install` subcommand is a simple convenience for `nixos-install`, similar
to the shortcut for `nixos-rebuild`, all additional arguments are passed
through.
## Example
```sh
flk install NixOS
```
This will install _hosts/NixOS.nix_ to /mnt. You can override this directory
using standard `nixos-install` args.

1
doc/flk/iso.md
View file

@ -1 +0,0 @@
../start/iso.md

4
doc/flk/up.md
View file

@ -1,4 +0,0 @@
# up
The `up` subcommand is a simple shortcut for `nixos-generate-config` that is
compatible with devos. There is a short explanation in the the getting started
[guide](../start/from-nixos.md#generate-configuration).

22
doc/flk/update.md
View file

@ -1,22 +0,0 @@
# update
The `update` subcommand is a simple alias for:
```sh
nix flake update
```
As it sounds, this will update your lock file.
## Updating Package Sources
If you pass directory name then it will update that input if the directory
contains a flake.nix, with an optional arguement to update only a specific
input in the subflake.
For example, you can update any
[package sources](../outputs/pkgs.md#automatic-source-updates) you may have
declared in _pkgs/flake.nix_:
```sh
flk update pkgs
```
or just its _nixpkgs_:
```sh
flk update pkgs nixpkgs
```

2
doc/integrations/nvfetcher.md
View file

@ -38,6 +38,6 @@ fetch.git = "https://github.com/mlvzk/manix.git" # responsible for fetching
> ##### _Note:_
> Please refer to the [NvFetcher Readme][nvf-readme] for more options.
[nvf: https://github.com/berberman/nvfetcher
[nvf]: https://github.com/berberman/nvfetcher
[nvf-readme]: https://github.com/berberman/nvfetcher#readme
[sources.toml]: https://github.com/divnix/devos/tree/core/pkgs/sources.toml

541
doc/mkFlakeOptions.md
View file

@ -1,541 +0,0 @@
## channels
nixpkgs channels to create
*_Type_*:
attribute set of submodules
*_Default_*
```
{}
```
## channels.\<name\>.config
nixpkgs config for this channel
*_Type_*:
attribute set or path convertible to it
*_Default_*
```
{}
```
## channels.\<name\>.input
nixpkgs flake input to use for this channel
*_Type_*:
nix flake
*_Default_*
```
"self.inputs.<name>"
```
## channels.\<name\>.overlays
overlays to apply to this channel
these will get exported under the 'overlays' flake output
as \<channel\>/\<name\> and any overlay pulled from ${inputs}
will be filtered out
*_Type_*:
list of valid Nixpkgs overlay or path convertible to its or anything convertible to it
*_Default_*
```
[]
```
## channelsConfig
nixpkgs config for all channels
*_Type_*:
attribute set or path convertible to it
*_Default_*
```
{}
```
## devshell
Modules to include in your devos shell. the `modules` argument
will be exported under the `devshellModules` output
*_Type_*:
submodule
*_Default_*
```
{}
```
## devshell.externalModules
modules to include that won't be exported
meant importing modules from external flakes
*_Type_*:
list of valid module or path convertible to its or anything convertible to it
*_Default_*
```
[]
```
## devshell.modules
modules to include in all hosts and export to devshellModules output
*_Type_*:
list of path to a modules or anything convertible to it or path convertible to it
*_Default_*
```
[]
```
## home
hosts, modules, suites, and profiles for home-manager
*_Type_*:
submodule
*_Default_*
```
{}
```
## home.externalModules
modules to include that won't be exported
meant importing modules from external flakes
*_Type_*:
list of valid module or path convertible to its or anything convertible to it
*_Default_*
```
[]
```
## home.importables
Packages of paths to be passed to modules as `specialArgs`.
*_Type_*:
attribute set
*_Default_*
```
{}
```
## home.importables.suites
collections of profiles
*_Type_*:
attribute set of list of paths or anything convertible to its
## home.modules
modules to include in all hosts and export to homeModules output
*_Type_*:
list of path to a modules or anything convertible to it or path convertible to it
*_Default_*
```
[]
```
## home.profiles
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
both with the importables option. `rakeLeaves` can be used to create profiles and
by passing a module or `rec` set to `importables`, suites can access profiles.
Example:
```
importables = rec {
profiles = digga.lib.importers.rakeLeaves ./profiles;
suites = with profiles; { };
}
```
See https://github.com/divnix/digga/pull/30 for more details
*_Type_*:
list of paths
*_Default_*
```
[]
```
## home.suites
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
both with the importables option. `rakeLeaves` can be used to create profiles and
by passing a module or `rec` set to `importables`, suites can access profiles.
Example:
```
importables = rec {
profiles = digga.lib.importers.rakeLeaves ./profiles;
suites = with profiles; { };
}
```
See https://github.com/divnix/digga/pull/30 for more details
*_Type_*:
function that evaluates to a(n) attrs or path convertible to it
## nixos
hosts, modules, suites, and profiles for nixos
*_Type_*:
submodule
*_Default_*
```
{}
```
## nixos.hostDefaults
Defaults for all hosts.
the modules passed under hostDefaults will be exported
to the 'nixosModules' flake output.
They will also be added to all hosts.
*_Type_*:
submodule
*_Default_*
```
{}
```
## nixos.hostDefaults.channelName
Channel this host should follow
*_Type_*:
a channel defined in `channels`
*_Default_*
```
null
```
## nixos.hostDefaults.externalModules
modules to include that won't be exported
meant importing modules from external flakes
*_Type_*:
list of valid module or path convertible to its or anything convertible to it
*_Default_*
```
[]
```
## nixos.hostDefaults.modules
modules to include in all hosts and export to nixosModules output
*_Type_*:
list of path to a modules or anything convertible to it or path convertible to it
*_Default_*
```
[]
```
## nixos.hostDefaults.system
system for this host
*_Type_*:
system defined in `supportedSystems`
*_Default_*
```
null
```
## nixos.hosts
configurations to include in the nixosConfigurations output
*_Type_*:
attribute set of submodules
*_Default_*
```
{}
```
## nixos.hosts.\<name\>.channelName
Channel this host should follow
*_Type_*:
a channel defined in `channels`
*_Default_*
```
null
```
## nixos.hosts.\<name\>.modules
modules to include
*_Type_*:
list of valid module or path convertible to its or anything convertible to it
*_Default_*
```
[]
```
## nixos.hosts.\<name\>.system
system for this host
*_Type_*:
system defined in `supportedSystems`
*_Default_*
```
null
```
## nixos.importables
Packages of paths to be passed to modules as `specialArgs`.
*_Type_*:
attribute set
*_Default_*
```
{}
```
## nixos.importables.suites
collections of profiles
*_Type_*:
attribute set of list of paths or anything convertible to its
## nixos.profiles
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
both with the importables option. `rakeLeaves` can be used to create profiles and
by passing a module or `rec` set to `importables`, suites can access profiles.
Example:
```
importables = rec {
profiles = digga.lib.importers.rakeLeaves ./profiles;
suites = with profiles; { };
}
```
See https://github.com/divnix/digga/pull/30 for more details
*_Type_*:
list of paths
*_Default_*
```
[]
```
## nixos.suites
WARNING: The 'suites' and `profiles` options have been deprecated, you can now create
both with the importables option. `rakeLeaves` can be used to create profiles and
by passing a module or `rec` set to `importables`, suites can access profiles.
Example:
```
importables = rec {
profiles = digga.lib.importers.rakeLeaves ./profiles;
suites = with profiles; { };
}
```
See https://github.com/divnix/digga/pull/30 for more details
*_Type_*:
function that evaluates to a(n) attrs or path convertible to it
## outputsBuilder
builder for flake system-spaced outputs
The builder gets passed an attrset of all channels
*_Type_*:
function that evaluates to a(n) attrs
*_Default_*
```
"channels: { }"
```
## self
The flake to create the devos outputs for
*_Type_*:
nix flake
## supportedSystems
The systems supported by this flake
*_Type_*:
list of strings
*_Default_*
```
["aarch64-linux","i686-linux","x86_64-darwin","x86_64-linux"]
```

10
doc/outputs/pkgs.md
View file

@ -13,16 +13,6 @@ the supported systems listed in the package's `meta.platforms` attribute.
And, as usual, every package in the overlay is also available to any NixOS
[host](../concepts/hosts.md).
## Automatic Source Updates
There is the added, but optional, convenience of declaring your sources in
_pkgs/flake.nix_ as an input. You can then access them from the `srcs` package.
This allows updates to be managed automatically by simply
[updating](../flk/update.md#updating-package-sources) the lock file. No
more manually entering sha256 hashes!
As an added bonus, version strings are also generated automatically from either
the flake ref, or the date and git revision of the source.
## Example
pkgs/development/libraries/libinih/default.nix:
```nix

4
doc/start/iso.md
View file

@ -2,13 +2,13 @@
Making and writing an installable iso for `hosts/NixOS.nix` is as simple as:
```sh
flk iso NixOS
bud build NixOS bootstrapIso
dd bs=4M if=result/iso/*.iso of=/dev/$your_installation_device \
status=progress oflag=sync
```
This works for any file matching `hosts/*.nix` excluding `default.nix`.
This works for any host.
## ISO image nix store & cache

2
flake.nix
View file

@ -152,7 +152,7 @@
}
//
{
budModules = { devos = import ./pkgs/bud; };
budModules = { devos = import ./bud; };
}
;
}