Major update to Nix Flakes

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
-    - uses: cachix/install-nix-action@v14
+    - uses: cachix/install-nix-action@v17
     - uses: cachix/cachix-action@v10
       with:
         name: shajra

config.nix

@@ -3,6 +3,8 @@
     default.ergodoxez.keymaps = keymaps/ergodox_ez;
     default.model01.keymap = "shajra";
     default.model01.keymaps = keymaps/model_01;
+    default.model100.keymap = "shajra";
+    default.model100.keymaps = keymaps/model_100;
     default.moonlander.keymap = "shajra";
     default.moonlander.keymaps = keymaps/moonlander;
 }

default.nix

@@ -1 +1 @@
-(import ./nix {}).distribution
+(import nix/compat.nix).defaultNix

doc/design.md

@@ -56,7 +56,7 @@ For reference, below are diagrams of the keymaps for the Model 01 and Ergodox EZ
 
 ## Model 01 "shajra" keymap<a id="sec-3-1"></a>
 
-![img](./model-01-shajra-layout.png)
+![img](./model-100-shajra-layout.png)
 
 ## Ergodox EZ "shajra" keymap<a id="sec-3-2"></a>
 

doc/design.org

@@ -1,5 +1,5 @@
 #+title: Design of the "shajra" Keymap
-#+setupfile: links.org
+#+setupfile: internal/links.org
 
 * Designing a keyboard mapping
 
@@ -57,7 +57,7 @@ EZ.
 
 ** Model 01 "shajra" keymap
 
-[[file:./model-01-shajra-layout.png]]
+[[file:./model-100-shajra-layout.png]]
 
 ** Ergodox EZ "shajra" keymap
 

doc/links.org → doc/internal/links.org

@@ -1,6 +1,8 @@
 #+link: cachix https://cachix.org
+#+link: docstring https://en.wikipedia.org/wiki/Docstring
 #+link: ergodox-ez https://ergodox-ez.com
-#+link: github-actions https://github.com/shajra/shajra-keyboards/actions
+#+link: fhs https://www.pathname.com/fhs/
+#+link: github-actions https://github.com/shajra/nix-project/actions
 #+link: kaleidoscope https://github.com/keyboardio/Kaleidoscope
 #+link: kaleidoscope-oneshot https://kaleidoscope.readthedocs.io/en/latest/plugins/OneShot.html
 #+link: kaleidoscope-qukey https://kaleidoscope.readthedocs.io/en/latest/plugins/Qukeys.html
@@ -9,20 +11,23 @@
 #+link: keyboardio https://shop.keyboard.io
 #+link: key-compose https://en.wikipedia.org/wiki/Compose_key
 #+link: moonlander https://www.zsa.io/moonlander/
-#+link: niv https://github.com/nmattia/niv
 #+link: nix https://nixos.org/nix
-#+link: nix-darwin https://daiderd.com/nix-darwin
-#+link: nix-env https://nixos.org/nix/manual/#sec-nix-env
-#+link: nix-expr https://nixos.org/nix/manual/#ch-expression-language
-#+link: nix-install https://nixos.org/nix/manual/#chap-installation
+#+link: nix-flake-compat https://github.com/edolstra/flake-compat
+#+link: nix-install-manual https://nixos.org/manual/nix/stable/installation/installation.html
+#+link: nix-install-quick https://nixos.org/download.html#download-nix
+#+link: nix-language-manual https://nixos.org/manual/nix/stable/language/index.html
+#+link: nix-language-tutorial https://nixos.org/guides/nix-language.html
 #+link: nix-learn https://nixos.org/learn.html
 #+link: nixos https://nixos.org
+#+link: nixos-search https://search.nixos.org/packages
 #+link: nixpkgs https://github.com/NixOS/nixpkgs
-#+link: nix-tutorial https://github.com/shajra/example-nix/tree/master/tutorials/0-nix-intro
+#+link: nixpkgs-manual https://nixos.org/nixpkgs/manual
+#+link: nix-uninstall https://nixos.org/manual/nix/stable/installation/installing-binary.html#uninstalling
 #+link: qmk https://docs.qmk.fm
 #+link: qmk-modtap https://docs.qmk.fm/#/mod_tap
 #+link: qmk-oneshot https://docs.qmk.fm/#/one_shot_keys
 #+link: qmk-setup https://docs.qmk.fm/#/flashing?id=halfkay
+#+link: repl https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop
 #+link: signature_plastics https://pimpmykeyboard.com/key-cap-family-specs
 #+link: teensy https://www.pjrc.com/teensy/loader_cli.html
 #+link: vim https://www.vim.org

doc/internal/nix-introduction-compat.org

@@ -0,0 +1,63 @@
+#+begin_comment
+DO NOT READ. Some documentation for this project is generated from snippets of
+text like this one. Whether it gets woven into the final project is
+project-dependent.
+#+end_comment
+
+* Helping non-flakes users
+
+A few users make work in organizations or contribute to projects that disallow
+experimental features such as flakes.
+
+To buffer this compromise, this project uses and encourages the use of the
+[[nix-flake-compat][flake-compat]] project, which enables an end user who has opted not to enable
+flakes to at least access the flake's contents, packages or otherwise.
+
+With flake-compat, end users will have a normal (non-flake) Nix expression they
+can evaluate. However, since dependencies are managed with flakes, the project
+maintainer must have flakes enabled to manage dependencies (for example,
+updating to the latest dependencies with =nix flake update=).
+
+* Documenting an end user experience
+
+To deal with the transition of the Nix community to flake, this project provides
+two user guides:
+
+- [[file:nix-usage-flakes.org][Nix Usage with Flakes (Recommended) ]]
+- [[file:nix-usage-noflakes.org][Nix Usage without Flakes]]
+
+Links generally steer users to the recommended guide, which then links users to
+the non-flakes guide if they have the interest or need.
+
+The non-flakes guide intentionally avoids commands like =nix-shell= and
+=nix-channel=. These commands lead users to setting the =NIX_PATH= environment
+variable, which can lead to unreliable builds.
+
+Though this guide avoid the =flakes= experimental feature, it still invites end
+users to use the experimental =nix-command= to get the following subcommands:
+- =nix search=
+- =nix shell=
+- =nix run=
+
+In general, the non-flakes guide only explains usage of experimental =nix=
+subcommands when there exist no other alternatives, or when the alternatives are
+considered worse for new users.
+
+=nix search= simply has no good alternative within the set of non-experimental
+Nix tools, but it's too useful to not tell users about. Again, this is an
+example of the Nix community leading users to experimental features.
+
+=nix shell= and =nix run= are shown as improved alternatives to =nix-shell=.
+=nix-shell= is a complicated tool that has been historically used for a lot of
+different purposes:
+- debugging the build environments of packages
+- creating a developer environment for a package (=nix develop= does this
+  better, but for only for flakes)
+- entering a shell with Nix-build executables on the path (=nix shell= does this
+  better)
+- running arbitrary commands with Nix-build executables on the path (=nix run=
+  does this better)
+
+To cover all of these scenarios, =nix-shell= became so complex it is hard to
+explain to new users. =nix-shell= is really only best for debugging builds,
+which is beyond the scope of the documentation provided by this project.

doc/internal/nix-introduction-include.org

@@ -0,0 +1 @@
+#+include: "nix-introduction-compat.org"

doc/internal/nix-usage-flakes-include.org

@@ -0,0 +1 @@
+#+include: "nix-usage-flakes-optional.org"

doc/internal/nix-usage-flakes-optional.org

@@ -0,0 +1,16 @@
+#+begin_comment
+DO NOT READ. Some documentation for this project is generated from snippets of
+text like this one. Whether it gets woven into the final project is
+project-dependent.
+#+end_comment
+
+This project supports a still-experimental feature of Nix called /flakes/, which
+this guide shows users how to use. [[file:nix-usage-noflakes.org][Another guide]] explains how to do
+everything illustrated in this document, but without flakes.
+
+#+begin_quote
+*_NOTE:_* If you're new to flakes, please read the provided [[file:nix-introduction.org][supplemental
+introduction to Nix]] to understand the experimental nature of flakes and how it
+may or may not affect you. Hopefully you'll find these trade-offs acceptable so
+you can take advantage of the improved experience flakes offer.
+#+end_quote

doc/internal/nix-usage-flakes-required.org

@@ -0,0 +1,9 @@
+#+begin_comment
+DO NOT READ. Some documentation for this project is generated from snippets of
+text like this one. Whether it gets woven into the final project is
+project-dependent.
+#+end_comment
+
+This project requires an experimental feature of Nix called /flakes/. To
+understand more about what flakes are and the consequences of using a
+still-experimental feature of Nix, please see the provided [[file:nix-introduction.org][introduction to Nix]].

doc/internal/params.el

@@ -0,0 +1,15 @@
+((package-attr-short   . "licenses-thirdparty")
+ (package-attr-long    . "packages.x86_64-linux.licenses-thirdparty")
+ (package-name         . "shajra-keyboards-licenses")
+ (package-type         . "executable")
+ (package-target-short . "shajra-keyboards-licenses")
+ (package-target-long  . "bin/shajra-keyboards-licenses")
+ (run-attr-short       . "licenses-thirdparty")
+ (run-attr-long        . "packages.x86_64-linux.licenses-thirdparty")
+ ;; run-name must be the same as run-target-short
+ ;; run-type must be "executable"
+ (run-target-short     . "shajra-keyboards-licenses")
+ ;; run-target-long will always prefix "bin/"
+ (nix-latest           . "2.19")
+ (nixos-latest         . "23.11")
+ (platforms            . "Linux on x86-64 machines"))

doc/nix-installation.md

@@ -0,0 +1,114 @@
+- [About this document](#sec-1)
+- [Prerequisites](#sec-2)
+- [Level of commitment/risk](#sec-3)
+- [Nix package manager installation](#sec-4)
+- [Cache setup](#sec-5)
+- [Setting up experimental features](#sec-6)
+
+
+# About this document<a id="sec-1"></a>
+
+This document explains how to
+
+-   install [the Nix package manager](https://nixos.org/nix)
+-   set up Nix to download pre-built packages from a cache (optionally)
+-   set up the Nix's experimental flakes feature (optionally)
+
+If you're unsure if you want to enable flakes or not, read the provided [introduction to Nix](nix-introduction.md).
+
+# Prerequisites<a id="sec-2"></a>
+
+This project supports Linux on x86-64 machines.
+
+All we need to use this project is to install Nix, which this document covers. Nix can be installed on a variety of Linux and Mac systems. Nix can also be installed in Windows via the Windows Subsystem for Linux (WSL). Installation on WSL may involve steps not covered in this documentation, though.
+
+Note, some users may be using [NixOS](https://nixos.org), a Linux operating system built on top of Nix. Those users already have Nix and don't need to install it separately. To use this project, you don't need to use NixOS as well.
+
+# Level of commitment/risk<a id="sec-3"></a>
+
+Unless you're on NixOS, you're likely already using another package manager for your operating system already (APT, DNF, etc.). You don't have to worry about Nix or packages installed by Nix conflicting with anything already on your system. Running Nix along side other package managers is safe.
+
+All the files of a Nix package are located under `/nix` a directory, well isolated from any other package manager. Nix won't touch critical directories under `/usr` or `/var`. Nix then symlinks files under `/nix` to your home directory under dot-files like `~/.nix-profile`. There is also some light configuration under `/etc/nix`.
+
+Hopefully this alleviates any worry about installing a complex program on your machine. Uninstallation is not too much more than deleting everything under `/nix`.
+
+# Nix package manager installation<a id="sec-4"></a>
+
+> **<span class="underline">NOTE:</span>** You don't need this step if you're running NixOS, which comes with Nix baked in.
+
+If you don't already have Nix, [the official installation script](https://nixos.org/download.html#download-nix) should work on a variety of UNIX-like operating systems. If you're okay with the script calling `sudo` you can install Nix on a non-WSL machine with the following recommended command:
+
+```bash
+sh <(curl -L https://nixos.org/nix/install) --daemon
+```
+
+The `--daemon` switch installs Nix in the multi-user mode, which is generally recommended (single-user installation with `--no-daemon` instead is recommended for WSL). The script reports everything it does and touches.
+
+After installation, you may have to exit your terminal session and log back in to have environment variables configured to put Nix executables on your `PATH`.
+
+The Nix manual describes [other methods of installing Nix](https://nixos.org/manual/nix/stable/installation/installation.html) that may suit you more. If you later want to uninstall Nix, see the [uninstallation steps documented in the Nix manual](https://nixos.org/manual/nix/stable/installation/installing-binary.html#uninstalling).
+
+# Cache setup<a id="sec-5"></a>
+
+This project pushes built Nix packages to [Cachix](https://cachix.org) as part of its [continuous integration](https://github.com/shajra/nix-project/actions). It's recommended to configure Nix to use shajra.cachix.org as a Nix *substituter*. Once configured, Nix will pull down pre-built packages from Cachix, instead of building them locally (potentially saving a lot of time). This augments Nix's default substituter that pulls from cache.nixos.org.
+
+You can configure shajra.cachix.org as a supplemental substituter with the following command:
+
+```sh
+nix run \
+    --file https://cachix.org/api/v1/install \
+    cachix \
+    --command cachix use shajra
+```
+
+Cachix is a service that anyone can use. You can call this command later to add substituters for someone else using Cachix, replacing “shajra” with their cache's name.
+
+If you've just run a multi-user Nix installation and are not yet a trusted user in `/etc/nix/nix.conf`, this command may not work. But it will report back some options to proceed.
+
+One option sets you up as a trusted user, and installs Cachix configuration for Nix locally at `~/.config/nix/nix.conf`. This configuration will be available immediately, and any subsequent invocation of Nix commands will take advantage of the Cachix cache.
+
+You can alternatively configure Cachix as a substituter globally by running the above command as a root user (say with `sudo`), which sets up Cachix directly in `/etc/nix/nix.conf`. The invocation may give further instructions upon completion.
+
+# Setting up experimental features<a id="sec-6"></a>
+
+This project can take advantage of two experimental Nix features:
+
+-   `nix-command`
+-   `flakes`
+
+The provided [introduction to Nix](nix-introduction.md) covers in detail what these features are and can help you decide whether you want to enable them.
+
+As you can guess, the `flakes` feature enables flakes functionality in Nix. The `nix-command` feature enables a variety of subcommands of Nix's newer `nix` command-line tool, some of which allow us to work with flakes.
+
+If you don't enable experimental features globally, there is a switch to enable features local to just a single command-line invocation. For example, too use flakes-related commands we call `nix --extra-experimental-features 'nix-command flakes' …`. For users not enabling these features globally, this can be useful to set to a shell alias. Here's an example that works in most POSIX-compliant shells:
+
+```sh
+alias nix-flakes = nix --extra-experimental-features 'nix-command flakes'
+```
+
+As discussed in the introduction, `nix-command` is actually enabled by default. You don't need to enable it explicitly (though you could disable it).
+
+To use flakes there are two things we need to do:
+
+1.  make sure the version of Nix we're on is at least 2.4
+2.  enable both the `nix-command` and `flakes` experimental features.
+
+Since the latest release of Nix is already at 2.19, if you installed Nix recently as per the instructions above, you should be on a recent-enough version:
+
+```sh
+nix --version
+```
+
+    nix (Nix) 2.18.1
+
+The easiest way to turn on experimental features is to create a file `~/.config/nix/nix.conf` if it doesn't already exist, and in it put the following line:
+
+```text
+experimental-features = nix-command flakes
+```
+
+Then you should see that the appropriate features are enabled:
+
+```sh
+nix show-config | grep experimental-features
+```