NixOS/nix-pills
NixOS/nix-pills
1
0
Fork 0
mirror of https://github.com/NixOS/nix-pills synced 2024-09-19 04:00:13 -04:00
Code Activity

Merge pull request #129 from sarcasticadmin/sa/reading-corrections-1

Browse source 
Grammar suggestions for pills 6-12
This commit is contained in:
Wael Nasreddine 2020-03-09 22:51:18 -07:00 committed by GitHub
parent b1c0f7c896 cb4781d9f4
commit c3a2df2160
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 71 additions and 70 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
pills/06-our-first-derivation.xml
View file

@ -151,7 +151,7 @@
</para>
<para>
Many things are empty in that <filename>.drv</filename>, however I write a
Many things are empty in that <filename>.drv</filename>, however I'll write a
summary of the <link
xlink:href="http://nixos.org/~eelco/pubs/phd-thesis.pdf">.drv format</link>
for you:
@ -245,8 +245,8 @@
<title>What's in a derivation set</title>
<para>
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:
</para>
<screen><xi:include href="./06/inspect-values.txt" parse="text" /></screen>
@ -457,7 +457,7 @@
<title>Conclusion</title>
<para>
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.
</para>
<para>

25
pills/08-generic-builders.xml
View file

@ -25,14 +25,14 @@
<para>
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.
</para>
<para>
<link xlink:href="http://www.gnu.org/software/hello/">GNU hello world</link>,
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:
<link xlink:href="http://ftp.gnu.org/gnu/hello/hello-2.10.tar.gz">http://ftp.gnu.org/gnu/hello/hello-2.10.tar.gz</link>.
</para>
@ -247,15 +247,16 @@
<screen><xi:include href="./08/hello-nix-rev-2.txt" parse="text" /></screen>
<para>
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:
</para>
<itemizedlist>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
@ -293,15 +294,15 @@
</para>
<para>
Out of this we managed to create a generic builder for autotools projects,
and a function <code>mkDerivation</code> 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 <code>mkDerivation</code> that composes by default
the common components used in autotools projects instead of repeating them
in all the packages we would write.
</para>
<para>
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.
</para>
<para>

24
pills/09-automatic-runtime.xml
View file

@ -149,8 +149,8 @@
</para>
<para>
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 <command>strip</command> can be used.
</para>
</section>
@ -227,9 +227,9 @@
<para>
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 <filename>/nix/store</filename> necessary to run nix
<link linkend="install-on-your-running-system">when we installed it</link>.
you will be able to run it. Remember, only a very few components under
the <filename>/nix/store</filename> are required to
<link linkend="install-on-your-running-system">run nix</link>.
The hello binary will use that exact version of glibc library and
interpreter, not the system one:
</para>
@ -248,13 +248,13 @@
<para>
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..
</para>
<para>
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
<link xlink:href="https://nixos.org/nix/manual/#ch-relnotes-0.8">one-click install</link>,
@ -268,9 +268,9 @@
<title>Next pill</title>
<para>
...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?
</para>

18
pills/10-developing-with-nix-shell.xml
View file

@ -8,16 +8,16 @@
<para>
Welcome to the 10th Nix pill. In the previous
<link linkend="automatic-runtime-dependencies">9th pill</link> we have seen
<link linkend="automatic-runtime-dependencies">9th pill</link> we saw
one of the powerful features of nix, automatic discovery of runtime
dependencies and finalized the GNU hello world package.
</para>
<para>
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.
</para>
<section>
@ -27,7 +27,7 @@
The <link
xlink:href="https://nixos.org/nix/manual/#sec-nix-shell">nix-shell</link>
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.
</para>
@ -177,7 +177,7 @@
</para>
<para>
It's all that straight, <command>nix-shell</command> builds the .drv file
It's that straightforward, <command>nix-shell</command> 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 @@
<para>
With <command>nix-shell</command> we're able to drop into an isolated
environment for developing a project, with the necessary dependencies
just like <command>nix-build</command> does, except we can build and
just like <command>nix-build</command> 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 <command>gcc</command>,
operating system. Note that we never installed <command>gcc</command>,
<command>make</command>, etc. system-wide. These tools and libraries are
available per-build.
</para>

34
pills/11-garbage-collector.xml
View file

@ -9,18 +9,18 @@
<para>
Welcome to the 11th Nix pill. In the previous
<link linkend="developing-with-nix-shell">10th pill</link> we managed to
obtain a self-contained environment for developing a project. The concept
is that whereas <command>nix-build</command> is able to build a derivation
in isolation, <command>nix-shell</command> is able to drop us in a shell
with (almost) the same environment used by <command>nix-build</command>.
obtain a self-contained development environment for a project. The concept
is that <command>nix-build</command> is able to build a derivation
in isolation, while <command>nix-shell</command> is able to drop us in a
shell with (almost) the same environment used by <command>nix-build</command>.
This allows us to debug, modify and manually build software.
</para>
<para>
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.
</para>
@ -28,15 +28,15 @@
<title>How does it work</title>
<para>
Other package managers, like <command>dpkg</command>, have somehow a way
to remove unused software. However, nix is much more precise compared to
other systems.
Other package managers, like <command>dpkg</command>, have ways of
removing unused software. Nix is much more precise in its garbage
ollection compared to these other systems.
</para>
<para>
I bet with <command>dpkg</command>, <command>rpm</command> or anything
else, you end up with having some unnecessary package installed or
dangling files. With nix this does not happen.
I bet with <command>dpkg</command>, <command>rpm</command> or similar
traditional packaging systems, you end up having some unnecessary
packages installed or dangling files. With nix this does not happen.
</para>
@ -91,7 +91,7 @@
<para>
Before playing with the GC, first run the
<link xlink:href="http://nixos.org/nix/manual/#sec-nix-collect-garbage">nix garbage collector</link>
once, so that we have a cleaned up playground for our experiments:
once, so that we have a clean playground for our experiments:
</para>
<screen><xi:include href="./11/nix-collect-garbage.txt" parse="text" /></screen>
@ -126,7 +126,7 @@
<screen><xi:include href="./11/remove-bsd-games.txt" parse="text" /></screen>
<para>
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.
</para>
<para>
@ -164,7 +164,7 @@
<title>Indirect roots</title>
<para>
I remind you that building the GNU hello world package with
Remember that building the GNU hello world package with
<command>nix-build</command> produces a <filename>result</filename>
symlink in the current directory. Despite the collected garbage done
above, the <command>hello</command> program is still working: therefore
@ -276,7 +276,7 @@
<para>
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.
</para>
@ -293,7 +293,7 @@
<para>
...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

32
pills/12-inputs-design-pattern.xml
View file

@ -9,12 +9,12 @@
Welcome to the 12th Nix pill. In the previous <link linkend="garbage-collector">11th pill</link> we stopped packaging and cleaned up the system with the garbage collector.
</para>
<para>
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?
</para>
<section>
<title>Repositories in Nix</title>
<para>
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.
</para>
<para>
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 "<literal>inputs</literal>" pattern, we can start talking about another pattern first which I'd like to call "<literal>single repository</literal>" pattern.
</para>
<para>
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.
</para>
<para>
Systems like Gentoo instead, put package descriptions all in a single repository.
Alternatively, systems like Gentoo put package descriptions all in a single repository.
</para>
<para>
The nix reference for packages is <link xlink:href="https://github.com/NixOS/nixpkgs">nixpkgs</link>, a single repository of all descriptions of all packages. I find this approach very natural and attractive for new contributions.
</para>
<para>
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.
</para>
<para>
But isn't that heavy? It isn't, because Nix is a lazy language, it evaluates only what's needed! And that's why <literal>nixpkgs</literal> is able to maintain such a big software repository in a giant attribute set.
@ -53,7 +53,7 @@
<section>
<title>Packaging graphviz</title>
<para>
We have packaged <package>GNU hello world</package>, I guess you would like to package something else for creating at least a repository of two projects :-) . I chose <package>graphviz</package>, which uses the standard autotools build system, requires no patching and dependencies are optional.
We have packaged <package>GNU hello world</package>, imagine you would like to package something else for creating at least a repository of two projects :-) . I chose <package>graphviz</package>, which uses the standard autotools build system, requires no patching and dependencies are optional.
</para>
<para>
Download <package>graphviz</package> from <link xlink:href="http://pkgs.fedoraproject.org/repo/pkgs/graphviz/graphviz-2.38.0.tar.gz/5b6a829b2ac94efcd5fa3c223ed6d3ae/graphviz-2.38.0.tar.gz">here</link>. The <filename>graphviz.nix</filename> expression is straightforward:
@ -64,10 +64,10 @@
</para>
<screen><xi:include href="./12/simple-png.txt" parse="text" /></screen>
<para>
Oh of course... <package>graphviz</package> can't know about png. It built only the output formats it supports natively, without using any extra library.
Oh of course... <package>graphviz</package> doesn't know about png. It built only the output formats it supports natively, without using any extra library.
</para>
<para>
I remind you, in <filename>autotools.nix</filename> there's a <literal>buildInputs</literal> variable which gets concatenated to <literal>baseInputs</literal>. 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 <filename>autotools.nix</filename> there's a <literal>buildInputs</literal> variable which gets concatenated to <literal>baseInputs</literal>. 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.
</para>
<para>
This 2.38 version of <package>graphviz</package> has several plugins to output png. For simplicity, we will use <package>libgd</package>.
@ -79,7 +79,7 @@
The <package>gd</package>, <package>jpeg</package>, <package>fontconfig</package> and <package>bzip2</package> libraries (dependencies of <package>gd</package>) don't use <command>pkg-config</command> to specify which flags to pass to the compiler. Since there's no global location for libraries, we need to tell <command>gcc</command> and <command>ld</command> where to find includes and libs.
</para>
<para>
The <literal>nixpkgs</literal> provides <package>gcc</package> and <package>binutils</package>, and we are using them for our packaging. Not only, it also <link xlink:href="http://nixos.org/nixpkgs/manual/#ssec-setup-hooks">provides wrappers</link> for them which allow passing extra arguments to <command>gcc</command> and <command>ld</command>, bypassing the project build systems:
The <literal>nixpkgs</literal> provides <package>gcc</package> and <package>binutils</package>, which we are currently using for our packaging. It also <link xlink:href="http://nixos.org/nixpkgs/manual/#ssec-setup-hooks">provides wrappers</link> for them which allow passing extra arguments to <command>gcc</command> and <command>ld</command>, bypassing the project build systems:
<itemizedlist>
<listitem><para><varname>NIX_CFLAGS_COMPILE</varname>: extra flags to <command>gcc</command> at compile time</para></listitem>
<listitem><para><varname>NIX_LDFLAGS</varname>: extra flags to <command>ld</command></para></listitem>
@ -113,7 +113,7 @@
<section>
<title>The repository expression</title>
<para>
Now that we have two packages, what's a good way to put them together in a single repository? We do something like <literal>nixpkgs</literal> does. With <literal>nixpkgs</literal>, we <literal>import</literal> 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 <literal>nixpkgs</literal> does. With <literal>nixpkgs</literal>, we <literal>import</literal> it and then we pick derivations by accessing the giant attribute set.
</para>
<para>
For us nixers, this is a good technique, because it abstracts from the file names. We don't refer to a package by <filename>REPO/some/sub/dir/package.nix</filename> but by <literal>importedRepo.package</literal> (or <literal>pkgs.package</literal> in our examples).
@ -140,7 +140,7 @@
For pythoners, it is similar to <filename>__init__.py</filename>.
</para>
<para>
With <command>nix-env</command>, to install the package in your user environment:
With <command>nix-env</command>, install the package into your user environment:
</para>
<screen><xi:include href="./12/nix-env-install-graphviz.txt" parse="text" /></screen>
<para>
@ -159,7 +159,7 @@
<section>
<title>The inputs pattern</title>
<para>
After a long preparation, we finally arrived. I know you have a big doubt in this moment. It's about the <filename>hello.nix</filename> and <filename>graphviz.nix</filename>. They are very, very dependent on <literal>nixpkgs</literal>:
After a long preparation, we finally arrived. I know you're having a big doubt in this moment. It's about the <filename>hello.nix</filename> and <filename>graphviz.nix</filename>. They are very, very dependent on <literal>nixpkgs</literal>:
<itemizedlist>
<listitem><para>First big problem: they import <literal>nixpkgs</literal> directly. In <filename>autotools.nix</filename> instead we pass <literal>nixpkgs</literal> as an argument. That's a much better approach.</para></listitem>
<listitem><para>Second problem: what if we want a variant of <package>graphviz</package> without <package>libgd</package> support?</para></listitem>
@ -167,10 +167,10 @@
</itemizedlist>
</para>
<para>
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).
</para>
<para>
With the <literal>inputs</literal> pattern, we choose to give another answer: let the user change the <literal>inputs</literal> of the expression (or change the caller to pass different inputs).
With the <literal>inputs</literal> pattern, we decided to provide another answer: let the user change the <literal>inputs</literal> of the expression (or change the caller to pass different inputs).
</para>
<para>
By inputs of an expression, we refer to the set of derivations needed to build that expression. In this case:
@ -186,7 +186,7 @@
<emphasis role="underline">Goal:</emphasis> make package expressions independent of the repository.
</para>
<para>
How do we achieve that? The answer is simple: use functions to declare inputs for a derivation. Doing it for <filename>graphviz.nix</filename>, 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 <filename>graphviz.nix</filename>, will make the derivation independent of the repository and customizable:
</para>
<screen><xi:include href="./12/graphviz-mkderivation.txt" parse="text" /></screen>
<para>
@ -224,7 +224,7 @@
<section>
<title>Conclusion</title>
<para>
The "<literal>inputs</literal>" 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 "<literal>inputs</literal>" 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.
</para>
<para>
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.