std: Stabilize a number of new fs features

[alexcrichton]

This commit stabilizes the following APIs, slating them all to be cherry-picked
into the 1.1 release.

• fs::FileType (and transitively the derived trait implementations)
• fs::Metadata::file_type
• fs::FileType::is_dir
• fs::FileType::is_file
• fs::FileType::is_symlink
• fs::DirEntry::metadata
• fs::DirEntry::file_type
• fs::DirEntry::file_name
• fs::set_permissions
• fs::symlink_metadata
• os::raw::{self, *}
• os::{android, bitrig, linux, ...}::raw::{self, *}
• os::{android, bitrig, linux, ...}::fs::MetadataExt
• os::{android, bitrig, linux, ...}::fs::MetadataExt::as_raw_stat
• os::unix::fs::PermissionsExt
• os::unix::fs::PermissionsExt::mode
• os::unix::fs::PermissionsExt::set_mode
• os::unix::fs::PermissionsExt::from_mode
• os::unix::fs::OpenOptionsExt
• os::unix::fs::OpenOptionsExt::mode
• os::unix::fs::DirEntryExt
• os::unix::fs::DirEntryExt::ino
• os::windows::fs::MetadataExt
• os::windows::fs::MetadataExt::file_attributes
• os::windows::fs::MetadataExt::creation_time
• os::windows::fs::MetadataExt::last_access_time
• os::windows::fs::MetadataExt::last_write_time
• os::windows::fs::MetadataExt::file_size

The os::unix::fs::Metadata structure was also removed entirely, moving all of
its associated methods into the os::unix::fs::MetadataExt trait instead. The
methods are all marked as #[stable] still.

As some minor cleanup, some deprecated and unstable fs apis were also removed:

• File::path
• Metadata::accessed
• Metadata::modified

Features that were explicitly left unstable include:

• fs::WalkDir - the semantics of this were not considered in the recent fs
  expansion RFC.
• fs::DirBuilder - it's still not 100% clear if the naming is right here and if
  the set of functionality exposed is appropriate.
• fs::canonicalize - the implementation on Windows here is specifically in
  question as it always returns a verbatim path. Additionally the Unix
  implementation is susceptible to buffer overflows on long paths unfortunately.
• fs::PathExt - as this is just a convenience trait, it is not stabilized at
  this time.
• fs::set_file_times - this funciton is still waiting on a time abstraction.

[rust-highfive]

r? @huonw

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

[alexcrichton]

r? @aturon

cc @rust-lang/libs

[steveklabnik]

Does this let Cargo build on stable? IIRC, it was only missing some FS labels.

I'm 👍 to backporting this to beta because it's 1.1. If it were 1.2, I'd say just wait.

[alexcrichton]

It does indeed! Cargo also needs the catch_panic feature to build 100% on stable, but it can just not use that feature of git2-rs for now and have panics turn into aborts (Cargo rarely panics anyway)

[retep998]

With this winapi will be able to drop its dependence on libc!

[BurntSushi]

Yay! I think this also lets xsv compile on Rust stable too.

👍

[alexcrichton]

This PR is now entering the final comment period for stabilizing these APIs!

[sfackler]

Should os::windows::fs::MetadataExt::{creation_time, last_access_time, last_write_time} be left unstable until a suitable time type exists, or perhaps renamed in the same style as wait_timeout_ms?

[alexcrichton]

I personally view os::*::fs::MetadataExt as accessors of the raw underlying fields, so even if we had an abstraction for time I'd probably still opt to not return the abstraction but rather the u64 itself. There definitely does seem to be a use case, however, for a middle layer of abstraction sometimes, and this may not be the best way to draw the line in the end.

[sfackler]

Works for me.

[bors]

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

[Stebalien]

I probably missed the discussion but why is this not an (extensible) enum? This seems like a really good candidate. Yes, some of the variants won't make sense on certain platforms but I don't think that's really an issue (we'll just have extra variants) and being able to match on filetype would be really nice.

[Stebalien]

Variants:

enum FileType {
    // Common
    Directory, File, Symlink,
    // Windows Only
    ReparsePoint,
    // Unix Only
    CharDev, BlockDev, NamedPipe, Socket,
    #[doc(hidden)]
    __non_exhaustive
}

[alexcrichton]

We're currently not necessarily considering a hidden/unstable variant to be an "unstable enum", it was mostly just how ErrorKind worked out. The set of file types also varies quite a bit across platforms, and the extra types made somewhat more sense to provide through extension traits instead of via this enum.

Finally, using an opaque structure allows one day accessing the raw bits used to determine the file type which may contain some unknown information.

[Stebalien]

This actually makes it easier to write cross-platform code because the coder doesn't need to care about the platform: they just handle all cases on all platforms (when possible).

[alexcrichton]

It's somewhat of a fine line between being able to write cross-platform code while still understand what is indeed cross platform. If we were to have an exhaustive enum which is the union of all file types on all platforms, it's suddenly not clear what file types come up on which platforms. Which is to say that it's not clear to me that having a union is indeed more cross platform as you're probably still going to have platform-specific code handling various file types on various platforms.

[Stebalien]

We're currently not necessarily considering a hidden/unstable variant to be an "unstable enum", it was mostly just how ErrorKind worked out.

Given that we're already doing this, I don't see why we shouldn't do it here.

The set of file types also varies quite a bit across platforms, and the extra types made somewhat more sense to provide through extension traits instead of via this enum.

The problem with extension traits is that they force the user to care about the platform. With an enum, I could write:

fn format_filetype(s: &mut String, entry: &DirEntry) {
   match entry.file_type() {
        File => s.push('f'),
        NamedPipe => s.push('p'),
        ReparsePoint => s.push('r'),
        Other => s.push('?'),
        // ...
   }
}

With extension traits, I need one function per platform (each one importing a different extension trait). Extension traits are useful when some set of functionality is nonsensical on a platform but in this case, the extra file types make sense, they just aren't used.

Finally, using an opaque structure allows one day accessing the raw bits used to determine the file type which may contain some unknown information.

This unknown information is stored in the Metadata structure. Are you worried about unknown file types or something? Pretty much by definition, a file should only have one type so an enum should always be able to describe it.

[Stebalien]

Sorry, I'm not re-loading before posting... For now, I feel that the enum is small enough that this isn't really an issue however, I can see this becoming an issue in the future as more platforms are added and this enum grows. So I see your point.

[alexcrichton]

triage: beta-accepted

[alexcrichton]

re-r? @aturon

I've rebased and updated this PR to include a snippet in RELEASES.md to talk about the new features.

[retep998]

Uh, shouldn't all these be stable for 1.1.0 and not 1.0.0?

[alexcrichton]

Ah oops, thanks!

[aturon]

This has gone through FCP and been reviewed by the core team, and we're ready to land the stabilization!

@bors: r+

[bors]

📌 Commit ec68c4a has been approved by aturon

[bors]

⌛️ Testing commit ec68c4a with merge 50ab23d...

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-gnu-32-nopt-t, auto-win-gnu-32-opt, auto-win-gnu-64-nopt-t, auto-win-gnu-64-opt