Deprecate std::fs::soft_link in favor of platform-specific versions

On Windows, when you create a symbolic link you must specify whether it
points to a directory or a file, even if it is created dangling, while
on Unix, the same symbolic link could point to a directory, a file, or
nothing at all.  Furthermore, on Windows special privilege is necessary
to use a symbolic link, while on Unix, you can generally create a
symbolic link in any directory you have write privileges to.

This means that it is unlikely to be able to use symbolic links purely
portably; anyone who uses them will need to think about the cross
platform implications.  This means that using platform-specific APIs
will make it easier to see where code will need to differ between the
platforms, rather than trying to provide some kind of compatibility
wrapper.

Furthermore, `soft_link` has no precedence in any other API, so to avoid
confusion, move back to the more standard `symlink` terminology.

Create a `std::os::unix::symlink` for the Unix version that is
destination type agnostic, as well as `std::os::windows::{symlink_file,
symlink_dir}` for Windows.

Because this is a stable API, leave a compatibility wrapper in
`std::fs::soft_link`, which calls `symlink` on Unix and `symlink_file`
on Windows, preserving the existing behavior of `soft_link`.

1 files changed, 48 insertions, 0 deletions

diff --git a/src/libstd/sys/windows/ext.rs b/src/libstd/sys/windows/ext.rs
index 90548dcefb4..eac6496870e 100644
--- a/src/libstd/sys/windows/ext.rs
+++ b/src/libstd/sys/windows/ext.rs
@@ -191,7 +191,11 @@ pub mod ffi {
 #[unstable(feature = "fs_ext", reason = "may require more thought/methods")]
 pub mod fs {
     use fs::OpenOptions;
+    use sys;
     use sys_common::AsInnerMut;
+    use path::Path;
+    use convert::AsRef;
+    use io;
 
     /// Windows-specific extensions to `OpenOptions`
     pub trait OpenOptionsExt {
@@ -235,6 +239,50 @@ pub mod fs {
             self.as_inner_mut().share_mode(access); self
         }
     }
+
+    /// Creates a new file symbolic link on the filesystem.
+    ///
+    /// The `dst` path will be a file symbolic link pointing to the `src`
+    /// path.
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// #![feature(fs_ext)]
+    /// use std::os::windows::fs;
+    ///
+    /// # fn foo() -> std::io::Result<()> {
+    /// try!(fs::symlink_file("a.txt", "b.txt"));
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q)
+                                                        -> io::Result<()>
+    {
+        sys::fs2::symlink_inner(src.as_ref(), dst.as_ref(), false)
+    }
+
+    /// Creates a new directory symlink on the filesystem.
+    ///
+    /// The `dst` path will be a directory symbolic link pointing to the `src`
+    /// path.
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// #![feature(fs_ext)]
+    /// use std::os::windows::fs;
+    ///
+    /// # fn foo() -> std::io::Result<()> {
+    /// try!(fs::symlink_file("a", "b"));
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>> (src: P, dst: Q)
+                                                        -> io::Result<()>
+    {
+        sys::fs2::symlink_inner(src.as_ref(), dst.as_ref(), true)
+    }
 }
 
 /// A prelude for conveniently writing platform-specific code.