From f387a80bdc9ce0572d441f1cedb471c9f71a9885 Mon Sep 17 00:00:00 2001 From: Youwen Wu Date: Sun, 11 Aug 2024 15:05:42 -0700 Subject: [PATCH] docs(readme): formatting and some more content --- .prettierrc.toml | 2 ++ README.md | 84 +++++++++++++++++++++++++++++++++++------------- 2 files changed, 64 insertions(+), 22 deletions(-) create mode 100644 .prettierrc.toml diff --git a/.prettierrc.toml b/.prettierrc.toml new file mode 100644 index 0000000..e975861 --- /dev/null +++ b/.prettierrc.toml @@ -0,0 +1,2 @@ +lineWidth = 72 +proseWrap = "always" diff --git a/README.md b/README.md index 152765d..161fcd9 100755 --- a/README.md +++ b/README.md @@ -1,60 +1,100 @@ # liminalOS -This is a repository that implements liminalOS, my personal Linux distribution based on [NixOS](https://nixos.org/). +This is a repository that implements liminalOS, my personal Linux distribution +based on [NixOS](https://nixos.org/). -Traditionally, we expect to configure each of our computers separately. We have a general idea of the programs, settings, and minor tweaks that we like -to make on every computer, but we have to manually set all of these up. Many Unix hackers have therefore created sprawling installation scripts to manage -their various systems so they can be deployed in a predictable manner each time. Of course, scripts are still heavily dependent on environment and prone to breakage. -When they inevitably break, the system is left in a malformed state, where some setup actions have been taken and others have not, and it is up to the system -administrator to fix the failing script and ensure the system is set up properly. +Traditionally, we expect to configure each of our computers separately. We have +a general idea of the programs, settings, and minor tweaks that we like to make +on every computer, but we have to manually set all of these up. Many Unix +hackers have therefore created sprawling installation scripts to manage their +various systems so they can be deployed in a predictable manner each time. Of +course, scripts are still heavily dependent on environment and prone to +breakage. When they inevitably break, the system is left in a malformed state, +where some setup actions have been taken and others have not, and it is up to +the system administrator to fix the failing script and ensure the system is set +up properly. -In essence, the primary failure of setup scripts is that they are _imperative_ - they must specify precisely _how_ to set up the system, down to minute details, whereas in a _declarative_ approach, the user can simply specify what the system _should look like_, and abstractions take care of the _how_. +In essence, the primary failure of setup scripts is that they are _imperative_ - +they must specify precisely _how_ to set up the system, down to minute details, +whereas in a _declarative_ approach, the user can simply specify what the system +_should look like_, and abstractions take care of the _how_. -NixOS provides the key tools for reliably deploying systems - namely, a _purely functional_ package manager that's reproducible by default and -the necessary abstractions needed for a declarative system configuration. liminalOS is my set of opinionated NixOS and `home-manager` modules that aim to -set up a computing environment _independent of the host_. This makes it possible for me to share common configuration between a multitude of entirely distinct machines, -including an `x86_64` desktop, an `x86_64` laptop, an Apple Silicon Macbook running NixOS `aarch64` using [Asahi Linux](https://asahilinux.org/), and the same Macbook running macOS with `nix-darwin`, sharing `home-manager` configuration with NixOS. Specific configuration necessary to adjust hardware-specific details -between each machines are isolated to the [hosts](./hosts) directory. +NixOS provides the key tools for reliably deploying systems - namely, a _purely +functional_ package manager that's reproducible by default and the necessary +abstractions needed for a declarative system configuration. liminalOS is my set +of opinionated NixOS and `home-manager` modules that aim to set up a computing +environment _independent of the host_. This makes it possible for me to share +common configuration between a multitude of entirely distinct machines, +including an `x86_64` desktop, an `x86_64` laptop, an Apple Silicon Macbook +running NixOS `aarch64` using [Asahi Linux](https://asahilinux.org/), and the +same Macbook running macOS with `nix-darwin`, sharing `home-manager` +configuration with NixOS. Specific configuration necessary to adjust +hardware-specific details between each machines are isolated to the +[hosts](./hosts) directory. > **lim·i·nal** > > 1. between or belonging to two different places, states, etc. -The goal of liminalOS is to allow my computing environment to exist in different places at the same time, without the twiddling and settings syncing -and minor disparities that arise from traditional approaches. This works exceptionally well, demonstrated by the fact that I have the exact same environment across +The goal of liminalOS is to allow my computing environment to exist in different +places at the same time, without the twiddling and settings syncing and minor +disparities that arise from traditional approaches. This works exceptionally +well, demonstrated by the fact that I have the exact same environment across three separate machines, spanning two completely different CPU architectures. ## Installation guide -TBD. May use `deploy-rs` or the in-house [dartgun](https://github.com/youwen5/dartgun) tool for easy deployment. +TBD. May use `deploy-rs` or the in-house +[dartgun](https://github.com/youwen5/dartgun) tool for easy deployment. ## FAQ ### This looks like a collection of NixOS configuration files and modules. What makes it a distinct distribution? -Most Linux[^1] users will agree that any self-respecting distribution must include at least the following: installer, package manager, and some set of default packages. Therefore, anything that implements the aforementioned items must also be a Linux distribution. +Most Linux[^1] users will agree that any self-respecting distribution must +include at least the following: installer, package manager, and some set of +default packages. Therefore, anything that implements the aforementioned items +must also be a Linux distribution. -liminalOS comes with the Nix package manager (nobody said you need a _unique_ package manager - Ubuntu and Debian are distinct distributions yet both use `apt`), a custom desktop environment composed of Waybar, Hyprland, rofi, as well as various applications installed by default, and [the means to generate an installer](https://nixos.wiki/wiki/Creating_a_NixOS_live_CD). Therefore, liminalOS is a Linux distribution. QED.[^2] +liminalOS comes with the Nix package manager (nobody said you need a _unique_ +package manager - Ubuntu and Debian are distinct distributions yet both use +`apt`), a custom desktop environment comprised of Waybar, Hyprland, rofi, as +well as various applications installed by default, and +[the means to generate an installer](https://nixos.wiki/wiki/Creating_a_NixOS_live_CD). +Therefore, liminalOS is a Linux distribution. QED.[^2] ### Should I actually install this? -No. You should instead use the modules as configuration examples if you need them as they are heavily customized for my needs, which are not the same as yours. +No. You should instead use the modules as configuration examples if you need +them as they are heavily customized for my needs, which are not the same as +yours. ## Hosts -The modules in liminalOS are designed to be utilized by a wide variety of machine configurations, including via nix-darwin on macOS. To that end, modules are organized by operating system (darwin vs. linux), architecture (x86_64 vs. aarch-64), and form factor (desktop vs laptop). Anything that is agnostic of these distinctions is considered a "common module" and allows configuration to be shared between the various host types. This generally includes core programs like CLI tools, the window manager, etc. +The modules in liminalOS are designed to be utilized by a wide variety of +machine configurations, including via nix-darwin on macOS. To that end, modules +are organized by operating system (darwin vs. linux), architecture (x86_64 vs. +aarch-64), and form factor (desktop vs laptop). Anything that is agnostic of +these distinctions is considered a "common module" and allows configuration to +be shared between the various host types. This generally includes core programs +like CLI tools, the window manager, etc. -The [flake.nix](/flake.nix) currently contains configuration for three hosts: +The [flake.nix](/flake.nix) currently contains my configuration for four hosts: | Hostname | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "callisto" | a Macbook Pro M1 (2021) running under Asahi Linux. Imports the laptop module sets as well as the core NixOS module sets. | | "demeter" | a custom desktop with an i7-13700KF and RTX 4080. Imports the desktop module, the core NixOS modules, and additionally the gaming module. | | "phobos" | Macbook Pro M1 (2021) running macOS with nix-darwin. Imports the core home-manager module as well as some darwin-specific modules for window managers and the like. | +| "adrastea" | Razer Blade 14 (2021) with RTX 3070. Imports the laptop module, the core NixOS modules, and the gaming module. | -[^1]: also known as GNU/Linux, GNU+Linux, Freedesktop/systemd/musl/busybox Linux, Linux+friends, etc +[^1]: + also known as GNU/Linux, GNU+Linux, Freedesktop/systemd/musl/busybox Linux, + Linux+friends, etc -[^2]: although this is not actually how the converse works, the rigor-hungry mathematicians reading can cry about it. +[^2]: + although this is not actually how the converse works, the rigor-hungry + mathematicians reading can cry about it. ## Keybinds