Where is -A vm documented?

I am wondering how I got to know that I can create a vm using

nix-build '<nixpkgs/nixos>' -A vm -I nixos-config=./configuration.nix

-A is in Common Options - Nix Reference Manual

But where should the vm attribute be documented?

1 Like

It’s not in the NixOS manual for sure (ctrl+F for “-A vm” shows no results). It’s just there in the source code and you may have picked up the command line invocation being used in some random document on the internet.

nix-build '<nixpkgs/nixos>' -A tab tab … shows a list of possible attributes.

It’s what powers nixos-rebuild build-vm documented at NixOS 23.11 manual | Nix & NixOS


I am still a bit confused about what -A vm exactly does.
Maybe my question is: What is the relation between attribute and derivation?

In { a = <derivation /nix/store/foobar>; } a is the attribute and <derivation /nix/store/foobar> the derivation.

In general, “attribute” refers to the “key” in a “key/value” store (and is always a string and usually also a valid identifier), while a derivation is a single value, which is special in the case, that it can be “realised” into the nix-store.

Am I right that all attributes that can be build using nix-build need to have the structure of a “deriviation” as documented in the nix manual: Derivations - Nix Reference Manual and Nix Pills | Nix & NixOS ?

To me it seems that you use the term derivation differently than in the nix manual or do I misunderstand your notation. Is the notation <derivation /nix/store/foobar> documented somewhere?

The <derivation …> notation was in line with the way how the REPL inspects a derivation, though the REPL uses guilemonts, instead of greater/lesser than, which I can’t enter directly on my keyboard wihtout looking them up first. Therefore I simplified this.

And “derivation” specifically refers to a datatype in nix, which describes how to build some output.

The problem with that term is, that its usage is quite watered and often used synonymously with “package” which is only half of the truth.

Most of the usage you see is actually wrong. But I’m not sure how to teach proper usage, as I do not fully understand the term myself.

A derivation, list of derivations or set of derivations can be instantiated & realised by nix-build.

What the manual an Pill describe is the built-in function derivation which is used to generate the data structure also called “derivation”.

The function itself is not very significant (doesn’t actually do much) but you will encounter some of its wrappers; mkDerivation for example.

I had a section in the Nix language tutorial at some point, but took it out again because it was off topic. We should include it in some tutorial or the Nix manual at some point though.

1 Like