See CHANGELOG for a description of what’s been done.
--- /dev/null
+symlink 1.0.0 (unreleased)
+==========================
+
+Completely backwards-compatible, but I think it’s time to declare it 1.0.0 rather than releasing this as 0.1.1.
+
+• All functions are now available on all platforms.
+ Before, cfg(not(any(target_os = "redox", unix, windows))) platforms got an empty crate.
+ Now, the functions will fall back to std::fs::soft_link and std::fs::remove_file on other platforms,
+ which typically means trying to create a symlink will produce an std::io::ErrorKind::Unsupported error.
+
+ • But this does mean that wasm32-wasi now works (though untested).
+
+• I updated the documentation for correctness.
+ Most obviously, I said this crate wasn’t as useful as it looked because stable Windows couldn’t do symlinks yet.
+ Well, that was five years ago. For four and a half it has been able to.
+
+• I adjusted some stylistic conventions in code and comments throughout.
+ Things like links in the documentation, for example.
+
+• I have removed all mentions of Redox, including in cfg(target_os = "redox").
+ This used to be necessary, but in mid-2019 Redox became unix-family <https://github.com/rust-lang/rust/pull/60547>.
+
+• I now offer this crate under the BlueOak-1.0.0 license, as well the existing Apache-2.0 and MIT licenses.
+
+symlink 0.1.0 (2017-01-27)
+==========================
+
+initial release
-This project is dual-licensed under the terms of the MIT and Apache (version 2.0) licenses.
+Copyright © 2017–2022 Chris Morgan
-Copyright (c) 2014 Chris Morgan and the Teepee project developers
+This project is distributed under the terms of three different licenses,
+at your choice:
+
+- Blue Oak Model License 1.0.0: https://blueoakcouncil.org/license/1.0.0
+- MIT License: https://opensource.org/licenses/MIT
+- Apache License, Version 2.0: https://www.apache.org/licenses/LICENSE-2.0
+
+If you do not have particular cause to select the MIT or the Apache-2.0
+license, Chris Morgan recommends that you select BlueOak-1.0.0, which is
+better and simpler than both MIT and Apache-2.0, which are only offered
+due to their greater recognition and their conventional use in the Rust
+ecosystem. (BlueOak-1.0.0 was only published in March 2019.)
+
+When using this code, ensure you comply with the terms of at least one of
+these licenses.
[package]
name = "symlink"
-version = "0.1.0"
-authors = ["Chris Morgan <me@chrismorgan.info>"]
description = "Create symlinks in a cross-platform manner"
-documentation = "https://docs.rs/symlink"
-repository = "https://gitlab.com/chris-morgan/symlink"
+authors = ["Chris Morgan <rust@chrismorgan.info>"]
+license = "BlueOak-1.0.0 OR MIT OR Apache-2.0"
+version = "0.1.0"
readme = "README.md"
keywords = ["file", "fs"]
categories = ["filesystem"]
-license = "MIT/Apache-2.0"
+repository = "https://git.chrismorgan.info/symlink"
+++ /dev/null
- Apache License
- Version 2.0, January 2004
- http://www.apache.org/licenses/
-
-TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-1. Definitions.
-
- "License" shall mean the terms and conditions for use, reproduction,
- and distribution as defined by Sections 1 through 9 of this document.
-
- "Licensor" shall mean the copyright owner or entity authorized by
- the copyright owner that is granting the License.
-
- "Legal Entity" shall mean the union of the acting entity and all
- other entities that control, are controlled by, or are under common
- control with that entity. For the purposes of this definition,
- "control" means (i) the power, direct or indirect, to cause the
- direction or management of such entity, whether by contract or
- otherwise, or (ii) ownership of fifty percent (50%) or more of the
- outstanding shares, or (iii) beneficial ownership of such entity.
-
- "You" (or "Your") shall mean an individual or Legal Entity
- exercising permissions granted by this License.
-
- "Source" form shall mean the preferred form for making modifications,
- including but not limited to software source code, documentation
- source, and configuration files.
-
- "Object" form shall mean any form resulting from mechanical
- transformation or translation of a Source form, including but
- not limited to compiled object code, generated documentation,
- and conversions to other media types.
-
- "Work" shall mean the work of authorship, whether in Source or
- Object form, made available under the License, as indicated by a
- copyright notice that is included in or attached to the work
- (an example is provided in the Appendix below).
-
- "Derivative Works" shall mean any work, whether in Source or Object
- form, that is based on (or derived from) the Work and for which the
- editorial revisions, annotations, elaborations, or other modifications
- represent, as a whole, an original work of authorship. For the purposes
- of this License, Derivative Works shall not include works that remain
- separable from, or merely link (or bind by name) to the interfaces of,
- the Work and Derivative Works thereof.
-
- "Contribution" shall mean any work of authorship, including
- the original version of the Work and any modifications or additions
- to that Work or Derivative Works thereof, that is intentionally
- submitted to Licensor for inclusion in the Work by the copyright owner
- or by an individual or Legal Entity authorized to submit on behalf of
- the copyright owner. For the purposes of this definition, "submitted"
- means any form of electronic, verbal, or written communication sent
- to the Licensor or its representatives, including but not limited to
- communication on electronic mailing lists, source code control systems,
- and issue tracking systems that are managed by, or on behalf of, the
- Licensor for the purpose of discussing and improving the Work, but
- excluding communication that is conspicuously marked or otherwise
- designated in writing by the copyright owner as "Not a Contribution."
-
- "Contributor" shall mean Licensor and any individual or Legal Entity
- on behalf of whom a Contribution has been received by Licensor and
- subsequently incorporated within the Work.
-
-2. Grant of Copyright License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- copyright license to reproduce, prepare Derivative Works of,
- publicly display, publicly perform, sublicense, and distribute the
- Work and such Derivative Works in Source or Object form.
-
-3. Grant of Patent License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- (except as stated in this section) patent license to make, have made,
- use, offer to sell, sell, import, and otherwise transfer the Work,
- where such license applies only to those patent claims licensable
- by such Contributor that are necessarily infringed by their
- Contribution(s) alone or by combination of their Contribution(s)
- with the Work to which such Contribution(s) was submitted. If You
- institute patent litigation against any entity (including a
- cross-claim or counterclaim in a lawsuit) alleging that the Work
- or a Contribution incorporated within the Work constitutes direct
- or contributory patent infringement, then any patent licenses
- granted to You under this License for that Work shall terminate
- as of the date such litigation is filed.
-
-4. Redistribution. You may reproduce and distribute copies of the
- Work or Derivative Works thereof in any medium, with or without
- modifications, and in Source or Object form, provided that You
- meet the following conditions:
-
- (a) You must give any other recipients of the Work or
- Derivative Works a copy of this License; and
-
- (b) You must cause any modified files to carry prominent notices
- stating that You changed the files; and
-
- (c) You must retain, in the Source form of any Derivative Works
- that You distribute, all copyright, patent, trademark, and
- attribution notices from the Source form of the Work,
- excluding those notices that do not pertain to any part of
- the Derivative Works; and
-
- (d) If the Work includes a "NOTICE" text file as part of its
- distribution, then any Derivative Works that You distribute must
- include a readable copy of the attribution notices contained
- within such NOTICE file, excluding those notices that do not
- pertain to any part of the Derivative Works, in at least one
- of the following places: within a NOTICE text file distributed
- as part of the Derivative Works; within the Source form or
- documentation, if provided along with the Derivative Works; or,
- within a display generated by the Derivative Works, if and
- wherever such third-party notices normally appear. The contents
- of the NOTICE file are for informational purposes only and
- do not modify the License. You may add Your own attribution
- notices within Derivative Works that You distribute, alongside
- or as an addendum to the NOTICE text from the Work, provided
- that such additional attribution notices cannot be construed
- as modifying the License.
-
- You may add Your own copyright statement to Your modifications and
- may provide additional or different license terms and conditions
- for use, reproduction, or distribution of Your modifications, or
- for any such Derivative Works as a whole, provided Your use,
- reproduction, and distribution of the Work otherwise complies with
- the conditions stated in this License.
-
-5. Submission of Contributions. Unless You explicitly state otherwise,
- any Contribution intentionally submitted for inclusion in the Work
- by You to the Licensor shall be under the terms and conditions of
- this License, without any additional terms or conditions.
- Notwithstanding the above, nothing herein shall supersede or modify
- the terms of any separate license agreement you may have executed
- with Licensor regarding such Contributions.
-
-6. Trademarks. This License does not grant permission to use the trade
- names, trademarks, service marks, or product names of the Licensor,
- except as required for reasonable and customary use in describing the
- origin of the Work and reproducing the content of the NOTICE file.
-
-7. Disclaimer of Warranty. Unless required by applicable law or
- agreed to in writing, Licensor provides the Work (and each
- Contributor provides its Contributions) on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied, including, without limitation, any warranties or conditions
- of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
- PARTICULAR PURPOSE. You are solely responsible for determining the
- appropriateness of using or redistributing the Work and assume any
- risks associated with Your exercise of permissions under this License.
-
-8. Limitation of Liability. In no event and under no legal theory,
- whether in tort (including negligence), contract, or otherwise,
- unless required by applicable law (such as deliberate and grossly
- negligent acts) or agreed to in writing, shall any Contributor be
- liable to You for damages, including any direct, indirect, special,
- incidental, or consequential damages of any character arising as a
- result of this License or out of the use or inability to use the
- Work (including but not limited to damages for loss of goodwill,
- work stoppage, computer failure or malfunction, or any and all
- other commercial damages or losses), even if such Contributor
- has been advised of the possibility of such damages.
-
-9. Accepting Warranty or Additional Liability. While redistributing
- the Work or Derivative Works thereof, You may choose to offer,
- and charge a fee for, acceptance of support, warranty, indemnity,
- or other liability obligations and/or rights consistent with this
- License. However, in accepting such obligations, You may act only
- on Your own behalf and on Your sole responsibility, not on behalf
- of any other Contributor, and only if You agree to indemnify,
- defend, and hold each Contributor harmless for any liability
- incurred by, or claims asserted against, such Contributor by reason
- of your accepting any such warranty or additional liability.
-
-END OF TERMS AND CONDITIONS
-
-APPENDIX: How to apply the Apache License to your work.
-
- To apply the Apache License to your work, attach the following
- boilerplate notice, with the fields enclosed by brackets "[]"
- replaced with your own identifying information. (Don't include
- the brackets!) The text should be enclosed in the appropriate
- comment syntax for the file format. We also recommend that a
- file or class name and description of purpose be included on the
- same "printed page" as the copyright notice for easier
- identification within third-party archives.
-
-Copyright [yyyy] [name of copyright owner]
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+++ /dev/null
-Copyright (c) 2014 Chris Morgan and the Teepee project developers
-
-Permission is hereby granted, free of charge, to any
-person obtaining a copy of this software and associated
-documentation files (the "Software"), to deal in the
-Software without restriction, including without
-limitation the rights to use, copy, modify, merge,
-publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software
-is furnished to do so, subject to the following
-conditions:
-
-The above copyright notice and this permission notice
-shall be included in all copies or substantial portions
-of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
-ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
-TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
-PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
-SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
-IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-DEALINGS IN THE SOFTWARE.
Rust’s standard library exposes platform-specific ways to create symlinks:
- On Windows, `std::os::windows::fs::{symlink_file, symlink_dir}` (because Windows does file and directory symlinks differently);
-- On Unixy platforms and Redox, `std::os::unix::fs::symlink` (because they don’t care about whether it’s a file or a directory).
+- On Unix platforms, `std::os::unix::fs::symlink` (because they don’t care about whether it’s a file or a directory).
-The situation is similar when removing symlinks: on Unixy platforms all symlinks are files and must be removed with `std::fs::remove_file`, but on Windows directory symlinks must be removed with `std::fs::remove_dir` instead.
+There’s also `std::fs::soft_link`, deprecated because of the whole Windows situation, but potentially still useful: as I write, at the start of 2022, it’s the only stable way to create a symlink on the wasm32-wasi target (`std::os::wasi::fs::symlink_path` not yet being stable).
-This is all a pain: as soon as you touch symlinks for Unix you need to add in lots of `#[cfg]` branches and other such messy things, or else lose Windows support for no good reason.
+The situation is similar when removing symlinks: on most platforms all symlinks are files and must be removed with `std::fs::remove_file`, but on Windows directory symlinks must be removed with `std::fs::remove_dir` instead.
+
+This is all a pain: as soon as you touch symlinks for Unix you need to add in lots of `#[cfg]` branches and other such messy things, or else lose Windows support for no good reason, or use a deprecated function that makes directory symlinks not work on Windows.
Enter the `symlink` crate. This crate gives you six cross-platform functions instead:
- `remove_symlink_dir`, which removes a directory symlink on Windows and a perfectly ordinary symlink on other platforms;
- `remove_symlink_auto`, which removes a file or directory symlink on Windows, depending on an examination of the path, and a perfectly ordinary symlink on other platforms.
-“What about `std::fs::soft_link`?” I hear you say. Yeah, that one got deprecated in Rust 1.1.0 because it didn’t do anything clever on Windows, it just created a file symlink, which is often wrong. `symlink_auto` creates a file *or* directory symlink, depending on what the target is. (Unlike `symlink_file` and `symlink_dir`, it returns an error if the destination doesn’t exist or can’t be statted.)
-
-And there’s no good way to delete a symlink at all.
+Back on the topic of `std::fs::soft_link`: it got deprecated in Rust 1.1.0 because it just created a file symlink on Windows, which is often wrong. `symlink_auto` creates a file *or* directory symlink, depending on what the target is. (But it’s also more fragile: unlike `symlink_file` and `symlink_dir`, it returns an error if the destination doesn’t exist or can’t be statted.)
-So that’s why this crate exists.
+And before this crate there was no good way to delete a symlink at all on Windows. Who knows, perhaps windows_file_type_ext will be stabilised eventually. But until then, there’s this crate.
## Best practices
**Make sure you use absolute paths for the destination.** I haven’t tested whether relative paths are treated consistently across platforms yet (whether they’re relative to the working directory or the symlink source path). TODO!
-## Caution: this isn’t as useful as it looks
+## Caution: symlinks are still less reliable on Windows
-So now you can create or delete symlinks, right? Not so fast. Although Windows supports symlinks from Windows Vista onwards, it was viewed as a security or compatibility or something risk, and so prior to the Windows 10 Creators Update (due by mid-2017; currently available through the Windows Insider Program) it requires a special privilege, which basically means you’ve got to run a program as admin for it to be allowed to manipulate symlinks.
+You can only reliably use symlinks from the Windows 10 Creators Update (mid-2017) onwards.
-Also [Rust PR #38921](https://github.com/rust-lang/rust/pull/38921) needs to land before unprivileged symlink creation will work on the Windows 10 Creators Update. So we’re talking Rust 1.16 as the earliest.
+Before that, manipulating symlinks required a special privilege which practically meant you had to run a program as admin to get it to work. And symlinks were new to Vista; XP and older didn’t support them.
## My goal: integration with Rust
**Concerning `remove_*`**: I guess what’s done with the other three functions will guide what’s done with these three.
-## Usage
-
-Cargo all the way: it’s the [`symlink` crate on crates.io](http://crates.io/crates/symlink).
-
## Unsafe code in this library
-On Windows only there is some unavoidable unsafe code in `remove_symlink_auto` to determine whether a symlink is a file symlink or a directory symlink, because this detail is not exposed in the standard library.
+On Windows only there is some unavoidable unsafe code in `remove_symlink_auto` to determine whether a symlink is a file symlink or a directory symlink, because this detail is not exposed in a stable function in the standard library.
## Author
-[Chris Morgan](http://chrismorgan.info/) ([chris-morgan](https://gitlab.com/chris-morgan)) is the primary author and maintainer of this library.
+[Chris Morgan](https://chrismorgan.info/) is the author and maintainer of this library.
## License
-This library is distributed under similar terms to Rust: dual licensed under the MIT license and the Apache license (version 2.0).
+Copyright © 2017–2022 Chris Morgan
+
+This project is distributed under the terms of three different licenses,
+at your choice:
+
+- Blue Oak Model License 1.0.0: https://blueoakcouncil.org/license/1.0.0
+- MIT License: https://opensource.org/licenses/MIT
+- Apache License, Version 2.0: https://www.apache.org/licenses/LICENSE-2.0
+
+If you do not have particular cause to select the MIT or the Apache-2.0
+license, Chris Morgan recommends that you select BlueOak-1.0.0, which is
+better and simpler than both MIT and Apache-2.0, which are only offered
+due to their greater recognition and their conventional use in the Rust
+ecosystem. (BlueOak-1.0.0 was only published in March 2019.)
-See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.
+When using this code, ensure you comply with the terms of at least one of
+these licenses.
//! A small, cross-platform crate for creating symlinks.
//!
-#![cfg_attr(not(any(target_os = "redox", unix, windows)), doc = "**This platform is not Unix, Windows or Redox; symlinks are not available.**")]
-//!
-//! For efficiency, you should prefer to use `symlink_file` or `symlink_dir`—whichever is
-//! appropriate—rather than `symlink_auto`
+//! For efficiency, you should prefer to use [`symlink_file`] or [`symlink_dir`]—whichever is
+//! appropriate—rather than [`symlink_auto`].
+
+// Building docs produces rustdoc::broken_intra_doc_links warnings on std::os::{windows, unix},
+// depending on your platform. This is unfortunate because I then can’t RUSTDOCFLAGS="-D warnings"
+// unless I suppress those, but suppressing those ones alone is messy, and suppressing all harmful,
+// so I’m just leaving it at spurious square brackets being left in the output.
// It’s generally nicer to produce an empty crate on unsupported platforms than to explode.
#[path = "windows/mod.rs"]
mod internal;
-#[cfg(any(target_os = "redox", unix))]
+#[cfg(not(windows))]
mod internal {
pub use std::fs::remove_file as remove_symlink_dir;
pub use std::fs::remove_file as remove_symlink_auto;
- // Note that this symlink function takes src and dst as &Path rather than as impl AsRef<Path>.
- // I don’t know why that is, but I think we’ll go with impl AsRef<Path> in our public
- // functions. Because of this disparity of signature, when I say that things are equivalent to
- // calling std::os::unix::fs::symlink on Unix, you can see that I’m not being *quite* rigorous.
+ // Look, frankly, std::fs::soft_link and std::os::unix::fs::symlink call the same function,
+ // so this probably whole separate mod probably isn’t even warranted.
+ // But deprecated blah blah blah so I decided to use the std::os one anyway.
+ #[cfg(unix)]
pub use std::os::unix::fs::{symlink as symlink_auto,
symlink as symlink_file,
symlink as symlink_dir};
+ #[cfg(not(unix))]
+ // The compiler claims that std::fs::soft_link has been “replaced with
+ // std::os::unix::fs::symlink and std::os::windows::fs::{symlink_file, symlink_dir}”
+ // (rustc nightly 2021-12-26 deprecation warning message), but although that was true enough
+ // when it was deprecated, it’s no longer quite true because of the wasm32-wasi target, which
+ // supports symlinks through std::fs::soft_link but has no stable alternative (as I write,
+ // std::os::wasi::fs::symlink_path is behind feature(wasi_ext)). Frankly, I think that’s a fair
+ // (though imperfect) reason to *undeprecate* soft_link. Who knows what other platforms may in
+ // the future stop returning std::io::ErrorKind::Unsupported errors and start supporting
+ // std::fs::soft_link? (And for clarity, I note that no others do at the time of writing.)
+ #[allow(deprecated)]
+ pub use std::fs::{soft_link as symlink_auto,
+ soft_link as symlink_file,
+ soft_link as symlink_dir};
}
/// Create a symlink (non-preferred way).
/// type of symlink based on that result. Therefore, if the destination does not exist or if you do
/// not have permission to fetch its metadata, this will return an error on Windows.
///
-/// On Unix platforms there is no distinction, so this isn’t magic: it’s precisely equivalent to
-/// calling `std::os::unix::fs::symlink`.
+/// On other platforms there is no distinction, so this isn’t magic: it’s precisely equivalent to
+/// calling [`std::os::unix::fs::symlink`] or [`std::fs::soft_link`].
///
/// # A note on using this function
///
/// Because this is slightly less efficient and more hazardous on Windows, you should prefer to use
-/// [`symlink_file`](fn.symlink_file.html) or [`symlink_dir`](fn.symlink_dir.html) instead. Only
-/// use this if you don’t know or care whether the destination is a file or a directory (but even
-/// then, you do need to know that it exists).
+/// [`symlink_file`] or [`symlink_dir`] instead. Only use this if you don’t know or care whether
+/// the destination is a file or a directory (but even then, you do need to know that it exists).
///
/// # Errors
///
/// An error will be returned if the symlink cannot be created, or—on Windows—if the destination
/// does not exist or cannot be read.
-#[cfg(any(target_os = "redox", unix, windows))]
#[inline]
pub fn symlink_auto<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
internal::symlink_auto(src.as_ref(), dst.as_ref())
/// Create a symlink to a file.
///
-/// On Windows, this is equivalent to `std::os::windows::fs::symlink_file`. If you call it with a
-/// directory as the destination, TODO CONSEQUENCES.
+/// On Windows, this is equivalent to [`std::os::windows::fs::symlink_file`]. If you call it with a
+/// directory as the destination, [something may happen; you never know what][fow].
///
-/// On Unix, this is equivalent to `std::os::unix::fs::symlink`. If you call it with a directory as
-/// the destination, nothing bad will happen, but you’re ruining your cross-platform technique and
-/// ruining the point of this crate, so please don’t.
+/// On Unix, this is equivalent to [`std::os::unix::fs::symlink`], and on other platforms it’s
+/// equivalent to [`std::fs::soft_link`]. If you call it with a directory as the destination,
+/// nothing bad will happen, but you’re ruining your cross-platform technique and ruining the point
+/// of this crate, so please don’t.
///
/// # Errors
///
/// An error will be returned if the symlink cannot be created.
-#[cfg(any(target_os = "redox", unix, windows))]
+///
+/// [fow]: https://en.wikipedia.org/wiki/A_Fish_Out_of_Water_(book)
#[inline]
pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
internal::symlink_file(src.as_ref(), dst.as_ref())
/// Create a symlink to a directory.
///
-/// On Windows, this is equivalent to `std::os::windows::fs::symlink_dir`. If you call it with a
-/// directory as the destination, TODO CONSEQUENCES.
+/// On Windows, this is equivalent to [`std::os::windows::fs::symlink_dir`]. If you call it with a
+/// directory as the destination, [something may happen; you never know what][fow].
///
-/// On Unix, this is equivalent to `std::os::unix::fs::symlink`. If you call it with a directory as
-/// the destination, nothing bad will happen, but you’re ruining your cross-platform technique and
-/// ruining the point of this crate, so please don’t.
+/// On Unix, this is equivalent to [`std::os::unix::fs::symlink`], and on other platforms it’s
+/// equivalent to [`std::fs::soft_link`]. If you call it with a directory as the destination,
+/// nothing bad will happen, but you’re ruining your cross-platform technique and ruining the point
+/// of this crate, so please don’t.
///
/// # Errors
///
/// An error will be returned if the symlink cannot be created.
-#[cfg(any(target_os = "redox", unix, windows))]
+///
+/// [fow]: https://en.wikipedia.org/wiki/A_Fish_Out_of_Water_(book)
#[inline]
pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()> {
internal::symlink_dir(src.as_ref(), dst.as_ref())
/// # A note on using this function
///
/// Because this is slightly less efficient on Windows, you should prefer to use
-/// [`remove_symlink_file`](fn.remove_symlink_file.html) or
-/// [`remove_symlink_dir`](fn.remove_symlink_dir.html) instead. Only use this if you don’t know or
+/// [`remove_symlink_file`] or [`remove_symlink_dir`] instead. Only use this if you don’t know or
/// care whether the destination is a file or a directory (but even then, you do need to know that
/// it exists).
///
/// # Errors
///
/// An error will be returned if the symlink cannot be removed.
-#[cfg(any(target_os = "redox", unix, windows))]
#[inline]
pub fn remove_symlink_auto<P: AsRef<Path>>(path: P) -> io::Result<()> {
internal::remove_symlink_auto(path)
/// Remove a directory symlink.
///
-/// On Windows, this corresponds to `std::fs::remove_dir`.
+/// On Windows, this corresponds to [`std::fs::remove_dir`].
///
-/// On Unix, this corresponds to `std::fs::remove_file`.
-#[cfg(any(target_os = "redox", unix, windows))]
+/// On Unix, this corresponds to [`std::fs::remove_file`].
#[inline]
pub fn remove_symlink_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
internal::remove_symlink_dir(path)
/// Remove a file symlink.
///
-/// This just calls `std::fs::remove_file`, but the function is provided here to correspond to
-/// `remove_symlink_dir`.
-///
-/// On Unix, this corresponds to `std::fs::remove_file`.
-#[cfg(any(target_os = "redox", unix, windows))]
+/// This just calls [`std::fs::remove_file`], but the function is provided here to correspond to
+/// [`remove_symlink_dir`].
#[inline]
pub fn remove_symlink_file<P: AsRef<Path>>(path: P) -> io::Result<()> {
fs::remove_file(path)
-// These are copied from libstd/sys/windows/c.rs out of necessity.
-// Note that I *can’t* use the winapi crate only, apparently, as it curiously lacks
-// REPARSE_DATA_BUFFER and MAXIMUM_REPARSE_DATA_BUFFER_SIZE (at 0.2.8, anyway). So I just threw in
-// the towel and decided not to use kernel32-sys and winapi at all.
+// These were copied from libstd/sys/windows/c.rs out of necessity; and even five years after I
+// first wrote this crate, I’m amused to note winapi 0.3.9 still lacks REPARSE_DATA_BUFFER, though
+// it’s picked up MAXIMUM_REPARSE_DATA_BUFFER_SIZE since 0.2.8, the other thing that was missing.
+// Anyway, I just threw in the towel and decided not to use kernel32-sys and winapi at all.
#![allow(non_snake_case, non_camel_case_types)]