Document lang items #978
Document lang items #978
Conversation
src/lang-items.md
Outdated
| ## List of all language items | ||
|
|
||
| This is a list of all language items in Rust along with where they are located in | ||
| the source code. | ||
|
|
||
| - Primitives | ||
| - `i8`: `libcore/num/mod.rs` | ||
| - `i16`: `libcore/num/mod.rs` | ||
| - `i32`: `libcore/num/mod.rs` | ||
| - `i64`: `libcore/num/mod.rs` | ||
| - `i128`: `libcore/num/mod.rs` | ||
| - `isize`: `libcore/num/mod.rs` | ||
| - `u8`: `libcore/num/mod.rs` | ||
| - `u16`: `libcore/num/mod.rs` | ||
| - `u32`: `libcore/num/mod.rs` | ||
| - `u64`: `libcore/num/mod.rs` | ||
| - `u128`: `libcore/num/mod.rs` | ||
| - `usize`: `libcore/num/mod.rs` | ||
| - `f32`: `libstd/f32.rs` | ||
| - `f64`: `libstd/f64.rs` | ||
| - `char`: `libcore/char.rs` | ||
| - `slice`: `liballoc/slice.rs` | ||
| - `str`: `liballoc/str.rs` | ||
| - `const_ptr`: `libcore/ptr.rs` | ||
| - `mut_ptr`: `libcore/ptr.rs` | ||
| - Runtime | ||
| - `start`: `libstd/rt.rs` | ||
| - `eh_personality`: `libpanic_unwind/emcc.rs` (EMCC) | ||
| - `eh_personality`: `libpanic_unwind/gcc.rs` (GNU) | ||
| - `eh_personality`: `libpanic_unwind/seh.rs` (SEH) | ||
| - `eh_catch_typeinfo`: `libpanic_unwind/emcc.rs` (EMCC) | ||
| - `panic`: `libcore/panicking.rs` | ||
| - `panic_bounds_check`: `libcore/panicking.rs` | ||
| - `panic_impl`: `libcore/panicking.rs` | ||
| - `panic_impl`: `libstd/panicking.rs` | ||
| - Allocations | ||
| - `owned_box`: `liballoc/boxed.rs` | ||
| - `exchange_malloc`: `liballoc/heap.rs` | ||
| - `box_free`: `liballoc/heap.rs` | ||
| - Operands | ||
| - `not`: `libcore/ops/bit.rs` | ||
| - `bitand`: `libcore/ops/bit.rs` | ||
| - `bitor`: `libcore/ops/bit.rs` | ||
| - `bitxor`: `libcore/ops/bit.rs` | ||
| - `shl`: `libcore/ops/bit.rs` | ||
| - `shr`: `libcore/ops/bit.rs` | ||
| - `bitand_assign`: `libcore/ops/bit.rs` | ||
| - `bitor_assign`: `libcore/ops/bit.rs` | ||
| - `bitxor_assign`: `libcore/ops/bit.rs` | ||
| - `shl_assign`: `libcore/ops/bit.rs` | ||
| - `shr_assign`: `libcore/ops/bit.rs` | ||
| - `deref`: `libcore/ops/deref.rs` | ||
| - `deref_mut`: `libcore/ops/deref.rs` | ||
| - `index`: `libcore/ops/index.rs` | ||
| - `index_mut`: `libcore/ops/index.rs` | ||
| - `add`: `libcore/ops/arith.rs` | ||
| - `sub`: `libcore/ops/arith.rs` | ||
| - `mul`: `libcore/ops/arith.rs` | ||
| - `div`: `libcore/ops/arith.rs` | ||
| - `rem`: `libcore/ops/arith.rs` | ||
| - `neg`: `libcore/ops/arith.rs` | ||
| - `add_assign`: `libcore/ops/arith.rs` | ||
| - `sub_assign`: `libcore/ops/arith.rs` | ||
| - `mul_assign`: `libcore/ops/arith.rs` | ||
| - `div_assign`: `libcore/ops/arith.rs` | ||
| - `rem_assign`: `libcore/ops/arith.rs` | ||
| - `eq`: `libcore/cmp.rs` | ||
| - `ord`: `libcore/cmp.rs` | ||
| - Functions | ||
| - `fn`: `libcore/ops/function.rs` | ||
| - `fn_mut`: `libcore/ops/function.rs` | ||
| - `fn_once`: `libcore/ops/function.rs` | ||
| - `generator_state`: `libcore/ops/generator.rs` | ||
| - `generator`: `libcore/ops/generator.rs` | ||
| - Opting out | ||
| - `unsafe_cell` (relaxes pointer provenance rules, allowing const-to-mut casts): `libcore/cell.rs` | ||
| - `manually_drop` (opts out of implicit destructor call): `libcore/mem/manually_drop.rs` | ||
| - Other | ||
| - `coerce_unsized`: `libcore/ops/unsize.rs` | ||
| - `drop`: `libcore/ops/drop.rs` | ||
| - `drop_in_place`: `libcore/ptr.rs` | ||
| - `clone`: `libcore/clone.rs` | ||
| - `copy`: `libcore/marker.rs` | ||
| - `send`: `libcore/marker.rs` | ||
| - `sized`: `libcore/marker.rs` | ||
| - `unsize`: `libcore/marker.rs` | ||
| - `sync`: `libcore/marker.rs` | ||
| - `phantom_data`: `libcore/marker.rs` | ||
| - `discriminant_kind`: `libcore/marker.rs` | ||
| - `freeze`: `libcore/marker.rs` |
There was a problem hiding this comment.
This will very rapidly get out of date. Since you can easily rederive it with rg 'lang = "', I don't think it needs to go in the guide.
There was a problem hiding this comment.
(Also the filenames are wrong: it should be library/core/src/... not libcore/...)
There was a problem hiding this comment.
Maybe it's better to link to https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/lang_items/enum.LangItem.html instead? That will always be up to date. It won't have the files in library but you can grep for those pretty easily.
|
Oh, I should have made it clear that I'm not author of this text (but of course I can try to improve it according to review). It's a bit actualized page from the unstable book. @nikomatsakis proposed moving it to rustc-dev-guide. I think documentation of std implementation details fits rustc-dev-guide. Is there a better place? |
|
@spastorino do you have opinions on this? |
|
@jyn514 I like the idea of having content about lang items in the guide and this is great but as you pointed out we may want to improve some things. I don't have any further comment than what you've already stated. |
jyn514
added
the
S-waiting-on-author
src/lang-items.md
Outdated
| - `generator_state`: `library/core/src/ops/generator.rs` | ||
| - `generator`: `library/core/src/ops/generator.rs` | ||
| - Opting out | ||
| - `unsafe_cell` (relaxes pointer provenance rules, allowing const-to-mut casts): `library/core/src/cell.rs` |
There was a problem hiding this comment.
Btw, you need to wrap this line.
|
Hi @MikailBag, it's been a while - are you still planning to work on this? |
There was a problem hiding this comment.
This seems pretty useful to document indeed. I was expecting though to read more about how the code in the compiler can gain access to lang items and some of the patterns we have around that.
Another interesting angle: sometimes, when you have compiler errors in libcore, it's useful to create a standalone binary / library for reproducing the failure. That might be a good thing to mention or even use as the motivating case.
I think we should land this PR, but it'd be ideal to tweak it to have more of a "rustc-dev" angle.
|
Sorry for the huge delay. I've just turned this PR into an MVP that only contains a small introduction and a list of lang items. I think that examples should be better added (or ported from the Unstable Book) in follow-up PRs because my compiler knowledge (and English writing skills 😄) is not enough for writing a good example. |
| Others can be overriden to achieve some | ||
| specific goals. | ||
|
|
||
| For example, later sections describe how to control | ||
| your binary startup or override panic implementation. |
There was a problem hiding this comment.
This is no longer true.
| Others can be overriden to achieve some | |
| specific goals. | |
| For example, later sections describe how to control | |
| your binary startup or override panic implementation. | |
| Others can be overridden to achieve some specific goals; for example, you can control your binary's entrypoint. |
| - the traits in `std::marker` used to indicate types of | ||
| various kinds; lang items `send`, `sync` and `copy`. |
There was a problem hiding this comment.
| - the traits in `std::marker` used to indicate types of | |
| various kinds; lang items `send`, `sync` and `copy`. | |
| - the traits in `std::marker` used to indicate properties of | |
| types that are used by the compiler; lang items `send`, `sync` and `copy`. |
| ## List of all language items | ||
|
|
||
| This is a list of all language items in Rust along with where they are located in | ||
| the source code. | ||
|
|
||
| - Primitives | ||
| - `i8`: `library/core/src/num/mod.rs` | ||
| - `i16`: `library/core/src/num/mod.rs` | ||
| - `i32`: `library/core/src/num/mod.rs` | ||
| - `i64`: `library/core/src/num/mod.rs` | ||
| - `i128`: `library/core/src/num/mod.rs` | ||
| - `isize`: `library/core/src/num/mod.rs` | ||
| - `u8`: `library/core/src/num/mod.rs` | ||
| - `u16`: `library/core/src/num/mod.rs` | ||
| - `u32`: `library/core/src/num/mod.rs` | ||
| - `u64`: `library/core/src/num/mod.rs` | ||
| - `u128`: `library/core/src/num/mod.rs` | ||
| - `usize`: `library/core/src/num/mod.rs` | ||
| - `f32`: `library/std/src/f32.rs` | ||
| - `f64`: `library/std/src/f64.rs` | ||
| - `char`: `library/core/src/char.rs` | ||
| - `slice`: `library/alloc/src/slice.rs` | ||
| - `str`: `library/alloc/src/str.rs` | ||
| - `const_ptr`: `library/core/src/ptr.rs` | ||
| - `mut_ptr`: `library/core/src/ptr.rs` | ||
| - Runtime | ||
| - `start`: `library/std/src/rt.rs` | ||
| - `eh_personality`: `library/panic_unwind/src/emcc.rs` (EMCC) | ||
| - `eh_personality`: `library/panic_unwind/src/gcc.rs` (GNU) | ||
| - `eh_personality`: `library/panic_unwind/src/seh.rs` (SEH) | ||
| - `eh_catch_typeinfo`: `library/panic_unwind/src/emcc.rs` (EMCC) | ||
| - `panic`: `library/core/src/panicking.rs` | ||
| - `panic_bounds_check`: `library/core/src/panicking.rs` | ||
| - `panic_impl`: `library/core/src/panicking.rs` | ||
| - `panic_impl`: `library/std/src/panicking.rs` | ||
| - Allocations | ||
| - `owned_box`: `library/alloc/src/boxed.rs` | ||
| - `exchange_malloc`: `library/alloc/src/heap.rs` | ||
| - `box_free`: `library/alloc/src/heap.rs` | ||
| - Operands | ||
| - `not`: `library/core/src/ops/bit.rs` | ||
| - `bitand`: `library/core/src/ops/bit.rs` | ||
| - `bitor`: `library/core/src/ops/bit.rs` | ||
| - `bitxor`: `library/core/src/ops/bit.rs` | ||
| - `shl`: `library/core/src/ops/bit.rs` | ||
| - `shr`: `library/core/src/ops/bit.rs` | ||
| - `bitand_assign`: `library/core/src/ops/bit.rs` | ||
| - `bitor_assign`: `library/core/src/ops/bit.rs` | ||
| - `bitxor_assign`: `library/core/src/ops/bit.rs` | ||
| - `shl_assign`: `library/core/src/ops/bit.rs` | ||
| - `shr_assign`: `library/core/src/ops/bit.rs` | ||
| - `deref`: `library/core/src/ops/deref.rs` | ||
| - `deref_mut`: `library/core/src/ops/deref.rs` | ||
| - `index`: `library/core/src/ops/index.rs` | ||
| - `index_mut`: `library/core/src/ops/index.rs` | ||
| - `add`: `library/core/src/ops/arith.rs` | ||
| - `sub`: `library/core/src/ops/arith.rs` | ||
| - `mul`: `library/core/src/ops/arith.rs` | ||
| - `div`: `library/core/src/ops/arith.rs` | ||
| - `rem`: `library/core/src/ops/arith.rs` | ||
| - `neg`: `library/core/src/ops/arith.rs` | ||
| - `add_assign`: `library/core/src/ops/arith.rs` | ||
| - `sub_assign`: `library/core/src/ops/arith.rs` | ||
| - `mul_assign`: `library/core/src/ops/arith.rs` | ||
| - `div_assign`: `library/core/src/ops/arith.rs` | ||
| - `rem_assign`: `library/core/src/ops/arith.rs` | ||
| - `eq`: `library/core/src/cmp.rs` | ||
| - `ord`: `library/core/src/cmp.rs` | ||
| - Functions | ||
| - `fn`: `library/core/src/ops/function.rs` | ||
| - `fn_mut`: `library/core/src/ops/function.rs` | ||
| - `fn_once`: `library/core/src/ops/function.rs` | ||
| - `generator_state`: `library/core/src/ops/generator.rs` | ||
| - `generator`: `library/core/src/ops/generator.rs` | ||
| - Opting out | ||
| - `unsafe_cell` (relaxes pointer provenance rules, allowing const-to-mut | ||
| casts): `library/core/src/cell.rs` | ||
| - `manually_drop` (opts out of implicit destructor call): `library/core/src/mem/manually_drop.rs` | ||
| - Other | ||
| - `coerce_unsized`: `library/core/src/ops/unsize.rs` | ||
| - `drop`: `library/core/src/ops/drop.rs` | ||
| - `drop_in_place`: `library/core/src/ptr.rs` | ||
| - `clone`: `library/core/src/clone.rs` | ||
| - `copy`: `library/core/src/marker.rs` | ||
| - `send`: `library/core/src/marker.rs` | ||
| - `sized`: `libcrary/ore/msrc/arker.rs` | ||
| - `unsize`: `library/core/src/marker.rs` | ||
| - `sync`: `library/core/src/marker.rs` | ||
| - `phantom_data`: `libcore/marker.rs` | ||
| - `discriminant_kind`: `library/core/src/marker.rs` | ||
| - `freeze`: `library/core/src/marker.rs` |
There was a problem hiding this comment.
I still think this is not a good fit because it will get outdated so rapidly. Maybe instead you could recommend rg '#\[lang' library or looking at https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/lang_items/enum.LangItem.html ?
There was a problem hiding this comment.
Yeah, I was going to suggest that it would be better to have people look at the autogenerated docs. And suggesting rg -F '#[lang' library/ is probably a good idea too.
|
Hi @MikailBag, are you planning to follow-up on this? |
|
Given that I don't have enough understanding of how this page should look, I'm going to close this PR for now. |
I'm not sure where to put this page, selected the simplest place.