Request: Document "Hacking" in CONTRIBUTING.md

[abhillman]

Problem

When I hack on nixpkgs, I do the following -- for which there must be something much better:

--- a/pkgs/development/ocaml-modules/expat/default.nix
+++ b/pkgs/development/ocaml-modules/expat/default.nix
@@ -1,4 +1,5 @@
-{ stdenv, lib, fetchFromGitHub, expat, ocaml, findlib, ounit }:
+with import <nixpkgs> {};
+# { stdenv, lib, fetchFromGitHub, expat, ocaml, findlib, ounit }:

so that I can run things like nix-build against a given package.

Another way is to do something like nix-shell default.nix --arg stdenv '(import <nixpkgs> {}).stdenv ..., but this is pretty cumbersome.

Checklist

I did try my best here, though each are quite long of course --

• [x] checked latest Nixpkgs manual
• [x] checked open documentation issues for possible duplicates
• [x] checked open documentation pull requests for possible solutions

Proposal

Add a blurb about how to best hack on a given package in CONTRIBUTING.md.

[abhillman]

Per @jtojnar, a much more ideal workaround than changing the code is the following:

nix-shell -p 'with (import <nixpkgs> {}); pkgs.ocamlPackages.callPackage ./default.nix {}'

That is: in this example, using the respective callPackage implementation for a group of derivations (e.g. ocamlPackages in the above case). https://github.com/NixOS/nixpkgs/issues/172061#issuecomment-1374752560

---

This is the sort of thing I'm thinking could be especially useful in https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md.

[jtojnar]

I still think that if you are contributing a package to Nixpkgs, it is best to add an attribute to the appropriate package set. Then you will be able to just use e.g. nix-build -A ocamlPackages.ocaml_expat:

https://github.com/NixOS/nixpkgs/blob/e9857feb1d4c30e0ac9e7b8d94a165c30f6c9ad3/pkgs/top-level/ocaml-packages.nix#L981-L984

Looks like the OCaml section of the manual does not mention that OCaml packages are defined in pkgs/top-level/ocaml-packages.nix. There should probably be a paragraph about it like in the Octave section:

All Octave packages are defined in pkgs/top-level/octave-packages.nix rather than pkgs/all-packages.nix . Each package is defined in their own file in the pkgs/development/octave-modules directory. Octave packages are made available through all-packages.nix through both the attribute octavePackages and octave.pkgs . You can test building an Octave package as follows:

[abhillman]

I still think that if you are contributing a package to Nixpkgs, it is best to add an attribute to the appropriate package set. Then you will be able to just use e.g. nix-build -A ocamlPackages.ocaml_expat:

https://github.com/NixOS/nixpkgs/blob/e9857feb1d4c30e0ac9e7b8d94a165c30f6c9ad3/pkgs/top-level/ocaml-packages.nix#L981-L984

Looks like the OCaml section of the manual does not mention that OCaml packages are defined in pkgs/top-level/ocaml-packages.nix. There should probably be a paragraph about it like in the Octave section:

All Octave packages are defined in pkgs/top-level/octave-packages.nix rather than pkgs/all-packages.nix . Each package is defined in their own file in the pkgs/development/octave-modules directory. Octave packages are made available through all-packages.nix through both the attribute octavePackages and octave.pkgs . You can test building an Octave package as follows:

This very much makes sense to me; so the documentation could be oriented around, say the very example I was working on (attempting to make a modification to an OCaml library). And point out that when making edits, calling from the top-level (i.e. ocaml-packages.nix in this case) is most effective for iterating.

Are there good guidelines on acceptance criteria for documentation and any "owners" in that domain for nixpkgs? Would love to help.

[jtojnar]

Are there good guidelines on acceptance criteria for documentation and any "owners" in that domain for nixpkgs? Would love to help.

You are probably best off looking on who contributed to it in the past: https://github.com/NixOS/nixpkgs/commits/master/doc/languages-frameworks/ocaml.section.md

There is also documentation team: https://matrix.to/#/#docs:nixos.org

[abhillman]

Looks like a reference to this could be good to add as well

https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html