mirror of
https://github.com/ryan4yin/nixos-and-flakes-book.git
synced 2024-12-30 18:48:50 +01:00
Ryan Yin
GitHub
commit
06044d13b4
17
README.md
17
README.md
@ -4,9 +4,9 @@
|
||||
|
||||
Want to know NixOS & Flakes in detail? Looking for a beginner-friendly tutorial? Then you've come to the right place!
|
||||
|
||||
An unofficial and opinionated NixOS & Flakes :book: for beginners: https://nixos-and-flakes.thiscute.world/introduction/
|
||||
An unofficial and opinionated NixOS & Flakes :book: for beginners: https://nixos-and-flakes.thiscute.world/
|
||||
|
||||
中文版: https://nixos-and-flakes.thiscute.world/zh/introduction/
|
||||
中文版: https://nixos-and-flakes.thiscute.world/zh/
|
||||
|
||||
> If you're using macOS, [ryan4yin/nix-darwin-kickstarter](https://github.com/ryan4yin/nix-darwin-kickstarter) may be a good starting point for you,
|
||||
> you can learn how to use Nix with this book and take nix-darwin-kickstarter as a start point to build your own Nix configuration.
|
||||
@ -15,19 +15,6 @@ An unofficial and opinionated NixOS & Flakes :book: for beginners: https://nixos
|
||||
|
||||
Want to discuss the content of this book? Have any questions? Please feel free to open an issue or join the discussion on [GitHub Discussions](https://github.com/ryan4yin/nixos-and-flakes-book/discussions).
|
||||
|
||||
Historical feedback and discussion:
|
||||
|
||||
- [[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-24] An unofficial NixOS & Flakes book for beginners - Discourse](https://discourse.nixos.org/t/an-unofficial-nixos-flakes-book-for-beginners/29561)
|
||||
- [[2023-07-06] This isn't an issue but it has to be said: - Issues](https://github.com/ryan4yin/nix-config/issues/3)
|
||||
|
||||
中文反馈与相关讨论：
|
||||
|
||||
- [[2023-05-09] NixOS 与 Nix Flakes 新手入门 - v2ex 社区](https://www.v2ex.com/t/938569#reply45)
|
||||
- [[2023-06-24] NixOS 与 Flakes | 一份非官方的新手指南 - v2ex 社区](https://www.v2ex.com/t/951190#reply9)
|
||||
- [[2023-06-24] NixOS 与 Flakes | 一份非官方的新手指南 - 0xffff 社区](https://0xffff.one/d/1547-nixos-yu-flakes-yi-fen-fei-guan)
|
||||
|
||||
## Introduction to Flakes
|
||||
|
||||
The flakes experimental feature is a major development for Nix, it introduces a policy for managing dependencies between Nix expressions, it improves reproducibility, composability and usability in the Nix ecosystem. Although it's still an experimental feature, flakes have been widely used by the Nix community.[^1]
|
||||
|
||||
@ -73,11 +73,16 @@ function themeConfigEnglish() {
|
||||
// https://vitepress.dev/reference/default-theme-config
|
||||
nav: [
|
||||
{ text: "Home", link: "/" },
|
||||
{ text: "Preface", link: "/preface.md" },
|
||||
{ text: "Get Started", link: "/introduction/index.md" },
|
||||
{ text: "Best Practices", link: "/best-practices/intro.md" },
|
||||
],
|
||||
|
||||
sidebar: [
|
||||
{
|
||||
text: "Preface",
|
||||
items: [{ text: "Preface", link: "/preface.md" }],
|
||||
},
|
||||
{
|
||||
text: "Get Started",
|
||||
items: [
|
||||
@ -245,11 +250,16 @@ function themeConfigChinese() {
|
||||
// https://vitepress.dev/reference/default-theme-config
|
||||
nav: [
|
||||
{ text: "首页", link: "/zh/" },
|
||||
{ text: "前言", link: "/zh/preface.md" },
|
||||
{ text: "开始使用", link: "/zh/introduction/index.md" },
|
||||
{ text: "最佳实践", link: "/zh/best-practices/intro.md" },
|
||||
],
|
||||
|
||||
sidebar: [
|
||||
{
|
||||
text: "前言",
|
||||
items: [{ text: "前言", link: "/zh/preface.md" }],
|
||||
},
|
||||
{
|
||||
text: "开始使用",
|
||||
items: [
|
||||
|
||||
@ -12,6 +12,9 @@ hero:
|
||||
src: /logo.png
|
||||
alt: NixOS Flakes
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Preface
|
||||
link: /preface.md
|
||||
- theme: brand
|
||||
text: Get Started
|
||||
link: /introduction/index.md
|
||||
|
||||
57
docs/preface.md
Normal file
57
docs/preface.md
Normal file
@ -0,0 +1,57 @@
|
||||
# About This Book
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
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].
|
||||
|
||||
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.
|
||||
|
||||
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."
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
## Characteristics of This Book
|
||||
|
||||
1. Focuses on NixOS and Flakes, abandoning the traditional Nix configuration approach.
|
||||
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
|
||||
|
||||
English feedback and 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-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-24] An unofficial NixOS & Flakes book for beginners - Discourse](https://discourse.nixos.org/t/an-unofficial-nixos-flakes-book-for-beginners/29561)
|
||||
- [[2023-07-06] This isn't an issue but it has to be said: - Issues](https://github.com/ryan4yin/nix-config/issues/3)
|
||||
|
||||
Chinese feedback and discussions:
|
||||
|
||||
- [[2023-05-09] NixOS 与 Nix Flakes 新手入门 - v2ex 社区](https://www.v2ex.com/t/938569#reply45)
|
||||
- [[2023-06-24] NixOS 与 Flakes | 一份非官方的新手指南 - v2ex 社区](https://www.v2ex.com/t/951190#reply9)
|
||||
- [[2023-06-24] NixOS 与 Flakes | 一份非官方的新手指南 - 0xffff 社区](https://0xffff.one/d/1547-nixos-yu-flakes-yi-fen-fei-guan)
|
||||
|
||||
[^1]: [NixOS & Nix Flakes - A Guide for Beginners - This Cute World](https://thiscute.world/en/posts/nixos-and-flake-basics/)
|
||||
[^2]: [NixOS & Nix Flakes - A Guide for Beginners - Reddit](https://www.reddit.com/r/NixOS/comments/13dxw9d/nixos_nix_flakes_a_guide_for_beginners/)
|
||||
[^3]: [Updates: NixOS & Nix Flakes - A Guide for Beginners - Reddit](https://www.reddit.com/r/NixOS/comments/14fvz1q/comment/jp4xhj3/?context=3)
|
||||
@ -13,7 +13,10 @@ hero:
|
||||
alt: NixOS Flakes
|
||||
actions:
|
||||
- theme: brand
|
||||
text: 开始使用
|
||||
text: 前言
|
||||
link: /zh/preface.md
|
||||
- theme: brand
|
||||
text: 开始学习
|
||||
link: /zh/introduction/index.md
|
||||
- theme: alt
|
||||
text: "前往 GitHub 仓库"
|
||||
|
||||
68
docs/zh/preface.md
Normal file
68
docs/zh/preface.md
Normal file
@ -0,0 +1,68 @@
|
||||
# 前言
|
||||
|
||||
## NixOS 初学者之痛 - 文档与 Flakes
|
||||
|
||||
NixOS 是个非常特殊的 Linux 发行版，它基于 Nix 包管理器构建，其设计哲学跟传统的 Ubuntu/CentOS/ArchLinux 大相径庭。
|
||||
|
||||
NixOS 相比其他发行版最大的优势，是它的可复现能力（即在多台机器上复现出一致的系统环境的能力）以及声明式配置。
|
||||
|
||||
NixOS 很强大，但它的强大也带来了系统复杂度的提升，提高了使用门槛。
|
||||
你使用其他 Linux 发行版的很多经验很难在 NixOS 上复用，另一方面 NixOS 又一直因为官方文档与社区文档的散乱陈旧而饱受诟病，劝退新手。
|
||||
|
||||
再说到 Nix 包管理器的实验特性 Flakes，它借鉴了 npm/cargo 的设计思路，使用 flake.nix 记录所有外部依赖项，使用 flake.lock 锁定所有依赖的版本，极大地增强了 Nix 包管理器及 NixOS 的可复现能力跟配置可组合能力。
|
||||
因为 Flakes 的好处很大，它已经在社区被广泛使用，据官方调查，目前 GitHub 新建的 nix 仓库超过半数都使用了 Flakes.
|
||||
|
||||
但是另一方面 Flakes 作为一个实验性能力存在不确定性，官方文档为了保持稳定性，几乎未包含任何 Flakes 相关的内容。
|
||||
这使非常多的 Nix/NixOS 用户感到非常困惑，看到大家都在用 Flakes，想学习下它但却无处学起，只能到处拼凑零散的资料、翻 Nixpkgs 源码、找前辈高人请教。
|
||||
|
||||
|
||||
## 本书的由来
|
||||
|
||||
我在今年（2023） 4 月份入坑 NixOS 时就深深地爱上了它的设计哲学，同时在朋友的推荐我了解到了 Flakes 这个实验特性，在对比了 Flakes 与传统的 NixOS 配置方式后，我意识到只有带上了 Flakes 的 NixOS 才符合我对它的期待。
|
||||
于是我完全忽略掉了传统的 Nix 配置方式，在入门阶段就直接学习使用 Flakes 来配置我的 NixOS 系统，遇到的最大困难就是 Flakes 的文档稀少且琐碎，大量的文档写的都是传统的 Nix 配置方法，为了避免后面再次踩坑，我在学习过程中记录了大量的零散笔记。
|
||||
|
||||
在拥有了一定使用经验后，今年 5 月初的时候我将自己的主力 PC 切换到了 NixOS，然后将这份写了大半个月的 NixOS 新手笔记整理润色后发布到了我的博客[^1] ，并分享到了 NixOS 中文社区。
|
||||
中文社区的朋友们表示写得很棒，在他们的建议下，我将这篇文章翻译成了英文并分享到了 Reddit，收到非常强烈的正反馈[^2]
|
||||
|
||||
这份笔记分享出来后好评不断，这让我备感振奋，也就很有动力持续迭代内容。在我的持续更新下其内容不断增多，逐渐扩充到了 2 万多字，阅读体验不太好。于是在读者的建议下[^3]，
|
||||
我将文章内容迁移到了一个 GitHub 仓库，搭建了一个专门的文档站点，方便大家阅读与贡献。
|
||||
|
||||
至此，一本中英双语的开源书籍诞生了，我给它取名叫 <NixOS & Flakes Book>，中文名叫《NixOS 与 Flakes 新手指南》。
|
||||
|
||||
这本开源书籍的内容是我在使用 NixOS 的过程中，以及与读者的沟通中一步步优化的，读者的好评带来的成就感是我更新的最大动力，一些读者的反馈也对它的「进化」产生了很大的帮助。
|
||||
我最初只是想分享一下自己的 NixOS 折腾心得，内容也写得比较随意，没想到最后却成了一本开源书籍，国外的阅读量甚至是国内的两倍，而且还得到了许多 stars ，这真是完全没预料到的。
|
||||
|
||||
感谢所有对本书做出过贡献、提出过建议的朋友们，感谢所有读者的支持与鼓励，没有你们，这本书的内容可能会一直停留在我个人的博客上，也不会有今天的样子。
|
||||
|
||||
我希望这本书能够帮助到更多的人，让更多的人能够享受到 NixOS 带来的乐趣，也希望这本书能够帮助到 NixOS 社区，让更多的人加入到 NixOS 社区的建设中来。
|
||||
|
||||
本书内容仍在持续更新，还有许多内容有待完善，欢迎大家在 [GitHub](https://github.com/ryan4yin/nixos-and-flakes-book) 上提出建议与贡献。
|
||||
|
||||
## 本书的特点
|
||||
|
||||
1. 以 NixOS 与 Flakes 为核心进行讲解，摈弃了传统的 Nix 配置方式
|
||||
1. 新手友好，内容尽可能地从拥有一定 Linux 使用经验与编程经验的 NixOS 初学者角度出发进行讲解
|
||||
2. step-by-step，渐进式地学习
|
||||
3. 内容连贯，组织良好，比较成体系。读者既可以渐进式地阅读本书，也可以通过快速找到他/她需要的信息
|
||||
|
||||
## 本书的历史反馈与相关讨论
|
||||
|
||||
英文反馈与相关讨论：
|
||||
|
||||
- [[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-24] An unofficial NixOS & Flakes book for beginners - Discourse](https://discourse.nixos.org/t/an-unofficial-nixos-flakes-book-for-beginners/29561)
|
||||
- [[2023-07-06] This isn't an issue but it has to be said: - Issues](https://github.com/ryan4yin/nix-config/issues/3)
|
||||
|
||||
中文反馈与相关讨论：
|
||||
|
||||
- [[2023-05-09] NixOS 与 Nix Flakes 新手入门 - v2ex 社区](https://www.v2ex.com/t/938569#reply45)
|
||||
- [[2023-06-24] NixOS 与 Flakes | 一份非官方的新手指南 - v2ex 社区](https://www.v2ex.com/t/951190#reply9)
|
||||
- [[2023-06-24] NixOS 与 Flakes | 一份非官方的新手指南 - 0xffff 社区](https://0xffff.one/d/1547-nixos-yu-flakes-yi-fen-fei-guan)
|
||||
|
||||
|
||||
[^1]: [NixOS 与 Nix Flakes 新手入门](https://thiscute.world/posts/nixos-and-flake-basics/)
|
||||
[^2]: [NixOS & Nix Flakes - A Guide for Beginners - Reddit](https://www.reddit.com/r/NixOS/comments/13dxw9d/nixos_nix_flakes_a_guide_for_beginners/)
|
||||
[^3]: [Updates: NixOS & Nix Flakes - A Guide for Beginners - Reddit](https://www.reddit.com/r/NixOS/comments/14fvz1q/comment/jp4xhj3/?context=3)
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user