Format markdown with Prettier

Author: Noam Yorav-Raphael

pills/01-why-you-should-give-it-try.md

@@ -26,7 +26,7 @@ Let's say you need an nginx service and also an nginx-openresty service. You hav
 
 Or suppose that you want to run two different instances of mysql: 5.2 and 5.5. The same thing applies, plus you have to also make sure the two mysqlclient libraries do not collide.
 
-This is not impossible but it *is* very inconvenient. If you want to install two whole stacks of software like GNOME 3.10 and GNOME 3.12, you can imagine the amount of work.
+This is not impossible but it _is_ very inconvenient. If you want to install two whole stacks of software like GNOME 3.10 and GNOME 3.12, you can imagine the amount of work.
 
 From an administrator's point of view: you can use containers. The typical solution nowadays is to create a container per service, especially when different versions are needed. That somewhat solves the problem, but at a different level and with other drawbacks. For example, needing orchestration tools, setting up a shared cache of packages, and new machines to monitor rather than simple services.
 
@@ -36,7 +36,7 @@ And so on. Nix solves all this at the packaging level and solves it well. A sing
 
 ## Being purely functional
 
-Nix makes no assumptions about the global state of the system. This has many advantages, but also some drawbacks of course. The core of a Nix system is the Nix store, usually installed under `/nix/store`, and some tools to manipulate the store. In Nix there is the notion of a *derivation* rather than a package. The difference can be subtle at the beginning, so I will often use the words interchangeably.
+Nix makes no assumptions about the global state of the system. This has many advantages, but also some drawbacks of course. The core of a Nix system is the Nix store, usually installed under `/nix/store`, and some tools to manipulate the store. In Nix there is the notion of a _derivation_ rather than a package. The difference can be subtle at the beginning, so I will often use the words interchangeably.
 
 Derivations/packages are stored in the Nix store as follows: `/nix/store/hash-name`, where the hash uniquely identifies the derivation (this isn't quite true, it's a little more complex), and the name is the name of the derivation.
 
@@ -85,7 +85,7 @@ If there is a data format change, then migrating to the new data format remains
 
 Nix lets you compose software at build time with maximum flexibility, and with builds being as reproducible as possible. Not only that, due to its nature deploying systems in the cloud is so easy, consistent, and reliable that in the Nix world all existing self-containment and orchestration tools are deprecated by [NixOps](http://nixos.org/nixops/).
 
-It however *currently* falls short when working with dynamic composition at runtime or replacing low level libraries, due to the need to rebuild dependencies.
+It however _currently_ falls short when working with dynamic composition at runtime or replacing low level libraries, due to the need to rebuild dependencies.
 
 That may sound scary, however after running NixOS on both a server and a laptop desktop, I'm very satisfied so far. Some of the architectural problems just need some man-power, other design problems still need to be solved as a community.
 

pills/02-install-on-your-running.md

@@ -8,7 +8,7 @@ For installation instructions, please refer to the Nix Reference Manual on [ Ins
 
 ## Installation
 
-These articles are not a tutorial on *using* Nix. Instead, we're going to walk through the Nix system to understand the fundamentals.
+These articles are not a tutorial on _using_ Nix. Instead, we're going to walk through the Nix system to understand the fundamentals.
 
 The first thing to note: derivations in the Nix store refer to other derivations which are themselves in the Nix store. They don't use `libc` from our system or anywhere else. It's a self-contained store of all the software we need to bootstrap up to any particular package.
 
@@ -50,7 +50,7 @@ Note: If this is the first time you're using Nix after the initial installation,
 
 <div class="warning">
 
-Important: Never change `/nix/store` manually. If you do, then it will no longer be in sync with the sqlite db, unless you *really* know what you are doing.
+Important: Never change `/nix/store` manually. If you do, then it will no longer be in sync with the sqlite db, unless you _really_ know what you are doing.
 
 </div>
 
@@ -124,11 +124,11 @@ You can see for yourself, don't worry if you see multiple bash derivations:
 
 Keeping the store in `/nix` means we can grab the binary cache from nixos.org (just like you grab packages from debian mirrors) otherwise:
 
--   glibc would be installed under `/foo/store`
+- glibc would be installed under `/foo/store`
 
--   Thus bash would need to point to glibc under `/foo/store`, instead of under `/nix/store`
+- Thus bash would need to point to glibc under `/foo/store`, instead of under `/nix/store`
 
--   So the binary cache can't help, because we need a *different* bash, and so we'd have to recompile everything ourselves.
+- So the binary cache can't help, because we need a _different_ bash, and so we'd have to recompile everything ourselves.
 
 After all `/nix` is a sensible place for the store.
 

pills/03-enter-environment.md

@@ -28,13 +28,13 @@ Back to the installation:
 
 Now you can run `hello`. Things to notice:
 
--   We installed software as a user, and only for the Nix user.
+- We installed software as a user, and only for the Nix user.
 
--   It created a new user environment. That's a new generation of our Nix user profile.
+- It created a new user environment. That's a new generation of our Nix user profile.
 
--   The [nix-env](https://nixos.org/manual/nix/stable/command-ref/nix-env.html) tool manages environments, profiles and their generations.
+- The [nix-env](https://nixos.org/manual/nix/stable/command-ref/nix-env.html) tool manages environments, profiles and their generations.
 
--   We installed `hello` by derivation name minus the version. I repeat: we specified the **derivation name** (minus the version) to install it.
+- We installed `hello` by derivation name minus the version. I repeat: we specified the **derivation name** (minus the version) to install it.
 
 We can list generations without walking through the `/nix` hierarchy:
 
@@ -135,7 +135,7 @@ A nicer view of the closure:
     $ nix-store -q --tree `which man`
     [...]
 
-With the above command, you can find out exactly why a *runtime* dependency, be it direct or indirect, exists for a given derivation.
+With the above command, you can find out exactly why a _runtime_ dependency, be it direct or indirect, exists for a given derivation.
 
 The same applies to environments. As an exercise, run `nix-store -q --tree ~/.nix-profile`, and see that the first children are direct dependencies of the user environment: the installed derivations, and the `manifest.nix`.
 
@@ -162,7 +162,7 @@ The first option is to rollback:
 
 The second option is to install Nix, thus creating a new generation:
 
-    $ /nix/store/ig31y9gfpp8pf3szdd7d4sf29zr7igbr-nix-2.1.3/bin/nix-env -i /nix/store/ig31y9gfpp8pf3szdd7d4sf29zr7igbr-nix-2.1.3/bin/nix-env 
+    $ /nix/store/ig31y9gfpp8pf3szdd7d4sf29zr7igbr-nix-2.1.3/bin/nix-env -i /nix/store/ig31y9gfpp8pf3szdd7d4sf29zr7igbr-nix-2.1.3/bin/nix-env
 
 ## Channels
 

pills/04-basics-of-language.md

@@ -106,7 +106,7 @@ Escaping `${...}` within double quoted strings is done with the backslash. Withi
 
 ## Lists
 
-Lists are a sequence of expressions delimited by space (*not* comma):
+Lists are a sequence of expressions delimited by space (_not_ comma):
 
     nix-repl> [ 2 "foo" true (2+3) ]
     [ 2 "foo" true 5 ]
@@ -201,7 +201,7 @@ This kind of expression is something you rarely see in other languages. You can
     nix-repl> with longName; a + b
     7
 
-That's it, it takes an attribute set and includes symbols from it in the scope of the inner expression. Of course, only valid identifiers from the keys of the set will be included. If a symbol exists in the outer scope and would also be introduced by the `with`, it will *not* be shadowed. You can however still refer to the attribute set:
+That's it, it takes an attribute set and includes symbols from it in the scope of the inner expression. Of course, only valid identifiers from the keys of the set will be included. If a symbol exists in the outer scope and would also be introduced by the `with`, it will _not_ be shadowed. You can however still refer to the attribute set:
 
     nix-repl> let a = 10; in with longName; a + b
     14

pills/05-functions-and-imports.md

@@ -115,13 +115,13 @@ That's it, you give a name to the whole parameter with name@ before the set patt
 
 Advantages of using argument sets:
 
--   Named unordered arguments: you don't have to remember the order of the arguments.
+- Named unordered arguments: you don't have to remember the order of the arguments.
 
--   You can pass sets, that adds a whole new layer of flexibility and convenience.
+- You can pass sets, that adds a whole new layer of flexibility and convenience.
 
 Disadvantages:
 
--   Partial application does not work with argument sets. You have to specify the whole attribute set, not part of it.
+- Partial application does not work with argument sets. You have to specify the whole attribute set, not part of it.
 
 You may find similarities with [Python \*\*kwargs](https://docs.python.org/3/faq/programming.html#how-can-i-pass-optional-or-keyword-parameters-from-one-function-to-another).
 
@@ -173,11 +173,11 @@ So how do we pass information to the module? Use functions, like we did with `mu
 
 Explaining:
 
--   In `test.nix` we return a function. It accepts a set, with default attributes `b`, `trueMsg` and `falseMsg`.
+- In `test.nix` we return a function. It accepts a set, with default attributes `b`, `trueMsg` and `falseMsg`.
 
--   `builtins.trace` is a [built-in function](https://nixos.org/manual/nix/stable/expressions/builtins.html) that takes two arguments. The first is the message to display, the second is the value to return. It's usually used for debugging purposes.
+- `builtins.trace` is a [built-in function](https://nixos.org/manual/nix/stable/expressions/builtins.html) that takes two arguments. The first is the message to display, the second is the value to return. It's usually used for debugging purposes.
 
--   Then we import `test.nix`, and call the function with that set.
+- Then we import `test.nix`, and call the function with that set.
 
 So when is the message shown? Only when it needs to be evaluated.
 

pills/06-our-first-derivation.md

@@ -14,11 +14,11 @@ That's where the real power comes in.
 
 The `derivation` function receives a set as its first argument. This set requires at least the following three attributes:
 
--   name: the name of the derivation. In the nix store the format is hash-name, that's the name.
+- name: the name of the derivation. In the nix store the format is hash-name, that's the name.
 
--   system: is the name of the system in which the derivation can be built. For example, x86_64-linux.
+- system: is the name of the system in which the derivation can be built. For example, x86_64-linux.
 
--   builder: is the binary program that builds the derivation.
+- builder: is the binary program that builds the derivation.
 
 First of all, what's the name of our system as seen by nix?
 
@@ -39,11 +39,11 @@ What's that `.drv` file? It is the specification of how to build the derivation,
 
 Before continuing, some analogies with the C language:
 
--   `.nix` files are like `.c` files.
+- `.nix` files are like `.c` files.
 
--   `.drv` files are intermediate files like `.o` files. The `.drv` describes how to build a derivation; it's the bare minimum information.
+- `.drv` files are intermediate files like `.o` files. The `.drv` describes how to build a derivation; it's the bare minimum information.
 
--   out paths are then the product of the build.
+- out paths are then the product of the build.
 
 Both drv paths and out paths are stored in the nix store as you can see.
 
@@ -257,9 +257,9 @@ Nix does not build derivations **during evaluation** of Nix expressions. In fact
 
 An important separation is made in Nix:
 
--   **Instantiate/Evaluation time**: the Nix expression is parsed, interpreted and finally returns a derivation set. During evaluation, you can refer to other derivations because Nix will create .drv files and we will know out paths beforehand. This is achieved with [nix-instantiate](https://nixos.org/manual/nix/stable/command-ref/nix-instantiate.html).
+- **Instantiate/Evaluation time**: the Nix expression is parsed, interpreted and finally returns a derivation set. During evaluation, you can refer to other derivations because Nix will create .drv files and we will know out paths beforehand. This is achieved with [nix-instantiate](https://nixos.org/manual/nix/stable/command-ref/nix-instantiate.html).
 
--   **Realise/Build time**: the .drv from the derivation set is built, first building .drv inputs (build dependencies). This is achieved with [nix-store -r](https://nixos.org/manual/nix/stable/command-ref/nix-store.html#operation---realise).
+- **Realise/Build time**: the .drv from the derivation set is built, first building .drv inputs (build dependencies). This is achieved with [nix-store -r](https://nixos.org/manual/nix/stable/command-ref/nix-store.html#operation---realise).
 
 Think of it as of compile time and link time like with C/C++ projects. You first compile all source files to object files. Then link object files in a single executable.
 

pills/07-working-derivation.md

@@ -29,7 +29,7 @@ What we have to do is create something in the path `$out`, be it a file or a dir
 
 In addition, we print out the environment variables during the build process. We cannot use env for this, because env is part of coreutils and we don't have a dependency to it yet. We only have bash for now.
 
-Like for coreutils in the previous pill, we get a blessed bash for free from our magic nixpkgs stuff: 
+Like for coreutils in the previous pill, we get a blessed bash for free from our magic nixpkgs stuff:
 
 ```
 nix-repl> :l <nixpkgs>
@@ -80,15 +80,15 @@ declare -x system="x86_64-linux"
 
 Let's inspect those environment variables printed during the build process.
 
--   `$HOME` is not your home directory, and `/homeless-shelter` doesn't exist at all. We force packages not to depend on `$HOME` during the build process.
+- `$HOME` is not your home directory, and `/homeless-shelter` doesn't exist at all. We force packages not to depend on `$HOME` during the build process.
 
--   `$PATH` plays the same game as `$HOME`
+- `$PATH` plays the same game as `$HOME`
 
--   `$NIX_BUILD_CORES` and `$NIX_STORE` are [nix configuration options](https://nixos.org/manual/nix/stable/command-ref/conf-file.html)
+- `$NIX_BUILD_CORES` and `$NIX_STORE` are [nix configuration options](https://nixos.org/manual/nix/stable/command-ref/conf-file.html)
 
--   `$PWD` and `$TMP` clearly show that nix created a temporary build directory
+- `$PWD` and `$TMP` clearly show that nix created a temporary build directory
 
--   Then `$builder`, `$name`, `$out`, and `$system` are variables set due to the .drv file's contents.
+- Then `$builder`, `$name`, `$out`, and `$system` are variables set due to the .drv file's contents.
 
 And that's how we were able to use `$out` in our derivation and put stuff in it. It's like Nix reserved a slot in the nix store for us, and we must fill it.
 
@@ -148,7 +148,7 @@ And its `simple_builder.sh`:
     mkdir $out
     gcc -o $out/simple $src
 
-Don't worry too much about where those variables come from yet; let's write the derivation and build it: 
+Don't worry too much about where those variables come from yet; let's write the derivation and build it:
 
 ```
 nix-repl> :l <nixpkgs>
@@ -196,9 +196,9 @@ Now you can build it with `nix-build simple.nix`. This will create a symlink `re
 
 nix-build does two jobs:
 
--   [ nix-instantiate ](https://nixos.org/manual/nix/stable/command-ref/nix-instantiate.html): parse and evaluate `simple.nix` and return the .drv file corresponding to the parsed derivation set
+- [ nix-instantiate ](https://nixos.org/manual/nix/stable/command-ref/nix-instantiate.html): parse and evaluate `simple.nix` and return the .drv file corresponding to the parsed derivation set
 
--   [ `nix-store -r` ](https://nixos.org/manual/nix/stable/command-ref/nix-store.html#operation---realise): realise the .drv file, which actually builds it.
+- [ `nix-store -r` ](https://nixos.org/manual/nix/stable/command-ref/nix-store.html#operation---realise): realise the .drv file, which actually builds it.
 
 Finally, it creates the symlink.
 
@@ -230,4 +230,4 @@ This syntax only makes sense inside sets. There's no magic involved, it's simply
 
 We will generalize the builder. You may have noticed that we wrote two separate `builder.sh` scripts in this post. We would like to have a generic builder script instead, especially since each build script goes in the nix store: a bit of a waste.
 
-*Is it really that hard to package stuff in Nix? No*, here we're studying the fundamentals of Nix.
+_Is it really that hard to package stuff in Nix? No_, here we're studying the fundamentals of Nix.

pills/08-generic-builders.md

@@ -71,6 +71,7 @@ Darwin (i.e. macOS) builds typically use `clang` rather than `gcc` for a C compi
     }
 
 Later, we will show how Nix can automatically handle these differences. For now, please be just aware that changes similar to the above may be needed in what follows.
+
 </div>
 
 Now build it with `nix-build hello.nix` and you can launch `result/bin/hello`. Nothing easier, but do we have to create a builder.sh for each package? Do we always have to pass the dependencies to the `derivation` function?
@@ -226,11 +227,11 @@ Then we rewrite `hello.nix` as follows:
 
 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.
+- We assigned to pkgs the import that we did in the previous expressions in the "with". Don't be afraid, it's that straightforward.
 
--   The mkDerivation variable is a nice example of partial application, look at it as (`import ./autotools.nix`) `pkgs`. First we import the expression, then we apply the `pkgs` parameter. That will give us a function that accepts the attribute set `attrs`.
+- The mkDerivation variable is a nice example of partial application, look at it as (`import ./autotools.nix`) `pkgs`. First we import the expression, then we apply the `pkgs` parameter. That will give us a function that accepts the attribute set `attrs`.
 
--   We create the derivation specifying only name and src. If the project eventually needed other dependencies to be in PATH, then we would simply add those to buildInputs (not specified in hello.nix because empty).
+- We create the derivation specifying only name and src. If the project eventually needed other dependencies to be in PATH, then we would simply add those to buildInputs (not specified in hello.nix because empty).
 
 Note we didn't use any other library. Special C flags may be needed to find include files of other libraries at compile time, and ld flags at link time.
 

pills/10-developing-with-nix-shell.md

@@ -31,9 +31,9 @@ This means that we can `source` our `builder.sh`, and it will build the derivati
 
 The derivation didn't install, but it did build. Note the following:
 
--   We sourced `builder.sh` and it ran all of the build steps, including setting up the `PATH` for us.
+- We sourced `builder.sh` and it ran all of the build steps, including setting up the `PATH` for us.
 
--   The working directory is no longer a temp directory created by `nix-build`, but is instead the directory in which we entered the shell. Therefore, `hello-2.10` has been unpacked in the current directory.
+- The working directory is no longer a temp directory created by `nix-build`, but is instead the directory in which we entered the shell. Therefore, `hello-2.10` has been unpacked in the current directory.
 
 We are able to `cd` into `hello-2.10` and type `make`, because `make` is now available.