From 2fcb3605eed05978fe4df0f5969aca552fa0e140 Mon Sep 17 00:00:00 2001 From: David Arnold Date: Sun, 1 Aug 2021 16:38:52 -0500 Subject: [PATCH] docs: soft update (fix the most obvious drift) --- .github/workflows/mdbook_docs.yml | 2 +- {pkgs/bud => bud}/default.nix | 0 {pkgs/bud => bud}/get.bash | 0 doc/CONTRIBUTING.md | 33 +- doc/SUMMARY.md | 12 +- doc/{flk => bud}/get.md | 2 +- doc/bud/index.md | 24 ++ doc/concepts/extern.md | 42 --- doc/concepts/index.md | 10 +- doc/concepts/users.md | 6 + doc/flk/doi.md | 10 - doc/flk/home.md | 8 - doc/flk/index.md | 20 -- doc/flk/install.md | 12 - doc/flk/iso.md | 1 - doc/flk/up.md | 4 - doc/flk/update.md | 22 -- doc/integrations/nvfetcher.md | 2 +- doc/mkFlakeOptions.md | 541 ------------------------------ doc/outputs/pkgs.md | 10 - doc/start/iso.md | 4 +- flake.nix | 2 +- 22 files changed, 59 insertions(+), 708 deletions(-) rename {pkgs/bud => bud}/default.nix (100%) rename {pkgs/bud => bud}/get.bash (100%) rename doc/{flk => bud}/get.md (90%) create mode 100644 doc/bud/index.md delete mode 100644 doc/concepts/extern.md delete mode 100644 doc/flk/doi.md delete mode 100644 doc/flk/home.md delete mode 100644 doc/flk/index.md delete mode 100644 doc/flk/install.md delete mode 120000 doc/flk/iso.md delete mode 100644 doc/flk/up.md delete mode 100644 doc/flk/update.md delete mode 100644 doc/mkFlakeOptions.md diff --git a/.github/workflows/mdbook_docs.yml b/.github/workflows/mdbook_docs.yml index 842171c4..5faf9c28 100644 --- a/.github/workflows/mdbook_docs.yml +++ b/.github/workflows/mdbook_docs.yml @@ -3,7 +3,7 @@ name: Deploy Docs to GitHub Pages on: push: branches: - - core + - main jobs: deploy: diff --git a/pkgs/bud/default.nix b/bud/default.nix similarity index 100% rename from pkgs/bud/default.nix rename to bud/default.nix diff --git a/pkgs/bud/get.bash b/bud/get.bash similarity index 100% rename from pkgs/bud/get.bash rename to bud/get.bash diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 4766cdf7..8574daea 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -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: ` 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 diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md index 4378683f..1d7bafe9 100644 --- a/doc/SUMMARY.md +++ b/doc/SUMMARY.md @@ -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) diff --git a/doc/flk/get.md b/doc/bud/get.md similarity index 90% rename from doc/flk/get.md rename to doc/bud/get.md index 8761f004..12263df0 100644 --- a/doc/flk/get.md +++ b/doc/bud/get.md @@ -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_. diff --git a/doc/bud/index.md b/doc/bud/index.md new file mode 100644 index 00000000..7b985792 --- /dev/null +++ b/doc/bud/index.md @@ -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 diff --git a/doc/concepts/extern.md b/doc/concepts/extern.md deleted file mode 100644 index 45d8dcb5..00000000 --- a/doc/concepts/extern.md +++ /dev/null @@ -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. diff --git a/doc/concepts/index.md b/doc/concepts/index.md index 8aca6e5c..618292cb 100644 --- a/doc/concepts/index.md +++ b/doc/concepts/index.md @@ -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 diff --git a/doc/concepts/users.md b/doc/concepts/users.md index 20f371de..12bf5622 100644 --- a/doc/concepts/users.md +++ b/doc/concepts/users.md @@ -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 diff --git a/doc/flk/doi.md b/doc/flk/doi.md deleted file mode 100644 index fc522cdd..00000000 --- a/doc/flk/doi.md +++ /dev/null @@ -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`. diff --git a/doc/flk/home.md b/doc/flk/home.md deleted file mode 100644 index f0bae767..00000000 --- a/doc/flk/home.md +++ /dev/null @@ -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. diff --git a/doc/flk/index.md b/doc/flk/index.md deleted file mode 100644 index 04fc1c48..00000000 --- a/doc/flk/index.md +++ /dev/null @@ -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 -``` diff --git a/doc/flk/install.md b/doc/flk/install.md deleted file mode 100644 index 3ae52504..00000000 --- a/doc/flk/install.md +++ /dev/null @@ -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. diff --git a/doc/flk/iso.md b/doc/flk/iso.md deleted file mode 120000 index fa658ef4..00000000 --- a/doc/flk/iso.md +++ /dev/null @@ -1 +0,0 @@ -../start/iso.md \ No newline at end of file diff --git a/doc/flk/up.md b/doc/flk/up.md deleted file mode 100644 index 265e03a0..00000000 --- a/doc/flk/up.md +++ /dev/null @@ -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). diff --git a/doc/flk/update.md b/doc/flk/update.md deleted file mode 100644 index 869db72f..00000000 --- a/doc/flk/update.md +++ /dev/null @@ -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 -``` diff --git a/doc/integrations/nvfetcher.md b/doc/integrations/nvfetcher.md index 2bfaa029..4670657e 100644 --- a/doc/integrations/nvfetcher.md +++ b/doc/integrations/nvfetcher.md @@ -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 diff --git a/doc/mkFlakeOptions.md b/doc/mkFlakeOptions.md deleted file mode 100644 index dbc7abc1..00000000 --- a/doc/mkFlakeOptions.md +++ /dev/null @@ -1,541 +0,0 @@ -## channels -nixpkgs channels to create - - -*_Type_*: -attribute set of submodules - - -*_Default_* -``` -{} -``` - - - - -## channels.\.config -nixpkgs config for this channel - - -*_Type_*: -attribute set or path convertible to it - - -*_Default_* -``` -{} -``` - - - - -## channels.\.input -nixpkgs flake input to use for this channel - - -*_Type_*: -nix flake - - -*_Default_* -``` -"self.inputs." -``` - - - - -## channels.\.overlays -overlays to apply to this channel -these will get exported under the 'overlays' flake output -as \/\ 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.\.channelName -Channel this host should follow - - -*_Type_*: -a channel defined in `channels` - - -*_Default_* -``` -null -``` - - - - -## nixos.hosts.\.modules -modules to include - - -*_Type_*: -list of valid module or path convertible to its or anything convertible to it - - -*_Default_* -``` -[] -``` - - - - -## nixos.hosts.\.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"] -``` - - - diff --git a/doc/outputs/pkgs.md b/doc/outputs/pkgs.md index 58ce52bd..548667ff 100644 --- a/doc/outputs/pkgs.md +++ b/doc/outputs/pkgs.md @@ -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 diff --git a/doc/start/iso.md b/doc/start/iso.md index efa515a0..8f5c6ab0 100644 --- a/doc/start/iso.md +++ b/doc/start/iso.md @@ -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 diff --git a/flake.nix b/flake.nix index dddcb528..bdd82cd9 100644 --- a/flake.nix +++ b/flake.nix @@ -152,7 +152,7 @@ } // { - budModules = { devos = import ./pkgs/bud; }; + budModules = { devos = import ./bud; }; } ; }