Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rollup of 9 pull requests #129464

Merged
merged 30 commits into from
Aug 23, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
e65a48e
Document WebAssembly target feature expectations
alexcrichton Aug 1, 2024
dea3846
Review comments
alexcrichton Aug 1, 2024
927633c
Add a note about libraries and `#[target_feature]`
alexcrichton Aug 1, 2024
cfe3ea6
Add new page to SUMMARY.md
alexcrichton Aug 1, 2024
ce7f1b7
Ignore two new doc blocks in testing
alexcrichton Aug 1, 2024
b6f65a4
Document on-by-default features
alexcrichton Aug 1, 2024
a5082ef
Appease tidy
alexcrichton Aug 1, 2024
06197ef
Review comments
alexcrichton Aug 2, 2024
7d2595f
Review comments
alexcrichton Aug 9, 2024
6a8ec81
Add a missing compatibility note in the 1.80.0 release notes
apiraino Aug 19, 2024
cd7cc3f
Update RELEASES.md
apiraino Aug 19, 2024
7613eee
Update RELEASES.md
apiraino Aug 19, 2024
dbad758
Stabilize feature `char_indices_offset`
eduardosm Aug 19, 2024
0a8343c
do not build `cargo-miri` by default on stable channel
onur-ozkan Aug 18, 2024
0ce7705
document `miri` and `cargo-miri` in `build.tools`
onur-ozkan Aug 18, 2024
87e4b67
Update RELEASES.md
apiraino Aug 22, 2024
6a878a9
Fix handling of macro arguments within the `dropping_copy_types lint
Urgau Aug 22, 2024
f1fac42
llvm 20: adapt integer comparison tests
krasimirgg Aug 21, 2024
8151de2
rustdoc-search: use tighter json for names and parents
notriddle Aug 22, 2024
b544603
Fix typo in help diagnostic
gurry Aug 23, 2024
2339560
kobzol vacation
Kobzol Aug 23, 2024
440076d
Rollup merge of #128511 - alexcrichton:doc-wasm-features, r=jieyouxu
GuillaumeGomez Aug 23, 2024
e5cd26a
Rollup merge of #129243 - onur-ozkan:stuff, r=Kobzol
GuillaumeGomez Aug 23, 2024
724f612
Rollup merge of #129263 - apiraino:add-missing-compat-note, r=cuviper
GuillaumeGomez Aug 23, 2024
26672c9
Rollup merge of #129276 - eduardosm:stabilize-char_indices_offset, r=…
GuillaumeGomez Aug 23, 2024
1bbb8d5
Rollup merge of #129350 - krasimirgg:llvm20, r=nikic
GuillaumeGomez Aug 23, 2024
81aca63
Rollup merge of #129408 - Urgau:macro-arg-drop_copy, r=compiler-errors
GuillaumeGomez Aug 23, 2024
db65b6c
Rollup merge of #129426 - notriddle:smaller-index-2024-08-22, r=Guill…
GuillaumeGomez Aug 23, 2024
09b3785
Rollup merge of #129437 - gurry:fix-diagnostic-typo, r=jieyouxu
GuillaumeGomez Aug 23, 2024
0369e85
Rollup merge of #129457 - Kobzol:kobzol-vacation, r=Kobzol
GuillaumeGomez Aug 23, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions RELEASES.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,8 @@ Compatibility Notes
- [Turn `proc_macro_back_compat` lint into a hard error.](https://github.com/rust-lang/rust/pull/125596/)
- [Detect unused structs even when implementing private traits](https://github.com/rust-lang/rust/pull/122382/)
- [`std::sync::ReentrantLockGuard<T>` is no longer `Sync` if `T: !Sync`](https://github.com/rust-lang/rust/pull/125527) which means [`std::io::StdoutLock` and `std::io::StderrLock` are no longer Sync](https://github.com/rust-lang/rust/issues/127340)
- [Type inference will fail in some cases due to new implementations of `FromIterator for Box<str>`.](https://github.com/rust-lang/rust/pull/99969/)
Notably, this breaks versions of the `time` crate before 0.3.35, due to no longer inferring the implementation for `Box<[_]>`.

<a id="1.80-Internal-Changes"></a>

Expand Down
5 changes: 3 additions & 2 deletions compiler/rustc_lint/src/drop_forget_useless.rs
Original file line number Diff line number Diff line change
Expand Up @@ -151,10 +151,11 @@ impl<'tcx> LateLintPass<'tcx> for DropForgetUseless {
&& let Node::Stmt(stmt) = node
&& let StmtKind::Semi(e) = stmt.kind
&& e.hir_id == expr.hir_id
&& let Some(arg_span) = arg.span.find_ancestor_inside(expr.span)
{
UseLetUnderscoreIgnoreSuggestion::Suggestion {
start_span: expr.span.shrink_to_lo().until(arg.span),
end_span: arg.span.shrink_to_hi().until(expr.span.shrink_to_hi()),
start_span: expr.span.shrink_to_lo().until(arg_span),
end_span: arg_span.shrink_to_hi().until(expr.span.shrink_to_hi()),
}
} else {
UseLetUnderscoreIgnoreSuggestion::Note
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1693,7 +1693,7 @@ impl<'a, 'tcx> TypeErrCtxt<'a, 'tcx> {
StringPart::highlighted("multiple different versions".to_string()),
StringPart::normal(" of crate `".to_string()),
StringPart::highlighted(format!("{name}")),
StringPart::normal("` the your dependency graph".to_string()),
StringPart::normal("` in the dependency graph".to_string()),
],
);
let candidates = if impl_candidates.is_empty() {
Expand Down
1 change: 1 addition & 0 deletions config.example.toml
Original file line number Diff line number Diff line change
Expand Up @@ -337,6 +337,7 @@
# "analysis",
# "src",
# "wasm-component-ld",
# "miri", "cargo-miri" # for dev/nightly channels
#]

# Verbosity level: 0 == not verbose, 1 == verbose, 2 == very verbose, 3 == print environment variables on each rustc invocation
Expand Down
1 change: 0 additions & 1 deletion library/core/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,6 @@
#![cfg_attr(bootstrap, feature(offset_of_nested))]
#![feature(array_ptr_get)]
#![feature(asm_experimental_arch)]
#![feature(char_indices_offset)]
#![feature(const_align_of_val)]
#![feature(const_align_of_val_raw)]
#![feature(const_align_offset)]
Expand Down
15 changes: 13 additions & 2 deletions library/core/src/str/iter.rs
Original file line number Diff line number Diff line change
Expand Up @@ -241,24 +241,35 @@ impl<'a> CharIndices<'a> {
/// Returns the byte position of the next character, or the length
/// of the underlying string if there are no more characters.
///
/// This means that, when the iterator has not been fully consumed,
/// the returned value will match the index that will be returned
/// by the next call to [`next()`](Self::next).
///
/// # Examples
///
/// ```
/// #![feature(char_indices_offset)]
/// let mut chars = "a楽".char_indices();
///
/// // `next()` has not been called yet, so `offset()` returns the byte
/// // index of the first character of the string, which is always 0.
/// assert_eq!(chars.offset(), 0);
/// // As expected, the first call to `next()` also returns 0 as index.
/// assert_eq!(chars.next(), Some((0, 'a')));
///
/// // `next()` has been called once, so `offset()` returns the byte index
/// // of the second character ...
/// assert_eq!(chars.offset(), 1);
/// // ... which matches the index returned by the next call to `next()`.
/// assert_eq!(chars.next(), Some((1, '楽')));
///
/// // Once the iterator has been consumed, `offset()` returns the length
/// // in bytes of the string.
/// assert_eq!(chars.offset(), 4);
/// assert_eq!(chars.next(), None);
/// ```
#[inline]
#[must_use]
#[unstable(feature = "char_indices_offset", issue = "83871")]
#[stable(feature = "char_indices_offset", since = "CURRENT_RUSTC_VERSION")]
pub fn offset(&self) -> usize {
self.front_offset
}
Expand Down
2 changes: 1 addition & 1 deletion src/bootstrap/src/core/build_steps/tool.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1096,7 +1096,7 @@ tool_extended!((self, builder),
CargoClippy, "src/tools/clippy", "cargo-clippy", stable=true;
Clippy, "src/tools/clippy", "clippy-driver", stable=true, add_bins_to_sysroot = ["clippy-driver", "cargo-clippy"];
Miri, "src/tools/miri", "miri", stable=false, add_bins_to_sysroot = ["miri"];
CargoMiri, "src/tools/miri/cargo-miri", "cargo-miri", stable=true, add_bins_to_sysroot = ["cargo-miri"];
CargoMiri, "src/tools/miri/cargo-miri", "cargo-miri", stable=false, add_bins_to_sysroot = ["cargo-miri"];
Rls, "src/tools/rls", "rls", stable=true;
Rustfmt, "src/tools/rustfmt", "rustfmt", stable=true, add_bins_to_sysroot = ["rustfmt", "cargo-fmt"];
);
Expand Down
1 change: 1 addition & 0 deletions src/doc/rustc/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,7 @@
- [wasm32-wasip1](platform-support/wasm32-wasip1.md)
- [wasm32-wasip1-threads](platform-support/wasm32-wasip1-threads.md)
- [wasm32-wasip2](platform-support/wasm32-wasip2.md)
- [wasm32-unknown-unknown](platform-support/wasm32-unknown-unknown.md)
- [wasm64-unknown-unknown](platform-support/wasm64-unknown-unknown.md)
- [\*-win7-windows-msvc](platform-support/win7-windows-msvc.md)
- [x86_64-fortanix-unknown-sgx](platform-support/x86_64-fortanix-unknown-sgx.md)
Expand Down
2 changes: 1 addition & 1 deletion src/doc/rustc/src/platform-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,7 @@ target | std | notes
[`thumbv8m.main-none-eabi`](platform-support/thumbv8m.main-none-eabi.md) | * | Bare Armv8-M Mainline
[`thumbv8m.main-none-eabihf`](platform-support/thumbv8m.main-none-eabi.md) | * | Bare Armv8-M Mainline, hardfloat
`wasm32-unknown-emscripten` | ✓ | WebAssembly via Emscripten
`wasm32-unknown-unknown` | ✓ | WebAssembly
[`wasm32-unknown-unknown`](platform-support/wasm32-unknown-unknown.md) | ✓ | WebAssembly
`wasm32-wasi` | ✓ | WebAssembly with WASI (undergoing a [rename to `wasm32-wasip1`][wasi-rename])
[`wasm32-wasip1`](platform-support/wasm32-wasip1.md) | ✓ | WebAssembly with WASI
[`wasm32-wasip1-threads`](platform-support/wasm32-wasip1-threads.md) | ✓ | WebAssembly with WASI Preview 1 and threads
Expand Down
198 changes: 198 additions & 0 deletions src/doc/rustc/src/platform-support/wasm32-unknown-unknown.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
# `wasm32-unknown-unknown`

**Tier: 2**

The `wasm32-unknown-unknown` target is a WebAssembly compilation target which
does not import any functions from the host for the standard library. This is
the "minimal" WebAssembly in the sense of making the fewest assumptions about
the host environment. This target is often used when compiling to the web or
JavaScript environments as there is no standard for what functions can be
imported on the web. This target can also be useful for creating minimal or
bare-bones WebAssembly binaries.

The `wasm32-unknown-unknown` target has support for the Rust standard library
but many parts of the standard library do not work and return errors. For
example `println!` does nothing, `std::fs` always return errors, and
`std::thread::spawn` will panic. There is no means by which this can be
overridden. For a WebAssembly target that more fully supports the standard
library see the [`wasm32-wasip1`](./wasm32-wasip1.md) or
[`wasm32-wasip2`](./wasm32-wasip2.md) targets.

The `wasm32-unknown-unknown` target has full support for the `core` and `alloc`
crates. It additionally supports the `HashMap` type in the `std` crate, although
hash maps are not randomized like they are on other platforms.

One existing user of this target (please feel free to edit and expand this list
too) is the [`wasm-bindgen` project](https://github.com/rustwasm/wasm-bindgen)
which facilitates Rust code interoperating with JavaScript code. Note, though,
that not all uses of `wasm32-unknown-unknown` are using JavaScript and the web.

## Target maintainers

When this target was added to the compiler platform-specific documentation here
was not maintained at that time. This means that the list below is not
exhaustive and there are more interested parties in this target. That being
said since when this document was last updated those interested in maintaining
this target are:

- Alex Crichton, https://github.com/alexcrichton

## Requirements

This target is cross-compiled. The target includes support for `std` itself,
but as mentioned above many pieces of functionality that require an operating
system do not work and will return errors.

This target currently has no equivalent in C/C++. There is no C/C++ toolchain
for this target. While interop is theoretically possible it's recommended to
instead use one of:

* `wasm32-unknown-emscripten` - for web-based use cases the Emscripten
toolchain is typically chosen for running C/C++.
* [`wasm32-wasip1`](./wasm32-wasip1.md) - the wasi-sdk toolchain is used to
compile C/C++ on this target and can interop with Rust code. WASI works on
the web so far as there's no blocker, but an implementation of WASI APIs
must be either chosen or reimplemented.

This target has no build requirements beyond what's in-tree in the Rust
repository. Linking binaries requires LLD to be enabled for the `wasm-ld`
driver. This target uses the `dlmalloc` crate as the default global allocator.

## Building the target

Building this target can be done by:

* Configure the `wasm32-unknown-unknown` target to get built.
* Configure LLD to be built.
* Ensure the `WebAssembly` target backend is not disabled in LLVM.

These are all controlled through `config.toml` options. It should be possible
to build this target on any platform.

## Building Rust programs

Rust programs can be compiled by adding this target via rustup:

```sh
$ rustup target add wasm32-unknown-unknown
```

and then compiling with the target:

```sh
$ rustc foo.rs --target wasm32-unknown-unknown
$ file foo.wasm
```

## Cross-compilation

This target can be cross-compiled from any host.

## Testing

This target is not tested in CI for the rust-lang/rust repository. Many tests
must be disabled to run on this target and failures are non-obvious because
`println!` doesn't work in the standard library. It's recommended to test the
`wasm32-wasip1` target instead for WebAssembly compatibility.

## Conditionally compiling code

It's recommended to conditionally compile code for this target with:

```text
#[cfg(all(target_family = "wasm", target_os = "unknown"))]
```

Note that there is no way to tell via `#[cfg]` whether code will be running on
the web or not.

## Enabled WebAssembly features

WebAssembly is an evolving standard which adds new features such as new
instructions over time. This target's default set of supported WebAssembly
features will additionally change over time. The `wasm32-unknown-unknown` target
inherits the default settings of LLVM which typically matches the default
settings of Emscripten as well.

Changes to WebAssembly go through a [proposals process][proposals] but reaching
the final stage (stage 5) does not automatically mean that the feature will be
enabled in LLVM and Rust by default. At this time the general guidance is that
features must be present in most engines for a "good chunk of time" before
they're enabled in LLVM by default. There is currently no exact number of
months or engines that are required to enable features by default.

[proposals]: https://github.com/WebAssembly/proposals

As of the time of this writing the proposals that are enabled by default (the
`generic` CPU in LLVM terminology) are:

* `multivalue`
* `mutable-globals`
* `reference-types`
* `sign-ext`

If you're compiling WebAssembly code for an engine that does not support a
feature in LLVM's default feature set then the feature must be disabled at
compile time. Note, though, that enabled features may be used in the standard
library or precompiled libraries shipped via rustup. This means that not only
does your own code need to be compiled with the correct set of flags but the
Rust standard library additionally must be recompiled.

Compiling all code for the initial release of WebAssembly looks like:

```sh
$ export RUSTFLAGS=-Ctarget-cpu=mvp
$ cargo +nightly build -Zbuild-std=panic_abort,std --target wasm32-unknown-unknown
```

Here the `mvp` "cpu" is a placeholder in LLVM for disabling all supported
features by default. Cargo's `-Zbuild-std` feature, a Nightly Rust feature, is
then used to recompile the standard library in addition to your own code. This
will produce a binary that uses only the original WebAssembly features by
default and no proposals since its inception.

To enable individual features it can be done with `-Ctarget-feature=+foo`.
Available features for Rust code itself are documented in the [reference] and
can also be found through:

```sh
$ rustc -Ctarget-feature=help --target wasm32-unknown-unknown
```

You'll need to consult your WebAssembly engine's documentation to learn more
about the supported WebAssembly features the engine has.

[reference]: https://doc.rust-lang.org/reference/attributes/codegen.html#wasm32-or-wasm64

Note that it is still possible for Rust crates and libraries to enable
WebAssembly features on a per-function level. This means that the build
command above may not be sufficient to disable all WebAssembly features. If the
final binary still has SIMD instructions, for example, the function in question
will need to be found and the crate in question will likely contain something
like:

```rust,ignore (not-always-compiled-to-wasm)
#[target_feature(enable = "simd128")]
fn foo() {
// ...
}
```

In this situation there is no compiler flag to disable emission of SIMD
instructions and the crate must instead be modified to not include this function
at compile time either by default or through a Cargo feature. For crate authors
it's recommended to avoid `#[target_feature(enable = "...")]` except where
necessary and instead use:

```rust,ignore (not-always-compiled-to-wasm)
#[cfg(target_feature = "simd128")]
fn foo() {
// ...
}
```

That is to say instead of enabling target features it's recommended to
conditionally compile code instead. This is notably different to the way native
platforms such as x86\_64 work, and this is due to the fact that WebAssembly
binaries must only contain code the engine understands. Native binaries work so
long as the CPU doesn't execute unknown code dynamically at runtime.
14 changes: 14 additions & 0 deletions src/doc/rustc/src/platform-support/wasm32-wasip1-threads.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,3 +162,17 @@ It's recommended to conditionally compile code for this target with:
Prior to Rust 1.80 the `target_env = "p1"` key was not set. Currently the
`target_feature = "atomics"` is Nightly-only. Note that the precise `#[cfg]`
necessary to detect this target may change as the target becomes more stable.

## Enabled WebAssembly features

The default set of WebAssembly features enabled for compilation includes two
more features in addition to that which
[`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md) enables:

* `bulk-memory`
* `atomics`

For more information about features see the documentation for
[`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md), but note that the
`mvp` CPU in LLVM does not support this target as it's required that
`bulk-memory`, `atomics`, and `mutable-globals` are all enabled.
6 changes: 6 additions & 0 deletions src/doc/rustc/src/platform-support/wasm32-wasip1.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,3 +132,9 @@ It's recommended to conditionally compile code for this target with:

Note that the `target_env = "p1"` condition first appeared in Rust 1.80. Prior
to Rust 1.80 the `target_env` condition was not set.

## Enabled WebAssembly features

The default set of WebAssembly features enabled for compilation is currently the
same as [`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md). See the
documentation there for more information.
6 changes: 6 additions & 0 deletions src/doc/rustc/src/platform-support/wasm32-wasip2.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,3 +61,9 @@ It's recommended to conditionally compile code for this target with:
```text
#[cfg(all(target_os = "wasi", target_env = "p2"))]
```

## Enabled WebAssembly features

The default set of WebAssembly features enabled for compilation is currently the
same as [`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md). See the
documentation there for more information.
Loading
Loading