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

lambda · 2015-04-09T07:36:14Z

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.

rust-highfive · 2015-04-09T07:36:30Z

r? @huonw

(rust_highfive has picked a reviewer for you, use r? to override)

bors · 2015-04-15T03:17:36Z

☔ The latest upstream changes (presumably #24433) made this pull request unmergeable. Please resolve the merge conflicts.

lambda · 2015-04-15T17:24:02Z

I've rebased and updated to include the split into std::os::unix::symlink and std::os::windows::{symlink_file, symlink_dir} per the latest discussion on rust-lang/rfcs#1048.

I don't have Windows available to build or test on, and tests for symlinks on a buildbot don't work properly as you need special permissions to create symlinks on Windows, so if it would be possible for someone to try it out and make sure that I didn't break anything on Windows I would appreciate that.

r? @alexcrichton

alexcrichton · 2015-04-15T17:25:47Z

src/libstd/sys/unix/ext.rs

+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>


symlink_file => symlink ?

Whoops, fixed.

alexcrichton · 2015-04-15T17:27:53Z

Looks great, thanks @lambda! It's ok to not worry about symlink tests for windows right now.

alexcrichton · 2015-04-17T23:45:48Z

src/libstd/fs.rs

@@ -828,17 +832,20 @@ pub fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<(
 /// # Ok(())
 /// # }
 /// ```
+#[deprecated(since = "1.0.0",
+             reason = "replaced with std::os::unix::fs::symlink and \
+                       std::os::windows::{symlink_file, symlink_dir}")]


Oh oops, windows::{ -> windows::fs::{

Whoops, thanks for the catch.

alexcrichton · 2015-04-17T23:46:51Z

I've now merged the RFC, just noticed a few nits though, but other than that r=me

lambda · 2015-04-18T03:53:48Z

Fixed up the nits.

r? @alexcrichton

alexcrichton · 2015-04-18T04:23:20Z

@bors: r+ acd426b

Thanks!

bors · 2015-04-18T07:03:34Z

⌛ Testing commit acd426b with merge caa75f0...

bors · 2015-04-18T07:09:21Z

💔 Test failed - auto-win-64-nopt-t

lambda · 2015-04-18T13:16:56Z

Added missing use statement.

r? @alexcrichton

alexcrichton · 2015-04-18T14:59:30Z

@bors: r+ 14044c9

bors · 2015-04-18T16:43:40Z

⌛ Testing commit 14044c9 with merge 1556209...

bors · 2015-04-18T17:53:08Z

💔 Test failed - auto-linux-64-nopt-t

lambda · 2015-04-21T04:12:50Z

Added feature gates to doc tests, and actually ran doc tests this time to ensure they work.

r? @alexcrichton

alexcrichton · 2015-04-21T05:11:34Z

@bors: r+ 1489e23

bors · 2015-04-21T10:00:25Z

⌛ Testing commit 1489e23 with merge feb8acd...

bors · 2015-04-21T11:46:14Z

💔 Test failed - auto-linux-64-nopt-t

lambda · 2015-04-21T13:29:16Z

😞 Hmm, this failure doesn't look like it's related to my change; it looks like it just hung for some unknown reason.

alexcrichton · 2015-04-21T15:08:28Z

@bors: retry

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`.

lambda · 2015-04-21T16:16:18Z

I realized that the Windows doc tests were likely to fail, because I included examples in the Windows docs, but as discussed, you can't create symlinks without special privileges.

I've updated the Windows example to use ignore to prevent this. Apologies for the churn.

r? @alexcrichton

alexcrichton · 2015-04-21T18:39:12Z

@bors: r+ 3cc84ef

No worries!

Implement [RFC rust-lang#1048][rfc]. 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`. [rfc]: rust-lang/rfcs#1048

rust-highfive assigned huonw Apr 9, 2015

lambda mentioned this pull request Apr 9, 2015

RFC: split up fs::soft_link into os::unix::fs::symlink and os::windows::fs::{symlink_file, symlink_dir} rust-lang/rfcs#1048

Merged

lambda force-pushed the rename-soft-link-to-symlink branch from 15ab7b4 to 72cfaae Compare April 15, 2015 17:19

rust-highfive assigned alexcrichton and unassigned huonw Apr 15, 2015

alexcrichton reviewed Apr 15, 2015
View reviewed changes

lambda force-pushed the rename-soft-link-to-symlink branch 2 times, most recently from 3c824c7 to e9f950b Compare April 15, 2015 18:00

alexcrichton reviewed Apr 17, 2015
View reviewed changes

lambda force-pushed the rename-soft-link-to-symlink branch from e9f950b to acd426b Compare April 18, 2015 03:17

lambda force-pushed the rename-soft-link-to-symlink branch from acd426b to 14044c9 Compare April 18, 2015 13:15

lambda force-pushed the rename-soft-link-to-symlink branch from 14044c9 to 1489e23 Compare April 21, 2015 04:10

lambda force-pushed the rename-soft-link-to-symlink branch from 1489e23 to 3cc84ef Compare April 21, 2015 16:14

bors merged commit 3cc84ef into rust-lang:master Apr 22, 2015

lambda changed the title ~~Rename std::fs::soft_link to std::fs::symlink~~ Deprecate std::fs::soft_link in favor of platform-specific versions Apr 27, 2015

pnkfelix mentioned this pull request Apr 29, 2015

std: Add missing stability for symlink functions #24724

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

lambda commented Apr 9, 2015

rust-highfive commented Apr 9, 2015

bors commented Apr 15, 2015

lambda commented Apr 15, 2015

alexcrichton Apr 15, 2015

lambda Apr 15, 2015

alexcrichton commented Apr 15, 2015

alexcrichton Apr 17, 2015

lambda Apr 18, 2015

alexcrichton commented Apr 17, 2015

lambda commented Apr 18, 2015

alexcrichton commented Apr 18, 2015

bors commented Apr 18, 2015

bors commented Apr 18, 2015

lambda commented Apr 18, 2015

alexcrichton commented Apr 18, 2015

bors commented Apr 18, 2015

bors commented Apr 18, 2015

lambda commented Apr 21, 2015

alexcrichton commented Apr 21, 2015

bors commented Apr 21, 2015

bors commented Apr 21, 2015

lambda commented Apr 21, 2015

alexcrichton commented Apr 21, 2015

lambda commented Apr 21, 2015

alexcrichton commented Apr 21, 2015

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

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

Conversation

lambda commented Apr 9, 2015

rust-highfive commented Apr 9, 2015

bors commented Apr 15, 2015

lambda commented Apr 15, 2015

alexcrichton Apr 15, 2015

Choose a reason for hiding this comment

lambda Apr 15, 2015

Choose a reason for hiding this comment

alexcrichton commented Apr 15, 2015

alexcrichton Apr 17, 2015

Choose a reason for hiding this comment

lambda Apr 18, 2015

Choose a reason for hiding this comment

alexcrichton commented Apr 17, 2015

lambda commented Apr 18, 2015

alexcrichton commented Apr 18, 2015

bors commented Apr 18, 2015

bors commented Apr 18, 2015

lambda commented Apr 18, 2015

alexcrichton commented Apr 18, 2015

bors commented Apr 18, 2015

bors commented Apr 18, 2015

lambda commented Apr 21, 2015

alexcrichton commented Apr 21, 2015

bors commented Apr 21, 2015

bors commented Apr 21, 2015

lambda commented Apr 21, 2015

alexcrichton commented Apr 21, 2015

lambda commented Apr 21, 2015

alexcrichton commented Apr 21, 2015