A few improvements to comments in user-facing crates
Not too many this time, and all concern comments (almost all doc comments) in user-facing crates (libstd, libcore, liballoc).
r? @steveklabnik
Monomorphize less code in fs::{read|write}
Since the generic-ness is only for the as_refs, might as well have std just compile the important part once instead of on every use.
There are two big categories of changes in here
- Removing lifetimes from common traits that can essentially never user a lifetime from an input (particularly `Drop` & `Debug`)
- Forwarding impls that are only possible because the lifetime doesn't matter (like `impl<R: Read + ?Sized> Read for &mut R`)
I omitted things that seemed like they could be more controversial, like the handful of iterators that have a `Item: 'static` despite the iterator having a lifetime or the `PartialEq` implementations where the flipped one cannot elide the lifetime.
Point out that the final component of the path name might be a filename
(and not a directory name). Previously, the doc said that all components
of the path must be directory names, when it actually only ment all but
the final one.
Fixes#54056.
Ever since we added a Cargo-based build system for the compiler the
standard library has always been a little special, it's never been able
to depend on crates.io crates for runtime dependencies. This has been a
result of various limitations, namely that Cargo doesn't understand that
crates from crates.io depend on libcore, so Cargo tries to build crates
before libcore is finished.
I had an idea this afternoon, however, which lifts the strategy
from #52919 to directly depend on crates.io crates from the standard
library. After all is said and done this removes a whopping three
submodules that we need to manage!
The basic idea here is that for any crate `std` depends on it adds an
*optional* dependency on an empty crate on crates.io, in this case named
`rustc-std-workspace-core`. This crate is overridden via `[patch]` in
this repository to point to a local crate we write, and *that* has a
`path` dependency on libcore.
Note that all `no_std` crates also depend on `compiler_builtins`, but if
we're not using submodules we can publish `compiler_builtins` to
crates.io and all crates can depend on it anyway! The basic strategy
then looks like:
* The standard library (or some transitive dep) decides to depend on a
crate `foo`.
* The standard library adds
```toml
[dependencies]
foo = { version = "0.1", features = ['rustc-dep-of-std'] }
```
* The crate `foo` has an optional dependency on `rustc-std-workspace-core`
* The crate `foo` has an optional dependency on `compiler_builtins`
* The crate `foo` has a feature `rustc-dep-of-std` which activates these
crates and any other necessary infrastructure in the crate.
A sample commit for `dlmalloc` [turns out to be quite simple][commit].
After that all `no_std` crates should largely build "as is" and still be
publishable on crates.io! Notably they should be able to continue to use
stable Rust if necessary, since the `rename-dependency` feature of Cargo
is soon stabilizing.
As a proof of concept, this commit removes the `dlmalloc`,
`libcompiler_builtins`, and `libc` submodules from this repository. Long
thorns in our side these are now gone for good and we can directly
depend on crates.io! It's hoped that in the long term we can bring in
other crates as necessary, but for now this is largely intended to
simply make it easier to manage these crates and remove submodules.
This should be a transparent non-breaking change for all users, but one
possible stickler is that this almost for sure breaks out-of-tree
`std`-building tools like `xargo` and `cargo-xbuild`. I think it should
be relatively easy to get them working, however, as all that's needed is
an entry in the `[patch]` section used to build the standard library.
Hopefully we can work with these tools to solve this problem!
[commit]: 28ee12db81
The methods on the structures `fs::FileType` and `fs::Metadata` of (respectively) `is_file`, `is_dir`, and
`is_symlink` had some ambiguity in documentation, where it was not noted whether files will pass those tests
exclusively or not. It is now written that the tests are mutually exclusive.
Fixes#48345.
Use File::metadata instead of fs::metadata to choose buffer size
This replaces a `stat` syscall with `fstat` or similar, which can be faster. Fixes#47519.
Implement libstd for CloudABI.
Though CloudABI is strongly inspired by POSIX, its absence of features that don't work well with capability-based sandboxing makes it different enough that adding bits to `sys/unix` will make things a mess. This change therefore adds CloudABI specific platform code under `sys/cloudabi`.
One of the goals of this implementation is to build as much as possible directly on top of CloudABI's system call layer, as opposed to using the C library. This is preferred, as the system call layer is supposed to be stable, whereas the C library ABI technically is not. An advantage of this approach is that it allows us to implement certain interfaces, such as mutexes and condition variables more optimally. They can be lighter than the ones provided by pthreads.
This change disables some modules that cannot realistically be implemented right now. For example, libstd's pathname abstraction is not designed with POSIX `*at()` (e.g., `openat()`) in mind. The `*at()` functions are the only set of file system APIs available on CloudABI. There is no global file system namespace, nor a process working directory. Discussions on how to port these modules over are outside the scope of this change.
