QUESTION: What exactly does nix-shell execute from the Nix expression (i.e., shell.nix, default.nix, etc.)?

ANSWER: Based on my current understanding, the answer is everything. It calls $stdenv/setup (see annotation below) to set up the most basic environment variables (TODO: expand on this), and "injects" the most common tools (e.g., gcc, sed) into it.

It also defines the phases (TODO: verify this) and builder functions, such as genericBuilder. For example, the default builder is just two lines:

source $stdenv/setup
genericBuild

TODO: pkgs/stdenv/generic/builder.sh is a mystery though.

QUESTION: Once dropping into nix-shell, how do I know what phases to execute by looking at a default.nix? (E.g., [..]freeswitch/default.nix)

ANSWER: As far as I can tell, one can override the phases in their Nix build expression (to build the derivation, see at the bottom), but they won't get executed as only the $stdenv/setup (see above) will get sourced, and no builders are called that, in return, invoke the phases (again, see above).

So if one is using nix-shell

• to create/hack on a package, the person has to manually invoke the builder or phases (TODO: still fuzzy on this subject)

• to set up an environment, then one doesn't even have to worry about builders/phases because we just use nix-shell to clear the environment and to inject tools that we need for a given task

QUESTION: When dropping into nix-shell, is this Nix expression (i.e., freeswitch/default.nix) executed? Or just parts of it?

ANSWER: As stated above, all of the input Nix expression is evaluated, but no builders and build phases are called; although, nothing prevents one to override the phases, in case they are creating/hacking on a package.

QUESTION:

The command nix-shell will build the dependencies of the specified derivation, but not the derivation itself.

What is the "derivation" here exactly? I know that it is a build expression, but does that mean the default.nix (or other Nix expression) nix-shell is invoked with?

^{This statement also seems like a contradiction with how `nix-shell` works (i.e., if one issues `nix-shell -p curl`, then `curl` will be available in that sub-shell), but `-p` acts like a shortcut to as if `curl` had been listed in `buildInputs` so this is not the case.}

ANSWER: I have the feeling my confusion comes from the fact that the term "derivation" is used ambiguously in the manuals, sometimes to mean multiple things (see list below).

TODO: Substantiate this claim, and make sure that it not coming from my misunderstanding certain topics.

• Nix build expression (such as default.nix) whose output is going to become the store derivation itself (see last item at the bottom about the Nix manual's glossary definition)

• store derivation.

Had multiple cracks at unambiguously define what a derivation is, and here's a list of these:

• What is the purpose of nix-instantiate? What is a store-derivation? (probably the best try yet)

• What is a Nix expression in regard to Nix package management? (feels sloppier, but commenter mentions ATerm, adding the possibility of making it very specific)

• Closure vs derivation in the Nix package manager (very short, and will have to be re-written, but adds closures to the mix)

• There is now a glossary definition of a derivation in the Nix manual; see this annotation why I find it problematic

nix-build <path> --run-env has been superseded by nix-shell. From Nix manual section C.12. Release 1.6 (2013-09-10):

The command nix-build --run-env has been renamed to nix-shell.

Or use the Nix package manager's nix-shell.

• https://toraritte.github.io/posts/2020-07-15-nix-shell-with-specific-path.html
• https://stackoverflow.com/a/62923700/1498178