Added a part explaining what is meant by literate, explained about the README.org en advised a workflow
This commit is contained in:
+273
-1
@@ -51,6 +51,278 @@ The system provides a predefined baseline configuration that installs and enable
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
** 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
|
||||
- Home-Manager modules
|
||||
- Generated documentation
|
||||
|
||||
There is no separation between “docs” and “code”.
|
||||
The documentation explains the intent.
|
||||
The source blocks define the system.
|
||||
Org-mode turns that narrative into both executable configuration and readable documentation.
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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 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 Two Core Commands
|
||||
|
||||
There are exactly two commands that matter.
|
||||
|
||||
**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`
|
||||
- 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
|
||||
|
||||
First the system is generated.
|
||||
Then the documentation is generated.
|
||||
Both come from the same source.
|
||||
|
||||
---
|
||||
|
||||
** Editing Generated Files
|
||||
|
||||
The directories:
|
||||
|
||||
- `./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.
|
||||
|
||||
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`
|
||||
2. Commit your experimental change
|
||||
3. Test the configuration
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
** Folder Structure Explained
|
||||
|
||||
The repository separates generated system code from non-generated supporting files.
|
||||
|
||||
****./assets**
|
||||
|
||||
Contains non-generated assisting files such as:
|
||||
|
||||
- Icons
|
||||
- Themes
|
||||
- Static configuration files
|
||||
|
||||
These files are safe to edit directly.
|
||||
|
||||
---
|
||||
|
||||
***./assets/configuration**
|
||||
|
||||
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`.
|
||||
|
||||
Contains:
|
||||
|
||||
- All NixOS modules
|
||||
- Service definitions
|
||||
- System-level configuration
|
||||
|
||||
This directory is output.
|
||||
|
||||
---
|
||||
|
||||
***./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`.
|
||||
|
||||
Contains:
|
||||
|
||||
- All Home-Manager modules
|
||||
- User-level configuration
|
||||
- Shell and desktop configuration
|
||||
|
||||
This directory is generated output.
|
||||
|
||||
---
|
||||
|
||||
***./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
|
||||
- Clear architectural reasoning
|
||||
- Controlled experimentation
|
||||
|
||||
You are not maintaining configuration files.
|
||||
|
||||
You are maintaining a structured narrative that builds an operating system.
|
||||
|
||||
** Base packages
|
||||
The baseline package set is defined explicitly within the repository to ensure reproducibility:
|
||||
|
||||
@@ -137,7 +409,7 @@ Available Flatpak identifiers can be discovered using:
|
||||
flatpak search <application-name>
|
||||
#+end_src
|
||||
|
||||
or by browsing: https://flathub.org/.
|
||||
or by browsing: https://flathub.org/.(manually)
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user