doc: add function argument order convention (#110060)

* doc: add function argument order convention

Ordering by usage is the de facto ordering given to arguments. It's
logical, and makes finding argument usage easier. Putting lib first is
common in NixOS modules, so it's reasonable to mirror this in nixpkgs
proper. Additionally, it's not a package as such, has zero dependencies,
and can be found used anywhere in a derivation.

* doc: clean up usage of lib

doc/contributing/coding-conventions.xml

@@ -178,6 +178,12 @@ args.stdenv.mkDerivation (args // {
 </programlisting>
     </para>
    </listitem>
+   <listitem>
+    <para>
+     Arguments should be listed in the order they are used, with the
+     exception of <varname>lib</varname>, which always goes first.
+    </para>
+   </listitem>
    <listitem>
     <para>
      Prefer using the top-level <varname>lib</varname> over its alias

doc/languages-frameworks/coq.section.md

@@ -42,8 +42,8 @@ It also takes other standard `mkDerivation` attributes, they are added as such,
 Here is a simple package example. It is a pure Coq library, thus it depends on Coq. It builds on the Mathematical Components library, thus it also takes some `mathcomp` derivations as `extraBuildInputs`.
 
 ```nix
-{ coq, mkCoqDerivation, mathcomp, mathcomp-finmap, mathcomp-bigenough,
-  lib, version ? null }:
+{ lib, mkCoqDerivation, version ? null
+, coq, mathcomp, mathcomp-finmap, mathcomp-bigenough }:
 with lib; mkCoqDerivation {
   /* namePrefix leads to e.g. `name = coq8.11-mathcomp1.11-multinomials-1.5.2` */
   namePrefix = [ "coq" "mathcomp" ];

doc/languages-frameworks/idris.section.md

@@ -69,11 +69,11 @@ prelude
 As an example of how a Nix expression for an Idris package can be created, here is the one for `idrisPackages.yaml`:
 
 ```nix
-{ build-idris-package
+{ lib
+, build-idris-package
 , fetchFromGitHub
 , contrib
 , lightyear
-, lib
 }:
 build-idris-package  {
   name = "yaml";
@@ -94,11 +94,11 @@ build-idris-package  {
     sha256 = "1g4pi0swmg214kndj85hj50ccmckni7piprsxfdzdfhg87s0avw7";
   };
 
-  meta = {
+  meta = with lib; {
     description = "Idris YAML lib";
     homepage = "https://github.com/Heather/Idris.Yaml";
-    license = lib.licenses.mit;
-    maintainers = [ lib.maintainers.brainrape ];
+    license = licenses.mit;
+    maintainers = [ maintainers.brainrape ];
   };
 }
 ```

doc/languages-frameworks/maven.section.md

@@ -116,7 +116,7 @@ The first step will be to build the Maven project as a fixed-output derivation i
 > Traditionally the Maven repository is at `~/.m2/repository`. We will override this to be the `$out` directory.
 
 ```nix
-{ stdenv, lib, maven }:
+{ lib, stdenv, maven }:
 stdenv.mkDerivation {
   name = "maven-repository";
   buildInputs = [ maven ];
@@ -168,7 +168,7 @@ If your package uses _SNAPSHOT_ dependencies or _version ranges_; there is a str
 Regardless of which strategy is chosen above, the step to build the derivation is the same.
 
 ```nix
-{ stdenv, lib, maven, callPackage }:
+{ stdenv, maven, callPackage }:
 # pick a repository derivation, here we will use buildMaven
 let repository = callPackage ./build-maven-repository.nix { };
 in stdenv.mkDerivation rec {
@@ -222,7 +222,7 @@ We will read the Maven repository and flatten it to a single list. This list wil
 We make sure to provide this classpath to the `makeWrapper`.
 
 ```nix
-{ stdenv, lib, maven, callPackage, makeWrapper, jre }:
+{ stdenv, maven, callPackage, makeWrapper, jre }:
 let
   repository = callPackage ./build-maven-repository.nix { };
 in stdenv.mkDerivation rec {
@@ -298,7 +298,7 @@ Main-Class: Main
 We will modify the derivation above to add a symlink to our repository so that it's accessible to our JAR during the `installPhase`.
 
 ```nix
-{ stdenv, lib, maven, callPackage, makeWrapper, jre }:
+{ stdenv, maven, callPackage, makeWrapper, jre }:
 # pick a repository derivation, here we will use buildMaven
 let repository = callPackage ./build-maven-repository.nix { };
 in stdenv.mkDerivation rec {

doc/languages-frameworks/ocaml.section.md

@@ -32,11 +32,11 @@ buildDunePackage rec {
   propagatedBuildInputs = [ bigstringaf result ];
   doCheck = true;
 
-  meta = {
+  meta = with lib; {
     homepage = "https://github.com/inhabitedtype/angstrom";
     description = "OCaml parser combinators built for speed and memory efficiency";
-    license = lib.licenses.bsd3;
-    maintainers = with lib.maintainers; [ sternenseemann ];
+    license = licenses.bsd3;
+    maintainers = with maintainers; [ sternenseemann ];
   };
 }
 ```

doc/languages-frameworks/perl.section.md

@@ -110,7 +110,7 @@ ClassC3Componentised = buildPerlPackage rec {
 On Darwin, if a script has too many `-Idir` flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the `shortenPerlShebang` function from the `postInstall` phase:
 
 ```nix
-{ stdenv, lib, buildPerlPackage, fetchurl, shortenPerlShebang }:
+{ lib, stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
 
 ImageExifTool = buildPerlPackage {
   pname = "Image-ExifTool";

doc/languages-frameworks/qt.section.md

@@ -8,7 +8,7 @@ There are primarily two problems which the Qt infrastructure is designed to addr
 
 ```{=docbook}
 <programlisting>
-{ mkDerivation, lib, qtbase }: <co xml:id='qt-default-nix-co-1' />
+{ mkDerivation, qtbase }: <co xml:id='qt-default-nix-co-1' />
 
 mkDerivation { <co xml:id='qt-default-nix-co-2' />
   pname = "myapp";

doc/languages-frameworks/r.section.md

@@ -32,14 +32,12 @@ However, if you'd like to add a file to your project source to make the
 environment available for other contributors, you can create a `default.nix`
 file like so:
 ```nix
-let
-  pkgs = import <nixpkgs> {};
-  stdenv = pkgs.stdenv;
-in with pkgs; {
+with import <nixpkgs> {};
+{
   myProject = stdenv.mkDerivation {
     name = "myProject";
     version = "1";
-    src = if pkgs.lib.inNixShell then null else nix;
+    src = if lib.inNixShell then null else nix;
 
     buildInputs = with rPackages; [
       R

doc/languages-frameworks/ruby.section.md

@@ -232,7 +232,7 @@ If you want to package a specific version, you can use the standard Gemfile synt
 Now you can also also make a `default.nix` that looks like this:
 
 ```nix
-{ lib, bundlerApp }:
+{ bundlerApp }:
 
 bundlerApp {
   pname = "mdl";

doc/languages-frameworks/rust.section.md

@@ -19,6 +19,8 @@ or use Mozilla's [Rust nightlies overlay](#using-the-rust-nightlies-overlay).
 Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`:
 
 ```
+{ lib, rustPlatform }:
+
 rustPlatform.buildRustPackage rec {
   pname = "ripgrep";
   version = "12.1.1";
@@ -226,8 +228,6 @@ source code in a reproducible way. If it is missing or out-of-date one can use
 the `cargoPatches` attribute to update or add it.
 
 ```
-{ lib, rustPlatform, fetchFromGitHub }:
-
 rustPlatform.buildRustPackage rec {
   (...)
   cargoPatches = [
@@ -263,7 +263,7 @@ Now, the file produced by the call to `carnix`, called `hello.nix`, looks like:
 
 ```
 # Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
-{ lib, stdenv, buildRustCrate, fetchgit }:
+{ stdenv, buildRustCrate, fetchgit }:
 let kernel = stdenv.buildPlatform.parsed.kernel.name;
     # ... (content skipped)
 in
@@ -292,7 +292,7 @@ following nix file:
 
 ```
 # Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
-{ lib, stdenv, buildRustCrate, fetchgit }:
+{ stdenv, buildRustCrate, fetchgit }:
 let kernel = stdenv.buildPlatform.parsed.kernel.name;
     # ... (content skipped)
 in