diff --git a/doc/Makefile b/doc/Makefile
index c6aed62a939..91b62fe138b 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 a8a4557b461..88ce6281a25 100644
--- a/doc/coding-conventions.xml
+++ b/doc/coding-conventions.xml
@@ -876,6 +876,107 @@ 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 doesn't have top-level
+ 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 doesn't stadartize 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.
+
+
+ You can use lib.fakeSha256,
+ lib.fakeSha512 or any other fake hash for this purpose.
+ 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 wanted hash.
+
+
+
+
+
+ Obtaining hashes securely
+
+
+ From security point of view first four methods are most secure.
+ nix-prefetch-url does verify TLS certificates for
+ https:// URLs. TLS certificates aren't
+ verified in fake hash method even when there is https://
+ URL. Obviously, getting hashes for http://
+ URLs isn't secure, so recheck using some other network that hash is same.
+
+
+
+ Upstream provided hashes are not secure if obtained over
+ http://.
+
+
+
+ Nixpkgs build farm can act as an additional verification step. When
+ compromised hash was obtained, package may be rejected on Hydra due to hash
+ mismatch.
+
+
+ Patches