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
This commit is contained in:
V 2021-01-21 01:07:16 +01:00 committed by GitHub
parent 77403c1c19
commit 7616206b77
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 30 additions and 26 deletions

View file

@ -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

View file

@ -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" ];

View file

@ -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 ];
};
}
```

View file

@ -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 {

View file

@ -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 ];
};
}
```

View file

@ -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";

View file

@ -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";

View file

@ -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

View file

@ -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";

View file

@ -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