diff --git a/doc/Makefile b/doc/Makefile
index c6aed62a9396..91b62fe138bc 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -9,8 +9,10 @@ debug:
.PHONY: format
format:
- find . -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \
- xmlformat --config-file "$$XMLFORMAT_CONFIG" -i {}
+ find . -iname '*.xml' -type f | while read f; do \
+ echo $$f ;\
+ xmlformat --config-file "$$XMLFORMAT_CONFIG" -i $$f ;\
+ done
.PHONY: fix-misc-xml
fix-misc-xml:
diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml
index a8a4557b461c..d2c7a1baae9c 100644
--- a/doc/coding-conventions.xml
+++ b/doc/coding-conventions.xml
@@ -814,7 +814,7 @@ args.stdenv.mkDerivation (args // {
There are multiple ways to fetch a package source in nixpkgs. The general
- guideline is that you should package sources with a high degree of
+ 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 fetchurl. Note that you should also
prefer protocols which have a corresponding proxy environment variable.
@@ -876,6 +876,123 @@ src = fetchFromGitHub {
+
+ Obtaining source hash
+
+
+ Preferred source hash type is sha256. There are several ways to get it.
+
+
+
+
+
+ Prefetch URL (with nix-prefetch-XXX
+ URL, where
+ XXX is one of url,
+ git, hg, cvs,
+ bzr, svn). Hash is printed to
+ stdout.
+
+
+
+
+ Prefetch by package source (with nix-prefetch-url
+ '<nixpkgs>' -A PACKAGE.src,
+ where PACKAGE is package attribute name). Hash
+ is printed to stdout.
+
+
+ This works well when you've upgraded existing package version and want to
+ find out new hash, but is useless if package can't be accessed by
+ attribute or package has multiple sources (.srcs,
+ architecture-dependent sources, etc).
+
+
+
+
+ Upstream provided hash: use it when upstream provides
+ sha256 or sha512 (when upstream
+ provides md5, don't use it, compute
+ sha256 instead).
+
+
+ A little nuance is that nix-prefetch-* tools produce
+ hash encoded with base32, but upstream usually provides
+ hexadecimal (base16) encoding. Fetchers understand both
+ formats. Nixpkgs does not standardize on any one format.
+
+
+ You can convert between formats with nix-hash, for example:
+
+$ nix-hash --type sha256 --to-base32 HASH
+
+
+
+
+
+ Extracting hash from local source tarball can be done with
+ sha256sum. Use nix-prefetch-url
+ file:///path/to/tarball if you want base32 hash.
+
+
+
+
+ Fake hash: set fake hash in package expression, perform build and extract
+ correct hash from error Nix prints.
+
+
+ For package updates it is enough to change one symbol to make hash fake.
+ For new packages, you can use lib.fakeSha256,
+ lib.fakeSha512 or any other fake hash.
+
+
+ This is last resort method when reconstructing source URL is non-trivial
+ and nix-prefetch-url -A isn't applicable (for example,
+
+ one of kodi dependencies). The easiest way then
+ would be replace hash with a fake one and rebuild. Nix build will fail and
+ error message will contain desired hash.
+
+ This method has security problems. Check below for details.
+
+
+
+
+ Obtaining hashes securely
+
+ 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:
+
+
+
+
+ http:// URLs are not secure to prefetch hash from;
+
+
+
+
+ hashes from upstream (in method 3) should be obtained via secure protocol;
+
+
+
+
+ https:// URLs are secure in methods 1, 2, 3;
+
+
+
+
+ https:// 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 https:// URL and prefetch it
+ with method 1.
+
+
+
+
+ Patches