Document lang items by MikailBag · Pull Request #978 · rust-lang/rustc-dev-guide

MikailBag · 2020-12-01T08:39:05Z

I'm not sure where to put this page, selected the simplest place.

jyn514

Thanks for writing it up! There's definitely useful info here, but I'm not sure the dev-guide is the right place for it.

src/lang-items.md

jyn514 · 2020-12-01T19:43:01Z

src/lang-items.md

+## 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`


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.

(Also the filenames are wrong: it should be library/core/src/... not libcore/...)

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.

MikailBag · 2020-12-01T20:45:24Z

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?

jyn514 · 2020-12-01T21:17:38Z

@spastorino do you have opinions on this?

spastorino · 2020-12-04T15:58:53Z

@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.

src/lang-items.md

camelid · 2020-12-06T19:46:02Z

src/lang-items.md

+  - `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`


Btw, you need to wrap this line.

src/lang-items.md

jyn514 · 2021-04-09T22:14:01Z

Hi @MikailBag, it's been a while - are you still planning to work on this?

nikomatsakis

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.

MikailBag · 2021-04-13T19:00:06Z

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.

jyn514 · 2021-04-13T19:02:17Z

src/lang-items.md

+Others can be overriden to achieve some
+specific goals.
+
+For example, later sections describe how to control
+your binary startup or override panic implementation.


This is no longer true.

Suggested change

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.

jyn514 · 2021-04-13T19:03:10Z

src/lang-items.md

+- the traits in `std::marker` used to indicate types of
+  various kinds; lang items `send`, `sync` and `copy`.


Suggested change

- 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`.

jyn514 · 2021-04-13T19:04:42Z

src/lang-items.md

+## 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`


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 ?

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.

jyn514 · 2021-04-27T17:10:12Z

Hi @MikailBag, are you planning to follow-up on this?

MikailBag · 2021-04-27T18:20:40Z

Given that I don't have enough understanding of how this page should look, I'm going to close this PR for now.

Document lang items

395fc50

jyn514 reviewed Dec 1, 2020

View reviewed changes

jyn514 added the S-waiting-on-author Status: this PR is waiting for additional action by the OP label Dec 6, 2020

Update docs a bit

603b088

jyn514 reviewed Dec 6, 2020

View reviewed changes

src/lang-items.md Outdated Show resolved Hide resolved

src/lang-items.md Outdated Show resolved Hide resolved

Update paths

5235869

camelid reviewed Dec 6, 2020

View reviewed changes

src/lang-items.md Outdated Show resolved Hide resolved

src/lang-items.md Outdated Show resolved Hide resolved

src/lang-items.md Outdated Show resolved Hide resolved

src/lang-items.md Outdated Show resolved Hide resolved

camelid reviewed Dec 6, 2020

View reviewed changes

camelid requested changes Dec 9, 2020

View reviewed changes

src/lang-items.md Outdated Show resolved Hide resolved

nikomatsakis reviewed Apr 13, 2021

View reviewed changes

Remove all examples

dd8a2e1

Fix line length

7002e15

jyn514 reviewed Apr 13, 2021

View reviewed changes

MikailBag closed this Apr 27, 2021

jyn514 mentioned this pull request Apr 29, 2021

Document lang items #1119

Merged

		- the traits in `std::marker` used to indicate types of
		various kinds; lang items `send`, `sync` and `copy`.

Conversation

MikailBag commented Dec 1, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jyn514 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jyn514 Dec 1, 2020

Choose a reason for hiding this comment

Uh oh!

camelid Dec 1, 2020

Choose a reason for hiding this comment

Uh oh!

jyn514 Dec 6, 2020

Choose a reason for hiding this comment

Uh oh!

MikailBag commented Dec 1, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jyn514 commented Dec 1, 2020

Uh oh!

spastorino commented Dec 4, 2020

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

camelid Dec 6, 2020

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jyn514 commented Apr 9, 2021

Uh oh!

nikomatsakis left a comment

Choose a reason for hiding this comment

Uh oh!

MikailBag commented Apr 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jyn514 Apr 13, 2021

Choose a reason for hiding this comment

Uh oh!

jyn514 Apr 13, 2021

Choose a reason for hiding this comment

Uh oh!

jyn514 Apr 13, 2021

Choose a reason for hiding this comment

Uh oh!

camelid Apr 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jyn514 commented Apr 27, 2021

Uh oh!

MikailBag commented Apr 27, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

MikailBag commented Dec 1, 2020 •

edited

Loading

MikailBag commented Dec 1, 2020 •

edited

Loading

MikailBag commented Apr 13, 2021 •

edited

Loading

camelid Apr 13, 2021 •

edited

Loading