extern/nixos-and-flakes-book
1
0
Fork 0
mirror of https://github.com/ryan4yin/nixos-and-flakes-book.git synced 2024-12-30 18:48:50 +01:00
Code Issues Packages Projects Releases Wiki Activity

feat: update preface

Browse Source
This commit is contained in:
Ryan Yin 2023-07-30 22:24:06 +08:00
parent 8672ce6981
commit a1cfd3b8f7
2 changed files with 44 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/preface.md
View File

@ -1,45 +1,49 @@
# About This Book # Preface
## The Pain of NixOS Beginners - Documentation and Flakes ## The Pain of NixOS Beginners - Documentation and Flakes
NixOS is a highly distinctive Linux distribution built on top of the Nix package manager, with a design philosophy vastly different from traditional distributions like Ubuntu, CentOS, ArchLinux, etc. NixOS is a highly distinctive Linux distribution built upon the Nix package manager, with a design philosophy that sets it apart from traditional distributions like Ubuntu, CentOS, Arch Linux and others.
The biggest advantage of NixOS compared to other distributions lies in its reproducibility, which means it can consistently reproduce the same system environment across multiple machines, and its declarative configuration. One of NixOS's major advantages over other distributions lies in its reproducibility, allowing users to replicate consistent system environments across multiple machines, thanks to its declarative configuration.
NixOS is powerful, but its power also brings an increase in system complexity, making it more challenging for newcomers. Many experiences gained from using other Linux distributions are difficult to apply on NixOS. Furthermore, NixOS has long been criticized for its scattered and outdated official and community documentation, which has discouraged beginners. While NixOS is powerful, its strength also comes with increased system complexity, making it more challenging for newcomers. On the one hand, the knowledge accumulated on other Linux distributions is not easily transferable to NixOS. On the other hand, NixOS has long been criticized for its scattered and outdated official and community documentation, often deterring newcomers. These issues have troubled many NixOS beginners.
Speaking of Nix package manager's experimental feature called Flakes, it takes inspiration from the design philosophies of npm, cargo and other package managers. Flakes utilize `flake.nix` to record all external dependencies and `flake.lock` to pin the versions of those dependencies, greatly enhancing the reproducibility and composability of the Nix package manager and NixOS configurations. Due to its numerous benefits, Flakes have been widely adopted in the community, and according to official surveys, over half of the new Nix repositories on GitHub now use Flakes. Speaking of the experimental feature of the Nix package manager called Flakes. Inspired by package managers like npm and cargo, Flakes use `flake.nix` to record all external dependencies and `flake.lock` to lock their versions. This significantly enhances the reproducibility and composability of the Nix package manager and NixOS configurations. Flakes' advantages have made it widely popular within the community. According to official surveys, over half of the new Nix repositories created on GitHub now utilize Flakes, making the traditional Nix configuration method less prevalent.
However, on the other hand, Flakes being an experimental feature introduces uncertainties, and to maintain stability, the official documentation barely covers any content related to Flakes. This has left many Nix/NixOS users confused. They see everyone using Flakes and want to learn it, but they have no proper starting point, leading them to gather scattered information, dig into Nixpkgs source code, and seek guidance from experienced individuals. However, on the flip side, Flakes, being an experimental feature, comes with uncertainties. To maintain stability, the official documentation barely covers any Flakes-related content. This has left many Nix/NixOS users feeling confused. They see everyone using Flakes and want to learn it too, but find nowhere to start, often having to piece together scattered information, search through Nixpkgs source code, or seek help from more experienced users.
## The Origin of This Book ## The Origin of This Book
When I dived into NixOS in April this year (2023), I fell in love with its design philosophy. Later, a friend recommended I explore the experimental feature Flakes. After comparing Flakes with the traditional NixOS configuration approach, I realized that only NixOS with Flakes fulfilled my expectations. So, I completely ignored the traditional Nix configuration and began learning to configure my NixOS system using Flakes. The most significant difficulty I encountered was the scarcity and fragmentation of Flakes documentation. A large portion of the available documentation focused on traditional Nix configuration methods. To avoid stumbling into issues later, I documented many scattered notes while learning. This book originated from my scattered notes when I first started with NixOS.
After gaining some experience, in early May of this year, I switched my main PC to NixOS and then organized and refined the notes I had written for about half a month. I published them on my blog[^1] and shared them in the NixOS Chinese community. My friends in the Chinese community praised the content, and upon their suggestion, I translated the article into English and shared it on Reddit, receiving strong positive feedback[^2]. In April of this year (2023), when I got into NixOS, I fell in love with its design philosophy. At the recommendation of a friend, I learned about Nix's Flakes experimental feature. After comparing Flakes with the traditional NixOS configuration method, I realized that only a Flakes-enabled NixOS met my expectations. Consequently, I completely ignored the traditional Nix configuration approach and directly learned to configure my NixOS system using Flakes during my initial steps.
The continuous stream of positive feedback after sharing my notes was exhilarating, and it motivated me to keep iterating on the content. As I kept updating it, the content grew to over 20,000 words, making the reading experience less than ideal. Consequently, based on readers' suggestions[^3], I migrated the content to a GitHub repository and set up a dedicated documentation site to facilitate reading and contributions. Throughout my learning process, I found that there were very few beginner-friendly Flakes resources. The vast majority of documentation focused on the traditional Nix configuration approach, forcing me to extract the information I needed from various sources such as the NixOS Wiki, Zero to Nix, Nixpkgs Manual, and Nixpkgs source code while disregarding any non-Flakes-related content. This learning journey was quite convoluted and painful. To prevent future stumbling, I diligently documented numerous scattered notes as I progressed.
Thus, a bilingual open-source book was born, and I named it <NixOS & Flakes Book>, with the Chinese title being "NixOS & Flakes: A Beginner's Guide." With some experience under my belt, in early May of this year, I switched my main PC to NixOS. After organizing and refining my NixOS newcomer notes, I published them on my blog[^1] and shared them in the NixOS Chinese community. The Chinese community responded positively, and based on their advice, I translated the article into English and shared it on Reddit, receiving strong feedback[^2].
The content of this open-source book has been continuously refined through my experience using NixOS and interactions with readers. The sense of achievement from positive feedback has been the driving force behind my updates, and feedback from readers has been immensely helpful in its evolution. Initially, I just wanted to share my NixOS tinkering experiences, and the content was relatively casual. I never expected it to become an open-source book, with foreign readership even surpassing that in China, and it has garnered many stars—a completely unforeseen outcome. The positive reception of this shared document encouraged me and drove me to continue improving it. Through continuous updates, the content of this document expanded to over 20,000 words. Some readers suggested that the reading experience could be improved, leading me to their suggestions[^3]. As a result, I migrated the article's content to a GitHub repository, established a dedicated documentation site, and adjusted the presentation to make it more aligned with a beginner's guide rather than a personal notebook.
I want to express my gratitude to all friends who contributed and provided suggestions for this book and to all readers for their support and encouragement. Without all of you, the content of this book might have remained on my personal blog, never reaching its current form. And so, a bilingual open-source book was born, which I named "<NixOS & Flakes Book>" with the Chinese title "NixOS & Flakes 新手指南" ("NixOS & Flakes Beginner's Guide").
I hope this book can help more people enjoy the pleasures of NixOS and contribute to the NixOS community by encouraging more people to join in its development. This open-source book's content evolved step by step as I used NixOS and engaged with readers. The sense of accomplishment from readers' positive feedback has been my greatest motivation for updates. Some readers' feedback has been immensely helpful in its "evolution." Initially, I only wanted to share my experiences with NixOS in a somewhat casual manner, but it unexpectedly turned into an open-source book. Its readership abroad even surpassed that within my own country, and it garnered many stars - a result I never anticipated.
The book's content is still continuously updated, and there is much room for improvement. I welcome everyone to suggest and contribute on [GitHub](https://github.com/ryan4yin/nixos-and-flakes-book). I am grateful to all friends who have contributed to this book and offered suggestions, and I appreciate all the support and encouragement from the readers. Without all of you, this book's content might have remained confined to my personal blog, and it wouldn't have reached its current form.
## Characteristics of This Book My hope is that this book can help more people, enabling them to experience the joys of NixOS. I also wish for this book to benefit the NixOS community by encouraging more people to contribute to its development.
1. Focuses on NixOS and Flakes, abandoning the traditional Nix configuration approach. The content of this book is continually being updated, with much room for improvement. I welcome everyone to provide suggestions and contribute on [GitHub](https://github.com/ryan4yin/nixos-and-flakes-book).
2. Beginner-friendly, with content explained from the perspective of NixOS beginners who have some experience with Linux and programming.
3. Step-by-step learning for a gradual understanding.
4. Coherent and well-organized content, forming a structured system. Readers can read the book progressively or quickly find the information they need.
## Historical Feedback and Related Discussions ## The Features of This Book
English feedback and discussions: 1. Focused on NixOS and Flakes, disregarding the traditional Nix configuration approach.
2. Beginner-friendly, with explanations from the perspective of NixOS newcomers who have some experience with Linux usage and programming.
3. Step-by-step, progressive learning.
4. Coherent content, well-organized, and structured. Readers can either read the book gradually or quickly find the information they need.
## Historical Feedback and Discussions on This Book
English feedback and related discussions:
- [[2023-05-11] NixOS & Nix Flakes - A Guide for Beginners - Reddit](https://www.reddit.com/r/NixOS/comments/13dxw9d/nixos_nix_flakes_a_guide_for_beginners/) - [[2023-05-11] NixOS & Nix Flakes - A Guide for Beginners - Reddit](https://www.reddit.com/r/NixOS/comments/13dxw9d/nixos_nix_flakes_a_guide_for_beginners/)
- [[2023-06-22] Updates: NixOS & Nix Flakes - A Guide for Beginners - Reddit](https://www.reddit.com/r/NixOS/comments/14fvz1q/updates_nixos_nix_flakes_a_guide_for_beginners/) - [[2023-06-22] Updates: NixOS & Nix Flakes - A Guide for Beginners - Reddit](https://www.reddit.com/r/NixOS/comments/14fvz1q/updates_nixos_nix_flakes_a_guide_for_beginners/)

29
docs/zh/preface.md
View File

@ -2,30 +2,39 @@
## NixOS 初学者之痛 - 文档与 Flakes ## NixOS 初学者之痛 - 文档与 Flakes
NixOS 是个非常特殊的 Linux 发行版，它基于 Nix 包管理器构建，其设计哲学跟传统的 Ubuntu/CentOS/ArchLinux 大相径庭。 NixOS 是个非常特殊的 Linux 发行版，它构建在 Nix 包管理器之上，设计哲学也跟传统的 Ubuntu, CentOS, Arch Linux 等发行版大相径庭。
NixOS 相比其他发行版最大的优势，是它的可复现能力（即在多台机器上复现出一致的系统环境的能力）以及声明式配置。 NixOS 相比其他发行版最大的优势，是它的可复现能力（即在多台机器上复现出一致的系统环境的能力）以及声明式配置。
NixOS 很强大，但它的强大也带来了系统复杂度的提升，提高了使用门槛。 NixOS 很强大，但它的强大也带来了系统复杂度的提升，提高了使用门槛。
你使用其他 Linux 发行版的很多经验很难在 NixOS 上复用，另一方面 NixOS 又一直因为官方文档与社区文档的散乱陈旧而饱受诟病，劝退新手。 一方面你在 Linux 发行版上积累很多经验很难在 NixOS 上复用，另一方面 NixOS 又一直因为官方文档与社区文档的散乱陈旧而饱受诟病，劝退新手，这些问题都困扰着许多 NixOS 新手。
再说到 Nix 包管理器的实验特性 Flakes，它借鉴了 npm/cargo 的设计思路，使用 flake.nix 记录所有外部依赖项，使用 flake.lock 锁定所有依赖的版本，极大地增强了 Nix 包管理器及 NixOS 的可复现能力跟配置可组合能力。 再说到 Nix 包管理器的实验特性 Flakes，它借鉴了 npm/cargo 等包管理器的设计思路，使用 flake.nix 记录所有外部依赖项，使用 flake.lock 锁定所有依赖的版本，极大地增强了 Nix 包管理器及 NixOS 的可复现能力跟配置可组合能力。
因为 Flakes 的好处很大，它已经在社区被广泛使用，据官方调查，目前 GitHub 新建的 nix 仓库超过半数都使用了 Flakes. 因为 Flakes 的好处很大，社区非常喜欢它。据官方调查，目前 GitHub 新建的 nix 仓库超过半数都使用了 Flakes，传统的 Nix 配置方式已经不再是主流。
但是另一方面 Flakes 作为一个实验性能力存在不确定性，官方文档为了保持稳定性，几乎未包含任何 Flakes 相关的内容。 但是另一方面 Flakes 作为一个实验性能力存在不确定性，官方文档为了保持稳定性，几乎未包含任何 Flakes 相关的内容。
这使非常多的 Nix/NixOS 用户感到非常困惑，看到大家都在用 Flakes，想学习下它但却无处学起，只能到处拼凑零散的资料、翻 Nixpkgs 源码、找前辈高人请教。 这使许多 Nix/NixOS 用户感到相当困惑——他们看到大家都在用 Flakes，也想学习下它，但却发现无处学起，只能到处拼凑零散的资料、翻 Nixpkgs 源码，或者找前辈高人请教。
## 本书的由来 ## 本书的由来
我在今年（2023） 4 月份入坑 NixOS 时就深深地爱上了它的设计哲学，同时在朋友的推荐我了解到了 Flakes 这个实验特性，在对比了 Flakes 与传统的 NixOS 配置方式后，我意识到只有带上了 Flakes 的 NixOS 才符合我对它的期待。 本书最初源于我入坑 NixOS 时的一份零散学习笔记。
于是我完全忽略掉了传统的 Nix 配置方式，在入门阶段就直接学习使用 Flakes 来配置我的 NixOS 系统，遇到的最大困难就是 Flakes 的文档稀少且琐碎，大量的文档写的都是传统的 Nix 配置方法，为了避免后面再次踩坑，我在学习过程中记录了大量的零散笔记。
我在今年（2023） 4 月份入坑 NixOS 时就深深地爱上了它的设计哲学，同时在朋友的推荐下我了解到了 Nix 的 Flakes 实验特性。
在对比了 Flakes 与传统的 NixOS 配置方式后，我意识到只有带上了 Flakes 的 NixOS 才符合我对它的期待。
于是我完全忽略掉了传统的 Nix 配置方式，在入门阶段就直接学习使用 Flakes 来配置我的 NixOS 系统。
在学习的过程中，我发现适合新手的 Flakes 文档几乎没有，大量的文档都是传统的 Nix 配置方法，我需要从 NixOS Wiki、Zero to Nix、Nixpkgs Manual、
Nixpkgs 源码等各种资料中提取出我需要的信息，同时还要忽略掉所有非 Flakes 的内容。
这个学习过程非常曲折痛苦。
为了避免后面再次踩坑，我在学习过程中记录了大量的零散笔记。
在拥有了一定使用经验后，今年 5 月初的时候我将自己的主力 PC 切换到了 NixOS，然后将这份写了大半个月的 NixOS 新手笔记整理润色后发布到了我的博客[^1] ，并分享到了 NixOS 中文社区。 在拥有了一定使用经验后，今年 5 月初的时候我将自己的主力 PC 切换到了 NixOS，然后将这份写了大半个月的 NixOS 新手笔记整理润色后发布到了我的博客[^1] ，并分享到了 NixOS 中文社区。
中文社区的朋友们表示写得很棒，在他们的建议下，我将这篇文章翻译成了英文并分享到了 Reddit，收到非常强烈的正反馈[^2] 中文社区的朋友们表示写得很棒，在他们的建议下，我又将这篇文章翻译成了英文并分享到了 Reddit，收到了非常强烈的正反馈[^2]。
这份笔记分享出来后好评不断，这让我备感振奋，也就很有动力持续迭代内容。在我的持续更新下其内容不断增多，逐渐扩充到了 2 万多字，阅读体验不太好。于是在读者的建议下[^3]， 这份笔记分享出来后好评不断，这让我备感振奋，继续完善它的热情也高涨。
在我的持续更新下这份笔记的内容不断增多，逐渐扩充到了 2 万多字，有读者反馈阅读体验不太好，于是在他的建议下[^3]，
我将文章内容迁移到了一个 GitHub 仓库，搭建了一个专门的文档站点，方便大家阅读与贡献。 我将文章内容迁移到了一个 GitHub 仓库，搭建了一个专门的文档站点，方便大家阅读与贡献。
同时也调整了内容的表述，去掉了一些过于个人化的内容，使其更贴近一本新手指南的风格，而不是一份个人笔记。
至此，一本中英双语的开源书籍诞生了，我给它取名叫 <NixOS & Flakes Book>，中文名叫《NixOS 与 Flakes 新手指南》。 至此，一本中英双语的开源书籍诞生了，我给它取名叫 <NixOS & Flakes Book>，中文名叫《NixOS 与 Flakes 新手指南》。