| Age | Commit message (Collapse) | Author | Lines |
|---|
|
Fix typo in csky-unknown-linux-gnuabiv2.md
|
|
Add x86_64-unknown-trusty as tier 3 target
This PR adds a third target for the Trusty platform, `x86_64-unknown-trusty`.
Please let me know if an MCP is required. https://github.com/rust-lang/compiler-team/issues/582 was made when adding the first two targets, I can make another one for the new target as well if needed.
# Target Tier Policy Acknowledgements
> A tier 3 target must have a designated developer or developers (the "target maintainers") on record to be CCed when issues arise regarding the target. (The mechanism to track and CC such developers may evolve over time.)
- Nicole LeGare (```@randomPoison)```
- Andrei Homescu (```@ahomescu)```
- Chris Wailes (chriswailes@google.com)
- As a fallback trusty-dev-team@google.com can be contacted
Note that this does not reflect the maintainers currently listed in [`trusty.md`](https://github.com/rust-lang/rust/blob/c52c23b6f44cd19718721a5e3b2eeb169e9c96ff/src/doc/rustc/src/platform-support/trusty.md). #130452 is currently open to update the list of maintainers in the documentation.
> Targets must use naming consistent with any existing targets; for instance, a target for the same CPU or OS as an existing Rust target should use the same name for that CPU or OS. Targets should normally use the same names and naming conventions as used elsewhere in the broader ecosystem beyond Rust (such as in other toolchains), unless they have a very good reason to diverge. Changing the name of a target can be highly disruptive, especially once the target reaches a higher tier, so getting the name right is important even for a tier 3 target.
The new target `x86_64-unknown-trusty` follows the existing naming convention for similar targets.
> Target names should not introduce undue confusion or ambiguity unless absolutely necessary to maintain ecosystem compatibility. For example, if the name of the target makes people extremely likely to form incorrect beliefs about what it targets, the name should be changed or augmented to disambiguate it.
đź‘Ť
> Tier 3 targets may have unusual requirements to build or use, but must not create legal issues or impose onerous legal terms for the Rust project or for Rust developers or users.
There are no known legal issues or license incompatibilities.
> Neither this policy nor any decisions made regarding targets shall create any binding agreement or estoppel by any party. If any member of an approving Rust team serves as one of the maintainers of a target, or has any legal or employment requirement (explicit or implicit) that might affect their decisions regarding a target, they must recuse themselves from any approval decisions regarding the target's tier status, though they may otherwise participate in discussions.
đź‘Ť
> Tier 3 targets should attempt to implement as much of the standard libraries as possible and appropriate (core for most targets, alloc for targets that can support dynamic memory allocation, std for targets with an operating system or equivalent layer of system-provided functionality), but may leave some code unimplemented (either unavailable or stubbed out as appropriate), whether because the target makes it impossible to implement or challenging to implement. The authors of pull requests are not obligated to avoid calling any portions of the standard library on the basis of a tier 3 target not implementing those portions.
This PR only adds the target. `std` support is being worked on and will be added in a future PR.
> The target must provide documentation for the Rust community explaining how to build for the target, using cross-compilation if possible. If the target supports running binaries, or running tests (even if they do not pass), the documentation must explain how to run such binaries or tests for the target, using emulation if possible or dedicated hardware if necessary.
đź‘Ť
> Tier 3 targets must not impose burden on the authors of pull requests, or other developers in the community, to maintain the target. In particular, do not post comments (automated or manual) on a PR that derail or suggest a block on the PR based on a tier 3 target. Do not send automated messages or notifications (via any medium, including via ```@)``` to a PR author or others involved with a PR regarding a tier 3 target, unless they have opted into such messages.
đź‘Ť
> Patches adding or updating tier 3 targets must not break any existing tier 2 or tier 1 target, and must not knowingly break another tier 3 target without approval of either the compiler team or the maintainers of the other tier 3 target.
đź‘Ť
> Tier 3 targets must be able to produce assembly using at least one of rustc's supported backends from any host target. (Having support in a fork of the backend is not sufficient, it must be upstream.)
đź‘Ť
|
|
|
|
Implement RFC3695 Allow boolean literals as cfg predicates
This PR implements https://github.com/rust-lang/rfcs/pull/3695: allow boolean literals as cfg predicates, i.e. `cfg(true)` and `cfg(false)`.
r? `@nnethercote` *(or anyone with parser knowledge)*
cc `@clubby789`
|
|
|
|
Rollup of 4 pull requests
Successful merges:
- #130005 (Replace -Z default-hidden-visibility with -Z default-visibility)
- #130229 (ptr::add/sub: do not claim equivalence with `offset(c as isize)`)
- #130773 (Update Unicode escapes in `/library/core/src/char/methods.rs`)
- #130933 (rustdoc: lists items that contain multiple paragraphs are more clear)
r? `@ghost`
`@rustbot` modify labels: rollup
|
|
Replace -Z default-hidden-visibility with -Z default-visibility
Issue #105518
|
|
Support clobber_abi and vector/access registers (clobber-only) in s390x inline assembly
This supports `clobber_abi` which is one of the requirements of stabilization mentioned in #93335.
This also supports vector registers (as `vreg`) and access registers (as `areg`) as clobber-only, which need to support clobbering of them to implement clobber_abi.
Refs:
- "1.2.1.1. Register Preservation Rules" section in ELF Application Binary Interface s390x Supplement, Version 1.6.1 (lzsabi_s390x.pdf in https://github.com/IBM/s390x-abi/releases/tag/v1.6.1)
- Register definition in LLVM:
- Vector registers https://github.com/llvm/llvm-project/blob/llvmorg-19.1.0/llvm/lib/Target/SystemZ/SystemZRegisterInfo.td#L249
- Access registers https://github.com/llvm/llvm-project/blob/llvmorg-19.1.0/llvm/lib/Target/SystemZ/SystemZRegisterInfo.td#L332
I have three questions:
- ~~ELF Application Binary Interface s390x Supplement says that `cc` (condition code, bits 18-19 of PSW) is "Volatile".
However, we do not have a register class for `cc` and instead mark `cc` as clobbered unless `preserves_flags` is specified (https://github.com/rust-lang/rust/pull/111331).
Therefore, in the current implementation, if both `preserves_flags` and `clobber_abi` are specified, `cc` is not marked as clobbered. Is this okay? Or even if `preserves_flags` is used, should `cc` be marked as clobbered if `clobber_abi` is used?~~ UPDATE: resolved https://github.com/rust-lang/rust/pull/130630#issuecomment-2367923121
- ~~ELF Application Binary Interface s390x Supplement says that `pm` (program mask, bits 20-23 of PSW) is "Cleared".
There does not appear to be any registers associated with this in either [LLVM](https://github.com/llvm/llvm-project/blob/llvmorg-19.1.0/llvm/lib/Target/SystemZ/SystemZRegisterInfo.td) or [GCC](https://github.com/gcc-mirror/gcc/blob/33ccc1314dcdb0b988a9276ca6b6ce9b07bea21e/gcc/config/s390/s390.h#L407-L431), so at this point I don't see any way other than to just ignore it. Is this okay as-is?~~ UPDATE: resolved https://github.com/rust-lang/rust/pull/130630#issuecomment-2367923121
- Is "areg" a good name for register class name for access registers? It may be a bit confusing between that and `reg_addr`, which uses the “a” constraint (https://github.com/rust-lang/rust/pull/119431)...
Note:
- GCC seems to [recognize only `a0` and `a1`](https://github.com/gcc-mirror/gcc/blob/33ccc1314dcdb0b988a9276ca6b6ce9b07bea21e/gcc/config/s390/s390.h#L428-L429), and using `a[2-15]` [causes errors](https://godbolt.org/z/a46vx8jjn).
Given that cg_gcc has a similar problem with other architecture (https://github.com/rust-lang/rustc_codegen_gcc/issues/485), I don't feel this is a blocker for this PR, but it is worth mentioning here.
- `vreg` should be able to accept `#[repr(simd)]` types as input if the `vector` target feature added in https://github.com/rust-lang/rust/pull/127506 is enabled, but core_arch has no s390x vector type and both `#[repr(simd)]` and `core::simd` are unstable, so I have not implemented it in this PR. EDIT: And supporting it is probably more complex than doing the equivalent on other architectures... https://github.com/rust-lang/rust/pull/88245#issuecomment-905559591
cc `@uweigand`
r? `@Amanieu`
`@rustbot` label +O-SystemZ
|
|
MCP: https://github.com/rust-lang/compiler-team/issues/782
Co-authored-by: bjorn3 <17426603+bjorn3@users.noreply.github.com>
|
|
r=notriddle,jyn514
Add `field@` and `variant@` doc-link disambiguators
I'm not sure if this is big enough to need an fcp or not, but this is something I found missing when trying to refer to a field in macro-generated docs, not knowing if a method might be defined as well. Obviously, there are definitely other uses.
In the case where it's not disambiguated, methods (and I suppose other associated items in the value namespace) still take priority, which `@jyn514` said was an oversight but I think is probably the desired behavior 99% of the time anyway - shadowing a field with an accessor method is a very common pattern. If fields and methods with the same name started conflicting, it would be a breaking change. Though, to quote them:
> jyn: maybe you can break this only if both [the method and the field] are public
> jyn: rustc has some future-incompat warning level
> jyn: that gets through -A warnings and --cap-lints from cargo
That'd be out of scope of this PR, though.
Fixes #80283
|
|
Improve `--print=check-cfg` documentation
This PR improves the `--print=check-cfg` documentation by:
1. switching to a table for better readability
2. adding a clear indication where the specific check-cfg syntax starts
3. adding a link to the main `--check-cfg` documentation
`@rustbot` label +F-check-cfg
|
|
|
|
coherency
|
|
|
|
Add RISC-V vxworks targets
Risc-V 32 and RISC-V 64 targets are to be added in the target list.
|
|
Update books
## rust-lang/book
5 commits in e7d217be2a75ef1753f0988d6ccaba4d7e376259..99cf75a5414fa8adbe3974bd0836661ca901708f
2024-09-23 16:18:39 UTC to 2024-09-11 18:38:03 UTC
- translations: remove broken link (rust-lang/book#4036)
- Update build instructions: include mdbook plugins (rust-lang/book#4032)
- Add `cargo init` usage suggestion to 1.3 (rust-lang/book#4025)
- Use immutable borrow of `TcpStream` when creating `BufReader` (rust-lang/book#4024)
- Upgrade to Rust 1.81 (rust-lang/book#4031)
## rust-lang/edition-guide
1 commits in b3ca7ade0f87d7e3fb538776defc5b2cc4188172..c7ebae25cb4801a31b6f05353f6d85bfa6feedd1
2024-09-22 08:47:02 UTC to 2024-09-22 08:47:02 UTC
- Update static_mut_refs now that it is a lint (rust-lang/edition-guide#322)
## rust-lang/reference
10 commits in 687faf9958c52116d003b41dfd29cc1cf44f5311..24fb2687cdbc54fa18ae4acf5d879cfceca77b2c
2024-09-22 09:07:12 UTC to 2024-09-10 19:24:17 UTC
- do not talk about the 'address of a constant' (rust-lang/reference#1624)
- Add spec identifier syntax to interior-mutability.md (rust-lang/reference#1585)
- Add spec identifier syntax to input-format.md (rust-lang/reference#1584)
- Document limitations on block doc comments (rust-lang/reference#1602)
- Places based on misaligned pointers: also mention 'static's as a possible base for place projections (rust-lang/reference#1606)
- type-layout: mention that call ABI compatibility is a separate concern (rust-lang/reference#1608)
- stabilize `const_extern_fn` (rust-lang/reference#1596)
- const_eval: update for const_mut_refs and const_refs_to_cell stabilization (rust-lang/reference#1590)
- fix: unclosed tag `sup` (rust-lang/reference#1612)
- Fix improper documentation on casting non_exhaustive enums (rust-lang/reference#1607)
## rust-lang/rustc-dev-guide
13 commits in 0ed9229f5b6f7824b333beabd7e3d5ba4b9bd971..555f3de2fa0d61c4294b74d245f1cbad6fcbf589
2024-09-23 12:51:33 UTC to 2024-09-10 07:32:10 UTC
- chore: add missing `.` (rust-lang/rustc-dev-guide#2074)
- Add remark on required free disk space (rust-lang/rustc-dev-guide#2073)
- fix broken links (rust-lang/rustc-dev-guide#2063)
- Add advice about submitting potentially hard-to-review PRs (rust-lang/rustc-dev-guide#2036)
- Edit a sentence for clarity (rust-lang/rustc-dev-guide#2071)
- Emphasize how to run a single tool test (rust-lang/rustc-dev-guide#2070)
- Remove chalk is owned by WG-traits (rust-lang/rustc-dev-guide#2068)
- Fix conditions lowering text for enums with no fields (rust-lang/rustc-dev-guide#2066)
- update proof tree chapter (rust-lang/rustc-dev-guide#2054)
- Add docs for JS tests (rust-lang/rustc-dev-guide#2048)
- Reflect `x.py test`'s `--rustc-args` option being renamed to `--compiletest-rustc-args` (rust-lang/rustc-dev-guide#2062)
- we standardized on this more reliable command (rust-lang/rustc-dev-guide#2061)
- Fix Typo and Remove Outdated Line About C Variadics (rust-lang/rustc-dev-guide#2060)
|
|
Add new Tier-3 target: `loongarch64-unknown-linux-ohos`
MCP: https://github.com/rust-lang/compiler-team/issues/784
|
|
|
|
MCP: https://github.com/rust-lang/compiler-team/issues/784
Co-authored-by: WANG Rui <wangrui@loongson.cn>
|
|
Remove x86_64-fuchsia and aarch64-fuchsia target aliases
Closes #106649.
|
|
|
|
|
|
|
|
inline assembly
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
r=jieyouxu
Fix default/minimum deployment target for Aarch64 simulator targets
The minimum that `rustc` encoded did not match [the version in Clang](https://github.com/llvm/llvm-project/blob/llvmorg-18.1.8/llvm/lib/TargetParser/Triple.cpp#L1900-L1932), and that meant that that when linking, Clang ended up bumping the version. See https://github.com/rust-lang/rust/issues/129432 for more motivation behind this change.
Specifically, this PR sets the correct deployment target of the following targets:
- `aarch64-apple-ios-sim` from 10.0 to 14.0
- `aarch64-apple-tvos-sim` from 10.0 to 14.0
- `aarch64-apple-watchos-sim` from 5.0 to 7.0
- `aarch64-apple-ios-macabi` from 13.1 to 14.0
I have chosen not to document the `-sim` changes in the platform support docs, as it is fundamentally uninteresting; the normal targets (e.g. `aarch64-apple-ios`) still have the same deployment target, and that's what developers should actually target.
r? compiler
CC `@BlackHoleFox`
|
|
This flag allows specifying the threshold size above which LLVM should
not consider placing small objects in a .sdata or .sbss section.
Support is indicated in the target options via the
small-data-threshold-support target option, which can indicate either an
LLVM argument or an LLVM module flag. To avoid duplicate specifications
in a large number of targets, the default value for support is
DefaultForArch, which is translated to a concrete value according to the
target's architecture.
|
|
|
|
The minimum that `rustc` encoded did not match the version in Clang, and
that meant that that when linking, we ended up bumping the version.
Specifically, this sets the correct deployment target of the following
simulator and Mac Catalyst targets:
- `aarch64-apple-ios-sim` from 10.0 to 14.0
- `aarch64-apple-tvos-sim` from 10.0 to 14.0
- `aarch64-apple-watchos-sim` from 5.0 to 7.0
- `aarch64-apple-ios-macabi` from 13.1 to 14.0
I have chosen to not document the simulator target versions in the
platform support docs, as it is fundamentally uninteresting; the normal
targets (e.g. `aarch64-apple-ios`, `aarch64-apple-tvos`) still have the
same deployment target as before, and that's what developers should
actually target.
|
|
|
|
thesummer:1-add-target-support-for-rtems-arm-xilinx-zedboard, r=tgross35
Add target support for RTEMS Arm
# `armv7-rtems-eabihf`
This PR adds a new target for the RTEMS RTOS. To get things started it focuses on Xilinx/AMD Zynq-based targets, but in theory it should also support other armv7-based board support packages in the future.
Given that RTEMS has support for many POSIX functions it is mostly enabling corresponding unix features for the new target.
I also previously started a PR in libc (https://github.com/rust-lang/libc/pull/3561) to add the needed OS specific C-bindings and was told that a PR in this repo is needed first. I will update the PR to the newest version after approval here.
I will probably also need to change one line in the backtrace repo.
Current status is that I could compile rustc for the new target locally (with the updated libc and backtrace) and could compile binaries, link, and execute a simple "Hello World" RTEMS application for the target hardware.
> A proposed target or target-specific patch that substantially changes code shared with other targets (not just target-specific code) must be reviewed and approved by the appropriate team for that shared code before acceptance.
There should be no breaking changes for existing targets. Main changes are adding corresponding `cfg` switches for the RTEMS OS and adding the C binding in libc.
# Tier 3 target policy
> - A tier 3 target must have a designated developer or developers (the "target maintainers") on record to be CCed when issues arise regarding the target. (The mechanism to track and CC such developers may evolve over time.)
I will do the maintenance (for now) further members of the RTEMS community will most likely join once the first steps have been done.
> - Targets must use naming consistent with any existing targets; for instance, a target for the same CPU or OS as an existing Rust target should use the same name for that CPU or OS. Targets should normally use the same names and naming conventions as used elsewhere in the broader ecosystem beyond Rust (such as in other toolchains), unless they have a very good reason to diverge. Changing the name of a target can be highly disruptive, especially once the target reaches a higher tier, so getting the name right is important even for a tier 3 target.
> - Target names should not introduce undue confusion or ambiguity unless absolutely necessary to maintain ecosystem compatibility. For example, if the name of the target makes people extremely likely to form incorrect beliefs about what it targets, the name should be changed or augmented to disambiguate it.
> - If possible, use only letters, numbers, dashes and underscores for the name. Periods (`.`) are known to cause issues in Cargo.
The proposed triple is `armv7-rtems-eabihf`
> - Tier 3 targets may have unusual requirements to build or use, but must not create legal issues or impose onerous legal terms for the Rust project or for Rust developers or users.
> - The target must not introduce license incompatibilities.
> - Anything added to the Rust repository must be under the standard Rust license (`MIT OR Apache-2.0`).
> - The target must not cause the Rust tools or libraries built for any other host (even when supporting cross-compilation to the target) to depend on any new dependency less permissive than the Rust licensing policy. This applies whether the dependency is a Rust crate that would require adding new license exceptions (as specified by the `tidy` tool in the rust-lang/rust repository), or whether the dependency is a native library or binary. In other words, the introduction of the target must not cause a user installing or running a version of Rust or the Rust tools to be subject to any new license requirements.
> - Compiling, linking, and emitting functional binaries, libraries, or other code for the target (whether hosted on the target itself or cross-compiling from another target) must not depend on proprietary (non-FOSS) libraries. Host tools built for the target itself may depend on the ordinary runtime libraries supplied by the platform and commonly used by other applications built for the target, but those libraries must not be required for code generation for the target; cross-compilation to the target must not require such libraries at all. For instance, `rustc` built for the target may depend on a common proprietary C runtime library or console output library, but must not depend on a proprietary code generation library or code optimization library. Rust's license permits such combinations, but the Rust project has no interest in maintaining such combinations within the scope of Rust itself, even at tier 3.
> - "onerous" here is an intentionally subjective term. At a minimum, "onerous" legal/licensing terms include but are _not_ limited to: non-disclosure requirements, non-compete requirements, contributor license agreements (CLAs) or equivalent, "non-commercial"/"research-only"/etc terms, requirements conditional on the employer or employment of any particular Rust developers, revocable terms, any requirements that create liability for the Rust project or its developers or users, or any requirements that adversely affect the livelihood or prospects of the Rust project or its developers or users.
The tools consists of the cross-compiler toolchain (gcc-based). The RTEMS kernel (BSD license) and parts of the driver stack of FreeBSD (BSD license). All tools are FOSS and publicly available here: https://gitlab.rtems.org/rtems
There are also no new features or dependencies introduced to the Rust code.
> - Neither this policy nor any decisions made regarding targets shall create any binding agreement or estoppel by any party. If any member of an approving Rust team serves as one of the maintainers of a target, or has any legal or employment requirement (explicit or implicit) that might affect their decisions regarding a target, they must recuse themselves from any approval decisions regarding the target's tier status, though they may otherwise participate in discussions.
N/A to me. I am not a reviewer nor Rust team member.
> - Tier 3 targets should attempt to implement as much of the standard libraries as possible and appropriate (`core` for most targets, `alloc` for targets that can support dynamic memory allocation, `std` for targets with an operating system or equivalent layer of system-provided functionality), but may leave some code unimplemented (either unavailable or stubbed out as appropriate), whether because the target makes it impossible to implement or challenging to implement. The authors of pull requests are not obligated to avoid calling any portions of the standard library on the basis of a tier 3 target not implementing those portions.
`core` and `std` compile. Some advanced features of the `std` lib might not work yet. However, the goal of this tier 3 target it to make it easier for other people to build and run test applications to better identify the unsupported features and work towards enabling them.
> - The target must provide documentation for the Rust community explaining how to build for the target, using cross-compilation if possible. If the target supports running binaries, or running tests (even if they do not pass), the documentation must explain how to run such binaries or tests for the target, using emulation if possible or dedicated hardware if necessary.
Building is described in platform support doc. Running simple unit tests works. Running the test suite of the stdlib is currently not that easy. Trying to work towards that after the this target has been added to the nightly.
> - Tier 3 targets must not impose burden on the authors of pull requests, or other developers in the community, to maintain the target. In particular, do not post comments (automated or manual) on a PR that derail or suggest a block on the PR based on a tier 3 target. Do not send automated messages or notifications (via any medium, including via ````@`)``` to a PR author or others involved with a PR regarding a tier 3 target, unless they have opted into such messages.
Understood.
> - Backlinks such as those generated by the issue/PR tracker when linking to an issue or PR are not considered a violation of this policy, within reason. However, such messages (even on a separate repository) must not generate notifications to anyone involved with a PR who has not requested such notifications.
Ok
> - Patches adding or updating tier 3 targets must not break any existing tier 2 or tier 1 target, and must not knowingly break another tier 3 target without approval of either the compiler team or the maintainers of the other tier 3 target.
> - In particular, this may come up when working on closely related targets, such as variations of the same architecture with different features. Avoid introducing unconditional uses of features that another variation of the target may not have; use conditional compilation or runtime detection, as appropriate, to let each target run code supported by that target.
I think, I didn't add any breaking changes for any existing targets (see the comment regarding features above).
> - Tier 3 targets must be able to produce assembly using at least one of rustc's supported backends from any host target.
Can produce assembly code via the llvm backend (tested on Linux).
>
> If a tier 3 target stops meeting these requirements, or the target maintainers no longer have interest or time, or the target shows no signs of activity and has not built for some time, or removing the target would improve the quality of the Rust codebase, we may post a PR to remove it; any such PR will be CCed to the target maintainers (and potentially other people who have previously worked on the target), to check potential interest in improving the situation.GIAt this tier, the Rust project provides no official support for a target, so we place minimal requirements on the introduction of targets.
Understood.
r? compiler-team
|
|
rustdoc: add header map to the table of contents
## Summary
Add header sections to the sidebar TOC.
### Preview
* http://notriddle.com/rustdoc-html-demo-9/toc/rust/std/index.html
* http://notriddle.com/rustdoc-html-demo-9/toc/rust-derive-builder/derive_builder/index.html
## Motivation
Some pages are very wordy, like these.
| crate | word count |
|--|--|
| [std::option](https://doc.rust-lang.org/stable/std/option/index.html) | 2,138
| [derive_builder](https://docs.rs/derive_builder/0.13.0/derive_builder/index.html) | 2,403
| [tracing](https://docs.rs/tracing/0.1.40/tracing/index.html) | 3,912
| [regex](https://docs.rs/regex/1.10.3/regex/index.html) | 8,412
This kind of very long document is more navigable with a table of contents, like Wikipedia's or the one [GitHub recently added](https://github.blog/changelog/2021-04-13-table-of-contents-support-in-markdown-files/) for READMEs.
In fact, the use case is so compelling, that it's been requested multiple times and implemented in an extension:
* https://github.com/rust-lang/rust/issues/80858
* https://github.com/rust-lang/rust/issues/28056
* https://github.com/rust-lang/rust/issues/14475
* https://rust.extension.sh/#show-table-of-content
(Some of these issues ask for more than this, so don’t close them.)
It's also been implemented by hand in some crates, because the author really thought it was needed. Protip: for a more exhaustive list, run [`site:docs.rs table of contents`](https://duckduckgo.com/?t=ffab&q=site%3Adocs.rs+table+of+contents&ia=web), though some of them are false positives.
* https://docs.rs/figment/0.10.14/figment/index.html#table-of-contents
* https://docs.rs/csv/1.3.0/csv/tutorial/index.html#table-of-contents
* https://docs.rs/axum/0.7.4/axum/response/index.html#table-of-contents
* https://docs.rs/regex-automata/0.4.5/regex_automata/index.html#table-of-contents
Unfortunately for these hand-built ToCs, because they're just part of the docs, there's no consistent way to turn them off if the reader doesn't want them. It's also more complicated to ensure they stay in sync with the docs they're supposed to describe, and they don't stay with you when you scroll like Wikipedia's [does now](https://uxdesign.cc/design-notes-on-the-2023-wikipedia-redesign-d6573b9af28d).
## Guide-level explanation
When writing docs for a top-level item, the first and second level of headers will be shown in an outline in the sidebar. In this context, "top level" means "not associated".
This means, if you're writing very long guides or explanations, and you want it to have a table of contents in the sidebar for its headings, the ideal place to attach it is usually the *module* or *crate*, because this page has fewer other things on it (and is the ideal place to describe "cross-cutting concerns" for its child items).
If you're reading documentation, and want to get rid of the table of contents, open the  Settings panel and checkmark "Hide table of contents."
## Reference-level explanation
Top-level items have an outline generated. This works for potentially-malformed header trees by pairing a header with the nearest header with a higher level. For example:
```markdown
## A
# B
# C
## D
## E
```
A, B, and C are all siblings, and D and E are children of C.
Rustdoc only presents two layers of tree, but it tracks up to the full depth of 6 while preparing it.
That means that these two doc comment both generate the same outline:
```rust
/// # First
/// ## Second
struct One;
/// ## First
/// ### Second
struct Two;
```
## Drawbacks
The biggest drawback is adding more stuff to the sidebar.
My crawl through docs.rs shows this to, surprisingly, be less of a problem than I thought. The manually-built tables of contents, and the pages with dozens of headers, usually seem to be modules or crates, not types (where extreme scrolling would become a problem, since they already have methods to deal with).
The best example of a type with many headers is [vec::Vec](https://doc.rust-lang.org/1.75.0/std/vec/struct.Vec.html), which still only has five headers, not dozens like [axum::extract](https://docs.rs/axum/0.7.4/axum/extract/index.html).
## Rationale and alternatives
### Why in the existing sidebar?
The method links and the top-doc header links have more in common with each other than either of them do with the "In [parent module]" links, and should go together.
### Why limited to two levels?
The sidebar is pretty narrow, and I don't want too much space used by indentation. Making the sidebar wider, while it has some upsides, also takes up more space on middling-sized screens or tiled WMs.
### Why not line wrap?
That behaves strangely when resizing.
## Prior art
### Doc generators that have TOC for headers
https://hexdocs.pm/phoenix/Phoenix.Controller.html is very close, in the sense that it also has header sections directly alongside functions and types.
Another example, referenced as part of the [early sidebar discussion](https://github.com/rust-lang/rust/issues/37856) that added methods, Ruby will show a table of contents in the sidebar (for example, on the [ARGF](https://docs.ruby-lang.org/en/master/ARGF.html) class). According to their changelog, [they added it in 2013](https://github.com/ruby/rdoc/blob/06137bde8ccc48cd502bc28178bcd8f2dfe37624/History.rdoc#400--2013-02-24-).
Haskell seems to mix text and functions even more freely than Elixir. For example, this [Naming conventions](https://hackage.haskell.org/package/base-4.19.0.0/docs/Control-Monad.html#g:3) is plain text, and is immediately followed by functions. And the [Pandoc top level](https://hackage.haskell.org/package/pandoc-3.1.11.1/docs/Text-Pandoc.html) has items split up by function, rather than by kind. Their TOC matches exactly with the contents of the page.
### Doc generators that don't have header TOC, but still have headers
Elm, interestingly enough, seems to have the same setup that Rust used to have: sibling navigation between modules, and no index within a single page. [They keep Haskell's habit of named sections with machine-generated type signatures](https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom), though.
[PHP](https://www.php.net/manual/en/book.datetime.php), like elm, also has a right-hand sidebar with sibling navigation. However, PHP has a single page for a single method, unlike Rust's page for an entire "class." So even though these pages have headers, it's never more than ten at most. And when they have guides, those guides are also multi-page.
## Unresolved questions
* Writing recommendations for anyone who wants to take advantage of this.
* Right now, it does not line wrap. That might be a bad idea: a lot of these are getting truncated.
* Split sidebars, which I [tried implementing](https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/Table.20of.20contents), are not required. The TOC can be turned off, if it's really a problem. Implemented in https://github.com/rust-lang/rust/pull/120818, but needs more, separate, discussion.
## Future possibilities
I would like to do a better job of distinguishing global navigation from local navigation. Rustdoc has a pretty reasonable information architecture, if only we did a better job of communicating it.
This PR aims, mostly, to help doc authors help their users by writing docs that can be more effectively skimmed. But it doesn't do anything to make it easier to tell the TOC and the Module Nav apart.
|
|
r=workingjubilee
Document the broken C ABI of `wasm32-unknown-unknown`
Inspired by discussion on
https://github.com/rust-lang/rust/issues/129486 this is intended to at least document the current state of the world in a more public location than throughout a series of issues.
|
|
|
|
|
|
This reverts commit acb4e8b6251f1d8da36f08e7a70fa23fc581839e, reversing
changes made to 100fde5246bf56f22fb5cc85374dd841296fce0e.
|
|
add `aarch64_unknown_nto_qnx700` target - QNX 7.0 support for aarch64le
This backports the QNX 7.1 aarch64 implementation to 7.0.
* [x] required `-lregex` disabled, see https://github.com/rust-lang/libc/pull/3775 (released in libc 0.2.156)
* [x] uses `libgcc.a` instead of `libgcc_s.so` (7.0 used ancient GCC 5.4 which didn't have gcc_s)
* [x] a fix in `backtrace` crate to support stack traces https://github.com/rust-lang/backtrace-rs/pull/648
This PR bumps libc dependency to 0.2.158
CC: to the folks who did the [initial implementation](https://doc.rust-lang.org/rustc/platform-support/nto-qnx.html): `@flba-eb,` `@gh-tr,` `@jonathanpallant,` `@japaric`
# Compile target
```bash
# Configure qcc build environment
source _path_/_to_/qnx7.0/qnxsdp-env.sh
# Tell rust to use qcc when building QNX 7.0 targets
export build_env='
CC_aarch64-unknown-nto-qnx700=qcc
CFLAGS_aarch64-unknown-nto-qnx700=-Vgcc_ntoaarch64le_cxx
CXX_aarch64-unknown-nto-qnx700=qcc
AR_aarch64_unknown_nto_qnx700=ntoaarch64-ar'
# Build rust compiler, libs, and the remote test server
env $build_env ./x.py build \
--target x86_64-unknown-linux-gnu,aarch64-unknown-nto-qnx700 \
rustc library/core library/alloc library/std src/tools/remote-test-server
rustup toolchain link stage1 build/host/stage1
```
# Compile "hello world"
```bash
source _path_/_to_/qnx7.0/qnxsdp-env.sh
cargo new hello_world
cd hello_world
cargo +stage1 build --release --target aarch64-unknown-nto-qnx700
```
# Configure a remote for testing
Do this from a new shell - we will need to run more commands in the previous one. I ran into these two issues, and found some workarounds.
* Temporary dir might not work properly
* Default `remote-test-server` has issues binding to an address
```
# ./remote-test-server
starting test server
thread 'main' panicked at src/tools/remote-test-server/src/main.rs:175:29:
called `Result::unwrap()` on an `Err` value: Os { code: 249, kind: AddrNotAvailable, message: "Can't assign requested address" }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```
Specifying `--bind` param actually fixes that, and so does setting `TMPDIR` properly.
```bash
# Copy remote-test-server to remote device. You may need to use sftp instead.
# ATTENTION: Note that the path is different from the one in the remote testing documentation for some reason
scp ./build/x86_64-unknown-linux-gnu/stage1-tools-bin/remote-test-server qnxdevice:/path/
# Run ssh with port forwarding - so that rust tester can connect to the local port instead
ssh -L 12345:127.0.0.1:12345 qnxdevice
# on the device, run
rm -rf tmp && mkdir -p tmp && TMPDIR=$PWD/tmp ./remote-test-server --bind 0.0.0.0:12345
```
# Run test suit
Assume all previous environment variables are still set, or re-init them
```bash
export TEST_DEVICE_ADDR="localhost:12345"
# tidy needs to be skipped due to using un-published libc dependency
export exclude_tests='
--exclude src/bootstrap
--exclude src/tools/error_index_generator
--exclude src/tools/linkchecker
--exclude src/tools/tidy
--exclude tests/ui-fulldeps
--exclude rustc
--exclude rustdoc
--exclude tests/run-make-fulldeps'
env $build_env ./x.py test $exclude_tests --stage 1 --target aarch64-unknown-nto-qnx700
```
try-job: dist-x86_64-msvc
|
|
linker: Synchronize native library search in rustc and linker
Also search for static libraries with alternative naming (`libname.a`) on MSVC when producing executables or dynamic libraries, and not just rlibs.
This unblocks https://github.com/rust-lang/rust/pull/123436.
try-job: x86_64-msvc
|
|
|
|
riscv64imac: allow shadow call stack sanitizer
cc `@Darksonn` for shadow call stack sanitizer support on RV64IMAC and RV64GC
|
|
Add `-Zlint-llvm-ir`
This flag is similar to `-Zverify-llvm-ir` and allows us to lint the generated IR.
r? compiler
|
|
debug-fmt-detail option
I'd like to propose a new option that makes `#[derive(Debug)]` generate no-op implementations that don't print anything, and makes `{:?}` in format strings a no-op.
There are a couple of motivations for this:
1. A more thorough stripping of debug symbols. Binaries stripped of debug symbols still retain some of them through `Debug` implementations. It's hard to avoid that without compiler's help, because debug formatting can be used in many places, including dependencies, and their loggers, asserts, panics, etc.
* In my testing it gives about 2% binary size reduction on top of all other binary-minimizing best practices (including `panic_immediate_abort`). There are targets like Web WASM or embedded where users pay attention to binary sizes.
* Users distributing closed-source binaries may not want to "leak" any symbol names as a matter of principle.
2. Adds ability to test whether code depends on specifics of the `Debug` format implementation in unwise ways (e.g. trying to get data unavailable via public interface, or using it as a serialization format). Because current Rust's debug implementation doesn't change, there's a risk of it becoming a fragile de-facto API that [won't be possible to change in the future](https://www.hyrumslaw.com/). An option that "breaks" it can act as a [grease](https://www.rfc-editor.org/rfc/rfc8701.html).
This implementation is a `-Z fmt-debug=opt` flag that takes:
* `full` — the default, current state.
* `none` — makes derived `Debug` and `{:?}` no-ops. Explicit `impl Debug for T` implementations are left unharmed, but `{:?}` format won't use them, so they may get dead-code eliminated if they aren't invoked directly.
* `shallow` — makes derived `Debug` print only the type's name, without recursing into fields. Fieldless enums print their variant names. `{:?}` works.
The `shallow` option is a compromise between minimizing the `Debug` code, and compatibility. There are popular proc-macro crates that use `Debug::fmt` as a way to convert enum values into their Rust source code.
There's a corresponding `cfg` flag: `#[cfg(fmt_debug = "none")]` that can be used in user code to react to this setting to minimize custom `Debug` implementations or remove unnecessary formatting helper functions.
|
|
|
|
|
