swarsel/.dotfiles
1
0
Fork 0
mirror of https://github.com/Swarsel/.dotfiles.git synced 2025-12-06 09:07:21 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: add flake structure section to introduction

Browse source
This commit is contained in:
Leon Schwarzäugl 2025-06-30 23:10:08 +02:00
parent 2aa5e0095c
commit 157bd5d45a
Signed by: swarsel
GPG key ID: 26A54C31F2A4FD84
2 changed files with 784 additions and 514 deletions
Download patch file Download diff file Expand all files Collapse all files

177
SwarselSystems.org
View file

@ -26,14 +26,13 @@ This configuration is part of a NixOS system that is (nearly) fully declarative
This literate configuration lets me explain my choices to my future self as well as you, the reader. I go to great lengths to explain the choices for all configuration steps that I take in order for me to pay due diligence in crafting my setup, and not simply copying big chunks of other peoples code. Also, the literate configuration approach is very convenient to me as I only need to keep of (ideally) a single file to manage all of my configuration. I hope that this documentation will make it easier for beginners to get into Emacs and NixOS as I know it can be a struggle in the beginning.
** Structure of this file
This file is structured as follows:
- [[#h:a86fe971-f169-4052-aacf-15e0f267c6cd][Introduction (no code)]]
This is the block you are currently in. It holds no code that actually builds the system, it just outlines the general approach and explains my rough mentality
- [[#h:d39b8dfb-536d-414f-9fc0-7d67df48cee4][Noweb-Ref blocks]]
This section hold code that can be templated at other parts of the configuration. This is mostly used for the NixOS side of the configuration where I define my host systems that usually have a lot in common.
- [[#h:c7588c0d-2528-485d-b2df-04d6336428d7][flake.nix]]
This block holds everything related to the heart of the nix side of the configuration - the =flake.nix= file.
@ -103,7 +102,108 @@ window.addEventListener('load', addDarkmodeWidget);
</script>
#+end_export
The rest of this file will now contain actual code that is used in the configuration.
This section hold code that can be templated at other parts of the configuration. This is mostly used for the NixOS side of the configuration where I define my host systems that usually have a lot in common.
- [[#h:8fc9f66a-7412-4091-8dee-a06f897baf67][Appendix A: Supplementary Files]]
This section holds files that are not written in nix but are still referenced in the configuration in some way. This is mostly used for configuration of programs that have no native nix support, like tridactyl. Note that shell scripts are still defined under their respective entry in [[#h:64a5cc16-6b16-4802-b421-c67ccef853e1][Packages]].
- Historical Note: Noweb-Ref blocks
These blocks were used in several places throughout the configurations, but not on all machines necessarily. For example, the theming section used need to be in a NixOS block on NixOS machines but in a home-manager block on non-NixOS.
Originally, I used this method a lot throughout my configuration. However, as my knowledge of NixOS grew, I have been weeding these snippets out more and more as I find more efficient native solutions. Now, only the theming block remains. For example, the above problem can be solved by defining a =theme= attribute set and using =lib.recursiveUpdate= as shown in [[#h:79f7150f-b162-4f57-abdf-07f40dffd932][Shared Configuration Options (holds firefox & stylix config parts)]] and [[#h:a92318cd-413e-4e78-a478-e63b09df019c][Theme (stylix)]].
As such, this served to reduce code duplication in this file. The tangled files experienced no size reduction, since noweb-ref only substitutes these blocks in.
For archival reasons, here is shown how to use a noweb-ref block, in case I ever decide to use it again, or it is interesting to you:
#+begin_src nix :tangle no :noweb-ref blockName
enable = true;
#+end_src
which can then be used in a block like:
#+begin_src nix :tangle :noweb yes
<<blockName>>
#+end_src
not that noweb-reffed blocks will not be indented correctly. You will want to account for that when checking your nix flake with the formatter of your choice. Personally, I have solved this issue using the functions defined in [[#h:59d4306e-9b73-4b2c-b039-6a6518c357fc][org-mode: Upon-save actions (Auto-tangle, export to html, formatting)]]. Originally, I also automatically exported to html there, but it incurred a too high memory penalty which made Emacs become sluggish over time.
** TODO Structure of this flake
The structure of this flake as seen many revisions, however lately I have settled on a system that I have grown to like:
- =hosts=: This folder is used to house all configurations that are used across the infrastructure. At the top level, it splits into the subfolders =nixos=, =home=, =darwin=, and =android=. These folders specify the mode that the configuration is running in:
- nixos: Full NixOS host (may or may not also use home-manager)
- darwin: Host that uses NixOS on MacOS (may or may not use home-manager)
- home: Host that uses only home-manager (no full NixOS)
- android: Phone using nix-on-droid (may or may not use home-manager)
The corresponding configurations are automatically generated by =mkFullHostConfigs= and =mkHalfHostConfigs=. A "full" host either in the nixos or darwin folder, while a "half" host is in either of home or android. This has to do with the scheme in which these configurations are generated.
These <hosttype> folders hold in turn a number of <hostname> folders, the actual configurations. At this time, the files stored in this folder are:
- default.nix:
This file holds the abstracted configuration of the host. This should mostly be enabling [[#h:f0f1c961-3e7a-47b8-99ab-1654bb45dffc][Profiles]] as well as setting some [[#h:f4f22166-e345-43e6-b15f-b7f5bb886554][Shared Configuration Options]].
- hardware-config.nix:
It is not clearly defined what I hold in this file. Mostly it is just the attributes that nix originally sets when setting up the system for the first time (although at this time modified by me!), bar any filesystem configuration. This makes my deployment in [[#h:74db57ae-0bb9-4257-84be-eddbc85130dd][swarsel-bootstrap]] a little bit simpler.
- disk-config.nix
Holds the aforementioned filesystem configuration and is applied using [[https://github.com/nix-community/disko][disko]].
- The hosts/<hosttype>/<hostname> folders may also have a =secrets= folder, under which a single file =pii.nix.enc= can be stored. As the name suggests, this file should be encrypted. Specifically, it needs to be a [[https://github.com/getsops/sops][sops]]-encrypted file (sops does not seem to suggest a file ending other than .yml or others, which is not verbose enough for me, so I went with =.enc=). This file should have the structure of a nix expression, e.g.:
#+begin_src nix :tangle no
{
my_value = 2;
my_attrSet = {
enable = true;
};
}
#+end_src
Using the mechanisms in [[#h:82b8ede2-02d8-4c43-8952-7200ebd4dc23][PII management]] (which in turn uses [[#h:87c7893e-e946-4fc0-8973-1ca27d15cf0e][extra-builtins]] and [[#h:315e6ef6-27d5-4cd8-85ff-053eabe60ddb][sops-decrypt-and-cache]]), these files are decrypted during evaluation time and stored under a persistent directory. As the name suggests, I am using these files to store personally identifiable information - these "secrets" are stored world-readable in the nix store. As such, this should not be used to store important secrets, but rather information that you would not like everyone on the internet to easily find in your git repo.
- =modules=
This folder holds the most part of the actual system configuration done in this repository. At some point I thought it was cool to have my whole configuration exposed under the flakes =nixosModules=, which is indeed achieved (its usefulness is however debatable). In any way, this folder splits up as:
- nixos: Holds true NixOS configuration
- home: Holds configuration to be used by home-manager (either as a NixOS submodule or not)
- darwin: Holds configuration for nix-darwin. This folder further splits up into a nixos and a home folder, which hold respective nix or home-manager configuration for nix-darwin.
- iso: Holds specific configuration for my installer ISO that I do not want to have loaded in the rest of the configuration.
The nixos and home folders further split up:
- common: Configuration that can be used by all hosts (TODO: this currently includes configuration used by my user devices, which will mostly not be used by servers)
- server: Configuration to be used on servers
- optional: Configuration that will be used rather rarely
This structure is very optionated and highly subjective. I will possibly change this in the future.
By themselves, most of the files in the modules folder will not do anything. In order for them to do something, their corresponding =config.swarselsystems.modules= attribute needs to be enabled. This is done using...
- =profiles=: This folder splits up into =home= and =nixos= subfolders, where groupings of module enablers are stored for the respective home and nix setups. Note that =home= profiles are also used in NixOS setups (extensively even)!
- =nix=: This special folder holds mostly =.nix= files that are not automatically loaded, but rather setup specific things that affect most of the flake. For example, here lies the aforementioned [[#h:87c7893e-e946-4fc0-8973-1ca27d15cf0e][extra-builtins]] as well as the setup for the [[*Globals][Globals]] system. TODO: Move flake-parts units there and explain them here.
- =lib=: This folder holds utility functions that I add to the nixpkgs library under the =swarselsystems= attribute set. An example would be the =mkIfElse= function.
- =pkgs=: This folder holds derivations (mostly packages) that I define myself. This is mostly used to grab versions that are not (yet) in nixpkgs, or modified versions of another package. Each derivation in this folder is in turn in its own folder which holds a defautlt.nix. Using the mechanism in [[#h:64a5cc16-6b16-4802-b421-c67ccef853e1][Packages]], these are automatically built and available to all configurations (packages still need to be installed e.g. in =environment.systemPackages=)
- =checks=: Holds a file that defines my pre-commit-hook checks. TODO: move this to /nix probably
- =scripts=: This folder holds a bunch of shell scripts that I use for various tasks. Nearly all of these are made into a derivation using =pkgs.writeShellApplication=. In the future (TODO?), I might convert these to native nix, but in the past I kept the as true shellfiles in case I ever wanted to move away from nix. This is becoming less and less likely, however. And even in case that this would happen, I could retrieve these files from the nix store and would simply have to remove the nix store paths.
- =secrets=: Unlike the similar folder under =hosts=, this folder holds actual sops-encrypted secrets that are created at activation time and not in the nix store. The folder splits up into a bunch of <hostname> folders, as well as a =repo= folder, which holds another =pii.nix.enc=, which holds global PII's, and a =certs= folder that holds some longer certificate style secrets.
- =overlays=: This holds a single =default.nix= that defines the overlay I am using in my configuration. It is responsible for adding my defined packages and modifications to the final nixpkgs. Also I add some other conveniences like all past stable nixpkgs and some other package sets.
- =programs=: This folder holds configurations for various programs (most notably emacs' =init.el= and =early-init.el=), that are being rendered using org-babel and loaded using nix.
- =wallpaper=: Holds wallpapers and profile pictures.
- =topology=: Holds the configuration used by [[https://github.com/oddlama/nix-topology][nix-topology]].
* flake.nix
:PROPERTIES:
@ -11994,7 +12094,7 @@ This section sets up all the imports that are used in the home-manager section.
}
#+end_src
**** Shared Configuration Options (hold firefox config parts)
**** Shared Configuration Options (holds firefox & stylix config parts)
:PROPERTIES:
:CUSTOM_ID: h:79f7150f-b162-4f57-abdf-07f40dffd932
:END:
@ -12004,6 +12104,12 @@ Provides settings related to nix-darwin systems. At the moment, I am only making
At work I am using several services that are using SSO login - however, as I am using four different accounts at work, this becomes a chore here. Hence, I have defined multiple profiles in [[#h:f0b2ea93-94c8-48d8-8d47-6fe58f58e0e6][Work]] that are all practically using the same configuration. To save screen space, I template that profile here.
Set in firefox =about:config > toolkit.legacyUserProfileCustomizations.stylesheets= to true. This should in principle be set automatically using the below config, but it seems not to be working reliably
For styling, I am using the [[https://github.com/danth/stylix][stylix]] NixOS module, loaded by flake. This package is really great, as it adds nix expressions for basically everything. Ever since switching to this, I did not have to play around with theming anywhere else.
The full list of nerd-fonts can be found here: https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/data/fonts/nerd-fonts/manifests/fonts.json
This is where the theme for the whole OS is defined. Originally, this noweb-ref section could not be copied to the general NixOS config since they are on different folder structure levels in the config, which would have made the flake impure. By now, I have found out that using the =${self}= method for referencing the flake root, I could circumvent this problem. Also, the noweb-ref block could in general be replaced by a custom attribute set (see for example [[#h:e7f98ad8-74a6-4860-a368-cce154285ff0][firefox]]). The difference here was, for a long time, that this block is used in a NixOS and a home-manager-only configuration, verbatim. If I were to use an attribute set, I would have to duplicate this block once each for NixOS and home-manager. Alas, this block stays (for now). However, I learned how to use an attribute set in a custom home-manager module and pass it to both NixOS and home-manager configurations, which also removed the need for that use of it.
#+begin_src nix :noweb yes :tangle modules/home/common/sharedsetup.nix
{ self, lib, pkgs, ... }:
{
@ -18862,67 +18968,6 @@ This sets up the =dashboard=, which is really quite useless. But, it looks cool
(add-hook 'comint-output-filter-functions 'comint-truncate-buffer)
#+end_src
* Appendix A: Noweb-Ref blocks
:PROPERTIES:
:CUSTOM_ID: h:d39b8dfb-536d-414f-9fc0-7d67df48cee4
:END:
These blocks are used in several places throughout the configurations, but not on all machines necessarily. For example, the theming section needs to be in a NixOS block on NixOS machines but in a home-manager block on non-NixOS.
Originally, I used this method a lot throughout my configuration. However, as my knowledge of NixOS grew, I have been weeding these snippets out more and more as I find more efficient native solutions. Now, only the theming block remains.
This serves only to reduce code duplication in this file. The tangled files experience no size reduction, since noweb-ref only substitutes these blocks in.
For styling, I am using the [[https://github.com/danth/stylix][stylix]] NixOS module, loaded by flake. This package is really great, as it adds nix expressions for basically everything. Ever since switching to this, I did not have to play around with theming anywhere else.
The full list of nerd-fonts can be found here: https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/data/fonts/nerd-fonts/manifests/fonts.json
This is where the theme for the whole OS is defined. Originally, this noweb-ref section could not be copied to the general NixOS config since they are on different folder structure levels in the config, which would have made the flake impure. By now, I have found out that using the =${self}= method for referencing the flake root, I could circumvent this problem. Also, the noweb-ref block could in general be replaced by a custom attribute set (see for example [[#h:e7f98ad8-74a6-4860-a368-cce154285ff0][firefox]]). The difference here was, for a long time, that this block is used in a NixOS and a home-manager-only configuration, verbatim. If I were to use an attribute set, I would have to duplicate this block once each for NixOS and home-manager. Alas, this block stays (for now). However, I learned how to use an attribute set in a custom home-manager module and pass it to both NixOS and home-manager configurations, which also removed the need for that use of it.
#+begin_src nix :tangle no :noweb-ref theme
enable = true;
base16Scheme = "${self}/programs/stylix/swarsel.yaml";
polarity = "dark";
opacity.popups = 0.5;
cursor = {
package = pkgs.banana-cursor;
# package = pkgs.capitaine-cursors;
name = "Banana";
# name = "capitaine-cursors";
size = 16;
};
fonts = {
sizes = {
terminal = 10;
applications = 11;
};
serif = {
# package = (pkgs.nerdfonts.override { fonts = [ "FiraMono" "FiraCode"]; });
package = pkgs.cantarell-fonts;
# package = pkgs.montserrat;
name = "Cantarell";
# name = "FiraCode Nerd Font Propo";
# name = "Montserrat";
};
sansSerif = {
# package = (pkgs.nerdfonts.override { fonts = [ "FiraMono" "FiraCode"]; });
package = pkgs.cantarell-fonts;
# package = pkgs.montserrat;
name = "Cantarell";
# name = "FiraCode Nerd Font Propo";
# name = "Montserrat";
};
monospace = {
package = pkgs.nerd-fonts.fira-mono; # has overrides
name = "FiraCode Nerd Font Mono";
};
emoji = {
package = pkgs.noto-fonts-emoji;
name = "Noto Color Emoji";
};
};
#+end_src
* Appendix B: Supplementary Files
:PROPERTIES:
:CUSTOM_ID: h:8fc9f66a-7412-4091-8dee-a06f897baf67