From 7616206b7747f12db15d32a7ab16b0ceaa3d7331 Mon Sep 17 00:00:00 2001 From: V Date: Thu, 21 Jan 2021 01:07:16 +0100 Subject: [PATCH] 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 | 6 ++++++ doc/languages-frameworks/coq.section.md | 4 ++-- doc/languages-frameworks/idris.section.md | 10 +++++----- doc/languages-frameworks/maven.section.md | 8 ++++---- doc/languages-frameworks/ocaml.section.md | 6 +++--- doc/languages-frameworks/perl.section.md | 2 +- doc/languages-frameworks/qt.section.md | 2 +- doc/languages-frameworks/r.section.md | 8 +++----- doc/languages-frameworks/ruby.section.md | 2 +- doc/languages-frameworks/rust.section.md | 8 ++++---- 10 files changed, 30 insertions(+), 26 deletions(-) diff --git a/doc/contributing/coding-conventions.xml b/doc/contributing/coding-conventions.xml index cb6d60c2c13..9005a9ebafd 100644 --- a/doc/contributing/coding-conventions.xml +++ b/doc/contributing/coding-conventions.xml @@ -178,6 +178,12 @@ args.stdenv.mkDerivation (args // { + + + Arguments should be listed in the order they are used, with the + exception of lib, which always goes first. + + Prefer using the top-level lib over its alias diff --git a/doc/languages-frameworks/coq.section.md b/doc/languages-frameworks/coq.section.md index 5e16a4c546a..8f564c6e46b 100644 --- a/doc/languages-frameworks/coq.section.md +++ b/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" ]; diff --git a/doc/languages-frameworks/idris.section.md b/doc/languages-frameworks/idris.section.md index 2d06c4a19de..41e4f7ec312 100644 --- a/doc/languages-frameworks/idris.section.md +++ b/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 ]; }; } ``` diff --git a/doc/languages-frameworks/maven.section.md b/doc/languages-frameworks/maven.section.md index 7a863c500bc..d66931e808d 100644 --- a/doc/languages-frameworks/maven.section.md +++ b/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 { diff --git a/doc/languages-frameworks/ocaml.section.md b/doc/languages-frameworks/ocaml.section.md index fa85a27e84f..9b92a80f471 100644 --- a/doc/languages-frameworks/ocaml.section.md +++ b/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 ]; }; } ``` diff --git a/doc/languages-frameworks/perl.section.md b/doc/languages-frameworks/perl.section.md index 309d8ebcc2b..dcb7dcb77b6 100644 --- a/doc/languages-frameworks/perl.section.md +++ b/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"; diff --git a/doc/languages-frameworks/qt.section.md b/doc/languages-frameworks/qt.section.md index 6cfdc663550..5dd415852c1 100644 --- a/doc/languages-frameworks/qt.section.md +++ b/doc/languages-frameworks/qt.section.md @@ -8,7 +8,7 @@ There are primarily two problems which the Qt infrastructure is designed to addr ```{=docbook} -{ mkDerivation, lib, qtbase }: +{ mkDerivation, qtbase }: mkDerivation { pname = "myapp"; diff --git a/doc/languages-frameworks/r.section.md b/doc/languages-frameworks/r.section.md index 32a39ade279..c420d112c91 100644 --- a/doc/languages-frameworks/r.section.md +++ b/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 {}; - stdenv = pkgs.stdenv; -in with pkgs; { +with import {}; +{ 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 diff --git a/doc/languages-frameworks/ruby.section.md b/doc/languages-frameworks/ruby.section.md index e292b3110ff..aeec154586c 100644 --- a/doc/languages-frameworks/ruby.section.md +++ b/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"; diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md index 550f2b576bd..8f6db28ab4d 100644 --- a/doc/languages-frameworks/rust.section.md +++ b/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