henrov/nixos
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Been working on chapters 1-4

Browse Source
This commit is contained in:
Henro Veijer
2026-02-23 21:58:22 +01:00
parent f19a3c0e05
commit 2378cea1e7
3 changed files with 420 additions and 649 deletions
Download Patch File Download Diff File Expand all files Collapse all files
henrovnix/README.org
+47 -139
View File
@@ -28,10 +28,7 @@ gf#+OPTIONS: toc:nil broken-links:t
* Introduction
#+HTML: <div align="center"><img src="./.github/images/need to create screenshot.png" width="100%" alt="Screenshot" /></div>
#+HTML_HEAD: <style>code{font-size:1.2em;}</style>
This repository contains a literate NixOS configuration built using Emacs Org mode. The primary source of truth is *this document itself*, which embeds configuration blocks that are tangled into individual files. These generated files are evaluated as a NixOS flake, resulting in an immutable, reproducible system configuration.
This work is based on the foundational efforts of Sandeep Nambiar (https://github.com/gamedolphin).
@@ -44,28 +41,31 @@ Customization is designed to occur primarily through modular .conf files, allowi
Before proceeding with installation, it is strongly recommended to read this documentation carefully. Understanding the structure and design philosophy will help ensure a smooth setup and provide the necessary context for extending the system effectively.
** What do you get?
This repository delivers a reproducible foundation built on NixOS, Home-Manager, and Flakes. It assumes a clean NixOS installation as a starting point, preferably minimal or headless, onto which the configuration is applied.
The system provides a predefined baseline configuration that installs and enables the essential components required for a functional and extensible environment. Rather than prescribing a complete desktop experience, it establishes the structural framework upon which such an environment can be composed.
Core packages are installed as part of the base configuration. Additional software can be incorporated in a controlled and modular manner by extending configuration files.
* what you don't get
** What you do not get
This repository does not provide a fully polished, bug-free desktop system with every default preconfigured and validated across all hardware combinations. It is a structured foundation, not a turnkey end-user distribution.
This is by no means a complete or bug-free environment. Certain components — such as the XDG portals — may still behave unpredictably or require additional tweaking. The goal is to provide a solid starting point for those who want to learn how to build an iterative system from a minimal foundation. Consider it a base to extend, refine, and improve over time. This project is very much a work in progress.
You should not expect graphical configuration tools, wizard-driven setup screens, or extensive GUI-based system management. Configuration is performed declaratively through Nix modules and supporting configuration files. Familiarity with reading logs, adjusting modules, and rebuilding the system is assumed.
** What Is a Literate System in the Context of NixOS?
Certain subsystems may require manual tuning depending on hardware, desktop environment, or portal backend selection. For example, XDG desktop portals can exhibit inconsistent behavior across compositors and applications, particularly in Wayland-based environments. File chooser dialogs, screen sharing, or drag-and-drop functionality may require additional configuration or troubleshooting.
This project favors clarity, reproducibility, and modular structure over convenience abstractions. As a result, some integration details are intentionally left explicit rather than hidden behind automated defaults.
In short, this repository provides a coherent and extensible base, not a finished consumer product. It is a work in progress.
* What Is a Literate System in the Context of NixOS?
A literate system combines documentation and implementation into a single, coherent source.
In this repository, that source is:
#+begin_src bash :tangle no block
README.org
#+end_src
Everything originates from this file:
- Architectural explanations
- Design decisions
- NixOS modules
@@ -80,92 +80,65 @@ Org-mode turns that narrative into both executable configuration and readable do
The README is not describing the system.
The README *is* the system.
---
** Two Types of Code Blocks
This literate system uses two different kinds of source blocks.
**1. Documentation Blocks**
These blocks exist purely for documentation purposes.
They generate visible code blocks in the exported documentation, but they do not create files.
Example:
#+begin_src bash :tangle no
<tekst>
#+end_src
#+begin_example
#+begin_src bash :tangle no
<tekst>
#+end_src
#+end_example
These are used to show commands, examples, or explanatory snippets in the generated documentation.
They are never tangled into the filesystem.
---
**2. File-Generating Blocks**
These blocks generate real `.nix` files and insert the same code into the documentation.
Example structure:
** =install_packages.nix=
<tekst>
#+begin_src nix :tangle configuration/apps/install_packages.nix :noweb tangle :mkdirp yes
<tekst>
#+end_src
These blocks generate real =.nix= files and insert the same code into the documentation.
Example:
#+begin_example
** install_packages.nix
<tekst>
#+begin_src nix :tangle configuration/apps/install_packages.nix :noweb tangle :mkdirp yes
<nixos code>
#+end_src
#+end_example
Explanation:
- The headline `=install_packages.nix=` becomes a documentation chapter.
- The paragraph `<tekst>` explains what the module does.
- The source block generates the file:
configuration/apps/install_packages.nix
- The headline =install_packages.nix= becomes a documentation chapter.
- The paragraph =<tekst>= explains what the module does.
- =<nixos code>= is exactly what will be written into the .nix module =configuration/apps/install_packages.nix=
- The same source block is rendered as a code block in the documentation.
This means:
- The explanation and the implementation live side-by-side.
- The documentation cannot drift away from the code.
- The generated `.nix` file is always derived from the canonical explanation.
---
- The generated .nix file is always derived from the canonical explanation.
** The Two Core Commands
There are exactly two commands that matter.
**1. Generate all `.nix` files**
**1. Generate all .nix files**
#+begin_src bash :tangle no block
emacs README.org --batch -f org-babel-tangle
#+end_src
This command:
- Regenerates `./configuration`
- Regenerates `./home`
- Regenerates ./configuration
- Regenerates ./home
- Overwrites previously generated modules
- Ensures the system matches the README
---
**2. Generate documentation**
#+begin_src bash :tangle no block
emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
#+end_src
This command exports the same README into HTML documentation.
---
In practice you usually combine them:
#+begin_src bash :tangle no block
emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
#+end_src
@@ -174,145 +147,94 @@ First the system is generated.
Then the documentation is generated.
Both come from the same source.
---
** Editing Generated Files
The directories:
- `./configuration`
- `./home`
- ./configuration
- ./home
are fully generated by:
#+begin_src bash :tangle no block
emacs README.org --batch -f org-babel-tangle
#+end_src
Editing these files directly is allowed only temporarily, for experimentation or testing.
Structural or permanent changes must always be implemented in the corresponding section inside `README.org`.
If you change a file in `./configuration` or `./home` without updating the README, your changes will disappear on the next tangle.
Structural or permanent changes must always be implemented in the corresponding section inside README.org.
If you change a file in ./configuration or ./home without updating the README, your changes will disappear on the next tangle.
Generated directories are output, not source.
---
** Recommended Workflow
This workflow allows safe experimentation while preserving literate structure.
1. Change any existing file in `./assets`, `./home` or `./configuration`
1. Change any existing file in ./assets, ./home or ./configuration
2. Commit your experimental change
3. Test the configuration
4. If satisfied, migrate the change into `README.org`
4. If satisfied, migrate the change into README.org
5. Regenerate system and documentation
6. Commit again
7. Test again
Commands:
#+begin_src bash :tangle no block
git add .
git commit -m "experiment: local change"
sudo nixos-rebuild test --flake .#your_hostname
#+end_src
After confirming the change:
#+begin_src bash :tangle no block
emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
git add .
git commit -m "literate: structural update"
sudo nixos-rebuild test --flake .#your_hostname
#+end_src
If you are confident about your changes, you may skip steps 1–3 and edit `README.org` directly.
---
If you are confident about your changes, you may skip steps 1–3 and edit README.org directly.
** Folder Structure Explained
The repository separates generated system code from non-generated supporting files.
****./assets**
*** ./assets
Contains non-generated assisting files such as:
- Icons
- Themes
- Static configuration files
These files are safe to edit directly.
---
***./assets/configuration**
*** ./assets/conf
Contains non-generated assisting configuration files that influence several aspects of builds.
Users are expected to modify these when needed.
---
***./configuration**
Fully (re)generated by `README.org`.
*** ./configuration
Fully (re)generated by README.org.
Contains:
- All NixOS modules
- Service definitions
- System-level configuration
This directory is output.
---
***./hardware**
Contains non-generated `hardware.nix` files detailing hardware-specific details.
*** ./hardware
Contains non-generated hardware.nix files detailing hardware-specific details.
This directory will likely be deprecated in the future.
---
***./home**
Fully (re)generated by `README.org`.
*** ./home
Fully (re)generated by README.org.
Contains:
- All Home-Manager modules
- User-level configuration
- Shell and desktop configuration
This directory is generated output.
---
***./machines**
*** ./machines
Contains one folder per machine you want to configure.
Each machine folder contains non-generated files detailing specifics for that machine:
- Host-specific overrides
- Hardware references
- Host definitions
These determine how shared modules apply to each system.
---
** Final Principle
A literate NixOS system guarantees:
- Single source of truth
- No divergence between documentation and configuration
- Reproducible system builds
@@ -320,7 +242,6 @@ A literate NixOS system guarantees:
- Controlled experimentation
You are not maintaining configuration files.
You are maintaining a structured narrative that builds an operating system.
** Base packages
@@ -409,25 +330,12 @@ Available Flatpak identifiers can be discovered using:
flatpak search <application-name>
#+end_src
or by browsing: https://flathub.org/.(manually)
or by browsing: https://flathub.org/.
The behavior and integration of Flatpak installation within the system are defined in =install_flatpaks.nix=, which reads the corresponding configuration files and ensures declarative installation.
This separation maintains clarity between system-level packages and user-facing Flatpak applications while preserving reproducibility and modular structure.
** What you do not get
This repository does not provide a fully polished, bug-free desktop system with every default preconfigured and validated across all hardware combinations. It is a structured foundation, not a turnkey end-user distribution.
You should not expect graphical configuration tools, wizard-driven setup screens, or extensive GUI-based system management. Configuration is performed declaratively through Nix modules and supporting configuration files. Familiarity with reading logs, adjusting modules, and rebuilding the system is assumed.
Certain subsystems may require manual tuning depending on hardware, desktop environment, or portal backend selection. For example, XDG desktop portals can exhibit inconsistent behavior across compositors and applications, particularly in Wayland-based environments. File chooser dialogs, screen sharing, or drag-and-drop functionality may require additional configuration or troubleshooting.
This project favors clarity, reproducibility, and modular structure over convenience abstractions. As a result, some integration details are intentionally left explicit rather than hidden behind automated defaults.
In short, this repository provides a coherent and extensible base, not a finished consumer product. It is a work in progress.
* Setting up your system manually
** Pre-requisites to build this setup
#+begin_src bash :tangle no block