From 3bfffff0462b4a6e58c4c3e1854fca8acd820665 Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Fri, 30 Jun 2023 17:00:03 +0800 Subject: [PATCH] fix: page title --- .github/CONTRIBUTING.md | 4 ++-- docs/advanced-topics/index.md | 2 +- docs/best-practices/debug-with-nix-repl.md | 2 +- docs/best-practices/intro.md | 4 +--- docs/best-practices/remote-deployment.md | 2 +- .../run-downloaded-binaries-on-nixos.md | 2 +- .../simplify-nixos-related-commands.md | 2 +- docs/development/cross-platform-compilation.md | 6 +++--- docs/development/dev-environments.md | 2 +- docs/development/distributed-building.md | 4 ++-- docs/development/intro.md | 8 ++++---- docs/development/kernel-development.md | 6 +++--- docs/development/packaging-101.md | 9 +++------ docs/introduction/advantages-and-disadvantages.md | 2 +- docs/introduction/index.md | 2 +- docs/introduction/installation.md | 2 +- .../downgrade-or-upgrade-packages.md | 2 +- docs/nixos-with-flakes/get-started-with-nixos.md | 2 +- docs/nixos-with-flakes/introduction-to-flakes.md | 2 +- .../modularize-the-configuration.md | 2 +- .../nixos-with-flakes/nixos-with-flakes-enabled.md | 10 +++++----- docs/nixos-with-flakes/other-useful-tips.md | 8 +++----- docs/nixos-with-flakes/start-using-home-manager.md | 2 +- docs/nixos-with-flakes/update-the-system.md | 2 +- docs/nixpkgs/callpackage.md | 2 +- docs/nixpkgs/intro.md | 3 +-- docs/nixpkgs/overlays.md | 2 +- docs/nixpkgs/overriding.md | 2 +- docs/other-usage-of-flakes/inputs.md | 2 +- docs/other-usage-of-flakes/intro.md | 2 +- docs/other-usage-of-flakes/outputs.md | 5 ++--- docs/other-usage-of-flakes/the-new-cli.md | 4 ++-- docs/the-nix-language/index.md | 3 +-- docs/zh/advanced-topics/index.md | 2 +- docs/zh/best-practices/debug-with-nix-repl.md | 3 +-- docs/zh/best-practices/intro.md | 3 +-- docs/zh/best-practices/remote-deployment.md | 5 ++--- .../run-downloaded-binaries-on-nixos.md | 5 ++--- .../simplify-nixos-related-commands.md | 5 ++--- docs/zh/development/cross-platform-compilation.md | 14 ++++++-------- docs/zh/development/dev-environments.md | 2 +- docs/zh/development/distributed-building.md | 11 +++++------ docs/zh/development/intro.md | 11 +++++------ docs/zh/development/kernel-development.md | 6 +++--- docs/zh/development/packaging-101.md | 9 +++------ .../introduction/advantages-and-disadvantages.md | 5 ++--- docs/zh/introduction/index.md | 5 +---- docs/zh/introduction/installation.md | 2 +- .../downgrade-or-upgrade-packages.md | 3 +-- .../zh/nixos-with-flakes/get-started-with-nixos.md | 5 ++--- .../zh/nixos-with-flakes/introduction-to-flakes.md | 2 +- .../modularize-the-configuration.md | 3 +-- .../nixos-with-flakes/nixos-with-flakes-enabled.md | 5 ++--- docs/zh/nixos-with-flakes/other-useful-tips.md | 5 ++--- .../nixos-with-flakes/start-using-home-manager.md | 2 +- docs/zh/nixos-with-flakes/update-the-system.md | 3 +-- docs/zh/nixpkgs/callpackage.md | 10 ++++------ docs/zh/nixpkgs/intro.md | 3 +-- docs/zh/nixpkgs/overlays.md | 7 +++---- docs/zh/nixpkgs/overriding.md | 6 ++---- docs/zh/other-usage-of-flakes/inputs.md | 5 ++--- docs/zh/other-usage-of-flakes/intro.md | 6 ++---- docs/zh/other-usage-of-flakes/outputs.md | 4 +--- docs/zh/other-usage-of-flakes/the-new-cli.md | 10 ++++------ docs/zh/the-nix-language/index.md | 2 +- 65 files changed, 119 insertions(+), 164 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 34befff..00106f4 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -11,10 +11,10 @@ the preferred channel for bug reports, features requests and submitting pull req But please respect the following restrictions: -* Please **do not** use the issue tracker for personal support requests (use +- Please **do not** use the issue tracker for personal support requests (use [Stack Overflow](https://stackoverflow.com) or IRC) -* Please **do not** derail or troll issues. Keep the discussion on topic and +- Please **do not** derail or troll issues. Keep the discussion on topic and respect the opinions of others ## License diff --git a/docs/advanced-topics/index.md b/docs/advanced-topics/index.md index 85fe3fb..a45af25 100644 --- a/docs/advanced-topics/index.md +++ b/docs/advanced-topics/index.md @@ -1,4 +1,4 @@ -## Advanced Topics +# Advanced Topics Once you're familiar with NixOS, you can explore Nix's three manuals and other documentation to discover more ways to use it: diff --git a/docs/best-practices/debug-with-nix-repl.md b/docs/best-practices/debug-with-nix-repl.md index a6ccac1..7d3e223 100644 --- a/docs/best-practices/debug-with-nix-repl.md +++ b/docs/best-practices/debug-with-nix-repl.md @@ -1,4 +1,4 @@ -## Debug with `nix repl` +# Debug with `nix repl` We've used `nix repl ''` many times to check the source code in this guide, it's a powerful tool to help us understand how things work in Nix. diff --git a/docs/best-practices/intro.md b/docs/best-practices/intro.md index 80133e1..b4e0821 100644 --- a/docs/best-practices/intro.md +++ b/docs/best-practices/intro.md @@ -1,10 +1,8 @@ -## Best Practices - +# Best Practices Nix is powerful and flexible, it provides a lot of ways to do things, making it difficult to find the most suitable way to do your job. Here are some best practices that I've learned from the community, hope it can help you. - ## References - [Tips&Tricks for NixOS Desktop - NixOS Discourse][Tips&Tricks for NixOS Desktop - NixOS Discourse] diff --git a/docs/best-practices/remote-deployment.md b/docs/best-practices/remote-deployment.md index fcc0e43..797f035 100644 --- a/docs/best-practices/remote-deployment.md +++ b/docs/best-practices/remote-deployment.md @@ -1,4 +1,4 @@ -## Remote deployment +# Remote deployment Some tools like [NixOps](https://github.com/NixOS/nixops), [deploy-rs](https://github.com/serokell/deploy-rs), and [colmena](https://github.com/zhaofengli/colmena) can all be used to deploy NixOS configuration to remote hosts, but they are all too complicated for me. diff --git a/docs/best-practices/run-downloaded-binaries-on-nixos.md b/docs/best-practices/run-downloaded-binaries-on-nixos.md index ebe16cd..e79100c 100644 --- a/docs/best-practices/run-downloaded-binaries-on-nixos.md +++ b/docs/best-practices/run-downloaded-binaries-on-nixos.md @@ -1,4 +1,4 @@ -## Run downloaded binaries on NixOS +# Run downloaded binaries on NixOS NixOS does not follow the FHS standard, so the binaries you download from the Internet will not likely work on NixOS. But there are some ways to make it work. diff --git a/docs/best-practices/simplify-nixos-related-commands.md b/docs/best-practices/simplify-nixos-related-commands.md index ff439e6..df490be 100644 --- a/docs/best-practices/simplify-nixos-related-commands.md +++ b/docs/best-practices/simplify-nixos-related-commands.md @@ -1,4 +1,4 @@ -## Simplify NixOS-related commands +# Simplify NixOS-related commands I use Makefile to simplify NixOS-related commands, which is very convenient. You can also use other similar tools to do this job, here I will only introduce my usage as a reference. diff --git a/docs/development/cross-platform-compilation.md b/docs/development/cross-platform-compilation.md index 8ac41f6..67b61e5 100644 --- a/docs/development/cross-platform-compilation.md +++ b/docs/development/cross-platform-compilation.md @@ -1,4 +1,4 @@ -## Cross-platform Compilation +# Cross-platform Compilation On any Linux platform, there are two ways to do cross-platform compilation. For example, to build an `aarch64-linux` program on an `x86_64-linux` host, you can use the following methods: @@ -13,7 +13,7 @@ If you use method one, you don't need to enable `binfmt_misc`, but you need to e If you use method two, you need to enable the `binfmt_misc` of the `aarch64` architecture in the NixOS configuration of the building machine. -### Cross Compilation +## Cross Compilation `nixpkgs` provides a set of predefined host platforms for cross-compilation called `pkgsCross`. You can explore them in `nix repl`. @@ -136,7 +136,7 @@ As for `flake.nix`, its setting method is very simple, even simpler than the set You do not need to add any additional modules, just specify `system` as `riscv64-linux`. Nix will automatically detect whether the current system is `riscv64-linux` during the build. If not, it will automatically build through the emulated system(QEMU). For users, these underlying operations are completely transparent. -### Custom build toolchain +## Custom build toolchain Sometimes we may need to use a custom toolchain for building, such as using our own gcc, or using our own musl libc, etc. This modification can be achieved through overlays. diff --git a/docs/development/dev-environments.md b/docs/development/dev-environments.md index 944ad51..cf873e0 100644 --- a/docs/development/dev-environments.md +++ b/docs/development/dev-environments.md @@ -1,4 +1,4 @@ -## Dev Environments +# Dev Environments We have learned how to build development environments, but it's a bit tedious to write `flake.nix` for each project. diff --git a/docs/development/distributed-building.md b/docs/development/distributed-building.md index 41df95b..07f85af 100644 --- a/docs/development/distributed-building.md +++ b/docs/development/distributed-building.md @@ -1,4 +1,4 @@ -## Distributed Building +# Distributed Building Distributed building can speed up the build process by utilizing multiple machines. @@ -9,7 +9,7 @@ Distributed building is of great value in scenarios where there is no cache avai 1. Users of `RISC-V` or `ARM64` architectures (especially `RISC-V`), because there are very few caches for these two architectures in the official cache repository, which often requires a lot of local compilation. 2. Users who customize the system a lot, because the packages in the official cache repository are all default configurations. If you change the build parameters, then the official cache is not applicable, and you need to compile locally. For instance, in the embedded scenario, there is often a need for customization of the underlying kernel, drivers, etc., which leads to the need for local compilation. -### Configure Distributed Building +## Configure Distributed Building Currently, there is no official documentation for distributed building. However, I have listed some recommended reference documents at the end of this chapter, along with my distributed build configuration (a NixOS Module). diff --git a/docs/development/intro.md b/docs/development/intro.md index 09dfcbc..ab64353 100644 --- a/docs/development/intro.md +++ b/docs/development/intro.md @@ -1,4 +1,4 @@ -## Development Environments on NixOS +# Development Environments on NixOS NixOS's reproducibility makes it ideal for building development environments. However, if you're used to other distros, you may encounter problems because NixOS has its own logic. We'll explain this briefly below. @@ -8,7 +8,7 @@ You should NOT install the development environment of each language in the globa In the following sections, we'll introduce how the development environment works in NixOS. -### Creating a Development Environment +## Creating a Development Environment We can create a development environment using `pkgs.mkShell { ... }` and open an interactive Bash shell of this development environment using `nix develop`. @@ -114,7 +114,7 @@ Here is a `flake.nix` that defined a development environment with nodejs 18 inst Create an empty folder, save the above configuration as `flake.nix`, and then execute `nix develop` (or more precisely, you can use `nix develop .#default`), you will find that you have entered a nodejs 18 development environment, you can use `node` `npm` `pnpm` `yarn` and other commands. And when you just entered, `shellHook` was also executed, outputting the current version of nodejs. -### Enter the build environment of any Nix package +## Enter the build environment of any Nix package Now let's take a look at `nix develop`, first read the help document output by `nix develop --help`: @@ -242,7 +242,7 @@ Hello, world! This usage is mainly used to debug the build process of a Nix package, or to execute some commands in the build environment of a Nix package. -### `nix shell` & `nix run` +## `nix shell` & `nix run` Compare to `nix develop`, these two commands are much simpler and easier to understand. diff --git a/docs/development/kernel-development.md b/docs/development/kernel-development.md index 0725ded..b559916 100644 --- a/docs/development/kernel-development.md +++ b/docs/development/kernel-development.md @@ -18,11 +18,11 @@ An example of kernel development with `flake.nix`. }; }; - outputs = inputs@{ + outputs = inputs@{ self ,nixpkgs ,thead-kernel - ,... }: + ,... }: let pkgsKernel = import nixpkgs { localSystem = "x86_64-linux"; @@ -68,7 +68,7 @@ An example of kernel development with `flake.nix`. # use `nix develop .#kernel` to enter the environment with the custom kernel build environment available. # and then use `unpackPhase` to unpack the kernel source code and cd into it. # then you can use `make menuconfig` to configure the kernel. - # + # # problem # - using `make menuconfig` - Unable to find the ncurses package. devShells.x86_64-linux.kernel = pkgsKernel.linuxPackages_thead.kernel.dev; diff --git a/docs/development/packaging-101.md b/docs/development/packaging-101.md index f162762..650eabb 100644 --- a/docs/development/packaging-101.md +++ b/docs/development/packaging-101.md @@ -4,19 +4,16 @@ TODO -### 1. stdenv - +## 1. stdenv TODO -### 2. language specific frameworks - +## 2. language specific frameworks TODO - ## References - [NixOS Series 3: Software Packaging 101 - LanTian](https://lantian.pub/en/article/modify-computer/nixos-packaging.lantian/) - [stdenv - Nixpkgs Manual](https://github.com/NixOS/nixpkgs/tree/nixos-unstable/doc/languages-frameworks) -- [languages-frameworks - Nixpkgs Manual](https://github.com/NixOS/nixpkgs/tree/nixos-unstable/doc/stdenv) \ No newline at end of file +- [languages-frameworks - Nixpkgs Manual](https://github.com/NixOS/nixpkgs/tree/nixos-unstable/doc/stdenv) diff --git a/docs/introduction/advantages-and-disadvantages.md b/docs/introduction/advantages-and-disadvantages.md index 5a1b2aa..f42006d 100644 --- a/docs/introduction/advantages-and-disadvantages.md +++ b/docs/introduction/advantages-and-disadvantages.md @@ -1,4 +1,4 @@ -## Advantages & Disadvantages of NixOS +# Advantages & Disadvantages of NixOS ## Advantages diff --git a/docs/introduction/index.md b/docs/introduction/index.md index 94faf73..ee757bf 100644 --- a/docs/introduction/index.md +++ b/docs/introduction/index.md @@ -1,4 +1,4 @@ -## Introduction to Nix & NixOS +# Introduction to Nix & NixOS Nix is a declarative package manager, that allows users to declare the expected system state in some configuration files, and Nix is responsible for achieving that goal. diff --git a/docs/introduction/installation.md b/docs/introduction/installation.md index f065c63..90d0d08 100644 --- a/docs/introduction/installation.md +++ b/docs/introduction/installation.md @@ -1,4 +1,4 @@ -## Installation +# Installation Nix can be installed in multiple ways: diff --git a/docs/nixos-with-flakes/downgrade-or-upgrade-packages.md b/docs/nixos-with-flakes/downgrade-or-upgrade-packages.md index 5870027..f6e2c5b 100644 --- a/docs/nixos-with-flakes/downgrade-or-upgrade-packages.md +++ b/docs/nixos-with-flakes/downgrade-or-upgrade-packages.md @@ -1,4 +1,4 @@ -## Downgrading or Upgrading Packages +# Downgrading or Upgrading Packages After using Flakes, most people are currently using the `nixos-unstable` branch of nixpkgs. However, sometimes you may encounter bugs, such as the [chrome/vscode crash problem](https://github.com/swaywm/sway/issues/7562). diff --git a/docs/nixos-with-flakes/get-started-with-nixos.md b/docs/nixos-with-flakes/get-started-with-nixos.md index 7caf1ff..f2e7220 100644 --- a/docs/nixos-with-flakes/get-started-with-nixos.md +++ b/docs/nixos-with-flakes/get-started-with-nixos.md @@ -1,4 +1,4 @@ -## Get Started with NixOS +# Get Started with NixOS After learning the basics of the Nix language, we can start using it to configure our NixOS. The default configuration for NixOS is located at `/etc/nixos/configuration.nix`, which contains all the declarative configuration for the system, such as time zone, language, keyboard layout, network, users, file system, boot options, etc. diff --git a/docs/nixos-with-flakes/introduction-to-flakes.md b/docs/nixos-with-flakes/introduction-to-flakes.md index 3257445..6a8774a 100644 --- a/docs/nixos-with-flakes/introduction-to-flakes.md +++ b/docs/nixos-with-flakes/introduction-to-flakes.md @@ -1,4 +1,4 @@ -## Introduction to Flakes +# 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] diff --git a/docs/nixos-with-flakes/modularize-the-configuration.md b/docs/nixos-with-flakes/modularize-the-configuration.md index 5d6cd2b..8be3eea 100644 --- a/docs/nixos-with-flakes/modularize-the-configuration.md +++ b/docs/nixos-with-flakes/modularize-the-configuration.md @@ -1,4 +1,4 @@ -## Modularize Your NixOS Configuration +# Modularize Your NixOS Configuration At this point, the skeleton of the entire system is configured. The current configuration structure in `/etc/nixos` should be: diff --git a/docs/nixos-with-flakes/nixos-with-flakes-enabled.md b/docs/nixos-with-flakes/nixos-with-flakes-enabled.md index 6b6e075..60b3f8a 100644 --- a/docs/nixos-with-flakes/nixos-with-flakes-enabled.md +++ b/docs/nixos-with-flakes/nixos-with-flakes-enabled.md @@ -1,6 +1,6 @@ -## NixOS with Flakes Enabled +# NixOS with Flakes Enabled -### Enabling Flakes Support +## Enabling Flakes Support Flakes provide better reproducibility and a clearer package structure that is easier to maintain compared to the default configuration approach of NixOS. Therefore, it's recommended to manage NixOS with Flakes. @@ -38,7 +38,7 @@ However, as Flakes is still an experimental feature, it's not enabled by default To apply the changes, run `sudo nixos-rebuild switch`. After that, you can write the configuration for NixOS with Flakes. -### Switching System Configuration to `flake.nix` +## Switching System Configuration to `flake.nix` After enabling `flakes`, `sudo nixos-rebuild switch` will first try to read `/etc/nixos/flake.nix` every time you run it. If not found, it will fallback to `/etc/nixos/configuration.nix`. @@ -135,7 +135,7 @@ We defined a NixOS system called `nixos-test` with a configuration file at `./co To apply the configuration, run `sudo nixos-rebuild switch`. No changes will be made to the system because we imported the old configuration file in `/etc/nixos/flake.nix`, so the actual state we declared remains unchanged. -### Manage System Software through Flakes +## Manage System Software through Flakes After the switch, we can manage the system through Flakes. The most common requirement for managing a system is to install packages. We have seen how to install packages through `environment.systemPackages` before, and these packages are all from the official nixpkgs repository. @@ -199,7 +199,7 @@ Then update `configuration.nix` to install `helix` from the input `helix`: To deploy the changes, run `sudo nixos-rebuild switch`. Then start the Helix editor by running the `helix` command. -### Add Custom Cache Mirror +## Add Custom Cache Mirror > If you don't need to customize the cache mirror, you can safely skip this section. diff --git a/docs/nixos-with-flakes/other-useful-tips.md b/docs/nixos-with-flakes/other-useful-tips.md index 5a717b8..a745d33 100644 --- a/docs/nixos-with-flakes/other-useful-tips.md +++ b/docs/nixos-with-flakes/other-useful-tips.md @@ -1,7 +1,6 @@ -## Other useful Tips +# Other useful Tips - -### Manage the configuration with Git +## Manage the configuration with Git NixOS configuration is just a set of text files, it is very suitable to be managed with Git, and thus we can easily rollback to a previous version when we encounter some problems. @@ -42,7 +41,7 @@ sudo nixos-rebuild switch --flake .#nixos-test More operations on Git are not described here. Generally speaking, rollback can be done directly through Git. Only when the system crashes completely, you will need to restart into bootloader and boot the system from the previous historical version. -### View and delete history data {#view-and-delete-history} +## View and delete history data {#view-and-delete-history} As we mentioned before, each deployment of NixOS will generate a new version, and all versions will be added to the system boot options. In addition to restarting the computer, we can also query all available historical versions through the following command: @@ -66,7 +65,6 @@ Another command returns all packages installed in the system: nix-env -qa ``` - ## Reduce Disk Usage The following configuration can be used to reduce disk usage, feel free to add it into your NixOS Configuration. diff --git a/docs/nixos-with-flakes/start-using-home-manager.md b/docs/nixos-with-flakes/start-using-home-manager.md index 020dc69..ab91dd9 100644 --- a/docs/nixos-with-flakes/start-using-home-manager.md +++ b/docs/nixos-with-flakes/start-using-home-manager.md @@ -1,4 +1,4 @@ -## Getting Started with Home Manager +# Getting Started with Home Manager As I mentioned earlier, NixOS can only manage system-level configuration. To manage user-level configuration in the Home directory, we need to install Home Manager. diff --git a/docs/nixos-with-flakes/update-the-system.md b/docs/nixos-with-flakes/update-the-system.md index 698a45d..e153d0b 100644 --- a/docs/nixos-with-flakes/update-the-system.md +++ b/docs/nixos-with-flakes/update-the-system.md @@ -1,4 +1,4 @@ -## Updating the System +# Updating the System With Flakes, updating the system is simple. Just run the following commands in `/etc/nixos`: diff --git a/docs/nixpkgs/callpackage.md b/docs/nixpkgs/callpackage.md index bac39e1..25d84a6 100644 --- a/docs/nixpkgs/callpackage.md +++ b/docs/nixpkgs/callpackage.md @@ -1,4 +1,4 @@ -## pkgs.callPackage +# pkgs.callPackage In the previous section, we used `import xxx.nix` to import Nix files multiple times. This syntax simply returns the execution result of the file without any further processing. diff --git a/docs/nixpkgs/intro.md b/docs/nixpkgs/intro.md index 2641a32..258eaf9 100644 --- a/docs/nixpkgs/intro.md +++ b/docs/nixpkgs/intro.md @@ -1,5 +1,4 @@ -## Nixpkgs's Advanced Usage - +# Nixpkgs's Advanced Usage `callPackage`, `Overriding`, and `Overlays` are the techniques occasionally used when using Nix to customize the build method of Nix packages. diff --git a/docs/nixpkgs/overlays.md b/docs/nixpkgs/overlays.md index e4908f2..4655547 100644 --- a/docs/nixpkgs/overlays.md +++ b/docs/nixpkgs/overlays.md @@ -1,4 +1,4 @@ -## Overlays +# Overlays The `override` we introduced earlier generates a new Derivation that does not affect the original Derivation in `pkgs`. It's only suitable for use as a local parameter. If you need to override a Derivation that is also dependent on other Nix packages, then other Nix packages will still use the original Derivation. diff --git a/docs/nixpkgs/overriding.md b/docs/nixpkgs/overriding.md index 1a73c67..ed0f0f7 100644 --- a/docs/nixpkgs/overriding.md +++ b/docs/nixpkgs/overriding.md @@ -1,4 +1,4 @@ -## Overriding +# Overriding Simply put, all Nix packages in nixpkgs can be customized with `.override {}` to define some build parameters, which returns a new Derivation that uses custom parameters. For example: diff --git a/docs/other-usage-of-flakes/inputs.md b/docs/other-usage-of-flakes/inputs.md index 4f8f315..2d4903e 100644 --- a/docs/other-usage-of-flakes/inputs.md +++ b/docs/other-usage-of-flakes/inputs.md @@ -1,4 +1,4 @@ -## Flake inputs {#flake-inputs} +# Flake inputs {#flake-inputs} The `inputs` in `flake.nix` is an attribute set, used to specify the dependencies of the current flake, there are many types of `inputs`, for example: diff --git a/docs/other-usage-of-flakes/intro.md b/docs/other-usage-of-flakes/intro.md index cd5d406..a84402a 100644 --- a/docs/other-usage-of-flakes/intro.md +++ b/docs/other-usage-of-flakes/intro.md @@ -1,3 +1,3 @@ -## Other Usage of Flakes +# Other Usage of Flakes Up to now, we have written a lot of configurations with Flakes to manage NixOS. Here is a brief introduction to the more detailed content of the Flakes, as well as the new command lines commonly used with flakes. diff --git a/docs/other-usage-of-flakes/outputs.md b/docs/other-usage-of-flakes/outputs.md index ea0c1fb..fe64ec5 100644 --- a/docs/other-usage-of-flakes/outputs.md +++ b/docs/other-usage-of-flakes/outputs.md @@ -1,5 +1,4 @@ - -## Flake outputs +# Flake outputs the `outputs` in `flake.nix` are what a flake produces as part of its build. Each flake can have many different outputs simultaneously, including but not limited to: @@ -62,4 +61,4 @@ An example copy from NixOS Wiki: # Used by `nix flake init -t ` templates.default = { path = ""; description = ""; }; } -``` \ No newline at end of file +``` diff --git a/docs/other-usage-of-flakes/the-new-cli.md b/docs/other-usage-of-flakes/the-new-cli.md index 8e2b1be..d97aa41 100644 --- a/docs/other-usage-of-flakes/the-new-cli.md +++ b/docs/other-usage-of-flakes/the-new-cli.md @@ -1,4 +1,4 @@ -## Usage of The New CLI +# Usage of The New CLI after enabling `nix-command` & `flake`, you can use `nix help` to get all the info of [New Nix Commands][New Nix Commands], some useful examples are listed below: @@ -20,7 +20,7 @@ nix develop "github:DeterminateSystems/zero-to-nix#example" # instead of using a remote flake, you can open a bash shell using the flake located in the current directory. mkdir my-flake && cd my-flake -## init a flake with template +# init a flake with template nix flake init --template "github:DeterminateSystems/zero-to-nix#javascript-dev" # open a bash shell using the flake in current directory nix develop diff --git a/docs/the-nix-language/index.md b/docs/the-nix-language/index.md index e65526e..e9b2c43 100644 --- a/docs/the-nix-language/index.md +++ b/docs/the-nix-language/index.md @@ -1,5 +1,4 @@ - -## Basics of The Nix language +# Basics of The Nix language The Nix language is used to declare the configuration to be built by Nix, if you want to play with NixOS and Flakes and enjoy the benefits they bring, you must learn the basics of this language first. diff --git a/docs/zh/advanced-topics/index.md b/docs/zh/advanced-topics/index.md index 0171506..1d5d77e 100644 --- a/docs/zh/advanced-topics/index.md +++ b/docs/zh/advanced-topics/index.md @@ -1,4 +1,4 @@ -## 进阶玩法 {#advanced-topics} +# 进阶玩法 {#advanced-topics} 逐渐熟悉 Nix 这一套工具链后，可以进一步读一读 Nix 的三本手册，挖掘更多的玩法： diff --git a/docs/zh/best-practices/debug-with-nix-repl.md b/docs/zh/best-practices/debug-with-nix-repl.md index 6e5d498..d6a89d3 100644 --- a/docs/zh/best-practices/debug-with-nix-repl.md +++ b/docs/zh/best-practices/debug-with-nix-repl.md @@ -1,5 +1,4 @@ - -## 通过 `nix repl` 查看源码、调试配置 {#debug-via-nix-repl} +# 通过 `nix repl` 查看源码、调试配置 前面我们已经使用 `nix repl ''` 看过很多次源码了，这是一个非常强大的工具，可以帮助我们理解 Nix 的工作原理。 diff --git a/docs/zh/best-practices/intro.md b/docs/zh/best-practices/intro.md index c39e50b..db991d2 100644 --- a/docs/zh/best-practices/intro.md +++ b/docs/zh/best-practices/intro.md @@ -1,5 +1,4 @@ - -## 最佳实践 {#best-practices} +# 最佳实践 Nix 非常强大且灵活，做一件事有非常多的方法，这就导致了很难找到最合适的方法来做你的工作。 这里记录了一些我在使用 NixOS 中学习到的最佳实践，希望能帮到你。 diff --git a/docs/zh/best-practices/remote-deployment.md b/docs/zh/best-practices/remote-deployment.md index 8084236..3720fd4 100644 --- a/docs/zh/best-practices/remote-deployment.md +++ b/docs/zh/best-practices/remote-deployment.md @@ -1,5 +1,4 @@ - -## 远程部署 +# 远程部署 社区的一些工具，比如 [NixOps](https://github.com/NixOS/nixops), [deploy-rs](https://github.com/serokell/deploy-rs), 跟 [colmena](https://github.com/zhaofengli/colmena)，都可以用来部署 NixOS 配置到远程主机，但是都太复杂了，所以先全部跳过。 @@ -59,4 +58,4 @@ Host kana ```bash nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo --verbose -``` \ No newline at end of file +``` diff --git a/docs/zh/best-practices/run-downloaded-binaries-on-nixos.md b/docs/zh/best-practices/run-downloaded-binaries-on-nixos.md index b18c03b..d76fb23 100644 --- a/docs/zh/best-practices/run-downloaded-binaries-on-nixos.md +++ b/docs/zh/best-practices/run-downloaded-binaries-on-nixos.md @@ -1,4 +1,4 @@ -## 运行非 NixOS 的二进制文件 {#run-non-nixos-binaries} +# 运行非 NixOS 的二进制文件 NixOS 不遵循 FHS 标准，因此你从网上下载的二进制程序在 NixOS 上大概率是跑不了的。 为了在 NixOS 上跑这些非 NixOS 的二进制程序，需要做一些骚操作。有位老兄在这里总结了 10 种实现此目的的方法：[Different methods to run a non-nixos executable on Nixos](https://unix.stackexchange.com/questions/522822/different-methods-to-run-a-non-nixos-executable-on-nixos)，推荐一读。 @@ -55,5 +55,4 @@ $ fhs - [Tips&Tricks for NixOS Desktop - NixOS Discourse][Tips&Tricks for NixOS Desktop - NixOS Discourse]: Just as the title says, it is a collection of tips and tricks for NixOS desktop. - -[Tips&Tricks for NixOS Desktop - NixOS Discourse]: https://discourse.nixos.org/t/tips-tricks-for-nixos-desktop/28488 \ No newline at end of file +[Tips&Tricks for NixOS Desktop - NixOS Discourse]: https://discourse.nixos.org/t/tips-tricks-for-nixos-desktop/28488 diff --git a/docs/zh/best-practices/simplify-nixos-related-commands.md b/docs/zh/best-practices/simplify-nixos-related-commands.md index d5cac73..c3fc859 100644 --- a/docs/zh/best-practices/simplify-nixos-related-commands.md +++ b/docs/zh/best-practices/simplify-nixos-related-commands.md @@ -1,5 +1,4 @@ - -## 使用 Makefile 简化 NixOS 相关命令 +# 使用 Makefile 简化 NixOS 相关命令 > 注意: Makefile 的 target 名称不能与当前目录下的文件或者目录重名，否则 target 将不会被执行！ @@ -68,4 +67,4 @@ idols-debug: aqua-debug ruby-debug kana-debug ``` 将上述 Makefile 放到 NixOS 配置的根目录下，然后我们就可以使用 `make` 命令来执行相关的命令了。 -比如说我这里 `make deploy` 就是部署 NixOS 配置到本地主机，`make idols` 就是部署到我的远程主机集群。 \ No newline at end of file +比如说我这里 `make deploy` 就是部署 NixOS 配置到本地主机，`make idols` 就是部署到我的远程主机集群。 diff --git a/docs/zh/development/cross-platform-compilation.md b/docs/zh/development/cross-platform-compilation.md index fb62f82..95233fe 100644 --- a/docs/zh/development/cross-platform-compilation.md +++ b/docs/zh/development/cross-platform-compilation.md @@ -1,4 +1,4 @@ -## 跨平台编译 +# 跨平台编译 首先在任何 Linux 平台上，都有两种方法进行跨平台构建。 以在 x86_64 架构上构建 aarch64 架构程序为例，两种构建方法说明如下： @@ -14,7 +14,7 @@ 如果使用方法二，就不需要启用 binfmt_misc 了，但是需要通过交叉编译工具链来执行编译。 -### 交叉编译 +## 交叉编译 nixpkgs 包含了一系列预定义好的交叉编译工具链，其名为 `pkgsCross`，我们先通过 `nix repl` 来看看有哪些工具链： @@ -94,8 +94,7 @@ pkgsCross.mmix 模块中的 `nixpkgs.crossSystem` 参数用于将 `pkgs` 设置为交叉编译工具链，这样构建出的内容全都会是 `riscv64-linux` 架构的。 - -### 通过模拟系统进行跨平台编译 +## 通过模拟系统进行跨平台编译 第二种方法是通过模拟系统进行跨平台编译，这种方法不需要交叉编译工具链。 @@ -108,7 +107,7 @@ pkgsCross.mmix # Enable binfmt emulation. boot.binfmt.emulatedSystems = [ "aarch64-linux" "riscv64-linux" ]; - + # ...... } ``` @@ -138,7 +137,7 @@ pkgsCross.mmix 可以看到我们未添加任何额外的模块，仅仅是指定了 `system` 为 `riscv64-linux`. Nix 在构建时会自动检测当前系统是否为 `riscv64-linux`，如果不是，它会自动通过 QEMU 模拟系统进行构建，对用户而言这些底层操作完全是透明的。 -#### Linux binfmt_misc +## Linux binfmt_misc 前面只说了怎么用，如果你想了解更底层的细节，这里也简单介绍一下。 @@ -163,8 +162,7 @@ Linux 4.8 中新增“F”（fix binary，固定二进制）标志位，使 moun 总的来说，比起一般情况显式调用解释器去执行非原生架构程序，binfmt_misc 产生的一个重要意义在于透明性。有了 binfmt_misc 后，用户在执行程序时不需要再关心要用什么解释器去执行，好像任何架构的程序都能够直接执行一样，而可配置的“F”标志位更是锦上添花，使解释器程序在安装时立即就被加载进内存，后续的环境改变也不会影响执行过程。 - -### 自定义构建工具链 +## 自定义构建工具链 有时候我们会需要使用自定义的工具链进行构建，比如使用自己编译的 gcc，或者使用自己编译的 musl libc 等等，这种修改可以通过 overlays 来实现。 diff --git a/docs/zh/development/dev-environments.md b/docs/zh/development/dev-environments.md index 0b93ef7..cdb444a 100644 --- a/docs/zh/development/dev-environments.md +++ b/docs/zh/development/dev-environments.md @@ -1,4 +1,4 @@ -## Dev Environments +# Dev Environments 前面我们已经学习了构建开发环境的实现原理，但是每次都要自己写一堆重复性较高的 `flake.nix`，略显繁琐。 diff --git a/docs/zh/development/distributed-building.md b/docs/zh/development/distributed-building.md index db0a7a8..4d1df73 100644 --- a/docs/zh/development/distributed-building.md +++ b/docs/zh/development/distributed-building.md @@ -1,4 +1,4 @@ -## 分布式构建 +# 分布式构建 分布式构建可以通过多台机器来分担本地的编译压力，加快构建速度。 @@ -10,7 +10,7 @@ NixOS 官方的 cache.nixos.org 中提供了绝大多数 X86_64 架构的缓存 2. 对系统进行大量定制的用户，因为官方缓存仓库中的 packages 都是默认配置，如果你改了构建参数，那么官方缓存就不适用了，这时候就需要本地编译。 1. 比如嵌入式场景下往往对底层内核、驱动等有定制需求，导致需要本地编译。 -### 配置分布式构建 +## 配置分布式构建 官方没有详细文档讲这个，我在文末列出了一些建议阅读的参考文档，同时如下是我的分布式构建配置（一个 NixOS Module）： @@ -26,7 +26,7 @@ NixOS 官方的 cache.nixos.org 中提供了绝大多数 X86_64 架构的缓存 # set local's max-job to 0 to force remote building(disable local building) # nix.settings.max-jobs = 0; nix.distributedBuilds = true; - nix.buildMachines = + nix.buildMachines = let sshUser = "ryan"; # ssh key's path on local machine @@ -90,11 +90,11 @@ NixOS 官方的 cache.nixos.org 中提供了绝大多数 X86_64 架构的缓存 Host ai HostName 192.168.5.100 Port 22 - + Host aquamarine HostName 192.168.5.101 Port 22 - + Host ruby HostName 192.168.5.102 Port 22 @@ -137,7 +137,6 @@ NixOS 官方的 cache.nixos.org 中提供了绝大多数 X86_64 架构的缓存 3. 多机远程构建是以 Derivation 为单位的，因此在构建一些比较大的包时，其他机器可能会空闲很久，一直等这个大包构建完毕，这导致了资源的浪费。 1. 在构建的 packages 较多并且可以并行执行时，可以轻松将所有主机的 CPU 都用上，这确实非常爽。 - ## References - [Distributed build - NixOS Wiki](https://nixos.wiki/wiki/Distributed_build) diff --git a/docs/zh/development/intro.md b/docs/zh/development/intro.md index 214c794..95b5104 100644 --- a/docs/zh/development/intro.md +++ b/docs/zh/development/intro.md @@ -1,4 +1,4 @@ -## 在 NixOS 上进行开发工作 +# 在 NixOS 上进行开发工作 由于 NixOS 自身可复现的特性，它非常适合用于搭建开发环境。 但是如果你想直接将在其他发行版上的环境搭建经验用在 NixOS 上，可能会遇到许多问题，因为 NixOS 有自己的一套逻辑在，下面我们先对此稍作说明。 @@ -10,7 +10,7 @@ 在本章中我们先学习一下 Nix Flakes 开发环境的实现原理，后面的章节再按使用场景介绍一些更具体的内容。 -### 创建与使用开发环境 +## 创建与使用开发环境 在 Nix Flakes 中，我们可以通过 `pkgs.mkShell { ... }` 来定义一个项目环境，通过 `nix develop` 来打开一个该开发环境的交互式 Bash Shell. @@ -118,7 +118,7 @@ stdenv.mkDerivation ({ 建个空文件夹，将上面的配置保存为 `flake.nix`，然后执行 `nix develop`（或者更精确点，可以用 `nix develop .#default`），你会发现你已经进入了一个 nodejs 18 的开发环境，可以使用 `node` `npm` `pnpm` `yarn` 等命令了。而且刚进入时，`shellHook` 也被执行了，输出了当前 nodejs 的版本。 -### 进入任何 Nix 包的构建环境 +## 进入任何 Nix 包的构建环境 现在再来看看 `nix develop`，先读下 `nix develop --help` 输出的帮助文档： @@ -246,7 +246,7 @@ Hello, world! 这种用法的主要应用场景是调试某个 Nix 包的构建过程，或者在某个 Nix 包的构建环境中执行一些命令。 -### `nix shell` 与 `nix run` +## `nix shell` 与 `nix run` 与 `nix develop` 相比，这两个命令就简单且好理解很多了。 @@ -287,9 +287,8 @@ Hello, world! 比如说我们上面测试的包 hello，`nix run` 实际会执行 `$out/bin/hello` 这个程序。 - ## References - [pkgs.mkShell - nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell) - [A minimal nix-shell](https://fzakaria.com/2021/08/02/a-minimal-nix-shell.html) -- [One too many shell, Clearing up with nix' shells nix shell and nix-shell - Yannik Sander](https://blog.ysndr.de/posts/guides/2021-12-01-nix-shells/) \ No newline at end of file +- [One too many shell, Clearing up with nix' shells nix shell and nix-shell - Yannik Sander](https://blog.ysndr.de/posts/guides/2021-12-01-nix-shells/) diff --git a/docs/zh/development/kernel-development.md b/docs/zh/development/kernel-development.md index 2c0dda2..f056b0f 100644 --- a/docs/zh/development/kernel-development.md +++ b/docs/zh/development/kernel-development.md @@ -18,11 +18,11 @@ }; }; - outputs = inputs@{ + outputs = inputs@{ self ,nixpkgs ,thead-kernel - ,... }: + ,... }: let pkgsKernel = import nixpkgs { localSystem = "x86_64-linux"; @@ -68,7 +68,7 @@ # use `nix develop .#kernel` to enter the environment with the custom kernel build environment available. # and then use `unpackPhase` to unpack the kernel source code and cd into it. # then you can use `make menuconfig` to configure the kernel. - # + # # problem # - using `make menuconfig` - Unable to find the ncurses package. devShells.x86_64-linux.kernel = pkgsKernel.linuxPackages_thead.kernel.dev; diff --git a/docs/zh/development/packaging-101.md b/docs/zh/development/packaging-101.md index d9eef50..ce7c916 100644 --- a/docs/zh/development/packaging-101.md +++ b/docs/zh/development/packaging-101.md @@ -2,19 +2,16 @@ TODO -### 1. stdenv 构建介绍 - +## 1. stdenv 构建介绍 TODO -### 2. language specific frameworks - +## 2. language specific frameworks TODO - ## References - [NixOS 系列（三）：软件打包，从入门到放弃 - LanTian](https://lantian.pub/article/modify-computer/nixos-packaging.lantian/) - [stdenv - Nixpkgs Manual](https://github.com/NixOS/nixpkgs/tree/nixos-unstable/doc/languages-frameworks) -- [languages-frameworks - Nixpkgs Manual](https://github.com/NixOS/nixpkgs/tree/nixos-unstable/doc/stdenv) \ No newline at end of file +- [languages-frameworks - Nixpkgs Manual](https://github.com/NixOS/nixpkgs/tree/nixos-unstable/doc/stdenv) diff --git a/docs/zh/introduction/advantages-and-disadvantages.md b/docs/zh/introduction/advantages-and-disadvantages.md index 3cf66d6..e6d6109 100644 --- a/docs/zh/introduction/advantages-and-disadvantages.md +++ b/docs/zh/introduction/advantages-and-disadvantages.md @@ -1,11 +1,10 @@ -## NixOS 的优缺点 - +# NixOS 的优缺点 ## 优点 {#advantages} - 声明式配置，OS as Code，可以直接用 Git 管理配置 - NixOS 使用声明式配置来管理整个系统环境，只要你的配置文件不丢，系统就可以随时还原到任一历史状态（前面提过了，只有在 Nix 配置文件中声明了的状态才可被 NixOS 还原）。 - - 为了提升系统的可复现能力，Nix Flakes 还使用了 `flake.lock` 作为版本锁文件，它记录了所有相关数据的数据源地址、hash 值。这个设计实际是从 cargo/npm 等一些编程语言的包管理设计中借鉴来的。 + - 为了提升系统的可复现能力，Nix Flakes 还使用了 `flake.lock` 作为版本锁文件，它记录了所有相关数据的数据源地址、hash 值。这个设计实际是从 cargo/npm 等一些编程语言的包管理设计中借鉴来的。 - 与 Docker 相比，Dockerfile 实际是命令式的配置，而且也不存在版本锁这样的东西，Docker 容器环境的可复现实际依赖于直接通过 Docker Hub 分享构建结果（Docker 镜像），这可比 Dockerfile 本身大多了。 - 高度便捷的系统自定义能力 - 通过改几行配置，就可以简单地更换系统的各种组件。这是因为 Nix 将底层的复杂操作全部封装在了 Nix 软件包中，只给用户提供了简洁且必要的声明式参数。 diff --git a/docs/zh/introduction/index.md b/docs/zh/introduction/index.md index 9a1003a..7a7ca0d 100644 --- a/docs/zh/introduction/index.md +++ b/docs/zh/introduction/index.md @@ -1,5 +1,4 @@ - -## Nix 与 NixOS 简介 +# Nix 与 NixOS 简介 Nix 是一个声明式的软件包管理器，用户需要通过某些配置声明好期望的环境状态，而 Nix 负责达成这个目标。 @@ -17,8 +16,6 @@ Nix 是一个声明式的软件包管理器，用户需要通过某些配置声 因为 Nix 声明式、可复现的特性，Nix 不仅可用于管理桌面电脑的环境，也有很多人用它管理开发编译环境、云上虚拟机、容器镜像构建等等，Nix 官方的 [NixOps](https://github.com/NixOS/nixops) 与社区的 [deploy-rs](https://github.com/serokell/deploy-rs) 都是基于 Nix 实现的运维工具。 - - ## 为什么选择 NixOS？ 好几年前就听说过 Nix 包管理器，它用 Nix 语言编写配置来管理系统依赖，此外基于 Nix 包管理器设计的 Linux 发行版 NixOS，还能随时将系统回滚到任一历史状态（额实际上这个回滚有些限制，后面会介绍）。 虽然听着很牛，但是不仅要多学一门语言，装个包还得写代码，当时觉得太麻烦就没研究。 diff --git a/docs/zh/introduction/installation.md b/docs/zh/introduction/installation.md index e708118..1f1e6b8 100644 --- a/docs/zh/introduction/installation.md +++ b/docs/zh/introduction/installation.md @@ -1,4 +1,4 @@ -## 安装 NixOS +# 安装 NixOS Nix 有多种安装方式： diff --git a/docs/zh/nixos-with-flakes/downgrade-or-upgrade-packages.md b/docs/zh/nixos-with-flakes/downgrade-or-upgrade-packages.md index 0a1d63e..05fe1c9 100644 --- a/docs/zh/nixos-with-flakes/downgrade-or-upgrade-packages.md +++ b/docs/zh/nixos-with-flakes/downgrade-or-upgrade-packages.md @@ -1,5 +1,4 @@ - -## 降级与升级软件包 {#rollback-package-version} +# 降级与升级软件包 {#rollback-package-version} 在使用 Nix Flakes 后，目前大家用得比较多的都是 `nixos-unstable` 分支的 nixpkgs，有时候就会遇到一些 bug，比如我最近（2023/5/6）就遇到了 [chrome/vscode 闪退的问题](https://github.com/swaywm/sway/issues/7562)。 diff --git a/docs/zh/nixos-with-flakes/get-started-with-nixos.md b/docs/zh/nixos-with-flakes/get-started-with-nixos.md index f9d1b28..c2aecc8 100644 --- a/docs/zh/nixos-with-flakes/get-started-with-nixos.md +++ b/docs/zh/nixos-with-flakes/get-started-with-nixos.md @@ -1,4 +1,4 @@ -## 开始使用 NixOS +# 开始使用 NixOS 了解了 Nix 语言的基本用法之后，我们就可以开始使用 Nix 语言来配置 NixOS 系统了。 NixOS 的系统配置路径为 `/etc/nixos/configuration.nix`，它包含系统的所有声明式配置，如时区、语言、键盘布局、网络、用户、文件系统、启动项、桌面环境等等。 @@ -74,7 +74,6 @@ NixOS 的系统配置路径为 `/etc/nixos/configuration.nix`，它包含系统 - 系统级别的配置，可以考虑在 [Configuration - NixOS Manual](https://nixos.org/manual/nixos/unstable/index.html#ch-configuration) 找找相关文档 - 直接在 [nixpkgs](https://github.com/NixOS/nixpkgs) 仓库中搜索关键字，读相关的源码。 - ## 参考 -- [Overview of the NixOS Linux distribution]( https://nixos.wiki/wiki/Overview_of_the_NixOS_Linux_distribution) +- [Overview of the NixOS Linux distribution](https://nixos.wiki/wiki/Overview_of_the_NixOS_Linux_distribution) diff --git a/docs/zh/nixos-with-flakes/introduction-to-flakes.md b/docs/zh/nixos-with-flakes/introduction-to-flakes.md index 243b8a8..5fa597a 100644 --- a/docs/zh/nixos-with-flakes/introduction-to-flakes.md +++ b/docs/zh/nixos-with-flakes/introduction-to-flakes.md @@ -1,4 +1,4 @@ -## Flakes 简介 +# Flakes 简介 Flakes 实验特性是 Nix 项目的一项重大进展，它引入了一种管理 Nix 表达式之间的依赖关系的策略，提高了 Nix 生态系统中的可复现性、可组合性和可用性。 虽然 Flakes 仍然是一个试验性的功能，但已经被 Nix 社区广泛采用。[^1] diff --git a/docs/zh/nixos-with-flakes/modularize-the-configuration.md b/docs/zh/nixos-with-flakes/modularize-the-configuration.md index 38bb08d..776dc00 100644 --- a/docs/zh/nixos-with-flakes/modularize-the-configuration.md +++ b/docs/zh/nixos-with-flakes/modularize-the-configuration.md @@ -1,4 +1,4 @@ -## 模块化 NixOS 配置 {#modularize-nixos-configuration} +# 模块化 NixOS 配置 {#modularize-nixos-configuration} 到这里整个系统的骨架基本就配置完成了，当前我们 `/etc/nixos` 中的系统配置结构应该如下： @@ -246,7 +246,6 @@ nix-repl> outputs.nixosConfigurations.nixos-test.config.environment.systemPackag > 虽然单纯调整 `systemPackages` 的顺序没什么用，但是在其他地方可能会有用... - ## References - [Nix modules: Improving Nix's discoverability and usability ](https://cfp.nixcon.org/nixcon2020/talk/K89WJY/) diff --git a/docs/zh/nixos-with-flakes/nixos-with-flakes-enabled.md b/docs/zh/nixos-with-flakes/nixos-with-flakes-enabled.md index 89ce780..0e6d6a4 100644 --- a/docs/zh/nixos-with-flakes/nixos-with-flakes-enabled.md +++ b/docs/zh/nixos-with-flakes/nixos-with-flakes-enabled.md @@ -1,5 +1,4 @@ -## 使用 Flakes 来管理你的 NixOS - +# 使用 Flakes 来管理你的 NixOS ## 启用 NixOS 的 Flakes 支持 {#enable-nix-flakes} @@ -247,4 +246,4 @@ Nix 为了加快包构建速度，提供了 提前缓 改完后使用 `sudo nixos-rebuild switch` 应用配置即可生效，后续所有的包都会优先从国内镜像源查找缓存。 -> 注：上述手段只能加速部分包的下载，许多 inputs 数据源仍然会从 Github 拉取，另外如果找不到缓存，会执行本地构建，这通常仍然需要从国外下载源码与构建依赖，因此仍然会很慢。为了完全解决速度问题，仍然建议使用旁路由等局域网全局代理方案。 \ No newline at end of file +> 注：上述手段只能加速部分包的下载，许多 inputs 数据源仍然会从 Github 拉取，另外如果找不到缓存，会执行本地构建，这通常仍然需要从国外下载源码与构建依赖，因此仍然会很慢。为了完全解决速度问题，仍然建议使用旁路由等局域网全局代理方案。 diff --git a/docs/zh/nixos-with-flakes/other-useful-tips.md b/docs/zh/nixos-with-flakes/other-useful-tips.md index 837c22a..627c662 100644 --- a/docs/zh/nixos-with-flakes/other-useful-tips.md +++ b/docs/zh/nixos-with-flakes/other-useful-tips.md @@ -1,5 +1,4 @@ -## NixOS 的其他实用技巧 - +# NixOS 的其他实用技巧 ## 使用 Git 管理 NixOS 配置 {#git-manage-nixos-config} @@ -63,7 +62,7 @@ sudo nix store gc --debug nix-env -qa ``` -## 节约存储空间 +# 节约存储空间 如下配置可以比较好的缩减 NixOS 的磁盘占用，可以考虑将它们添加到你的 NixOS 配置中： diff --git a/docs/zh/nixos-with-flakes/start-using-home-manager.md b/docs/zh/nixos-with-flakes/start-using-home-manager.md index e6e0360..1974de2 100644 --- a/docs/zh/nixos-with-flakes/start-using-home-manager.md +++ b/docs/zh/nixos-with-flakes/start-using-home-manager.md @@ -1,4 +1,4 @@ -## 安装使用 Home Manager +# 安装使用 Home Manager 前面简单提过，NixOS 自身的配置文件只能管理系统级别的配置，而用户级别的配置则需要使用 home-manager 来管理。 diff --git a/docs/zh/nixos-with-flakes/update-the-system.md b/docs/zh/nixos-with-flakes/update-the-system.md index afdf286..2f2befc 100644 --- a/docs/zh/nixos-with-flakes/update-the-system.md +++ b/docs/zh/nixos-with-flakes/update-the-system.md @@ -1,5 +1,4 @@ - -## 更新系统 {#update-nixos-system} +# 更新系统 {#update-nixos-system} 在使用了 Nix Flakes 后，要更新系统也很简单，先更新 flake.lock 文件，然后部署即可。在配置文件夹中执行如下命令： diff --git a/docs/zh/nixpkgs/callpackage.md b/docs/zh/nixpkgs/callpackage.md index 63d4754..16fbe0a 100644 --- a/docs/zh/nixpkgs/callpackage.md +++ b/docs/zh/nixpkgs/callpackage.md @@ -1,5 +1,4 @@ -## pkgs.callPackage - +# pkgs.callPackage 前面我们介绍并大量使用了 `import xxx.nix` 来导入 Nix 文件，这种语法只是单纯地返回该文件的执行结果，不会对该结果进行进一步处理。 比如说 `xxx.nix` 的内容是形如 `{...}: {...}`，那么 `import xxx.nix` 的结果就是该文件中定义的这个函数。 @@ -34,7 +33,7 @@ modDirVersion = "5.10.113"; inherit src lib stdenv; - + # file path to the generated kernel config file(the `.config` generated by make menuconfig) # # here is a special usage to generate a file path from a string @@ -47,7 +46,7 @@ 那么就可以在任意 Nix Module 中使用 `pkgs.callPackage ./hello.nix {}` 来导入并使用它，并且替换它的任意参数。 ```nix -{ lib, pkgs, pkgsKernel, kernel-src, ... }: +{ lib, pkgs, pkgsKernel, kernel-src, ... }: { # ...... @@ -65,7 +64,6 @@ 就如上面所展示的，通过 `pkgs.callPackage` 我们可以给 `kernel.nix` 定义的函数传入不同的 `src` 与 `boardName`，来生成不同的内核包，这样就可以使用同一份 `kernel.nix` 来适配不同的内核源码与不同的开发板了。 - ## 参考 -- [Chapter 13. Callpackage Design Pattern - Nix Pills](https://nixos.org/guides/nix-pills/callpackage-design-pattern.html) \ No newline at end of file +- [Chapter 13. Callpackage Design Pattern - Nix Pills](https://nixos.org/guides/nix-pills/callpackage-design-pattern.html) diff --git a/docs/zh/nixpkgs/intro.md b/docs/zh/nixpkgs/intro.md index b09a128..012ca2c 100644 --- a/docs/zh/nixpkgs/intro.md +++ b/docs/zh/nixpkgs/intro.md @@ -1,5 +1,4 @@ - -## Nixpkgs 的高级用法 {#nixpkgs-advanced-usage} +# Nixpkgs 的高级用法 {#nixpkgs-advanced-usage} callPackage、Overriding 与 Overlays 是在使用 Nix 时偶尔会用到的技术，它们都是用来自定义 Nix 包的构建方法的。 diff --git a/docs/zh/nixpkgs/overlays.md b/docs/zh/nixpkgs/overlays.md index 38d7b38..a2b5bb8 100644 --- a/docs/zh/nixpkgs/overlays.md +++ b/docs/zh/nixpkgs/overlays.md @@ -1,4 +1,4 @@ -## Overlays +# Overlays 前面介绍的 override 函数都会生成新的 Derivation，不影响 pkgs 中原有的 Derivation，只适合作为局部参数使用。 但如果你需要覆写的 Derivation 还被其他 Nix 包所依赖，那其他 Nix 包使用的仍然会是原有的 Derivation. @@ -84,7 +84,7 @@ args: ```nix # 为了不使用默认的 rime-data，改用我自定义的小鹤音形数据，这里需要 override -# 参考 https://github.com/NixOS/nixpkgs/blob/e4246ae1e7f78b7087dce9c9da10d28d3725025f/pkgs/tools/inputmethods/fcitx5/fcitx5-rime.nix +## 参考 https://github.com/NixOS/nixpkgs/blob/e4246ae1e7f78b7087dce9c9da10d28d3725025f/pkgs/tools/inputmethods/fcitx5/fcitx5-rime.nix {pkgs, config, lib, ...}: (self: super: { @@ -167,7 +167,6 @@ args: 你可以在我的配置仓库 [ryan4yin/nix-config/v0.0.4](https://github.com/ryan4yin/nix-config/tree/v0.0.4) 查看更详细的内容，获取些灵感。 - ## 参考 -- [Chapter 3. Overlays - nixpkgs Manual](https://nixos.org/manual/nixpkgs/stable/#chap-overlays) \ No newline at end of file +- [Chapter 3. Overlays - nixpkgs Manual](https://nixos.org/manual/nixpkgs/stable/#chap-overlays) diff --git a/docs/zh/nixpkgs/overriding.md b/docs/zh/nixpkgs/overriding.md index d3b49c0..69d0caf 100644 --- a/docs/zh/nixpkgs/overriding.md +++ b/docs/zh/nixpkgs/overriding.md @@ -1,5 +1,4 @@ -## Overriding - +# Overriding 简单的说，所有 nixpkgs 中的 Nix 包都可以通过 `.override {}` 来自定义某些构建参数，它返回一个使用了自定义参数的新 Derivation. 举个例子： @@ -87,7 +86,6 @@ helloWithDebug = pkgs.hello.overrideAttrs (finalAttrs: previousAttrs: { 具体的内部参数可以通过 `nix repl ''` 然后输入 `:e stdenv.mkDerivation` 来查看其源码。 - ## 参考 -- [Chapter 4. Overriding - nixpkgs Manual](https://nixos.org/manual/nixpkgs/stable/#chap-overrides) \ No newline at end of file +- [Chapter 4. Overriding - nixpkgs Manual](https://nixos.org/manual/nixpkgs/stable/#chap-overrides) diff --git a/docs/zh/other-usage-of-flakes/inputs.md b/docs/zh/other-usage-of-flakes/inputs.md index 0235c8a..31a417f 100644 --- a/docs/zh/other-usage-of-flakes/inputs.md +++ b/docs/zh/other-usage-of-flakes/inputs.md @@ -1,5 +1,4 @@ - -## Flake 的 inputs {#flake-inputs} +# Flake 的 inputs {#flake-inputs} `flake.nix` 中的 `inputs` 是一个 attribute set，用来指定当前 Flake 的依赖，inputs 有很多种类型，举例如下： @@ -38,4 +37,4 @@ nixpkgs.url = "github:foo/bar?dir=shu"; } } -``` \ No newline at end of file +``` diff --git a/docs/zh/other-usage-of-flakes/intro.md b/docs/zh/other-usage-of-flakes/intro.md index 635758a..85da6cf 100644 --- a/docs/zh/other-usage-of-flakes/intro.md +++ b/docs/zh/other-usage-of-flakes/intro.md @@ -1,9 +1,7 @@ - -## Nix Flakes 的其他玩法 {#nix-flakes-usage} +# Nix Flakes 的其他玩法 {#nix-flakes-usage} 到这里我们已经写了不少 Nix Flakes 配置来管理 NixOS 系统了，这里再简单介绍下 Nix Flakes 更细节的内容，以及常用的 nix flake 命令。 此外 [Zero to Nix - Determinate Systems][Zero to Nix - Determinate Systems] 是一份全新的 Nix & Flake 新手入门文档，写得比较浅显易懂，也可以一读。 - -[Zero to Nix - Determinate Systems]: https://github.com/DeterminateSystems/zero-to-nix \ No newline at end of file +[Zero to Nix - Determinate Systems]: https://github.com/DeterminateSystems/zero-to-nix diff --git a/docs/zh/other-usage-of-flakes/outputs.md b/docs/zh/other-usage-of-flakes/outputs.md index 0df4a24..82ac62d 100644 --- a/docs/zh/other-usage-of-flakes/outputs.md +++ b/docs/zh/other-usage-of-flakes/outputs.md @@ -1,6 +1,4 @@ - - -## Flake 的 outputs {#flake-outputs} +# Flake 的 outputs {#flake-outputs} `flake.nix` 中的 `outputs` 是一个 attribute set，是整个 Flake 的构建结果，每个 Flake 都可以有许多不同的 outputs。 diff --git a/docs/zh/other-usage-of-flakes/the-new-cli.md b/docs/zh/other-usage-of-flakes/the-new-cli.md index c5ed663..ce8c213 100644 --- a/docs/zh/other-usage-of-flakes/the-new-cli.md +++ b/docs/zh/other-usage-of-flakes/the-new-cli.md @@ -1,5 +1,4 @@ - -## 新一代 Nix 命令行工具的使用 {#flake-commands-usage} +# 新一代 Nix 命令行工具的使用 {#flake-commands-usage} 在启用了 `nix-command` & `flakes` 功能后，我们就可以使用 Nix 提供的新一代 Nix 命令行工具 [New Nix Commands][New Nix Commands] 了，下面列举下其中常用命令的用法： @@ -22,9 +21,9 @@ nix develop "github:DeterminateSystems/zero-to-nix#example" # 除了使用远程 flake uri 之外，你也可以使用当前目录下的 flake 来创建一个开发环境。 mkdir my-flake && cd my-flake -## 通过模板初始化一个 flake +# 通过模板初始化一个 flake nix flake init --template "github:DeterminateSystems/zero-to-nix#javascript-dev" -## 使用当前目录下的 flake 创建一个开发环境，并打开一个 bash shell +# 使用当前目录下的 flake 创建一个开发环境，并打开一个 bash shell nix develop # 或者如果你的 flake 有多个 devShell 输出，你可以指定使用名为 example 的那个 nix develop .#example @@ -36,5 +35,4 @@ nix build "nixpkgs#bat" # 构建一个本地 flake 和 nix develop 是一样的，不再赘述 ``` - -[New Nix Commands]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html \ No newline at end of file +[New Nix Commands]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html diff --git a/docs/zh/the-nix-language/index.md b/docs/zh/the-nix-language/index.md index 5c6f9d3..c53f00e 100644 --- a/docs/zh/the-nix-language/index.md +++ b/docs/zh/the-nix-language/index.md @@ -1,4 +1,4 @@ -## Nix 语言入门 +# Nix 语言入门 Nix 语言是 Nix 包管理器的基础，要想玩得转 NixOS 与 Nix Flakes，享受到它们带来的诸多好处，就必须学会这门语言。