Deprecate (or break-fix) std::env::home_dir


This has nagged me for a long time, but the definition of home_dir in std is pretty arguably incorrect on Windows, and both rustup and cargo use their own custom definition.

The problem with it is that it prioritizes the HOME variable, which basically has no meaning on windows (the correct variable is “USERPROFILE”).

The practical result of this is that calls to home_dir on most windows environments result in a path like C:\Users\brson, but under cygwin and mingw result in things like /home/brian/.

Now, I have no doubt that is useful in some case, but I have not found that case yet, and find the function extremely misleading. When we found it in rustup and cargo, we felt like it was completely bogus and confusing behavior.

There might be a place for this function in the world, but I do not believe it is env::home_dir, and suggest deprecating it.



We have tried to fix this function before at but basically arrived at the same conclusion (deprecate it eventually, point to an external package instead.)


It looks like there’s a universal agreement that the current implementation is wrong, and the proposed one is better.

Wouldn’t that technically-breaking change be perceived merely as a bug fix?


I commented on @alexcrichton’s main objection to break-fixing home_dir. Both cargo and multirust still use it for - at this point - ancient backcompat hacks, that I expect to be removed. In particularl, rewrites how cargo home is discovered and does not take into account the hack.

Edit: the functions that cargo/rustup use are not home_dir - they are cargo/rustup specific. home::home_dir is exactly like env::home_dir but without considering %HOME on windows.


Anyway, just deprecating it is fine too. It’s just a bunk function and nobody should use it. And the home crate basically looks correct to me (for the home function specifically), besides the fact that on unix it calls std::env::home, and would need to be rewritten.

Once the cargo/rustup directory overhaul is done, the rest of the contents of the home crate will probably just be dead code, and home can literally contain one correct home_dir function.

On the other hand, we could just put a correct function in std - and I honestly doubt anybody is going to ding us for just fixing env::home_dir.


We could also point peaple at, though I don’t know if that is using a similar definition of HOME - I know it doesn’t care about %USERPROFILE% on windows, but stackoverflow also says not to use `%USERPROFILE%. My only doubt about that crate is that the scope is big, and its opinionated.

The definition of home though is probably fine, though I believe incomplete on some platforms Rust supports.

Edit: directories is MPL licensed :-/

Edit: heh, on unix, directories just defers to std::env::home(), just like home.


I do know that some people set %HOME% on Windows and expect that to work. And people who run programs under cygwin sometimes expect that behavior.

Perhaps we should just document the behavior very carefully, and also tell people what they should use if they don’t want that behavior?


I mean, we could, but I’m pretty convinced it’s the wrong default. Having this weird home_dir function in std and no “correct” function is a pretty big wart.


I agree with Brian. I think the best thing would be to just fix std::env::home and thoroughly document its behavior.

Can be addressed.

Anything wrong with that? Please let me know if there is any issue with it, and I’ll look into fixing it.