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

doc/contributing: clarify pname in package naming #121249

Closed
wants to merge 1 commit into from
Closed

doc/contributing: clarify pname in package naming #121249

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions doc/contributing/coding-conventions.chapter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,23 +179,23 @@ The key words _must_, _must not_, _required_, _shall_, _shall not_, _should_, _s

In Nixpkgs, there are generally three different names associated with a package:

- The `name` attribute of the derivation (excluding the version part). This is what most users see, in particular when using `nix-env`.
- The `name` (excluding the version part) or `pname` attribute of the derivation. This is what most users see, in particular when using `nix-env`.
Copy link
Member

Choose a reason for hiding this comment

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

Maybe it is time to use just pname here (with mention of name in this first use).


- The variable name used for the instantiated package in `all-packages.nix`, and when passing it as a dependency to other functions. Typically this is called the _package attribute name_. This is what Nix expression authors see. It can also be used when installing using `nix-env -iA`.

- The filename for (the directory containing) the Nix expression.

Most of the time, these are the same. For instance, the package `e2fsprogs` has a `name` attribute `"e2fsprogs-version"`, is bound to the variable name `e2fsprogs` in `all-packages.nix`, and the Nix expression is in `pkgs/os-specific/linux/e2fsprogs/default.nix`.
Most of the time, these are the same. For instance, the package `e2fsprogs` has a `pname` attribute `"e2fsprogs"`, is bound to the variable name `e2fsprogs` in `all-packages.nix`, and the Nix expression is in `pkgs/os-specific/linux/e2fsprogs/default.nix`.

There are a few naming guidelines:

- The `name` attribute _should_ be identical to the upstream package name.
- The `name` or `pname` attribute _should_ be identical to the upstream package name.

- The `name` attribute _must not_ contain uppercase letters — e.g., `"mplayer-1.0rc2"` instead of `"MPlayer-1.0rc2"`.
- The `name` or `pname` attribute _must not_ contain uppercase letters — e.g., `"mplayer-1.0rc2"` instead of `"MPlayer-1.0rc2"`.

- The version part of the `name` attribute _must_ start with a digit (following a dash) — e.g., `"hello-0.3.1rc2"`.
- The version part of the `name` attribute or `version` _must_ start with a digit (following a dash) — e.g., `"hello-0.3.1rc2"`.

- If a package is not a release but a commit from a repository, then the version part of the name _must_ be the date of that (fetched) commit. The date _must_ be in `"YYYY-MM-DD"` format. Also append `"unstable"` to the name - e.g., `"pkgname-unstable-2014-09-23"`.
- If a package is not a release but a commit from a repository, then the version part of the name _must_ be the date of that (fetched) commit. The date _must_ be in `"YYYY-MM-DD"` format. Also prepend `"unstable"` to the version - e.g., `"pkgname-unstable-2014-09-23"` or `pname = "pkgname"; version = "unstable-2014-09-23"`.
Copy link
Contributor

Choose a reason for hiding this comment

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

This affects the whole "where does the unstable go" problem to some degree, would be nice to mention that somewhere.

#68518
#100833
#110442

Copy link
Member Author

Choose a reason for hiding this comment

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

Right now it goes to version. It can't go to pname because people like to reuse that at many different places and pname shouldn't change with version updates and moving it to the end does not solve a problem and only introduces many changes.

Copy link
Member

@jtojnar jtojnar Apr 30, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

Actually, right now it goes to pname – that is literally what the text said before you changed it. Also the new suggestion would contradict the bullet point before it (funny, I did not even know this was explicitly declared somewhere).

Copy link
Contributor

Choose a reason for hiding this comment

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

Well, it works either way because the name would be constructed to the same result either way.

I think the convention was to put unstable-YYYY-MM-DD as a substitute for the version. e.g. name = packageA-unstable-YYYY-MM-DD. And there was no pname / version distinction originally as only name was passed.... then pname was introduced

Copy link
Member Author

Choose a reason for hiding this comment

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

Right now the text is about name and does not mention pname at all.

Copy link
Member Author

Choose a reason for hiding this comment

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

Suggested change
- If a package is not a release but a commit from a repository, then the version part of the name _must_ be the date of that (fetched) commit. The date _must_ be in `"YYYY-MM-DD"` format. Also prepend `"unstable"` to the version - e.g., `"pkgname-unstable-2014-09-23"` or `pname = "pkgname"; version = "unstable-2014-09-23"`.
- If a package is not a release but a commit from a repository, then the version part of the name _must_ be the date of that (fetched) commit. The date _must_ be in `"YYYY-MM-DD"` format. Also prepend `"unstable"` to the version - e.g., `name = "pkgname-unstable-2014-09-23"` or `pname = "pkgname"; version = "unstable-2014-09-23"`.


- Dashes in the package name _should_ be preserved in new variable names, rather than converted to underscores or camel cased — e.g., `http-parser` instead of `http_parser` or `httpParser`. The hyphenated style is preferred in all three package names.

Expand Down