Missing documentation: runCommand

[chris-martin]

I learned from #23971 (comment) of the existence of a function called runCommand which ought to be mentioned somewhere in the manual.

[ericsagnes]

+1 There are also some other useful trivial builders that deserve to be documented.
My guess is that this should go in the functions section of the nixpkgs manual, probably in a new builder sub-section that would also include buildFHSUserEnv.

[lexleogryfon]

Bump! Actually I quite surprised from the fact that I encountered same issue, after a year since OP noticed, and it still not resolved.

NIX need full API documentation of stdlib like https://docs.oracle.com/javase/7/docs/api/ and https://docs.python.org/3/library/index.html manner.

1. all functions of nixpkgs.* like runCommand , all lib.* and all builtins should be documented in clean manner (list, reference) when documentation explains what arguments those functions do accept, and what actions do they perform\return.

As of current date, many of those internal functions are not documented at https://nixos.org/nix/manual/ https://nixos.org/nixpkgs/manual

2. there are no examples in documentation how generate your own specific configuration files, from your templates and your.nix.option.variables

[bsima]

FWIW runCommand is defined here:

nixpkgs/pkgs/build-support/trivial-builders.nix

Lines 5 to 20 in 8de132f

	runCommand' = stdenv: name: env: buildCommand:
	stdenv.mkDerivation ({
	inherit name buildCommand;
	passAsFile = [ "buildCommand" ];
	} // env);
	in
	rec {
	# Run the shell command `buildCommand' to produce a store path named
	# `name'. The attributes in `env' are added to the environment
	# prior to running the command.
	runCommand = runCommandNoCC;
	runCommandNoCC = runCommand' stdenvNoCC;
	runCommandCC = runCommand' stdenv;

[chreekat]

Could someone with editorial wisdom suggest a good place to document runCommand, and perhaps list other trivial commands that could be documented? I was going to throw something together, but I wasn't even sure if it should go in the Nix manual or the Nixpkgs manual. Thanks!

[gleber-da]

@chreekat Definitely in nixpkgs, since that's where the function is defined.

[chris-martin]

Thanks @matthewbauer, greatly appreciated.

[chris-martin]

Since this issue turns up highly in web search results, just thought I'd add that if you're now looking for the runCommand documentation, you can find it here: https://nixos.org/manual/nixpkgs/stable/#trivial-builder-runCommand