Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: NixOS/nixpkgs
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: 8a08d7e7cc4a
Choose a base ref
...
head repository: NixOS/nixpkgs
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: 8d502fd425ed
Choose a head ref
86 contributors
Loading
Showing 540 changed files with 12,742 additions and 3,706 deletions.
7 changes: 4 additions & 3 deletions doc/.gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
*.chapter.xml
*.section.xml
.version
out
manual-full.xml
highlightjs
functions/library/generated
functions/library/locations.xml
highlightjs
manual-full.xml
out
98 changes: 51 additions & 47 deletions doc/coding-conventions.xml
View file
Original file line number Diff line number Diff line change
@@ -197,20 +197,14 @@ args.stdenv.mkDerivation (args // {
<title>Package naming</title>

<para>
The key words
<emphasis>must</emphasis>,
<emphasis>must not</emphasis>,
<emphasis>required</emphasis>,
<emphasis>shall</emphasis>,
<emphasis>shall not</emphasis>,
<emphasis>should</emphasis>,
<emphasis>should not</emphasis>,
<emphasis>recommended</emphasis>,
<emphasis>may</emphasis>,
and <emphasis>optional</emphasis> in this section
are to be interpreted as described in
<link xlink:href="https://tools.ietf.org/html/rfc2119">RFC 2119</link>.
Only <emphasis>emphasized</emphasis> words are to be interpreted in this way.
The key words <emphasis>must</emphasis>, <emphasis>must not</emphasis>,
<emphasis>required</emphasis>, <emphasis>shall</emphasis>, <emphasis>shall
not</emphasis>, <emphasis>should</emphasis>, <emphasis>should
not</emphasis>, <emphasis>recommended</emphasis>, <emphasis>may</emphasis>,
and <emphasis>optional</emphasis> in this section are to be interpreted as
described in <link xlink:href="https://tools.ietf.org/html/rfc2119">RFC
2119</link>. Only <emphasis>emphasized</emphasis> words are to be
interpreted in this way.
</para>

<para>
@@ -253,15 +247,15 @@ args.stdenv.mkDerivation (args // {
<itemizedlist>
<listitem>
<para>
The <literal>name</literal> attribute <emphasis>should</emphasis>
be identical to the upstream package name.
The <literal>name</literal> attribute <emphasis>should</emphasis> be
identical to the upstream package name.
</para>
</listitem>
<listitem>
<para>
The <literal>name</literal> attribute <emphasis>must not</emphasis>
contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal>
instead of <literal>"MPlayer-1.0rc2"</literal>.
The <literal>name</literal> attribute <emphasis>must not</emphasis>
contain uppercase letters — e.g., <literal>"mplayer-1.0rc2"</literal>
instead of <literal>"MPlayer-1.0rc2"</literal>.
</para>
</listitem>
<listitem>
@@ -275,28 +269,29 @@ args.stdenv.mkDerivation (args // {
<para>
If a package is not a release but a commit from a repository, then the
version part of the name <emphasis>must</emphasis> be the date of that
(fetched) commit. The date <emphasis>must</emphasis> be in <literal>"YYYY-MM-DD"</literal>
format. Also append <literal>"unstable"</literal> to the name - e.g.,
(fetched) commit. The date <emphasis>must</emphasis> be in
<literal>"YYYY-MM-DD"</literal> format. Also append
<literal>"unstable"</literal> to the name - e.g.,
<literal>"pkgname-unstable-2014-09-23"</literal>.
</para>
</listitem>
<listitem>
<para>
Dashes in the package name <emphasis>should</emphasis> be preserved in new variable names,
rather than converted to underscores or camel cased — e.g.,
<varname>http-parser</varname> instead of <varname>http_parser</varname>
or <varname>httpParser</varname>. The hyphenated style is preferred in
all three package names.
Dashes in the package name <emphasis>should</emphasis> be preserved in
new variable names, rather than converted to underscores or camel cased
— e.g., <varname>http-parser</varname> instead of
<varname>http_parser</varname> or <varname>httpParser</varname>. The
hyphenated style is preferred in all three package names.
</para>
</listitem>
<listitem>
<para>
If there are multiple versions of a package, this <emphasis>should</emphasis> be reflected in
the variable names in <filename>all-packages.nix</filename>, e.g.
<varname>json-c-0-9</varname> and <varname>json-c-0-11</varname>. If
there is an obvious “default” version, make an attribute like
<literal>json-c = json-c-0-9;</literal>. See also
<xref linkend="sec-versioning" />
If there are multiple versions of a package, this
<emphasis>should</emphasis> be reflected in the variable names in
<filename>all-packages.nix</filename>, e.g. <varname>json-c-0-9</varname>
and <varname>json-c-0-11</varname>. If there is an obvious “default”
version, make an attribute like <literal>json-c = json-c-0-9;</literal>.
See also <xref linkend="sec-versioning" />
</para>
</listitem>
</itemizedlist>
@@ -814,8 +809,8 @@ args.stdenv.mkDerivation (args // {

<para>
There are multiple ways to fetch a package source in nixpkgs. The general
guideline is that you should package reproducible sources with a high degree of
availability. Right now there is only one fetcher which has mirroring
guideline is that you should package reproducible sources with a high degree
of availability. Right now there is only one fetcher which has mirroring
support and that is <literal>fetchurl</literal>. Note that you should also
prefer protocols which have a corresponding proxy environment variable.
</para>
@@ -869,8 +864,10 @@ src = fetchFromGitHub {
}
</programlisting>
Find the value to put as <literal>sha256</literal> by running
<literal>nix run -f '&lt;nixpkgs&gt;' nix-prefetch-github -c nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS nix</literal>
or <literal>nix-prefetch-url --unpack https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz</literal>.
<literal>nix run -f '&lt;nixpkgs&gt;' nix-prefetch-github -c
nix-prefetch-github --rev 1f795f9f44607cc5bec70d1300150bfefcef2aae NixOS
nix</literal> or <literal>nix-prefetch-url --unpack
https://github.com/NixOS/nix/archive/1f795f9f44607cc5bec70d1300150bfefcef2aae.tar.gz</literal>.
</para>
</listitem>
</itemizedlist>
@@ -953,17 +950,23 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable>
would be replace hash with a fake one and rebuild. Nix build will fail and
error message will contain desired hash.
</para>
<warning><para>This method has security problems. Check below for details.</para></warning>
<warning>
<para>
This method has security problems. Check below for details.
</para>
</warning>
</listitem>
</orderedlist>

<section xml:id="sec-source-hashes-security">
<title>Obtaining hashes securely</title>

<para>
Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead of fetching
source you can fetch malware, and instead of source hash you get hash of malware. Here are
security considerations for this scenario:
Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead
of fetching source you can fetch malware, and instead of source hash you
get hash of malware. Here are security considerations for this scenario:
</para>

<itemizedlist>
<listitem>
<para>
@@ -972,7 +975,8 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable>
</listitem>
<listitem>
<para>
hashes from upstream (in method 3) should be obtained via secure protocol;
hashes from upstream (in method 3) should be obtained via secure
protocol;
</para>
</listitem>
<listitem>
@@ -982,12 +986,12 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable>
</listitem>
<listitem>
<para>
<literal>https://</literal> URLs are not secure in method 5. When obtaining hashes
with fake hash method, TLS checks are disabled. So
refetch source hash from several different networks to exclude MITM scenario.
Alternatively, use fake hash method to make Nix error, but instead of extracting
hash from error, extract <literal>https://</literal> URL and prefetch it
with method 1.
<literal>https://</literal> URLs are not secure in method 5. When
obtaining hashes with fake hash method, TLS checks are disabled. So
refetch source hash from several different networks to exclude MITM
scenario. Alternatively, use fake hash method to make Nix error, but
instead of extracting hash from error, extract
<literal>https://</literal> URL and prefetch it with method 1.
</para>
</listitem>
</itemizedlist>
19 changes: 9 additions & 10 deletions doc/configuration.xml
View file
Original file line number Diff line number Diff line change
@@ -132,13 +132,13 @@
</itemizedlist>

<para>
The difference between a package being unsupported on some system and
being broken is admittedly a bit fuzzy. If a program
<emphasis>ought</emphasis> to work on a certain platform, but doesn't, the
platform should be included in <literal>meta.platforms</literal>, but marked
as broken with e.g. <literal>meta.broken =
!hostPlatform.isWindows</literal>. Of course, this begs the question of what
"ought" means exactly. That is left to the package maintainer.
The difference between a package being unsupported on some system and being
broken is admittedly a bit fuzzy. If a program <emphasis>ought</emphasis> to
work on a certain platform, but doesn't, the platform should be included in
<literal>meta.platforms</literal>, but marked as broken with e.g.
<literal>meta.broken = !hostPlatform.isWindows</literal>. Of course, this
begs the question of what "ought" means exactly. That is left to the package
maintainer.
</para>
</section>
<section xml:id="sec-allow-unfree">
@@ -175,9 +175,8 @@
</programlisting>
</para>
<para>
For a more useful example, try the following. This configuration
only allows unfree packages named flash player and visual studio
code:
For a more useful example, try the following. This configuration only
allows unfree packages named flash player and visual studio code:
<programlisting>
{
allowUnfreePredicate = (pkg: builtins.elem
Loading