rust/library/rustc-std-workspace-core/README.md

# The `rustc-std-workspace-core` crate

This crate is a shim and empty crate which simply depends on `libcore` and
reexports all of its contents. The crate is the crux of empowering the standard
library to depend on crates from crates.io

Crates on crates.io that the standard library depend on the
`rustc-std-workspace-core` crate from crates.io. On crates.io, however, this
crate is empty. We use `[patch]` to override it to this crate in this
repository. As a result, crates on crates.io will draw a dependency edge to
`libcore`, the version defined in this repository. That should draw all the
dependency edges to ensure Cargo builds crates successfully!

Note that crates on crates.io need to depend on this crate with the name `core`
for everything to work correctly. To do that they can use:

```toml
core = { version = "1.0.0", optional = true, package = 'rustc-std-workspace-core' }
```

Through the use of the `package` key the crate is renamed to `core`, meaning
it'll look like

```
--extern core=.../librustc_std_workspace_core-XXXXXXX.rlib
```

when Cargo invokes the compiler, satisfying the implicit `extern crate core`
directive injected by the compiler.
std: Depend directly on crates.io crates 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]: https://github.com/alexcrichton/dlmalloc-rs/commit/28ee12db813a3b650a7c25d1c36d2c17dcb88ae3 2018-11-20 05:52:50 +00:00			# The `rustc-std-workspace-core` crate

			This crate is a shim and empty crate which simply depends on `libcore` and
			`reexports all of its contents. The crate is the crux of empowering the standard`
			`library to depend on crates from crates.io`

			`Crates on crates.io that the standard library depend on the`
			`rustc-std-workspace-core` crate from crates.io. On crates.io, however, this
			crate is empty. We use `[patch]` to override it to this crate in this
			`repository. As a result, crates on crates.io will draw a dependency edge to`
			`libcore`, the version defined in this repository. That should draw all the
			`dependency edges to ensure Cargo builds crates successfully!`

			Note that crates on crates.io need to depend on this crate with the name `core`
			`for everything to work correctly. To do that they can use:`

			```toml
			`core = { version = "1.0.0", optional = true, package = 'rustc-std-workspace-core' }`
			```

			Through the use of the `package` key the crate is renamed to `core`, meaning
			`it'll look like`

			```
			`--extern core=.../librustc_std_workspace_core-XXXXXXX.rlib`
			```

			when Cargo invokes the compiler, satisfying the implicit `extern crate core`
			`directive injected by the compiler.`