[commit: packages/directory] master: Deprecate HsDirectory.h and cbits/directory.c (6323523)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/directory

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/6323523cf08f30b2e4d26ca3a732b827bed551b6/directory

>---------------------------------------------------------------

commit 6323523cf08f30b2e4d26ca3a732b827bed551b6
Author: Phil Ruffwind <rf at rufflewind.com>
Date:   Thu Jun 4 15:56:50 2015 -0400

    Deprecate HsDirectory.h and cbits/directory.c
    
    Rationale for deprecation:
    
      - The definition of __hscore_long_path_size is dangerous: if PATH_MAX
        is not defined, we cannot assume there is a maximum limit at all,
        and thus POSIX functions such as realpath will be susceptible to
        buffer overflow.
    
      - It includes the internal HsDirectoryConfig.h header.  It is
        considered bad practice to expose Autoconf-generated headers in the
        public API due to the high probability of macro collisions.
    
      - It doesn't really offer any useful functionality that isn't
        available elsewhere via more convenient means.
    
    Eventually, HsDirectory.h and cbits/directory.c would be removed
    entirely and HsDirectoryConfig.h would be made private (i.e. for
    internal use only).


>---------------------------------------------------------------

6323523cf08f30b2e4d26ca3a732b827bed551b6
 cbits/directory.c     |  2 ++
 changelog.md          |  2 ++
 include/HsDirectory.h | 10 +++++-----
 3 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/cbits/directory.c b/cbits/directory.c
index 1a979ed..55cece2 100644
--- a/cbits/directory.c
+++ b/cbits/directory.c
@@ -4,6 +4,8 @@
  *
  */
 
+/* [DEPRECATED] This file may be removed in future versions. */
+
 #define INLINE
 #include "HsDirectory.h"
 
diff --git a/changelog.md b/changelog.md
index 75f2908..fd4bb4f 100644
--- a/changelog.md
+++ b/changelog.md
@@ -16,6 +16,8 @@ Changelog for the [`directory`][1] package
     current directory cannot be obtained
     ([#23](https://github.com/haskell/directory/issues/23))
 
+  * Deprecate use of `HsDirectory.h` and `HsDirectoryConfig.h`
+
 ## 1.2.2.1 (Apr 2015)
 
   * Fix dependency problem on NixOS when building with tests
diff --git a/include/HsDirectory.h b/include/HsDirectory.h
index eabaec1..46b7c51 100644
--- a/include/HsDirectory.h
+++ b/include/HsDirectory.h
@@ -6,6 +6,9 @@
  *
  * ---------------------------------------------------------------------------*/
 
+/* [DEPRECATED] Do not include this header nor HsDirectoryConfig.h.  They are
+   for internal use only and may be removed in future versions. */
+
 #ifndef __HSDIRECTORY_H__
 #define __HSDIRECTORY_H__
 
@@ -49,10 +52,8 @@
 # endif
 #endif
 
-/* A size that will contain many path names, but not necessarily all
- * (PATH_MAX is not defined on systems with unlimited path length,
- * e.g. the Hurd).
- */
+/* Do not use: it may give the wrong value on systems where PATH_MAX is not
+   defined (e.g. Hurd).  Instead, use System.Directory.Internal.c_PATH_MAX. */
 INLINE HsInt __hscore_long_path_size(void) {
 #ifdef PATH_MAX
     return PATH_MAX;
@@ -67,4 +68,3 @@ INLINE mode_t __hscore_S_IXUSR(void) { return S_IXUSR; }
 INLINE mode_t __hscore_S_IFDIR(void) { return S_IFDIR; }
 
 #endif /* __HSDIRECTORY_H__ */
-