path: root/docs
diff options
authorGravatar Thomas Petazzoni <thomas.petazzoni@free-electrons.com>2017-07-02 18:53:23 +0200
committerGravatar Peter Korsgaard <peter@korsgaard.com>2017-07-03 00:05:18 +0200
commita0c9b36b80d616b42dd1db04e728539e037de931 (patch)
treeec270e4677f6e8fc2bf77b4d1c58552ac860ea9f /docs
parenta2538e4b19c055ee99b5328fb606deb47fada06f (diff)
docs/manual: update details about hashes
This commit updates the manual about hashes, fixing a number of issues: - Adding the .hash file should no longer be optional: it *must* be added. Therefore the wording "You can add ..." is changed to "When possible, you must add ...". - We are now checking hashes for Git downloaded packages, so fix this as well, and indicate more clearly which download methods have hash checking. - We no longer want to have auto-generated patches be downloaded through <pkg>_PATCH because such patches are not stable over time, and their hash can change. For example, downloading patches from github.com should no longer be done. Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
Diffstat (limited to 'docs')
1 files changed, 16 insertions, 7 deletions
diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index 08f5d42f91..00b2033904 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -439,8 +439,10 @@ rules].
=== The +.hash+ file
-Optionally, you can add a third file, named +libfoo.hash+, that contains
-the hashes of the downloaded files for the +libfoo+ package.
+When possible, you must add a third file, named +libfoo.hash+, that
+contains the hashes of the downloaded files for the +libfoo+
+package. The only reason for not adding a +.hash+ file is when hash
+checking is not possible due to how the package is downloaded.
The hashes stored in that file are used to validate the integrity of the
downloaded files.
@@ -515,10 +517,17 @@ the downloaded file is left in the download directory since this
typically indicates that the +.hash+ file is wrong but the downloaded
file is probably OK.
-Sources that are downloaded from a version control system (git, subversion,
-etc...) can not have a hash, because the version control system and tar
-may not create exactly the same file (dates, files ordering...), so the
-hash could be wrong even for a valid download. Therefore, the hash check
-is entirely skipped for such sources.
+Hashes are currently checked for files fetched from http/ftp servers,
+Git repositories, files copied using scp and local files. Hashes are
+not checked for other version control systems (such as Subversion,
+CVS, etc.) because Buildroot currently does not generate reproducible
+tarballs when source code is fetched from such version control
+Hashes should only be added in +.hash+ files for files that are
+guaranteed to be stable. For example, patches auto-generated by Github
+are not guaranteed to be stable, and therefore their hashes can change
+over time. Such patches should not be downloaded, and instead be added
+locally to the package folder.
If the +.hash+ file is missing, then no check is done at all.