RFC: split up fs::soft_link into os::unix::fs::symlink and os::windows::fs::{symlink_file, symlink_dir}

[lambda]

Rendered

[andrew-d]

Absolutely 👍 from me - being the only ones using the "soft link" terminology seems like a bad idea.

[lambda]

cc @aturon

[lambda]

I've pushed a proposed branch to make this change in rust-lang/rust#24222. If one of the alternatives names is selected, I'll update that branch with the chosen alternative.

[nagisa]

Since a big part of the community, including myself, frowns upon abbreviations from 80ies, I 👎 this unless the proposed name is changed to symbolic_link.

[tshepang]

I like sym_link

[lambda]

@nagisa I'm curious about your reasoning. I can understand wanting to avoid some really bad legacy abbreviations, like creat or S_ISGID, but much of Rust style involves abbreviations (fn, mut, Vec, str, ptr, mem, create_dir, etc). What about an abbreviation being from the 80s and widely known makes it worse than many of the abbreviations already used in the language or standard library?

I should be clear that I am also happy with either symbolic_link or sym_link if people prefer one of those, I just picked symlink for the main proposal since it does seem to be the most common term and does seem to be well enough known.

[nagisa]

My reasoning usually boils down to two things: it is more natural to read (you don’t need to resolve the abbreviation) and is essentially free when even the most primitive code editors feature some form of autocompletion.

much of Rust style involves abbreviations (fn, mut, Vec, str, ptr, mem, create_dir

These are supposed to be exceptions, not a rule. Either because they’re used a lot (unlike a function to create a symbolic link), they’re a historical mistake (already! luckily most of these were fixed during the stabilisation) or having it abbreviated was deemed to be superior to the full word by the core team.

[nagisa]

Also symlink is not consistent with hard_link and read_link.

[alexcrichton]

After some thought on this I think that the precedent elsewhere is a pretty strong motivating factor for the renaming here. We've previously debated the name sym_link but rejected it due to the fact that it is not a commonly used term and the phrase "symlink" is the actual term and not super separable.

So I think that the three options for the name of this function would be symlink, soft_link, or symbolic_link. I personally lean towards symlink for the reasons outlined in this RFC (e.g. it may not actually be unix specific).

@nagisa I feel that while "symlink" may technically be an abbreviation for "symbolic link" that the term "symlink" has actually become quite common now and can also be considered to not be an abbreviation. Along those lines it seems even Windows very commonly refers to these as symlinks as well.

Also, could you elaborate a little more on why you think it's inconsistent with hard_link and read_link? The term "hard link" seems to be more widely accepted than "soft link" and I'd be ok with the "link" part of "read link" implying a symbolic link otherwise.

[seanmonstar]

Of the three proposed by @alexcrichton, I find symbolic_link the best.

[liigo]

+1 to symbolic_link (alongside hard_link). (symlink has too much unix feel.)

[nagisa]

Also, could you elaborate a little more on why you think it's inconsistent with hard_link and read_link?

If you look at them side by side:

• hard_link
• read_link
• symlink

symlink stands out like a sore thumb being the only abbreviated word and not having _. I strongly believe there will be a great many people complaining about that if we go with symlink.

[lambda]

After considering this further, I don't think that symbolic_link makes sense, as it is a noun, not a verb. The verb would be symbolically_link, while hard_link is grammatical as either a noun or a verb. symlink, on the other hand, acts as either a noun or a verb. Since this is the name for a function creating a symbolic link, it should be a verb.

You can confirm that this interpretation is borne out by common usage by searching Google for "symlink a file", "symbolic link a file", "symbolically link a file", "hard link a file". "Symlink a file", "symbolically link a file", and "hard link a file" are all used as verb phrases, while "symbolic link a file" is not.

If you look at the list of what the operation is called in other languages and APIs, every one that uses the full "symbolic link" form has the verb "create"; CreateSymbolicLink, createSymbolicLinkAtPath:withDestinationPath:error:, createSymbolicLink.

read_link is a valid verb phrase, hard_link is as well, symbolic_link is not. To make this a verb, you would need to name it something like create_symbolic_link, which is fairly cumbersome; and then, to be consistent, you would probably want to rename hard_link to create_hard_link.

One more point is that I found that Windows does actually use the term "symlink" in the constant for the reparse point type, IO_REPARSE_TAG_SYMLINK.

[tshepang]

Interesting observation @lambda. I still don't like symlink, for it breaks the Rust naming practices of separating words with underscores. So I vote for sym_link, though @alexcrichton mention a dislike for it.

In 2nd place is soft_link. I don't like symlink for reasons @nagisa gave, but it's better than symbolic_link. symbolically_link is just ridiculous.

[nagisa]

While these APIs are already stable and making more breakage than strictly necessary is bad… what about link_hard, link_symbolic and read_link?

[CloudiDust]

I think it is okay to use noun phrases as constructors. channel, for example.

For me, sym_link, symbolic_link, soft_link are all okay, but symlink is not.

[tshepang]

Why do you call these constructors? Aren't they just functions?

[CloudiDust]

@tshepang, yeah I should have said "factories/factory functions" (though in a language where constructors are not treated specially, factory functions and constructors are technically the same).

[alexcrichton]

@lambda given much of the discussion on #1044, I think that this may want to be updated a bit. I think that your suggestion is an excellent one as it strikes a nice balance between:

• Creation of symlinks is clearly platform-specific, and each platform will have clear documentation explaining why/why not it is available.
• The name of the functions remain "rustic" with symlink
• All other functionality like read_link or is_symlink (to be added) remain in the right cross platform location (std::fs).

Would you be ok updating this RFC to reflect that state of affairs?

[lambda]

@alexcrichton Updated the RFC based on the discussion in #1044, suggesting using symlink as the conventional name, and the platform-specific split.

[nagisa]

Nit: Deprecate std::fs::soft_link in favo(u)r of:

[nagisa]

I fully support this RFC in its current form.

[alexcrichton]

Looks great to me, thanks @lambda!

[alexcrichton]

After this discussion it definitely seems like this is the best direction to go in for now as it provides a nice balance between high-level APIs while following the standard library's principle of forcing confrontation with platform-specific differences. As a result we've decided to accept this, so I"m going to merge it. Thanks @lambda!