From 9e6982f10bd92f5fd3694f7f184c1191b34abfba Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sat, 16 Mar 2024 18:07:01 +0800 Subject: [PATCH] chore: format code via prettier (#125) --- .github/FUNDING.yml | 2 +- .github/ISSUE_TEMPLATE/bug_report.md | 13 ++-- .github/ISSUE_TEMPLATE/custom.md | 9 +-- .github/ISSUE_TEMPLATE/feature_request.md | 7 +- .github/workflows/release-pdf.yml | 78 +++++++++---------- docs/.vitepress/config.ts | 38 ++++----- docs/.vitepress/style/print.css | 10 +-- docs/.vitepress/theme/index.ts | 20 ++--- docs/.vitepress/vitepress-pdf.config.ts | 37 +++++---- docs/advanced-topics/index.md | 5 +- docs/best-practices/debugging.md | 2 - .../nix-path-and-flake-registry.md | 2 +- docs/best-practices/remote-deployment.md | 18 ++--- .../simplify-nixos-related-commands.md | 1 - docs/development/dev-environments.md | 22 +++--- docs/development/distributed-building.md | 2 +- docs/development/intro.md | 49 ++++++------ docs/development/packaging-101.md | 2 - docs/faq/index.md | 63 ++++++++------- docs/index.md | 1 + docs/introduction/index.md | 17 ++-- .../add-custom-cache-servers.md | 14 ++-- .../modularize-the-configuration.md | 5 +- .../nixos-with-flakes-enabled.md | 29 +++---- docs/nixos-with-flakes/other-useful-tips.md | 2 - .../start-using-home-manager.md | 6 +- docs/nixpkgs/callpackage.md | 6 +- docs/nixpkgs/multiple-nixpkgs.md | 2 +- docs/nixpkgs/overlays.md | 11 ++- docs/other-usage-of-flakes/inputs.md | 7 +- docs/other-usage-of-flakes/intro.md | 2 +- docs/other-usage-of-flakes/module-system.md | 2 +- docs/other-usage-of-flakes/testing.md | 2 - docs/other-usage-of-flakes/the-new-cli.md | 7 +- docs/preface.md | 6 +- docs/public/site.webmanifest | 34 ++++---- docs/the-nix-language/index.md | 7 +- docs/zh/advanced-topics/index.md | 4 - .../accelerating-dotfiles-debugging.md | 1 - docs/zh/best-practices/debugging.md | 3 - .../nix-path-and-flake-registry.md | 4 +- docs/zh/best-practices/remote-deployment.md | 19 +++-- docs/zh/development/dev-environments.md | 3 +- docs/zh/development/packaging-101.md | 3 - docs/zh/faq/index.md | 61 +++++++-------- docs/zh/index.md | 1 + docs/zh/introduction/index.md | 14 ++-- docs/zh/introduction/installation.md | 3 - .../add-custom-cache-servers.md | 3 +- .../introduction-to-flakes.md | 2 - .../modularize-the-configuration.md | 5 +- .../nixos-with-flakes-enabled.md | 2 - .../zh/nixos-with-flakes/other-useful-tips.md | 1 - .../start-using-home-manager.md | 3 - docs/zh/nixpkgs/callpackage.md | 13 ++-- docs/zh/nixpkgs/multiple-nixpkgs.md | 8 +- docs/zh/nixpkgs/overlays.md | 3 +- docs/zh/other-usage-of-flakes/intro.md | 1 - docs/zh/other-usage-of-flakes/testing.md | 2 - docs/zh/other-usage-of-flakes/the-new-cli.md | 3 +- docs/zh/preface.md | 4 - 61 files changed, 311 insertions(+), 395 deletions(-) diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index 9cd065f..77f812c 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1,3 +1,3 @@ # open_collective: nixos-and-flakes-book patreon: ryan4yin -custom: ['https://buymeacoffee.com/ryan4yin', 'https://afdian.net/a/ryan4yin'] +custom: ["https://buymeacoffee.com/ryan4yin", "https://afdian.net/a/ryan4yin"] diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 05822a2..99669f4 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,10 +1,9 @@ --- name: Bug report about: Create a report to help us improve -title: '' -labels: '' -assignees: '' - +title: "" +labels: "" +assignees: "" --- **Describe the bug** @@ -12,6 +11,7 @@ A clear and concise description of what the bug is. **To Reproduce** Steps to reproduce the behavior: + 1. Go to '...' 2. Click on '....' 3. Scroll down to '....' @@ -24,8 +24,9 @@ A clear and concise description of what you expected to happen. If applicable, add screenshots to help explain your problem. **Environment (please complete the following information):** - - NixOS Version: [e.g. 23.11] - - Nix version: [e.g. 2.18] + +- NixOS Version: [e.g. 23.11] +- Nix version: [e.g. 2.18] **Additional context** Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/custom.md b/.github/ISSUE_TEMPLATE/custom.md index 48d5f81..babf9b2 100644 --- a/.github/ISSUE_TEMPLATE/custom.md +++ b/.github/ISSUE_TEMPLATE/custom.md @@ -1,10 +1,7 @@ --- name: Custom issue template about: Describe this issue template's purpose here. -title: '' -labels: '' -assignees: '' - +title: "" +labels: "" +assignees: "" --- - - diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index bbcbbe7..2bc5d5f 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,10 +1,9 @@ --- name: Feature request about: Suggest an idea for this project -title: '' -labels: '' -assignees: '' - +title: "" +labels: "" +assignees: "" --- **Is your feature request related to a problem? Please describe.** diff --git a/.github/workflows/release-pdf.yml b/.github/workflows/release-pdf.yml index 494576e..80a1aa8 100644 --- a/.github/workflows/release-pdf.yml +++ b/.github/workflows/release-pdf.yml @@ -8,43 +8,43 @@ jobs: generate-pdf: runs-on: ubuntu-latest steps: - - name: Checkout repository - uses: actions/checkout@v4 - - name: Install nix - uses: cachix/install-nix-action@v23 - with: - nix_path: "nixpkgs=channel:nixpkgs-unstable" - extra_nix_config: | - experimental-features = nix-command flakes - access-tokens = github.com=${{ secrets.GITHUB_TOKEN }} - - name: Show nixpkgs version - run: nix-instantiate --eval -E '(import {}).lib.version' - - name: Run a command with nix develop - run: | - nix develop .#export-pdf --ignore-environment --command bash -c ' - pnpm install - pnpm export-pdf - ' - # # For debugging, upload the pdfs as artifacts - # - uses: actions/upload-artifact@v3 - # with: - # name: pdf - # path: '*.pdf' - - name: Generate changelog - run: | - # Get the previous tag - git fetch --tags - PREVIOUS_TAG=$(git tag --sort=-creatordate | head -n 2 | tail -n 1) - # Generate the changelog - git log --pretty=format:"%h %s" $PREVIOUS_TAG..HEAD > CHANGELOG + - name: Checkout repository + uses: actions/checkout@v4 + - name: Install nix + uses: cachix/install-nix-action@v23 + with: + nix_path: "nixpkgs=channel:nixpkgs-unstable" + extra_nix_config: | + experimental-features = nix-command flakes + access-tokens = github.com=${{ secrets.GITHUB_TOKEN }} + - name: Show nixpkgs version + run: nix-instantiate --eval -E '(import {}).lib.version' + - name: Run a command with nix develop + run: | + nix develop .#export-pdf --ignore-environment --command bash -c ' + pnpm install + pnpm export-pdf + ' + # # For debugging, upload the pdfs as artifacts + # - uses: actions/upload-artifact@v3 + # with: + # name: pdf + # path: '*.pdf' + - name: Generate changelog + run: | + # Get the previous tag + git fetch --tags + PREVIOUS_TAG=$(git tag --sort=-creatordate | head -n 2 | tail -n 1) + # Generate the changelog + git log --pretty=format:"%h %s" $PREVIOUS_TAG..HEAD > CHANGELOG - echo "Changelog from $PREVIOUS_TAG to HEAD:" - cat CHANGELOG - - name: Release PDF - uses: softprops/action-gh-release@v1 - if: startsWith(github.ref, 'refs/tags/') - with: - generate_release_notes: true - body_path: CHANGELOG - files: | - nixos-and-flakes-book.pdf + echo "Changelog from $PREVIOUS_TAG to HEAD:" + cat CHANGELOG + - name: Release PDF + uses: softprops/action-gh-release@v1 + if: startsWith(github.ref, 'refs/tags/') + with: + generate_release_notes: true + body_path: CHANGELOG + files: | + nixos-and-flakes-book.pdf diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 4ae74de..ad3d421 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,8 +1,8 @@ -import { createRequire } from "module"; -import { generateSitemap as sitemap } from "sitemap-ts"; -import { PageData, defineConfig } from "vitepress"; +import { createRequire } from "module" +import { generateSitemap as sitemap } from "sitemap-ts" +import { PageData, defineConfig } from "vitepress" -const require = createRequire(import.meta.url); +const require = createRequire(import.meta.url) // https://vitepress.dev/reference/site-config export default defineConfig({ @@ -18,7 +18,7 @@ export default defineConfig({ hostname: "https://nixos-and-flakes.thiscute.world/", outDir: outDir, generateRobotsTxt: true, - }); + }) }, // SEO Improvement - JSON-LD @@ -30,7 +30,7 @@ export default defineConfig({ ["script", { type: "application/ld+json" }, getJSONLD(pageData)], ], }, - }; + } }, head: [ @@ -78,14 +78,16 @@ export default defineConfig({ config: (md) => { // add support for footnote - md.use(require("markdown-it-footnote")); + md.use(require("markdown-it-footnote")) }, }, themeConfig: { footer: { - message: 'Licensed under CC BY-SA 4.0', - copyright: 'Copyright © 2023-present Ryan Yin', + message: + 'Licensed under CC BY-SA 4.0', + copyright: + 'Copyright © 2023-present Ryan Yin', }, search: { @@ -115,7 +117,7 @@ export default defineConfig({ root: themeConfigEnglish(), zh: themeConfigChinese(), }, -}); +}) function themeConfigEnglish() { return { @@ -311,7 +313,7 @@ function themeConfigEnglish() { }, ], }, - }; + } } function themeConfigChinese() { @@ -401,7 +403,7 @@ function themeConfigChinese() { items: [ { text: "简介", link: "/zh/nixpkgs/intro.md" }, { text: "callPackage", link: "/zh/nixpkgs/callpackage.md" }, - { text: "Overridding", link: "/zh/nixpkgs/overriding.md" }, + { text: "Overriding", link: "/zh/nixpkgs/overriding.md" }, { text: "Overlays", link: "/zh/nixpkgs/overlays.md" }, { text: "多 Nixpkgs 实例", @@ -506,7 +508,7 @@ function themeConfigChinese() { }, ], }, - }; + } } function getJSONLD(pageData: PageData) { @@ -518,7 +520,7 @@ function getJSONLD(pageData: PageData) { "inLanguage":"en", "description":"An unofficial and opinionated book for beginners", "name":"${pageData.title}" -}`; +}` } else if (pageData.relativePath === "zh/index.md") { return `{ "@context":"http://schema.org", @@ -527,12 +529,12 @@ function getJSONLD(pageData: PageData) { "inLanguage":"zh-CN", "description":"一份非官方的新手指南", "name":"${pageData.title}" -}`; +}` } else { - let lang = pageData.relativePath.startsWith("zh/") ? "zh-CN" : "en"; + let lang = pageData.relativePath.startsWith("zh/") ? "zh-CN" : "en" let url = `https:\/\/nixos-and-flakes.thiscute.world\/${pageData.relativePath .replace(/\.md$/, "") - .replace(/\/index\$/, "/")}`; + .replace(/\/index\$/, "/")}` return `{ "@context":"http://schema.org", "@type":"TechArticle", @@ -544,6 +546,6 @@ function getJSONLD(pageData: PageData) { }, "keywords":"NixOS, Nix, Flakes, Linux, Tutorial", "url":"${url}" -}`; +}` } } diff --git a/docs/.vitepress/style/print.css b/docs/.vitepress/style/print.css index d5d180e..f3877d5 100644 --- a/docs/.vitepress/style/print.css +++ b/docs/.vitepress/style/print.css @@ -1,7 +1,7 @@ @media print { - .VPNav, - .VPLocalNav, - .VPDocFooter { - display: none !important; - } + .VPNav, + .VPLocalNav, + .VPDocFooter { + display: none !important; + } } diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts index 5bbce72..2527783 100644 --- a/docs/.vitepress/theme/index.ts +++ b/docs/.vitepress/theme/index.ts @@ -1,22 +1,22 @@ // .vitepress/theme/index.ts -import DefaultTheme from "vitepress/theme"; -import giscusTalk from "vitepress-plugin-comment-with-giscus"; -import { useData, useRoute } from "vitepress"; +import DefaultTheme from "vitepress/theme" +import giscusTalk from "vitepress-plugin-comment-with-giscus" +import { useData, useRoute } from "vitepress" // custom CSS -import "../style/print.css"; +import "../style/print.css" export default { // Extending the Default Theme ...DefaultTheme, enhanceApp(ctx) { - DefaultTheme.enhanceApp(ctx); + DefaultTheme.enhanceApp(ctx) // ... }, setup() { // Get frontmatter and route - const { frontmatter } = useData(); - const route = useRoute(); + const { frontmatter } = useData() + const route = useRoute() // Obtain configuration from: https://giscus.app/ giscusTalk( @@ -41,7 +41,7 @@ export default { // The default is true, which means enabled, this parameter can be ignored; // If it is false, it means it is not enabled. // You can use `comment: true` preface to enable it separately on the page. - true, - ); + true + ) }, -}; +} diff --git a/docs/.vitepress/vitepress-pdf.config.ts b/docs/.vitepress/vitepress-pdf.config.ts index 60a1ae6..45aa362 100644 --- a/docs/.vitepress/vitepress-pdf.config.ts +++ b/docs/.vitepress/vitepress-pdf.config.ts @@ -1,31 +1,30 @@ -import { defineUserConfig } from "vitepress-export-pdf"; -import config from './config' - +import { defineUserConfig } from "vitepress-export-pdf" +import config from "./config" // convert `config.themeConfig?.sidebar` to a list of routes -let routeOrder = []; -const sidebar = config.locales.root.themeConfig?.sidebar; +let routeOrder = [] +const sidebar = config.locales.root.themeConfig?.sidebar if (sidebar) { sidebar.forEach((it) => { if (it.items) { it.items.forEach((subItem) => { - routeOrder.push(subItem.link.replace(/\.md$/, "")); - }); + routeOrder.push(subItem.link.replace(/\.md$/, "")) + }) } - }); + }) } // print routeOrder in terminal -console.log("routeOrder: ", routeOrder); +console.log("routeOrder: ", routeOrder) export default defineUserConfig({ - routePatterns: ["!/zh/**"], // exclude zh-CN pages - sorter: (pageA, pageB) => { - const aIndex = routeOrder.findIndex(route => route === pageA.path); - const bIndex = routeOrder.findIndex(route => route === pageB.path); - const index = aIndex - bIndex; - // console.log(`sorter: ${pageA.path} vs ${pageB.path} = ${index}`); - return index; - }, - urlOrigin: "https://nixos-and-flakes.thiscute.world/", -}); + routePatterns: ["!/zh/**"], // exclude zh-CN pages + sorter: (pageA, pageB) => { + const aIndex = routeOrder.findIndex((route) => route === pageA.path) + const bIndex = routeOrder.findIndex((route) => route === pageB.path) + const index = aIndex - bIndex + // console.log(`sorter: ${pageA.path} vs ${pageB.path} = ${index}`); + return index + }, + urlOrigin: "https://nixos-and-flakes.thiscute.world/", +}) diff --git a/docs/advanced-topics/index.md b/docs/advanced-topics/index.md index 00f8aa8..68f0a2a 100644 --- a/docs/advanced-topics/index.md +++ b/docs/advanced-topics/index.md @@ -5,12 +5,12 @@ Once you have become familiar with NixOS, you can explore advanced topics and di ## Community - [Nix Official - Community](https://nixos.org/community/): Contains information about the Nix community, forums, realtime chat, meetups, RFCs, the official team architecture, etc. -- [Nix Channel Status](https://status.nixos.org/): The build status of each Nix channel. +- [Nix Channel Status](https://status.nixos.org/): The build status of each Nix channel. - [nix-community/NUR](https://github.com/nix-community/NUR): Although Nixpkgs contains a large number of packages, some packages are not included in Nixpkgs due to reasons such as review speed and licensing agreements. NUR is a decentralized Nix package repository where anyone can create their own Nix repository and add it to NUR for others to use. If you want to use a package that is not in Nixpkgs, you can try to find it here. If you want to share your own Nix package with others, you can create and share your own Nix repository according to the README of NUR. ## Documentation and Videos -- [Eelco Dolstra - The Purely Functional Software Deployment Model - 2006](https://edolstra.github.io/pubs/phd-thesis.pdf): Eelco Dolstra's seminal PhD thesis about the Nix package manager, +- [Eelco Dolstra - The Purely Functional Software Deployment Model - 2006](https://edolstra.github.io/pubs/phd-thesis.pdf): Eelco Dolstra's seminal PhD thesis about the Nix package manager, - [Nix Reference Manual](https://nixos.org/manual/nix/stable/package-management/profiles.html): A comprehensive guide to the Nix package manager, covering its design and usage from the command line. - [nixpkgs Manual](https://nixos.org/manual/nixpkgs/unstable/): The manual for nixpkgs, which introduces its parameters, explains how to use, modify, and package Nix packages. - [NixOS Manual](https://nixos.org/manual/nixos/unstable/): A user manual for NixOS, providing configuration instructions for system-level components such as Wayland/X11 and GPU. @@ -22,7 +22,6 @@ And there are many official videos on the [NixOS Foundation](https://www.youtube - [Summer of Nix 2022 — Public Lecture Series](https://www.youtube.com/playlist?list=PLt4-_lkyRrOMWyp5G-m_d1wtTcbBaOxZk): A series of public lectures hosted by the NixOS Foundation, presented by core members of the Nix community such as Eelco Dolstra and Armijn Hemel. The content covers the development history of Nix, the history of NixOS, and the future of Nix, among other topics. - [Summer of Nix 2023 — Nix Developer Dialogues](https://www.youtube.com/playlist?list=PLt4-_lkyRrOPcBuz_tjm6ZQb-6rJjU3cf): A series of dialogues between core members of the Nix community in 2023. The content includes the evolution and architectural challenges of Nixpkgs, exploration of Nix's module system, discussion of the Nix ecosystem, AI applications in Nixpkgs, and the application of Nix in the commercial field and open source economics. - ## Advanced Techniques and Community Projects Once you are comfortable with Flakes, you can explore more advanced techniques and community projects. Here are some popular ones to try out: diff --git a/docs/best-practices/debugging.md b/docs/best-practices/debugging.md index a8b97cd..87fa59a 100644 --- a/docs/best-practices/debugging.md +++ b/docs/best-practices/debugging.md @@ -158,7 +158,6 @@ outputs.nixosConfigurations.ai.config.home-manager.users.ryan.home.file..config/ As you can see, after loading your Nix flake into the REPL, you can check every attribute of the flake. This capability is very convenient for debugging purposes. - ## Debugging functions provided by nixpkgs TODO @@ -172,4 +171,3 @@ TODO - [How to make nix build display all commands executed by make?](https://www.reddit.com/r/NixOS/comments/14stdgy/how_to_make_nix_build_display_all_commands/) - use `NIX_DEBUG=7` in derivation - [Collection of functions useful for debugging broken nix expressions.](https://github.com/NixOS/nixpkgs/blob/nixos-23.05/lib/debug.nix) - diff --git a/docs/best-practices/nix-path-and-flake-registry.md b/docs/best-practices/nix-path-and-flake-registry.md index 0411d90..7a44c7e 100644 --- a/docs/best-practices/nix-path-and-flake-registry.md +++ b/docs/best-practices/nix-path-and-flake-registry.md @@ -1,4 +1,4 @@ -# Custom NIX_PATH and Flake Registry +# Custom NIX_PATH and Flake Registry ## Introduction to NIX_PATH {#nix-path-introduction} diff --git a/docs/best-practices/remote-deployment.md b/docs/best-practices/remote-deployment.md index 5bb43d6..d27c22e 100644 --- a/docs/best-practices/remote-deployment.md +++ b/docs/best-practices/remote-deployment.md @@ -15,15 +15,15 @@ Let me briefly guide you through using colmena or `nixos-rebuild` for remote dep Before embarking on remote deployment, a few preparatory steps are necessary: 1. To prevent remote host's sudo password verification failure, choose one of the following methods: - 1. Deploy as the remote host's `root` user. - 2. Add `security.sudo.wheelNeedsPassword = false;` to the remote host's configuration and manually deploy once in advance to grant the user passwordless sudo permissions.. - 1. **This will allow user-level programs to silently obtain sudo permissions, posing a security risk**! Therefore, if you choose this method, it's advisable to create a dedicated user for remote deployment, rather than using your regular user account! + 1. Deploy as the remote host's `root` user. + 2. Add `security.sudo.wheelNeedsPassword = false;` to the remote host's configuration and manually deploy once in advance to grant the user passwordless sudo permissions.. + 1. **This will allow user-level programs to silently obtain sudo permissions, posing a security risk**! Therefore, if you choose this method, it's advisable to create a dedicated user for remote deployment, rather than using your regular user account! 2. Configure SSH public key authentication for the remote hosts. - 1. Use the `users.users..openssh.authorizedKeys.keys` option to complete this task. -1. Add the remote host's Known Hosts record to your local machine. Otherwise, colmena/nixos-rebuild will fail to deploy due to the inability to verify the remote host's identity. - 1. Use the `programs.ssh.knownHosts` option to add the remote host's public key to the Known Hosts record. -1. Manually use the `ssh root@` command to verify that you can login to the remote host. - 1. If you encounter any issues, resolve them before proceeding. + 1. Use the `users.users..openssh.authorizedKeys.keys` option to complete this task. +3. Add the remote host's Known Hosts record to your local machine. Otherwise, colmena/nixos-rebuild will fail to deploy due to the inability to verify the remote host's identity. + 1. Use the `programs.ssh.knownHosts` option to add the remote host's public key to the Known Hosts record. +4. Manually use the `ssh root@` command to verify that you can login to the remote host. + 1. If you encounter any issues, resolve them before proceeding. It's advisable to use the `root` user for deployment as it's more convenient and avoids the complexities of sudo permissions. @@ -99,7 +99,7 @@ In your system's `flake.nix`, add a new outputs named `colmena`. A simple exampl Now you can deploy your configuration to the device: ```bash -nix run nixpkgs#colmena apply +nix run nixpkgs#colmena apply ``` For more advanced usage, refer to colmena's official documentation at diff --git a/docs/best-practices/simplify-nixos-related-commands.md b/docs/best-practices/simplify-nixos-related-commands.md index b958778..7622e30 100644 --- a/docs/best-practices/simplify-nixos-related-commands.md +++ b/docs/best-practices/simplify-nixos-related-commands.md @@ -77,7 +77,6 @@ idols: aqua ruby kana idols-debug: aqua-debug ruby-debug kana-debug ``` - By Save this `Justfile` to the root directory of your Nix flake. Then, I can use `just deploy` to deploy the configuration to my local machine, and `just idols` to deploy the configuration to all my remote servers. This approach simplifies the execution of NixOS commands by abstracting them behind target names in the Justfile, providing a more user-friendly and convenient experience. diff --git a/docs/development/dev-environments.md b/docs/development/dev-environments.md index 04d362b..3e1b0d8 100644 --- a/docs/development/dev-environments.md +++ b/docs/development/dev-environments.md @@ -7,21 +7,20 @@ Luckily, some people in the community have done this for us. The following repos - [dev-templates](https://github.com/the-nix-way/dev-templates) - [MordragT/nix-templates](https://github.com/MordragT/nix-templates) -If you think the structure of `flake.nix` is still too complicated and want a simpler way, +If you think the structure of `flake.nix` is still too complicated and want a simpler way, you can consider using the following project, which encapsulates Nix more thoroughly and provides users with a simpler definition: - [cachix/devenv](https://github.com/cachix/devenv) - -If you don't want to write a single line of nix code and just want to get a reproducible development environment with minimal cost, +If you don't want to write a single line of nix code and just want to get a reproducible development environment with minimal cost, here's a tool that might meet your needs: - [jetpack-io/devbox](https://github.com/jetpack-io/devbox) ## Dev Environment for Python -The development environment for Python is much more cumbersome compared to languages like Java or Go because it defaults to installing software in the global environment. +The development environment for Python is much more cumbersome compared to languages like Java or Go because it defaults to installing software in the global environment. To install software for the current project, you must create a virtual environment first (unlike in languages such as JavaScript or Go, where virtual environments are not necessary). This behavior is very unfriendly for Nix. @@ -42,10 +41,10 @@ note: If you believe this is a mistake, please contact your Python installation hint: See PEP 668 for the detailed specification. ``` -Based on the error message, `pip install` is directly disabled by NixOS. Even when attempting `pip install --user`, it is similarly disabled. -To improve the reproducibility of the environment, Nix eliminates these commands altogether. -Even if we create a new environment using methods like `mkShell`, -these commands still result in errors (presumably because the pip command in Nixpkgs itself has +Based on the error message, `pip install` is directly disabled by NixOS. Even when attempting `pip install --user`, it is similarly disabled. +To improve the reproducibility of the environment, Nix eliminates these commands altogether. +Even if we create a new environment using methods like `mkShell`, +these commands still result in errors (presumably because the pip command in Nixpkgs itself has been modified to prevent any modification instructions like `install` from running). However, many project installation scripts are based on pip, which means these scripts cannot be used directly. @@ -66,8 +65,8 @@ This can be achieved by directly installing the dependencies from `requirements. There are existing Nix packaging tools available to assist with this: > Note that even in these environments, running commands like `pip install` directly will still fail. -Python dependencies must be installed through `flake.nix` because the data is located in the `/nix/store` directory, -and these modification commands can only be executed during the Nix build phase. +> Python dependencies must be installed through `flake.nix` because the data is located in the `/nix/store` directory, +> and these modification commands can only be executed during the Nix build phase. - [DavHau/mach-nix](https://github.com/DavHau/mach-nix) (currently unmaintained) - [poetry2nix](https://github.com/nix-community/poetry2nix) @@ -75,8 +74,5 @@ and these modification commands can only be executed during the Nix build phase. The advantage of these tools is that they utilize the lock mechanism of Nix Flakes to improve reproducibility. However, the downside is that they add an extra layer of abstraction, making the underlying system more complex. - Finally, in some more complex projects, neither of the above solutions may be feasible. In such cases, the best solution is to use containers such as Docker or Podman. Containers have fewer restrictions compared to Nix and can provide the best compatibility. - - diff --git a/docs/development/distributed-building.md b/docs/development/distributed-building.md index d794a18..13e124d 100644 --- a/docs/development/distributed-building.md +++ b/docs/development/distributed-building.md @@ -139,4 +139,4 @@ Here are some observed issues and limitations: - [Document available system features - nix#7380](https://github.com/NixOS/nix/issues/7380) - [Distributed builds seem to disable local builds - nix#2589](https://github.com/NixOS/nix/issues/2589) - [Offloading NixOS builds to a faster machine](https://sgt.hootr.club/molten-matter/nix-distributed-builds/) -- [tests/nixos/remote-builds.nix - Nix Source Code](https://github.com/NixOS/nix/blob/713836112/tests/nixos/remote-builds.nix#L46) \ No newline at end of file +- [tests/nixos/remote-builds.nix - Nix Source Code](https://github.com/NixOS/nix/blob/713836112/tests/nixos/remote-builds.nix#L46) diff --git a/docs/development/intro.md b/docs/development/intro.md index 30bd945..a85d269 100644 --- a/docs/development/intro.md +++ b/docs/development/intro.md @@ -140,14 +140,12 @@ Here is a `flake.nix` that defines a development environment with Node.js 18 ins 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`), the current version of nodejs will be outputted, and now you can use `node` `pnpm` `yarn` seamlessly. - ## Using zsh/fish/... instead of bash `pkgs.mkShell` uses `bash` by default, but you can also use `zsh` or `fish` by add `exec ` into `shellHook`. Here is an example: - ```nix { description = "A Nix-flake-based Node.js development environment"; @@ -185,7 +183,6 @@ Here is an example: With the above configuration, `nix develop` will enter the REPL environment of nushell. - ## Creating a Development Environment with `pkgs.runCommand` The derivation created by `pkgs.mkShell` cannot be used directly, but must be accessed via `nix develop`. @@ -270,7 +267,6 @@ Related source code: - [pkgs/build-support/trivial-builders/default.nix - runCommand](https://github.com/NixOS/nixpkgs/blob/nixos-23.11/pkgs/build-support/trivial-builders/default.nix#L21-L49) - [pkgs/build-support/setup-hooks/make-wrapper.sh](https://github.com/NixOS/nixpkgs/blob/nixos-23.11/pkgs/build-support/setup-hooks/make-wrapper.sh) - ## 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`: @@ -410,30 +406,30 @@ Here's an example: nix build "nixpkgs#ponysay" # Use the built 'ponysay' command › ./result/bin/ponysay 'hey buddy!' - ____________ + ____________ < hey buddy! > - ------------ - \ - \ - \ - ▄▄ ▄▄ ▄ ▄ - ▀▄▄▄█▄▄▄▄▄█▄▄▄ - ▀▄███▄▄██▄██▄▄██ - ▄██▄███▄▄██▄▄▄█▄██ - █▄█▄██▄█████████▄██ - ▄▄█▄█▄▄▄▄▄████████ - ▀▀▀▄█▄█▄█▄▄▄▄▄█████ ▄ ▄ - ▀▄████▄▄▄█▄█▄▄██ ▄▄▄▄▄█▄▄▄ - █▄██▄▄▄▄███▄▄▄██ ▄▄▄▄▄▄▄▄▄█▄▄ - ▀▄▄██████▄▄▄████ █████████████ - ▀▀▀▀▀█████▄▄ ▄▄▄▄▄▄▄▄▄▄██▄█▄▄▀ - ██▄███▄▄▄▄█▄▄▀ ███▄█▄▄▄█▀ - █▄██▄▄▄▄▄████ ███████▄██ - █▄███▄▄█████ ▀███▄█████▄ - ██████▀▄▄▄█▄█ █▄██▄▄█▄█▄ - ███████ ███████ ▀████▄████ + ------------ + \ + \ + \ + ▄▄ ▄▄ ▄ ▄ + ▀▄▄▄█▄▄▄▄▄█▄▄▄ + ▀▄███▄▄██▄██▄▄██ + ▄██▄███▄▄██▄▄▄█▄██ + █▄█▄██▄█████████▄██ + ▄▄█▄█▄▄▄▄▄████████ + ▀▀▀▄█▄█▄█▄▄▄▄▄█████ ▄ ▄ + ▀▄████▄▄▄█▄█▄▄██ ▄▄▄▄▄█▄▄▄ + █▄██▄▄▄▄███▄▄▄██ ▄▄▄▄▄▄▄▄▄█▄▄ + ▀▄▄██████▄▄▄████ █████████████ + ▀▀▀▀▀█████▄▄ ▄▄▄▄▄▄▄▄▄▄██▄█▄▄▀ + ██▄███▄▄▄▄█▄▄▀ ███▄█▄▄▄█▀ + █▄██▄▄▄▄▄████ ███████▄██ + █▄███▄▄█████ ▀███▄█████▄ + ██████▀▄▄▄█▄█ █▄██▄▄█▄█▄ + ███████ ███████ ▀████▄████ ▀▀█▄▄▄▀ ▀▀█▄▄▄▀ ▀██▄▄██▀█ - ▀ ▀▀█ + ▀ ▀▀█ ``` ## Using `nix profile` to manage development environments and entertainment environments @@ -458,4 +454,3 @@ There are other commands like `nix flake init`, which you can explore in [New Ni - [Shell Scripts - NixOS Wiki](https://nixos.wiki/wiki/Shell_Scripts) [New Nix Commands]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html - diff --git a/docs/development/packaging-101.md b/docs/development/packaging-101.md index 5c31cd0..e28775d 100644 --- a/docs/development/packaging-101.md +++ b/docs/development/packaging-101.md @@ -2,7 +2,6 @@ WIP work in progress, please refer to the following reference documents to learn Nix packaging. - ## 参考文档 - [NixOS Series 3: Software Packaging 101](https://lantian.pub/en/article/modify-computer/nixos-packaging.lantian/) @@ -19,4 +18,3 @@ WIP work in progress, please refer to the following reference documents to learn - FHS related - [pkgs/build-support/build-fhsenv-bubblewrap/buildFHSEnv.nix](https://github.com/NixOS/nixpkgs/blob/nixos-23.11/pkgs/build-support/build-fhsenv-bubblewrap/buildFHSEnv.nix): `pkgs.buildFHSEnvBubblewrap` - [pkgs/build-support/build-fhsenv-chroot/default.nix](https://github.com/NixOS/nixpkgs/blob/nixos-23.11/pkgs/build-support/build-fhsenv-bubblewrap/buildFHSEnv.nix): `pkgs.buildFHSEnvChroot` - diff --git a/docs/faq/index.md b/docs/faq/index.md index 1532003..c347dd9 100644 --- a/docs/faq/index.md +++ b/docs/faq/index.md @@ -19,7 +19,7 @@ When compared to widely used traditional tools like Ansible, Nix has the followi 1. One of the biggest problems with this Ansible is that each deployment is based on incremental changes to the current state of the system. The current state of the system, like the snapshots mentioned above, is not interpretable and is difficult to reproduce. NixOS declares the target state of the system through its configuration files, so that the deployment result is independent of the current state of the system, and repeated deployments will not cause any problems. 2. Nix Flakes uses a version lock file `flake.lock` to lock the hash value, version number, data source and other information of all dependencies, which greatly improves the reproducibility of the system. Traditional tools like Ansible don't have this feature, so they're not very reproducible. 1. This is why Docker is so popular - it provides, at a fraction of the cost, a **reproducible system environment on a wide range of machines** that traditional Ops tools like Ansible don't. -1. Nix provides a high degree of ease of system customization by shielding the underlying implementation details with a layer of declarative abstraction so that users only need to care about their core requirements. Tools like Ansible have much weaker abstractions. +3. Nix provides a high degree of ease of system customization by shielding the underlying implementation details with a layer of declarative abstraction so that users only need to care about their core requirements. Tools like Ansible have much weaker abstractions. 1. If you've ever used a declarative configuration tool like terraform/kubernetes, this should be easy to understand. The more complex the requirements, the greater the benefit of declarative configuration. ## What are the advantages of Nix compared to Docker container technology? @@ -71,7 +71,7 @@ this will cause the following error: ```bash error: builder for '/nix/store/n3scj3s7v9jsb6y3v0fhndw35a9hdbs6-home-manager-path.drv' failed with exit code 25; last 1 log lines: - > error: collision between `/nix/store/kvq0gvz6jwggarrcn9a8ramsfhyh1h9d-lldb-14.0.6/lib/python3.11/site-packages/six.py' + > error: collision between `/nix/store/kvq0gvz6jwggarrcn9a8ramsfhyh1h9d-lldb-14.0.6/lib/python3.11/site-packages/six.py' and `/nix/store/370s8inz4fc9k9lqk4qzj5vyr60q166w-python3-3.11.6-env/lib/python3.11/site-packages/six.py' For full logs, run 'nix log /nix/store/n3scj3s7v9jsb6y3v0fhndw35a9hdbs6-home-manager-path.drv'. ``` @@ -79,35 +79,34 @@ and `/nix/store/370s8inz4fc9k9lqk4qzj5vyr60q166w-python3-3.11.6-env/lib/python3. Here are some solutions: 1. Split the two packages into two different **profiles**. For example, you can install `lldb` via `environment.systemPackages` and `python311` via `home.packages`. -2. Different versions of Python3 are treated as different packages, so you can change your custom Python3 version to `python310` to avoid the conflict. -2. Use `override` to override the version of the library used by the package to be consistent with the version used by the other package. +2. Different versions of Python3 are treated as different packages, so you can change your custom Python3 version to `python310` to avoid the conflict. +3. Use `override` to override the version of the library used by the package to be consistent with the version used by the other package. - ```nix - { - # as a nixos module - # environment.systemPackages = with pkgs; [ - # - # or as a home manager module - home.packages = let - custom-python3 = (pkgs.python311.withPackages (ps: - with ps; [ - ipython - pandas - requests - pyquery - pyyaml - ] - )); - in - with pkgs; [ - # override the version of python3 - # NOTE: This will trigger a rebuild of lldb, it takes time - (lldb.override { - python3 = custom-python3; - }) - - custom-python3 - ]; - } - ``` +```nix +{ + # as a nixos module + # environment.systemPackages = with pkgs; [ + # + # or as a home manager module + home.packages = let + custom-python3 = (pkgs.python311.withPackages (ps: + with ps; [ + ipython + pandas + requests + pyquery + pyyaml + ] + )); + in + with pkgs; [ + # override the version of python3 + # NOTE: This will trigger a rebuild of lldb, it takes time + (lldb.override { + python3 = custom-python3; + }) + custom-python3 + ]; +} +``` diff --git a/docs/index.md b/docs/index.md index 7f4b971..3ac0a87 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,6 +29,7 @@ hero: # - title: Feature C # details: Lorem ipsum dolor sit amet, consectetur adipiscing elit --- +