[build-path-prefix-map-spec] 01/01: Add implementation notes for case-insensitive filesystems

[Ximin Luo]

This is an automated email from the git hooks/post-receive script.

infinity0 pushed a commit to branch master
in repository build-path-prefix-map-spec.

commit e5e39b51ad86ae994bd93f1a8bf38e9d51639882
Author: Ximin Luo <infinity0 at debian.org>
Date:   Wed Oct 18 19:04:43 2017 +0200

    Add implementation notes for case-insensitive filesystems
---
 build-path-prefix-map-spec.in.rst | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/build-path-prefix-map-spec.in.rst b/build-path-prefix-map-spec.in.rst
index f53e76b..7d55938 100644
--- a/build-path-prefix-map-spec.in.rst
+++ b/build-path-prefix-map-spec.in.rst
@@ -215,6 +215,9 @@ Consumers MAY for historical reasons internally store the map with the prefix
 pairs flipped as in (*source*, *target*), instead of (*target*, *source*) as
 described above. New code should prefer the latter representation.
 
+See the appendix for implementation notes on `case-insensitive filesystems
+<#case-insensitive-filesystems>`_.
+
 
 Notes and links
 ===============
@@ -261,6 +264,7 @@ POSIX system strings
   <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/limits.h.html>`_
   for the definition of ``CHAR_BIT``.
 
+
 Windows system strings
 ----------------------
 
@@ -332,6 +336,28 @@ Ximin Luo
 Appendix
 ============
 
+Case-insensitive filesystems
+----------------------------
+
+As per the section `Applying the decoded structure
+<#applying-the-decoded-structure>`_ above, programs are free to choose their
+own interpretation of "derived from" to deal with these.
+
+In practice, the following may be an effective approach:
+
+1. After decoding into a list-of-pairs, canonicalise all source paths in this
+   list.
+
+2. When applying the mapping, first canonicalise the path to be mapped (the
+   "subject path"), then apply it on the canonicalised map from step (1).
+
+The exact method for canonicalisation depends on the filesystem. It may involve
+(e.g.) converting to upper case for non-existing files and path components, and
+converting to the preserved case for existing files and path components, for
+filesystems that store this information. Hopefully your system already has a
+utility function that does this.
+
+
 Test vectors
 ------------
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/reproducible/build-path-prefix-map-spec.git