From 0991afab7d7eec658ec67fcbbbca901404cb6e85 Mon Sep 17 00:00:00 2001 From: Robert James Hernandez Date: Tue, 18 Feb 2020 17:42:22 -0800 Subject: [PATCH 1/6] Grammatical changes for pill 06 --- pills/06-our-first-derivation.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pills/06-our-first-derivation.xml b/pills/06-our-first-derivation.xml index 1156bca..eb6c529 100644 --- a/pills/06-our-first-derivation.xml +++ b/pills/06-our-first-derivation.xml @@ -151,7 +151,7 @@ - Many things are empty in that .drv, however I write a + Many things are empty in that .drv, however I'll write a summary of the .drv format for you: @@ -245,8 +245,8 @@ What's in a derivation set - I find useful to inspect the returned value from the derivation function for - you. First of all, the returned value is a plain set: + It is useful to start by inspecting the return value from the derivation function. + In this case, the returned value is a plain set: @@ -457,7 +457,7 @@ Conclusion - It's that complicated to create a package for Nix? No it's not. + Is it that complicated to create a package for Nix? No it's not. From f49d9f4848ec7a77e10bf4a4c4011a6318592953 Mon Sep 17 00:00:00 2001 From: Robert James Hernandez Date: Wed, 19 Feb 2020 19:00:45 -0800 Subject: [PATCH 2/6] Grammatical changes for pill 08 --- pills/08-generic-builders.xml | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/pills/08-generic-builders.xml b/pills/08-generic-builders.xml index 379481e..4ab190b 100644 --- a/pills/08-generic-builders.xml +++ b/pills/08-generic-builders.xml @@ -25,14 +25,14 @@ In the previous pill we packaged a simple .c file, which was being - compiled with a raw gcc call. That's not a good example of project. Many - use autotools, and since we're going to generalize our builder, better do - it with the most used build system. + compiled with a raw gcc call. That's not a good example of a project. Many + use autotools, and since we're going to generalize our builder, it would + be better do it with the most used build system. GNU hello world, - despite its name, is a simple yet complete project using autotools. + despite its name, is a simple yet complete project which uses autotools. Fetch the latest tarball here: http://ftp.gnu.org/gnu/hello/hello-2.10.tar.gz. @@ -247,15 +247,16 @@ - Finally! We got a very simple description of a package! A couple of - remarks that you may find useful to keep understanding the nix language: + Finally! We got a very simple description of a package! Below are a + couple of remarks that you may find useful as you're continuing to + understand the nix language: We assigned to pkgs the import that we did in the previous expressions - in the "with", don't be afraid. It's that straightforward. + in the "with". Don't be afraid, it's that straightforward. @@ -293,15 +294,15 @@ - Out of this we managed to create a generic builder for autotools projects, - and a function mkDerivation that composes by default the - common components used in autotools projects instead of repeating them + Out of this pill we managed to create a generic builder for autotools + projects, and a function mkDerivation that composes by default + the common components used in autotools projects instead of repeating them in all the packages we would write. - We are feeling the way a Nix system grows up: it's about creating and - composing derivations with the Nix language. + We are familiarizing ourselves with the way a Nix system grows up: it's + about creating and composing derivations with the Nix language. From d4d4a9106c133e5aeb31a5fadee6eb1b2ab6e394 Mon Sep 17 00:00:00 2001 From: Robert James Hernandez Date: Tue, 25 Feb 2020 22:23:45 -0800 Subject: [PATCH 3/6] Grammatical changes for pill 09 --- pills/09-automatic-runtime.xml | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/pills/09-automatic-runtime.xml b/pills/09-automatic-runtime.xml index 28cd197..f75afc4 100644 --- a/pills/09-automatic-runtime.xml +++ b/pills/09-automatic-runtime.xml @@ -149,8 +149,8 @@ - Not only, even after reducing the rpath the hello binary would still - depend upon gcc. Because of debugging information. For that, the well + Even after reducing the rpath the hello binary would still depend + upon gcc. This is because of debugging information. To fix is the well known strip can be used. @@ -227,9 +227,9 @@ The package is self-contained, copy its closure on another machine and - you will be able to run it. I remind you the very few components under - the /nix/store necessary to run nix - when we installed it. + you will be able to run it. Remember, only a very few components under + the /nix/store are required to + run nix. The hello binary will use that exact version of glibc library and interpreter, not the system one: @@ -248,13 +248,13 @@ Short post compared to previous ones as I'm still on vacation, but I hope you enjoyed it. Nix provides tools with cool features. In particular, Nix - is able to compute all runtime dependencies automatically for us. Not - only shared libraries, but also referenced executables, scripts, Python - libraries etc.. + is able to compute all runtime dependencies automatically for us. This is + not limited to only shared libraries, but also referenced executables, + scripts, Python libraries etc.. - This makes packages self-contained, because we're sure (apart data and + This makes packages self-contained, ensuring (apart data and configuration) that copying the runtime closure on another machine is sufficient to run the program. That's why Nix has one-click install, @@ -268,9 +268,9 @@ Next pill - ...we will introduce nix-shell. With nix-build we build derivations - always from scratch: the source gets unpacked, configured, built and - installed. But this may take a long time, think of WebKit. What if we + ...we will introduce nix-shell. With nix-build we always build + derivations from scratch: the source gets unpacked, configured, built + and installed. But this may take a long time, think of WebKit. What if we want to apply some small changes and compile incrementally instead, yet keeping a self-contained environment similar to nix-build? From 27ee505edb1d621fbb46b797275c371cf174a7ba Mon Sep 17 00:00:00 2001 From: Robert James Hernandez Date: Tue, 25 Feb 2020 23:56:29 -0800 Subject: [PATCH 4/6] Grammatical changes for pill 10 --- pills/10-developing-with-nix-shell.xml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/pills/10-developing-with-nix-shell.xml b/pills/10-developing-with-nix-shell.xml index 89a2bb0..fc2c63c 100644 --- a/pills/10-developing-with-nix-shell.xml +++ b/pills/10-developing-with-nix-shell.xml @@ -8,16 +8,16 @@ Welcome to the 10th Nix pill. In the previous - 9th pill we have seen + 9th pill we saw one of the powerful features of nix, automatic discovery of runtime dependencies and finalized the GNU hello world package. - In return from vacation, we want to hack a little the GNU hello world - program. The nix-build tool creates an isolated environment for building - the derivation, we want to do the same in order to modify some source - files of the project. + Having returned from vacation, we want to hack a little the GNU hello + world program. The nix-build tool allows for an isolated environment + while building the derivation. Additionally, we'd like the same + isolation in order to modify some source files of the project.
@@ -27,7 +27,7 @@ The nix-shell tool drops us in a shell by setting up the necessary environment - variables to hack a derivation. It does not build the derivation, it + variables to hack on a derivation. It does not build the derivation, it only serves as a preparation so that we can run the build steps manually. @@ -177,7 +177,7 @@ - It's all that straight, nix-shell builds the .drv file + It's that straightforward, nix-shell builds the .drv file and its input dependencies, then drops into a shell by setting up the environment variables necessary to build the .drv, in particular those passed to the derivation function. @@ -190,9 +190,9 @@ With nix-shell we're able to drop into an isolated environment for developing a project, with the necessary dependencies - just like nix-build does, except we can build and + just like nix-build does. Additionally, we can build and debug the project manually, step by step like you would do in any other - operating system. Note that we did never install gcc, + operating system. Note that we never installed gcc, make, etc. system-wide. These tools and libraries are available per-build. From 3ba87bf5f81bdaeb4f995568e2c0ff0bafac82f8 Mon Sep 17 00:00:00 2001 From: Robert James Hernandez Date: Mon, 2 Mar 2020 01:31:19 -0800 Subject: [PATCH 5/6] Grammatical changes for pill 11 --- pills/11-garbage-collector.xml | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/pills/11-garbage-collector.xml b/pills/11-garbage-collector.xml index 3cf34e2..c219e32 100644 --- a/pills/11-garbage-collector.xml +++ b/pills/11-garbage-collector.xml @@ -9,18 +9,18 @@ Welcome to the 11th Nix pill. In the previous 10th pill we managed to - obtain a self-contained environment for developing a project. The concept - is that whereas nix-build is able to build a derivation - in isolation, nix-shell is able to drop us in a shell - with (almost) the same environment used by nix-build. + obtain a self-contained development environment for a project. The concept + is that nix-build is able to build a derivation + in isolation, while nix-shell is able to drop us in a + shell with (almost) the same environment used by nix-build. This allows us to debug, modify and manually build software. Today we stop packaging and look at a mandatory nix component, the garbage collector. When using nix tools, often derivations are built. This include - both .drv files and out paths. These artifacts go in the nix store, and we - never cared about deleting them until now. + both .drv files and out paths. These artifacts go in the nix store, but + we've never cared about deleting them until now. @@ -28,15 +28,15 @@ How does it work - Other package managers, like dpkg, have somehow a way - to remove unused software. However, nix is much more precise compared to - other systems. + Other package managers, like dpkg, have ways of + removing unused software. Nix is much more precise in its garbage + ollection compared to these other systems. - I bet with dpkg, rpm or anything - else, you end up with having some unnecessary package installed or - dangling files. With nix this does not happen. + I bet with dpkg, rpm or similar + traditional packaging systems, you end up having some unnecessary + packages installed or dangling files. With nix this does not happen. @@ -91,7 +91,7 @@ Before playing with the GC, first run the nix garbage collector - once, so that we have a cleaned up playground for our experiments: + once, so that we have a clean playground for our experiments: @@ -126,7 +126,7 @@ - That's because the old generation is still in the nix store because it's a GC root. As we'll see below, all profiles and their generations are GC roots. + This is because the old generation is still in the nix store because it's a GC root. As we'll see below, all profiles and their generations are GC roots. @@ -164,7 +164,7 @@ Indirect roots - I remind you that building the GNU hello world package with + Remember that building the GNU hello world package with nix-build produces a result symlink in the current directory. Despite the collected garbage done above, the hello program is still working: therefore @@ -276,7 +276,7 @@ Garbage collection in Nix is a powerful mechanism to cleanup your system. - The nix-store commands allows us to know why a certain derivation is in + The nix-store commands allow us to know why a certain derivation is in the nix store. @@ -293,7 +293,7 @@ ...we will package another project and introduce what I call the "inputs" - design pattern. We only played with a single derivation until now, + design pattern. We've only played with a single derivation until now, however we'd like to start organizing a small repository of software. The "inputs" pattern is widely used in nixpkgs; it allows us to decouple derivations from the repository itself and increase customization From 1b8b37db057e80f54bf0444fc4c06903c8f710aa Mon Sep 17 00:00:00 2001 From: Robert James Hernandez Date: Wed, 4 Mar 2020 01:19:36 -0800 Subject: [PATCH 6/6] Grammatical changes for pill 12 --- pills/12-inputs-design-pattern.xml | 32 +++++++++++++++--------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/pills/12-inputs-design-pattern.xml b/pills/12-inputs-design-pattern.xml index 9f8228d..15af229 100644 --- a/pills/12-inputs-design-pattern.xml +++ b/pills/12-inputs-design-pattern.xml @@ -9,12 +9,12 @@ Welcome to the 12th Nix pill. In the previous 11th pill we stopped packaging and cleaned up the system with the garbage collector. - We restart our packaging, but we will improve a different aspect. We only packaged an hello world program so far, what if we want to create a repository of multiple packages? + We'll be resuming packaging, and improving different aspects of it. We've only packaged a hello world program so far, but what if we want to create a repository of multiple packages?
Repositories in Nix - Nix is a tool for build and deployment, it does not enforce any particular repository format. A repository of packages is the main usage for Nix, but not the only possibility. See it more like a consequence due to the need of organizing packages. + Nix is a tool for build and deployment, it does not enforce any particular repository format. A repository of packages is the main usage for Nix, but not the only possibility. It's more like a consequence due to the need of organizing packages. Nix is a language, and it is powerful enough to let you choose the format of your own repository. In this sense, it is not declarative, but functional. @@ -35,16 +35,16 @@ Before introducing the "inputs" pattern, we can start talking about another pattern first which I'd like to call "single repository" pattern. - Systems like Debian scatter packages in several small repositories. Personally, this makes it hard to track interdependent changes and to contribute to new packages. + Systems like Debian scatter packages in several small repositories. This can make it hard to track interdependent changes and to contribute to new packages. - Systems like Gentoo instead, put package descriptions all in a single repository. + Alternatively, systems like Gentoo put package descriptions all in a single repository. The nix reference for packages is nixpkgs, a single repository of all descriptions of all packages. I find this approach very natural and attractive for new contributions. - From now on, we will adopt this technique. The natural implementation in Nix is to create a top-level Nix expression, and one expression for each package. The top-level expression imports and combines all expressions in a giant attribute set with name -> package pairs. + For the rest is chapter, we will adopt the single repository technique. The natural implementation in Nix is to create a top-level Nix expression, and one expression for each package. The top-level expression imports and combines all expressions in a giant attribute set with name -> package pairs. But isn't that heavy? It isn't, because Nix is a lazy language, it evaluates only what's needed! And that's why nixpkgs is able to maintain such a big software repository in a giant attribute set. @@ -53,7 +53,7 @@
Packaging graphviz - We have packaged GNU hello world, I guess you would like to package something else for creating at least a repository of two projects :-) . I chose graphviz, which uses the standard autotools build system, requires no patching and dependencies are optional. + We have packaged GNU hello world, imagine you would like to package something else for creating at least a repository of two projects :-) . I chose graphviz, which uses the standard autotools build system, requires no patching and dependencies are optional. Download graphviz from here. The graphviz.nix expression is straightforward: @@ -64,10 +64,10 @@ - Oh of course... graphviz can't know about png. It built only the output formats it supports natively, without using any extra library. + Oh of course... graphviz doesn't know about png. It built only the output formats it supports natively, without using any extra library. - I remind you, in autotools.nix there's a buildInputs variable which gets concatenated to baseInputs. That would be the perfect place to add a build dependency. We created that variable exactly for this reason to be overridable from package expressions. + Remember, in autotools.nix there's a buildInputs variable which gets concatenated to baseInputs. That would be the perfect place to add a build dependency. We created that variable exactly for this reason to be overridable from package expressions. This 2.38 version of graphviz has several plugins to output png. For simplicity, we will use libgd. @@ -79,7 +79,7 @@ The gd, jpeg, fontconfig and bzip2 libraries (dependencies of gd) don't use pkg-config to specify which flags to pass to the compiler. Since there's no global location for libraries, we need to tell gcc and ld where to find includes and libs. - The nixpkgs provides gcc and binutils, and we are using them for our packaging. Not only, it also provides wrappers for them which allow passing extra arguments to gcc and ld, bypassing the project build systems: + The nixpkgs provides gcc and binutils, which we are currently using for our packaging. It also provides wrappers for them which allow passing extra arguments to gcc and ld, bypassing the project build systems: NIX_CFLAGS_COMPILE: extra flags to gcc at compile time NIX_LDFLAGS: extra flags to ld @@ -113,7 +113,7 @@
The repository expression - Now that we have two packages, what's a good way to put them together in a single repository? We do something like nixpkgs does. With nixpkgs, we import it and then we peek derivations by accessing the giant attribute set. + Now that we have two packages, what's a good way to put them together in a single repository? We'll do something like nixpkgs does. With nixpkgs, we import it and then we pick derivations by accessing the giant attribute set. For us nixers, this is a good technique, because it abstracts from the file names. We don't refer to a package by REPO/some/sub/dir/package.nix but by importedRepo.package (or pkgs.package in our examples). @@ -140,7 +140,7 @@ For pythoners, it is similar to __init__.py. - With nix-env, to install the package in your user environment: + With nix-env, install the package into your user environment: @@ -159,7 +159,7 @@
The inputs pattern - After a long preparation, we finally arrived. I know you have a big doubt in this moment. It's about the hello.nix and graphviz.nix. They are very, very dependent on nixpkgs: + After a long preparation, we finally arrived. I know you're having a big doubt in this moment. It's about the hello.nix and graphviz.nix. They are very, very dependent on nixpkgs: First big problem: they import nixpkgs directly. In autotools.nix instead we pass nixpkgs as an argument. That's a much better approach. Second problem: what if we want a variant of graphviz without libgd support? @@ -167,10 +167,10 @@ - The current answer to the above questions is: change the expression to match your needs (or change the callee to match your needs). + The current answers to the above questions are: change the expression to match your needs (or change the callee to match your needs). - With the inputs pattern, we choose to give another answer: let the user change the inputs of the expression (or change the caller to pass different inputs). + With the inputs pattern, we decided to provide another answer: let the user change the inputs of the expression (or change the caller to pass different inputs). By inputs of an expression, we refer to the set of derivations needed to build that expression. In this case: @@ -186,7 +186,7 @@ Goal: make package expressions independent of the repository. - How do we achieve that? The answer is simple: use functions to declare inputs for a derivation. Doing it for graphviz.nix, will make the derivation independent of the repository and customizable: + How do we achieve that? The answer is simple: use functions to declare inputs for a derivation. t for graphviz.nix, will make the derivation independent of the repository and customizable: @@ -224,7 +224,7 @@
Conclusion - The "inputs" pattern allows our expressions to be easily customizable through a set of arguments. These arguments could be flags, derivations, or whatelse. Our package expressions are functions, don't think there's any magic in there. + The "inputs" pattern allows our expressions to be easily customizable through a set of arguments. These arguments could be flags, derivations, or whatever else. Our package expressions are functions, don't think there's any magic in there. It also makes the expressions independent of the repository. Given that all the needed information is passed through arguments, it is possible to use that expression in any other context.