Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

std: Stabilize the fs module #23081

Merged
merged 1 commit into from
Mar 7, 2015
Merged

Conversation

alexcrichton
Copy link
Member

This commit performs a stabilization pass over the std::fs module now that
it's had some time to bake. The change was largely just adding #[stable] tags,
but there are a few APIs that remain #[unstable].

The following apis are now marked #[stable]:

  • std::fs (the name)
  • File
  • Metadata
  • ReadDir
  • DirEntry
  • OpenOptions
  • Permissions
  • File::{open, create}
  • File::{sync_all, sync_data}
  • File::set_len
  • File::metadata
  • Trait implementations for File and &File
  • OpenOptions::new
  • OpenOptions::{read, write, append, truncate, create}
  • OpenOptions::open - this function was modified, however, to not attempt to
    reject cross-platform openings of directories. This means that some platforms
    will succeed in opening a directory and others will fail.
  • Metadata::{is_dir, is_file, len, permissions}
  • Permissions::{readonly, set_readonly}
  • Iterator for ReadDir
  • DirEntry::path
  • remove_file - like with OpenOptions::open, the extra windows code to
    remove a readonly file has been removed. This means that removing a readonly
    file will succeed on some platforms but fail on others.
  • metadata
  • rename
  • copy
  • hard_link
  • soft_link
  • read_link
  • create_dir
  • create_dir_all
  • remove_dir
  • remove_dir_all
  • read_dir

The following apis remain #[unstable].

  • WalkDir and walk - there are many methods by which a directory walk can be
    constructed, and it's unclear whether the current semantics are the right
    ones. For example symlinks are not handled super well currently. This is now
    behind a new fs_walk feature.
  • File::path - this is an extra abstraction which the standard library
    provides on top of what the system offers and it's unclear whether we should
    be doing so. This is now behind a new file_path feature.
  • Metadata::{accessed, modified} - we do not currently have a good
    abstraction for a moment in time which is what these APIs should likely be
    returning, so these remain #[unstable] for now. These are now behind a new
    fs_time feature
  • set_file_times - like with Metadata::accessed, we do not currently have
    the appropriate abstraction for the arguments here so this API remains
    unstable behind the fs_time feature gate.
  • PathExt - the precise set of methods on this trait may change over time and
    some methods may be removed. This API remains unstable behind the path_ext
    feature gate.
  • set_permissions - we may wish to expose a more granular ability to set the
    permissions on a file instead of just a blanket "set all permissions" method.
    This function remains behind the fs feature.

The following apis are now #[deprecated]

The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked #[stable]. The std::fs module has a lot of room to grow and the
material is being tracked in a RFC issue.

Closes #22879

[breaking-change]

@rust-highfive
Copy link
Collaborator

r? @huonw

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

@aturon aturon mentioned this pull request Mar 5, 2015
91 tasks
@alexcrichton
Copy link
Member Author

r? @aturon

@rust-highfive rust-highfive assigned aturon and unassigned huonw Mar 5, 2015
@aturon
Copy link
Member

aturon commented Mar 5, 2015

@alexcrichton Would you mind putting the remarks about bits you're keeping as unstable in the stability reason itself? That helps us keep track of what needs to be resolved before stabilization.

pub struct DirEntry(fs_imp::DirEntry);

/// An iterator that recursively walks over the contents of a directory.
#[unstable(feature = "fs_walk")]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add in the reason that you have in the commit message here?

@aturon
Copy link
Member

aturon commented Mar 5, 2015

OK, I've left a few nits, but otherwise r=me.

@alexcrichton
Copy link
Member Author

@bors: r=aturon 3684a98

This commit performs a stabilization pass over the `std::fs` module now that
it's had some time to bake. The change was largely just adding `#[stable]` tags,
but there are a few APIs that remain `#[unstable]`.

The following apis are now marked `#[stable]`:

* `std::fs` (the name)
* `File`
* `Metadata`
* `ReadDir`
* `DirEntry`
* `OpenOptions`
* `Permissions`
* `File::{open, create}`
* `File::{sync_all, sync_data}`
* `File::set_len`
* `File::metadata`
* Trait implementations for `File` and `&File`
* `OpenOptions::new`
* `OpenOptions::{read, write, append, truncate, create}`
* `OpenOptions::open` - this function was modified, however, to not attempt to
  reject cross-platform openings of directories. This means that some platforms
  will succeed in opening a directory and others will fail.
* `Metadata::{is_dir, is_file, len, permissions}`
* `Permissions::{readonly, set_readonly}`
* `Iterator for ReadDir`
* `DirEntry::path`
* `remove_file` - like with `OpenOptions::open`, the extra windows code to
  remove a readonly file has been removed. This means that removing a readonly
  file will succeed on some platforms but fail on others.
* `metadata`
* `rename`
* `copy`
* `hard_link`
* `soft_link`
* `read_link`
* `create_dir`
* `create_dir_all`
* `remove_dir`
* `remove_dir_all`
* `read_dir`

The following apis remain `#[unstable]`.

* `WalkDir` and `walk` - there are many methods by which a directory walk can be
  constructed, and it's unclear whether the current semantics are the right
  ones. For example symlinks are not handled super well currently. This is now
  behind a new `fs_walk` feature.
* `File::path` - this is an extra abstraction which the standard library
  provides on top of what the system offers and it's unclear whether we should
  be doing so. This is now behind a new `file_path` feature.
* `Metadata::{accessed, modified}` - we do not currently have a good
  abstraction for a moment in time which is what these APIs should likely be
  returning, so these remain `#[unstable]` for now. These are now behind a new
  `fs_time` feature
* `set_file_times` - like with `Metadata::accessed`, we do not currently have
  the appropriate abstraction for the arguments here so this API remains
  unstable behind the `fs_time` feature gate.
* `PathExt` - the precise set of methods on this trait may change over time and
  some methods may be removed. This API remains unstable behind the `path_ext`
  feature gate.
* `set_permissions` - we may wish to expose a more granular ability to set the
  permissions on a file instead of just a blanket "set all permissions" method.
  This function remains behind the `fs` feature.

The following apis are now `#[deprecated]`

* The `TempDir` type is now entirely deprecated and is [located on
  crates.io][tempdir] as the `tempdir` crate with [its source][github] at
  rust-lang/tempdir.

[tempdir]: https://crates.io/crates/tempdir
[github]: https://github.com/rust-lang/tempdir

The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked `#[stable]`. The `std::fs` module has a lot of room to grow and the
material is [being tracked in a RFC issue][rfc-issue].

[rfc-issue]: rust-lang/rfcs#939

[breaking-change]
@alexcrichton
Copy link
Member Author

@bors: r=aturon 73b0b25

Manishearth added a commit to Manishearth/rust that referenced this pull request Mar 6, 2015
 This commit performs a stabilization pass over the `std::fs` module now that
it's had some time to bake. The change was largely just adding `#[stable]` tags,
but there are a few APIs that remain `#[unstable]`.

The following apis are now marked `#[stable]`:

* `std::fs` (the name)
* `File`
* `Metadata`
* `ReadDir`
* `DirEntry`
* `OpenOptions`
* `Permissions`
* `File::{open, create}`
* `File::{sync_all, sync_data}`
* `File::set_len`
* `File::metadata`
* Trait implementations for `File` and `&File`
* `OpenOptions::new`
* `OpenOptions::{read, write, append, truncate, create}`
* `OpenOptions::open` - this function was modified, however, to not attempt to
  reject cross-platform openings of directories. This means that some platforms
  will succeed in opening a directory and others will fail.
* `Metadata::{is_dir, is_file, len, permissions}`
* `Permissions::{readonly, set_readonly}`
* `Iterator for ReadDir`
* `DirEntry::path`
* `remove_file` - like with `OpenOptions::open`, the extra windows code to
  remove a readonly file has been removed. This means that removing a readonly
  file will succeed on some platforms but fail on others.
* `metadata`
* `rename`
* `copy`
* `hard_link`
* `soft_link`
* `read_link`
* `create_dir`
* `create_dir_all`
* `remove_dir`
* `remove_dir_all`
* `read_dir`

The following apis remain `#[unstable]`.

* `WalkDir` and `walk` - there are many methods by which a directory walk can be
  constructed, and it's unclear whether the current semantics are the right
  ones. For example symlinks are not handled super well currently. This is now
  behind a new `fs_walk` feature.
* `File::path` - this is an extra abstraction which the standard library
  provides on top of what the system offers and it's unclear whether we should
  be doing so. This is now behind a new `file_path` feature.
* `Metadata::{accessed, modified}` - we do not currently have a good
  abstraction for a moment in time which is what these APIs should likely be
  returning, so these remain `#[unstable]` for now. These are now behind a new
  `fs_time` feature
* `set_file_times` - like with `Metadata::accessed`, we do not currently have
  the appropriate abstraction for the arguments here so this API remains
  unstable behind the `fs_time` feature gate.
* `PathExt` - the precise set of methods on this trait may change over time and
  some methods may be removed. This API remains unstable behind the `path_ext`
  feature gate.
* `set_permissions` - we may wish to expose a more granular ability to set the
  permissions on a file instead of just a blanket \"set all permissions\" method.
  This function remains behind the `fs` feature.

The following apis are now `#[deprecated]`

* The `TempDir` type is now entirely deprecated and is [located on
  crates.io][tempdir] as the `tempdir` crate with [its source][github] at
  rust-lang/tempdir.

[tempdir]: https://crates.io/crates/tempdir
[github]: https://github.com/rust-lang/tempdir

The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked `#[stable]`. The `std::fs` module has a lot of room to grow and the
material is [being tracked in a RFC issue][rfc-issue].

[rfc-issue]: rust-lang/rfcs#939

Closes rust-lang#22879

[breaking-change]
@blaenk
Copy link
Contributor

blaenk commented Mar 6, 2015

good thing I saw this, now I know that tempdir is a separate crate. sounds good to me :D

@huonw huonw mentioned this pull request Mar 6, 2015
10 tasks
@bors bors merged commit 73b0b25 into rust-lang:master Mar 7, 2015
@alexcrichton alexcrichton deleted the stabilize-fs branch March 7, 2015 06:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Stop statting paths before opening them
6 participants