Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Doc: init stdenv.mkDerivation doc-comment #343031

Merged
merged 1 commit into from
Sep 20, 2024
Merged

Doc: init stdenv.mkDerivation doc-comment #343031

merged 1 commit into from
Sep 20, 2024

Conversation

hsjobeki
Copy link
Contributor

@hsjobeki hsjobeki commented Sep 19, 2024 •
edited
Loading

Description of changes

Adds initial doc-comment for mkDerivation at the right position.

The nix-repl output look like this,

nix-repl> :doc stdenv.mkDerivation
Function mkDerivation
    … defined at /home/johannes/git/nixpkgs/pkgs/stdenv/generic/make-derivation.nix:57:5

    This function returns a derivation.

    Full reference see: https://nixos.org/manual/nixpkgs/stable/#sec-using-stdenv

    :::{.note} This is used as the fundamental building block of most other derivation creating functions in Nixpkgs.

    Arguments are transparently forwarded to builtins.derivation :::

Unfortunately nix-repl doesnt support markdown rendering thats why it looks a bit clunky.
But if the users shell supports link detection (i.e. vscode does) the user can click on the link directly.

A goal is to factor out the mkDerivation reference docs from stdenv docs and replace each occurence with references, but this is for another PR.

Things done

  • Built on platform(s)
    • x86_64-linux
    • aarch64-linux
    • x86_64-darwin
    • aarch64-darwin
  • For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
    • sandbox = relaxed
    • sandbox = true
  • Tested, as applicable:
  • Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
  • Tested basic functionality of all binary files (usually in ./result/bin/)
  • 24.11 Release Notes (or backporting 23.11 and 24.05 Release notes)
    • (Package updates) Added a release notes entry if the change is major or breaking
    • (Module updates) Added a release notes entry if the change is significant
    • (Module addition) Added a release notes entry if adding a new NixOS module
  • Fits CONTRIBUTING.md.

Add a 👍 reaction to pull requests you find important.

@github-actions github-actions bot added the 6.topic: stdenv Standard environment label Sep 19, 2024
@hsjobeki hsjobeki requested review from roberth and a team September 19, 2024 13:54
fricklerhandwerk
fricklerhandwerk reviewed Sep 19, 2024
View reviewed changes
Copy link
Contributor

@fricklerhandwerk fricklerhandwerk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice. Some phrasing nits from me.

pkgs/stdenv/generic/make-derivation.nix Outdated Show resolved Hide resolved
pkgs/stdenv/generic/make-derivation.nix Outdated Show resolved Hide resolved
pkgs/stdenv/generic/make-derivation.nix Outdated
:::{.note}
This is used as the fundamental building block of most other derivation creating functions in Nixpkgs.

Arguments are transparently forwarded to [`builtins.derivation`](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Arguments are transparently forwarded to [`builtins.derivation`](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations)
Arguments are transparently forwarded to [`builtins.derivation`](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations).

I'm not sure what this is supposed to mean though. Are all arguments passed through to builtins.derivation? If so:

Suggested change
Arguments are transparently forwarded to [`builtins.derivation`](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations)
All arguments are also passed through to to the underlying call to [`builtins.derivation`](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations).

Otherwise, please clarify.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Arguments are transparently forwarded to [`builtins.derivation`](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations)
Most arguments are forwarded to [`builtins.derivation`](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations).

Not all of them.

It'd be good to answer which, but let's not increase the scope of this PR 100-fold, and only discuss generalities for now.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also not always verbatim or "transparent" fwiw

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment was not addressed

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, I should have checked. @hsjobeki could you follow up on this?

@ofborg ofborg bot added 10.rebuild-darwin: 0 This PR does not cause any packages to rebuild on Darwin 10.rebuild-linux: 0 This PR does not cause any packages to rebuild on Linux labels Sep 19, 2024
roberth
roberth reviewed Sep 19, 2024
View reviewed changes
Copy link
Member

@roberth roberth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is so necessary! ❤️

Before discussing all of the individual arguments, let's describe the function in broad strokes. I've added a suggestion that I think makes for a good introduction to set the stage for all the things that happen the the arguments that do make it into the derivation.

pkgs/stdenv/generic/make-derivation.nix Outdated Show resolved Hide resolved
pkgs/stdenv/generic/make-derivation.nix Outdated
:::{.note}
This is used as the fundamental building block of most other derivation creating functions in Nixpkgs.

Arguments are transparently forwarded to [`builtins.derivation`](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Arguments are transparently forwarded to [`builtins.derivation`](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations)
Most arguments are forwarded to [`builtins.derivation`](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations).

Not all of them.

It'd be good to answer which, but let's not increase the scope of this PR 100-fold, and only discuss generalities for now.

@roberth
Copy link
Member

roberth commented Sep 19, 2024

Unfortunately nix-repl doesnt support markdown rendering thats why it looks a bit clunky.

It does render markdown, but a limited dialect (plain CommonMark?)

@hsjobeki
Copy link
Contributor Author

Nice thanks for all the suggestions.

@roberth roberth merged commit 039db25 into NixOS:master Sep 20, 2024
21 checks passed
@roberth
Copy link
Member

roberth commented Sep 20, 2024

Thanks!

@hsjobeki hsjobeki mentioned this pull request Sep 20, 2024
Merged
13 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@fricklerhandwerk fricklerhandwerk fricklerhandwerk left review comments

@roberth roberth roberth approved these changes

@Ericson2314 Ericson2314 Awaiting requested review from Ericson2314

Assignees
No one assigned
Labels
6.topic: stdenv Standard environment 10.rebuild-darwin: 0 This PR does not cause any packages to rebuild on Darwin 10.rebuild-linux: 0 This PR does not cause any packages to rebuild on Linux
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@hsjobeki @roberth @fricklerhandwerk