Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Fix -- dashes rendered as em-dash
  • Loading branch information
ysndr committed Dec 2, 2021
1 parent 61cb63a commit ead89be
Show file tree
Hide file tree
Showing 3 changed files with 17 additions and 17 deletions.
28 changes: 14 additions & 14 deletions src/posts/guides/nix-shells.md
Expand Up @@ -49,16 +49,16 @@ To make this process even easier, `nix develop` now comes with special arguments

This allows to _run phases_ individually in the shell using `$ unpackPhase`, `$ configurePhase` `$ buildPhase`, etc.

...or directly using `nix develop --<PHASE>` or `nix develop --phase PHASE` (for non-standard phases).
...or directly using `nix develop \--<PHASE>` or `nix develop \--phase PHASE` (for non-standard phases).

...or run an arbitrary command in the shell using `nix develop --command COMMAND [ARGS...]`
...or run an arbitrary command in the shell using `nix develop \--command COMMAND [ARGS...]`

**Why should you use this?**

It is most useful for locally developed packages.

Use it to set up the environment using e.g. the `configurePhase` and perform the subsequent development using `build` and `check` phases.
If your workflow includes things that are not part of a phase use `nix develop --command`
If your workflow includes things that are not part of a phase use `nix develop \--command`
:::

In essence, this is exactly what `nix-shell` was intended for!
Expand All @@ -70,7 +70,7 @@ As the default implementation in nix's `stdenv` is done as functions, an interna

**Solution**

Enter a shell using `nix develop` and run the overridden phases using `eval \$buildPhase` or `--command eval '\$buildPhase'`.
Enter a shell using `nix develop` and run the overridden phases using `eval \$buildPhase` or `\--command eval '\$buildPhase'`.

:::

Expand Down Expand Up @@ -216,7 +216,7 @@ This is useful to install temporary software

...from a [flake specifier](../../internals/2021-01-01-flake-ification/#flake-reference-conventions).

...from a `*.nix` file/arbitrary expression using `--impure --expr EXPR` flags
...from a `*.nix` file/arbitrary expression using `\--impure \--expr EXPR` flags

**Why should you use this?**

Expand All @@ -235,11 +235,11 @@ Notably, not mentioned here is the use of `nix shell` to load `FANCYLANGUAGE` wi

Apart from dropping into development shells, `nix-shell` can also be used to run commands and programs from derivation not currently installed to the user's profile. This is it can build a shell as before and run a command inside transparently.

We discussed the use of `nix-shell --command COMMAND ARGS` above, where we would run a command from within the build environment of a derivation. Similarly, we may want to just run a program provided by a derivation. For this `nix-shell` provided the `--run` argument
We discussed the use of `nix-shell \--command COMMAND ARGS` above, where we would run a command from within the build environment of a derivation. Similarly, we may want to just run a program provided by a derivation. For this `nix-shell` provided the `\--run` argument

:::{.info header="\"`--command`\" vs \"`run`\""}
:::{.info header="\"`\--command`\" vs \"`run`\""}

As a development aid, `--command` is interactive, meaning among other things, that *if a command fails or is interrupted by the user, the user is dropped into the shell with the build environment loaded*.
As a development aid, `\--command` is interactive, meaning among other things, that *if a command fails or is interrupted by the user, the user is dropped into the shell with the build environment loaded*.

This behavior translates into an invocation using the `-p PROGRAM` argument as well as seen in the following box.

Expand All @@ -257,7 +257,7 @@ Man page: asciidoc --help manpage
Syntax: asciidoc --help syntax
```

`--run` runs non-interactive and closes the shell after the command returns
`\--run` runs non-interactive and closes the shell after the command returns
```bash
$ asciidoc
zsh: command not found: asciidoc
Expand All @@ -277,19 +277,19 @@ zsh: command not found: asciidoc

As the functions of `nix-shell DERIVATION` and `nix-shell -p DERIVATION` were separated, the new tools come with new clearer semantics.

The generic `nix-shell --run` function is now `nix shell -c`. Given an installable, nix allows to run any command in an environment where the installable is present. Note that this command is run in a non-interactive shell. The shell is dropped as the command ends.
The generic `nix-shell \--run` function is now `nix shell -c`. Given an installable, nix allows to run any command in an environment where the installable is present. Note that this command is run in a non-interactive shell. The shell is dropped as the command ends.

:::{.info}
The above example using the new command would look like this:

```
$ nix shell -c nixpkgs#asciidoc -c asciidoc
$ nix shell nixpkgs#asciidoc -c asciidoc
```
:::

### `nix run`

Yet, `nix shell -c` will still require to type the name of the executed program. As for most programs this command is the same as the derivation name e.g. `nix shell -c nixpkgs#asciidoc -c asciidoc` another command was introduced named `nix run`. With `nix run` the previous command can be run as `nix run nixpkgs#asciidoc`.
Yet, `nix shell -c` will still require to type the name of the executed program. As for most programs this command is the same as the derivation name e.g. `nix shell nixpkgs#asciidoc -c asciidoc` another command was introduced named `nix run`. With `nix run` the previous command can be run as `nix run nixpkgs#asciidoc`.

Naturally, the functionality of `nix run` goes further and as is the case for many other new commands mainly concerns flakes. Next to `packages`, `nixosModules` and others, flakes can now also define `apps`. Written as records with two fields -`type` (currently, necessarily `app`) and `program` (an executable path) - these apps can be run directly using `nix run`.

Expand Down Expand Up @@ -371,7 +371,7 @@ As it stands this function does not [yet](https://github.com/NixOS/nix/pull/5189

## To flake or not to flake

Most of the new nix commands are designed in a flake first way. Most notably `nix {shell,develop,run}` expect [flake URLs](../internals/2021-01-01-flake-ification/#flake-reference-conventions) as argument. Traditional `*.nix` files can be used with the `--expr` argument all commands support. As flake mode imposes greater purity strictness, imports have to happen with the `--impure` flag given:
Most of the new nix commands are designed in a flake first way. Most notably `nix {shell,develop,run}` expect [flake URLs](../internals/2021-01-01-flake-ification/#flake-reference-conventions) as argument. Traditional `*.nix` files can be used with the `\--expr` argument all commands support. As flake mode imposes greater purity strictness, imports have to happen with the `\--impure` flag given:

```sh
$ nix shell --impure --expr "import my.nix {}"
Expand Down Expand Up @@ -431,5 +431,5 @@ Being so closely named to its _semantically different_ predecessor, it is imposs
| **runs `shellHook`s** | yes | yes | no | no |
| **use as interpreter** | yes | no | no | no |
| **supports flakes** | no | yes | yes | only |
| **evaluate nix file** | yes | with `--impure`, `-f` or `--expr` | with `--impure`, `-f` or `--expr` | with `--impure`, `-f` or `--expr` |
| **evaluate nix file** | yes | with `\--impure`, `-f` or `\--expr` | with `\--impure`, `-f` or `\--expr` | with `\--impure`, `-f` or `\--expr` |
| **modifies environment** | `PATH`, attributes mk`mkDerivation` and changes by `shellHooks` | `PATH`, attributes mk`mkDerivation` and changes by `shellHooks` | `PATH` | *nothing* |
2 changes: 1 addition & 1 deletion src/posts/internals/2020-04-10-built-with-nix.md
Expand Up @@ -315,7 +315,7 @@ Snapshots like these also allow rollbacks as they define which versions of depen

Nix has some integration with GitHub Actions through [install-nix](https://github.com/marketplace/actions/install-nix), an action that **installs nix** •_•

With nix installed, I run `$(nix-build -A ci.compile --no-out-link)` to make Nix build the blog generator and rebuild the blog's content into `build/site`. This works because `nix-build --no-out-link` will just print the path of the resulting package to `stdout`, which in this case is only an executable script produced by the `script` function above. The next step is to take that content and push it to the deployment branch.
With nix installed, I run `$(nix-build -A ci.compile \--no-out-link)` to make Nix build the blog generator and rebuild the blog's content into `build/site`. This works because `nix-build \--no-out-link` will just print the path of the resulting package to `stdout`, which in this case is only an executable script produced by the `script` function above. The next step is to take that content and push it to the deployment branch.

[See more...](https://github.com/ysndr/blog/blob/release/.github/workflows/main.yml)

Expand Down
4 changes: 2 additions & 2 deletions src/posts/internals/2021-01-01-flake-ification.md
Expand Up @@ -295,7 +295,7 @@ To take this apart again, we face three different sections here.
1. `flake-utils.lib.eachDefaultSystem`, like its name suggests will provide the attribute set in its scope for all default systems (basically linux and darwin on x86_64 hardware). Hence, we don't need to worry about these tags.
2. The actual output still needs to conform to flakes' expected attributes. In this case we set `packages`, `defaultPackage`, `apps`, `defaultApp` and `devShell`. There are even more most importantly `overlay` which are referenced [below](#output-attributes)
3. third one is the middle part and shows an important aspect of nix flakes.
Because there is no access to impure variables (`--arg`, environment variables, the current system, etc.), `nixpkgs` must be imported explicitly for each system. Additionally, this gives the opportunity to apply any possible overlay.
Because there is no access to impure variables (`\--arg`, environment variables, the current system, etc.), `nixpkgs` must be imported explicitly for each system. Additionally, this gives the opportunity to apply any possible overlay.
In the case of this blog everything is defined in an external `blog.nix` file and imported from there.

### Output attributes
Expand Down Expand Up @@ -334,7 +334,7 @@ is possible to use.
*Notice* that some inputs might need to be quoted due to substitution rules in your shell.
:::

`apps` is used together with `nix run`, similarly to `npm run`. You can define binaries that can then be run directly without explicitly building them first. This allowed me to change the somewhat cryptic `$(nix-build -A packages.x86_64-linux.ci.compile --no-out-link)` to `nix run ./#compile` in the CI script. Actually given that `defaultApp` point to the same `compile` attribute, the argument `./#compile` could be elided paying with decreased clarity.
`apps` is used together with `nix run`, similarly to `npm run`. You can define binaries that can then be run directly without explicitly building them first. This allowed me to change the somewhat cryptic `$(nix-build -A packages.x86_64-linux.ci.compile \--no-out-link)` to `nix run ./#compile` in the CI script. Actually given that `defaultApp` point to the same `compile` attribute, the argument `./#compile` could be elided paying with decreased clarity.

`devShell` is another special one used in combination with `nix develop` which opens a *`bash`* shell with the given derivation prepared.

Expand Down

0 comments on commit ead89be

Please sign in to comment.