From a1301c349510d9cd06ec618e905241f71a57f839 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 15 Feb 2017 17:43:03 -0500 Subject: Create "The Unstable Book" part of #39588 --- src/bootstrap/step.rs | 9 +++ src/doc/unstable-book/.gitignore | 1 + src/doc/unstable-book/src/SUMMARY.md | 91 ++++++++++++++++++++++ src/doc/unstable-book/src/abi-msp430-interrupt.md | 1 + src/doc/unstable-book/src/abi-ptx.md | 1 + src/doc/unstable-book/src/abi-sysv64.md | 1 + src/doc/unstable-book/src/abi-unadjusted.md | 1 + src/doc/unstable-book/src/abi-vectorcall.md | 1 + .../unstable-book/src/advanced-slice-patterns.md | 1 + src/doc/unstable-book/src/allocator.md | 1 + .../unstable-book/src/allow-internal-unstable.md | 1 + src/doc/unstable-book/src/asm.md | 1 + src/doc/unstable-book/src/associated-consts.md | 1 + .../unstable-book/src/associated-type-defaults.md | 1 + src/doc/unstable-book/src/attr-literals.md | 1 + src/doc/unstable-book/src/box-patterns.md | 1 + src/doc/unstable-book/src/box-syntax.md | 1 + src/doc/unstable-book/src/cfg-target-feature.md | 1 + src/doc/unstable-book/src/cfg-target-has-atomic.md | 1 + .../unstable-book/src/cfg-target-thread-local.md | 1 + src/doc/unstable-book/src/cfg-target-vendor.md | 1 + src/doc/unstable-book/src/compiler-builtins.md | 1 + src/doc/unstable-book/src/concat-idents.md | 1 + .../unstable-book/src/conservative-impl-trait.md | 1 + src/doc/unstable-book/src/const-fn.md | 1 + src/doc/unstable-book/src/const-indexing.md | 1 + src/doc/unstable-book/src/custom-attribute.md | 1 + src/doc/unstable-book/src/custom-derive.md | 1 + .../src/default-type-parameter-fallback.md | 1 + src/doc/unstable-book/src/drop-types-in-const.md | 1 + src/doc/unstable-book/src/dropck-eyepatch.md | 1 + src/doc/unstable-book/src/dropck-parametricity.md | 1 + .../unstable-book/src/exclusive-range-pattern.md | 1 + src/doc/unstable-book/src/field-init-shorthand.md | 1 + src/doc/unstable-book/src/fundamental.md | 1 + src/doc/unstable-book/src/generic-param-attrs.md | 1 + src/doc/unstable-book/src/i128-type.md | 1 + .../unstable-book/src/inclusive-range-syntax.md | 1 + src/doc/unstable-book/src/intrinsics.md | 1 + src/doc/unstable-book/src/lang-items.md | 1 + src/doc/unstable-book/src/link-args.md | 1 + src/doc/unstable-book/src/link-cfg.md | 1 + src/doc/unstable-book/src/link-llvm-intrinsics.md | 1 + src/doc/unstable-book/src/linkage.md | 1 + src/doc/unstable-book/src/log-syntax.md | 1 + src/doc/unstable-book/src/loop-break-value.md | 1 + src/doc/unstable-book/src/macro-reexport.md | 1 + src/doc/unstable-book/src/main.md | 1 + src/doc/unstable-book/src/naked-functions.md | 1 + src/doc/unstable-book/src/needs-allocator.md | 1 + src/doc/unstable-book/src/needs-panic-runtime.md | 1 + src/doc/unstable-book/src/never-type.md | 1 + src/doc/unstable-book/src/no-core.md | 1 + src/doc/unstable-book/src/no-debug.md | 1 + src/doc/unstable-book/src/non_ascii-idents.md | 1 + .../src/omit-gdb-pretty-printer-section.md | 1 + src/doc/unstable-book/src/on-unimplemented.md | 1 + src/doc/unstable-book/src/optin-builtin-traits.md | 1 + src/doc/unstable-book/src/panic-runtime.md | 1 + src/doc/unstable-book/src/placement-in-syntax.md | 1 + src/doc/unstable-book/src/platform-intrinsics.md | 1 + src/doc/unstable-book/src/plugin-registrar.md | 1 + src/doc/unstable-book/src/plugin.md | 1 + src/doc/unstable-book/src/prelude-import.md | 1 + src/doc/unstable-book/src/proc-macro.md | 1 + src/doc/unstable-book/src/pub-restricted.md | 1 + src/doc/unstable-book/src/quote.md | 1 + src/doc/unstable-book/src/relaxed-adts.md | 1 + src/doc/unstable-book/src/repr-simd.md | 1 + src/doc/unstable-book/src/rustc-attrs.md | 1 + .../unstable-book/src/rustc-diagnostic-macros.md | 1 + src/doc/unstable-book/src/sanitizer-runtime.md | 1 + src/doc/unstable-book/src/simd-ffi.md | 1 + src/doc/unstable-book/src/simd.md | 1 + src/doc/unstable-book/src/slice-patterns.md | 1 + src/doc/unstable-book/src/specialization.md | 1 + src/doc/unstable-book/src/staged-api.md | 1 + src/doc/unstable-book/src/start.md | 1 + src/doc/unstable-book/src/static-nobundle.md | 1 + src/doc/unstable-book/src/static-recursion.md | 1 + src/doc/unstable-book/src/stmt-expr-attributes.md | 1 + .../unstable-book/src/struct-field-attributes.md | 1 + src/doc/unstable-book/src/structural-match.md | 1 + src/doc/unstable-book/src/target-feature.md | 1 + src/doc/unstable-book/src/the-unstable-book.md | 1 + src/doc/unstable-book/src/thread-local.md | 1 + src/doc/unstable-book/src/trace-macros.md | 1 + src/doc/unstable-book/src/type-ascription.md | 1 + src/doc/unstable-book/src/unboxed-closures.md | 1 + src/doc/unstable-book/src/untagged-unions.md | 1 + src/doc/unstable-book/src/unwind-attributes.md | 1 + src/doc/unstable-book/src/use-extern-macros.md | 1 + src/doc/unstable-book/src/windows-subsystem.md | 1 + src/libsyntax/feature_gate.rs | 9 ++- 94 files changed, 198 insertions(+), 2 deletions(-) create mode 100644 src/doc/unstable-book/.gitignore create mode 100644 src/doc/unstable-book/src/SUMMARY.md create mode 100644 src/doc/unstable-book/src/abi-msp430-interrupt.md create mode 100644 src/doc/unstable-book/src/abi-ptx.md create mode 100644 src/doc/unstable-book/src/abi-sysv64.md create mode 100644 src/doc/unstable-book/src/abi-unadjusted.md create mode 100644 src/doc/unstable-book/src/abi-vectorcall.md create mode 100644 src/doc/unstable-book/src/advanced-slice-patterns.md create mode 100644 src/doc/unstable-book/src/allocator.md create mode 100644 src/doc/unstable-book/src/allow-internal-unstable.md create mode 100644 src/doc/unstable-book/src/asm.md create mode 100644 src/doc/unstable-book/src/associated-consts.md create mode 100644 src/doc/unstable-book/src/associated-type-defaults.md create mode 100644 src/doc/unstable-book/src/attr-literals.md create mode 100644 src/doc/unstable-book/src/box-patterns.md create mode 100644 src/doc/unstable-book/src/box-syntax.md create mode 100644 src/doc/unstable-book/src/cfg-target-feature.md create mode 100644 src/doc/unstable-book/src/cfg-target-has-atomic.md create mode 100644 src/doc/unstable-book/src/cfg-target-thread-local.md create mode 100644 src/doc/unstable-book/src/cfg-target-vendor.md create mode 100644 src/doc/unstable-book/src/compiler-builtins.md create mode 100644 src/doc/unstable-book/src/concat-idents.md create mode 100644 src/doc/unstable-book/src/conservative-impl-trait.md create mode 100644 src/doc/unstable-book/src/const-fn.md create mode 100644 src/doc/unstable-book/src/const-indexing.md create mode 100644 src/doc/unstable-book/src/custom-attribute.md create mode 100644 src/doc/unstable-book/src/custom-derive.md create mode 100644 src/doc/unstable-book/src/default-type-parameter-fallback.md create mode 100644 src/doc/unstable-book/src/drop-types-in-const.md create mode 100644 src/doc/unstable-book/src/dropck-eyepatch.md create mode 100644 src/doc/unstable-book/src/dropck-parametricity.md create mode 100644 src/doc/unstable-book/src/exclusive-range-pattern.md create mode 100644 src/doc/unstable-book/src/field-init-shorthand.md create mode 100644 src/doc/unstable-book/src/fundamental.md create mode 100644 src/doc/unstable-book/src/generic-param-attrs.md create mode 100644 src/doc/unstable-book/src/i128-type.md create mode 100644 src/doc/unstable-book/src/inclusive-range-syntax.md create mode 100644 src/doc/unstable-book/src/intrinsics.md create mode 100644 src/doc/unstable-book/src/lang-items.md create mode 100644 src/doc/unstable-book/src/link-args.md create mode 100644 src/doc/unstable-book/src/link-cfg.md create mode 100644 src/doc/unstable-book/src/link-llvm-intrinsics.md create mode 100644 src/doc/unstable-book/src/linkage.md create mode 100644 src/doc/unstable-book/src/log-syntax.md create mode 100644 src/doc/unstable-book/src/loop-break-value.md create mode 100644 src/doc/unstable-book/src/macro-reexport.md create mode 100644 src/doc/unstable-book/src/main.md create mode 100644 src/doc/unstable-book/src/naked-functions.md create mode 100644 src/doc/unstable-book/src/needs-allocator.md create mode 100644 src/doc/unstable-book/src/needs-panic-runtime.md create mode 100644 src/doc/unstable-book/src/never-type.md create mode 100644 src/doc/unstable-book/src/no-core.md create mode 100644 src/doc/unstable-book/src/no-debug.md create mode 100644 src/doc/unstable-book/src/non_ascii-idents.md create mode 100644 src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md create mode 100644 src/doc/unstable-book/src/on-unimplemented.md create mode 100644 src/doc/unstable-book/src/optin-builtin-traits.md create mode 100644 src/doc/unstable-book/src/panic-runtime.md create mode 100644 src/doc/unstable-book/src/placement-in-syntax.md create mode 100644 src/doc/unstable-book/src/platform-intrinsics.md create mode 100644 src/doc/unstable-book/src/plugin-registrar.md create mode 100644 src/doc/unstable-book/src/plugin.md create mode 100644 src/doc/unstable-book/src/prelude-import.md create mode 100644 src/doc/unstable-book/src/proc-macro.md create mode 100644 src/doc/unstable-book/src/pub-restricted.md create mode 100644 src/doc/unstable-book/src/quote.md create mode 100644 src/doc/unstable-book/src/relaxed-adts.md create mode 100644 src/doc/unstable-book/src/repr-simd.md create mode 100644 src/doc/unstable-book/src/rustc-attrs.md create mode 100644 src/doc/unstable-book/src/rustc-diagnostic-macros.md create mode 100644 src/doc/unstable-book/src/sanitizer-runtime.md create mode 100644 src/doc/unstable-book/src/simd-ffi.md create mode 100644 src/doc/unstable-book/src/simd.md create mode 100644 src/doc/unstable-book/src/slice-patterns.md create mode 100644 src/doc/unstable-book/src/specialization.md create mode 100644 src/doc/unstable-book/src/staged-api.md create mode 100644 src/doc/unstable-book/src/start.md create mode 100644 src/doc/unstable-book/src/static-nobundle.md create mode 100644 src/doc/unstable-book/src/static-recursion.md create mode 100644 src/doc/unstable-book/src/stmt-expr-attributes.md create mode 100644 src/doc/unstable-book/src/struct-field-attributes.md create mode 100644 src/doc/unstable-book/src/structural-match.md create mode 100644 src/doc/unstable-book/src/target-feature.md create mode 100644 src/doc/unstable-book/src/the-unstable-book.md create mode 100644 src/doc/unstable-book/src/thread-local.md create mode 100644 src/doc/unstable-book/src/trace-macros.md create mode 100644 src/doc/unstable-book/src/type-ascription.md create mode 100644 src/doc/unstable-book/src/unboxed-closures.md create mode 100644 src/doc/unstable-book/src/untagged-unions.md create mode 100644 src/doc/unstable-book/src/unwind-attributes.md create mode 100644 src/doc/unstable-book/src/use-extern-macros.md create mode 100644 src/doc/unstable-book/src/windows-subsystem.md diff --git a/src/bootstrap/step.rs b/src/bootstrap/step.rs index 36738b81c18..fe183c5bce8 100644 --- a/src/bootstrap/step.rs +++ b/src/bootstrap/step.rs @@ -577,6 +577,15 @@ pub fn build_rules<'a>(build: &'a Build) -> Rules { }) .default(build.config.docs) .run(move |s| doc::rustbook(build, s.target, "reference")); + rules.doc("doc-unstable-book", "src/doc/unstable-book") + .dep(move |s| { + s.name("tool-rustbook") + .host(&build.config.build) + .target(&build.config.build) + .stage(0) + }) + .default(build.config.docs) + .run(move |s| doc::rustbook(build, s.target, "unstable-book")); rules.doc("doc-standalone", "src/doc") .dep(move |s| { s.name("rustc") diff --git a/src/doc/unstable-book/.gitignore b/src/doc/unstable-book/.gitignore new file mode 100644 index 00000000000..7585238efed --- /dev/null +++ b/src/doc/unstable-book/.gitignore @@ -0,0 +1 @@ +book diff --git a/src/doc/unstable-book/src/SUMMARY.md b/src/doc/unstable-book/src/SUMMARY.md new file mode 100644 index 00000000000..98fbffcf84d --- /dev/null +++ b/src/doc/unstable-book/src/SUMMARY.md @@ -0,0 +1,91 @@ +[The Unstable Book](the-unstable-book.md) + +- [asm](asm.md) +- [concat_idents](concat-idents.md) +- [link_args](link-args.md) +- [log_syntax](log-syntax.md) +- [non_ascii_idents](non_ascii-idents.md) +- [plugin_registrar](plugin-registrar.md) +- [thread_local](thread-local.md) +- [trace_macros](trace-macros.md) +- [intrinsics](intrinsics.md) +- [lang_items](lang-items.md) +- [link_llvm_intrinsics](link-llvm-intrinsics.md) +- [linkage](linkage.md) +- [quote](quote.md) +- [simd](simd.md) +- [rustc_diagnostic_macros](rustc-diagnostic-macros.md) +- [advanced_slice_patterns](advanced-slice-patterns.md) +- [box_syntax](box-syntax.md) +- [placement_in_syntax](placement-in-syntax.md) +- [unboxed_closures](unboxed-closures.md) +- [allocator](allocator.md) +- [fundamental](fundamental.md) +- [main](main.md) +- [needs_allocator](needs-allocator.md) +- [on_unimplemented](on-unimplemented.md) +- [plugin](plugin.md) +- [simd_ffi](simd-ffi.md) +- [start](start.md) +- [structural_match](structural-match.md) +- [panic_runtime](panic-runtime.md) +- [needs_panic_runtime](needs-panic-runtime.md) +- [optin_builtin_traits](optin-builtin-traits.md) +- [macro_reexport](macro-reexport.md) +- [staged_api](staged-api.md) +- [no_core](no-core.md) +- [box_patterns](box-patterns.md) +- [dropck_parametricity](dropck-parametricity.md) +- [dropck_eyepatch](dropck-eyepatch.md) +- [custom_attribute](custom-attribute.md) +- [custom_derive](custom-derive.md) +- [rustc_attrs](rustc-attrs.md) +- [allow_internal_unstable](allow-internal-unstable.md) +- [slice_patterns](slice-patterns.md) +- [associated_consts](associated-consts.md) +- [const_fn](const-fn.md) +- [const_indexing](const-indexing.md) +- [prelude_import](prelude-import.md) +- [static_recursion](static-recursion.md) +- [default_type_parameter_fallback](default-type-parameter-fallback.md) +- [associated_type_defaults](associated-type-defaults.md) +- [repr_simd](repr-simd.md) +- [cfg_target_feature](cfg-target-feature.md) +- [platform_intrinsics](platform-intrinsics.md) +- [unwind_attributes](unwind-attributes.md) +- [naked_functions](naked-functions.md) +- [no_debug](no-debug.md) +- [omit_gdb_pretty_printer_section](omit-gdb-pretty-printer-section.md) +- [cfg_target_vendor](cfg-target-vendor.md) +- [stmt_expr_attributes](stmt-expr-attributes.md) +- [type_ascription](type-ascription.md) +- [cfg_target_thread_local](cfg-target-thread-local.md) +- [abi_vectorcall](abi-vectorcall.md) +- [inclusive_range_syntax](inclusive-range-syntax.md) +- [exclusive_range_pattern](exclusive-range-pattern.md) +- [specialization](specialization.md) +- [pub_restricted](pub-restricted.md) +- [drop_types_in_const](drop-types-in-const.md) +- [cfg_target_has_atomic](cfg-target-has-atomic.md) +- [conservative_impl_trait](conservative-impl-trait.md) +- [relaxed_adts](relaxed-adts.md) +- [never_type](never-type.md) +- [attr_literals](attr-literals.md) +- [abi_sysv64](abi-sysv64.md) +- [untagged_unions](untagged-unions.md) +- [compiler_builtins](compiler-builtins.md) +- [generic_param_attrs](generic-param-attrs.md) +- [field_init_shorthand](field-init-shorthand.md) +- [windows_subsystem](windows-subsystem.md) +- [link_cfg](link-cfg.md) +- [use_extern_macros](use-extern-macros.md) +- [loop_break_value](loop-break-value.md) +- [target_feature](target-feature.md) +- [abi_ptx](abi-ptx.md) +- [i128_type](i128-type.md) +- [abi_unadjusted](abi-unadjusted.md) +- [proc_macro](proc-macro.md) +- [struct_field_attributes](struct-field-attributes.md) +- [static_nobundle](static-nobundle.md) +- [abi_msp430_interrupt](abi-msp430-interrupt.md) +- [sanitizer_runtime](sanitizer-runtime.md) diff --git a/src/doc/unstable-book/src/abi-msp430-interrupt.md b/src/doc/unstable-book/src/abi-msp430-interrupt.md new file mode 100644 index 00000000000..ce5090829cb --- /dev/null +++ b/src/doc/unstable-book/src/abi-msp430-interrupt.md @@ -0,0 +1 @@ +# abi_msp430_interrupt diff --git a/src/doc/unstable-book/src/abi-ptx.md b/src/doc/unstable-book/src/abi-ptx.md new file mode 100644 index 00000000000..56ae04a23f7 --- /dev/null +++ b/src/doc/unstable-book/src/abi-ptx.md @@ -0,0 +1 @@ +# abi_ptx diff --git a/src/doc/unstable-book/src/abi-sysv64.md b/src/doc/unstable-book/src/abi-sysv64.md new file mode 100644 index 00000000000..be00f080fef --- /dev/null +++ b/src/doc/unstable-book/src/abi-sysv64.md @@ -0,0 +1 @@ +# abi_sysv64 diff --git a/src/doc/unstable-book/src/abi-unadjusted.md b/src/doc/unstable-book/src/abi-unadjusted.md new file mode 100644 index 00000000000..6db74ede168 --- /dev/null +++ b/src/doc/unstable-book/src/abi-unadjusted.md @@ -0,0 +1 @@ +# abi_unadjusted diff --git a/src/doc/unstable-book/src/abi-vectorcall.md b/src/doc/unstable-book/src/abi-vectorcall.md new file mode 100644 index 00000000000..98a919171f2 --- /dev/null +++ b/src/doc/unstable-book/src/abi-vectorcall.md @@ -0,0 +1 @@ +# abi_vectorcall diff --git a/src/doc/unstable-book/src/advanced-slice-patterns.md b/src/doc/unstable-book/src/advanced-slice-patterns.md new file mode 100644 index 00000000000..a9645725e76 --- /dev/null +++ b/src/doc/unstable-book/src/advanced-slice-patterns.md @@ -0,0 +1 @@ +# advanced_slice_patterns diff --git a/src/doc/unstable-book/src/allocator.md b/src/doc/unstable-book/src/allocator.md new file mode 100644 index 00000000000..f01c5bfb110 --- /dev/null +++ b/src/doc/unstable-book/src/allocator.md @@ -0,0 +1 @@ +# allocator diff --git a/src/doc/unstable-book/src/allow-internal-unstable.md b/src/doc/unstable-book/src/allow-internal-unstable.md new file mode 100644 index 00000000000..f79e31ff57f --- /dev/null +++ b/src/doc/unstable-book/src/allow-internal-unstable.md @@ -0,0 +1 @@ +# allow_internal_unstable diff --git a/src/doc/unstable-book/src/asm.md b/src/doc/unstable-book/src/asm.md new file mode 100644 index 00000000000..394345734ec --- /dev/null +++ b/src/doc/unstable-book/src/asm.md @@ -0,0 +1 @@ +# asm diff --git a/src/doc/unstable-book/src/associated-consts.md b/src/doc/unstable-book/src/associated-consts.md new file mode 100644 index 00000000000..70d01c05c86 --- /dev/null +++ b/src/doc/unstable-book/src/associated-consts.md @@ -0,0 +1 @@ +# associated_consts diff --git a/src/doc/unstable-book/src/associated-type-defaults.md b/src/doc/unstable-book/src/associated-type-defaults.md new file mode 100644 index 00000000000..a1ecb4d3207 --- /dev/null +++ b/src/doc/unstable-book/src/associated-type-defaults.md @@ -0,0 +1 @@ +# associated_type_defaults diff --git a/src/doc/unstable-book/src/attr-literals.md b/src/doc/unstable-book/src/attr-literals.md new file mode 100644 index 00000000000..6a04ee86d30 --- /dev/null +++ b/src/doc/unstable-book/src/attr-literals.md @@ -0,0 +1 @@ +# attr_literals diff --git a/src/doc/unstable-book/src/box-patterns.md b/src/doc/unstable-book/src/box-patterns.md new file mode 100644 index 00000000000..64d082229f4 --- /dev/null +++ b/src/doc/unstable-book/src/box-patterns.md @@ -0,0 +1 @@ +# box_patterns diff --git a/src/doc/unstable-book/src/box-syntax.md b/src/doc/unstable-book/src/box-syntax.md new file mode 100644 index 00000000000..a8c596c1090 --- /dev/null +++ b/src/doc/unstable-book/src/box-syntax.md @@ -0,0 +1 @@ +# box_syntax diff --git a/src/doc/unstable-book/src/cfg-target-feature.md b/src/doc/unstable-book/src/cfg-target-feature.md new file mode 100644 index 00000000000..c7f58a32cf2 --- /dev/null +++ b/src/doc/unstable-book/src/cfg-target-feature.md @@ -0,0 +1 @@ +# cfg_target_feature diff --git a/src/doc/unstable-book/src/cfg-target-has-atomic.md b/src/doc/unstable-book/src/cfg-target-has-atomic.md new file mode 100644 index 00000000000..c33e61817ec --- /dev/null +++ b/src/doc/unstable-book/src/cfg-target-has-atomic.md @@ -0,0 +1 @@ +# cfg_target_has_atomic diff --git a/src/doc/unstable-book/src/cfg-target-thread-local.md b/src/doc/unstable-book/src/cfg-target-thread-local.md new file mode 100644 index 00000000000..90f662f73f4 --- /dev/null +++ b/src/doc/unstable-book/src/cfg-target-thread-local.md @@ -0,0 +1 @@ +# cfg_target_thread_local diff --git a/src/doc/unstable-book/src/cfg-target-vendor.md b/src/doc/unstable-book/src/cfg-target-vendor.md new file mode 100644 index 00000000000..9f468d2cdc2 --- /dev/null +++ b/src/doc/unstable-book/src/cfg-target-vendor.md @@ -0,0 +1 @@ +# cfg_target_vendor diff --git a/src/doc/unstable-book/src/compiler-builtins.md b/src/doc/unstable-book/src/compiler-builtins.md new file mode 100644 index 00000000000..62ad0cdf807 --- /dev/null +++ b/src/doc/unstable-book/src/compiler-builtins.md @@ -0,0 +1 @@ +# compiler_builtins diff --git a/src/doc/unstable-book/src/concat-idents.md b/src/doc/unstable-book/src/concat-idents.md new file mode 100644 index 00000000000..081c32d7741 --- /dev/null +++ b/src/doc/unstable-book/src/concat-idents.md @@ -0,0 +1 @@ +# concat_idents diff --git a/src/doc/unstable-book/src/conservative-impl-trait.md b/src/doc/unstable-book/src/conservative-impl-trait.md new file mode 100644 index 00000000000..059006978a5 --- /dev/null +++ b/src/doc/unstable-book/src/conservative-impl-trait.md @@ -0,0 +1 @@ +# conservative_impl_trait diff --git a/src/doc/unstable-book/src/const-fn.md b/src/doc/unstable-book/src/const-fn.md new file mode 100644 index 00000000000..9c1a9025326 --- /dev/null +++ b/src/doc/unstable-book/src/const-fn.md @@ -0,0 +1 @@ +# const_fn diff --git a/src/doc/unstable-book/src/const-indexing.md b/src/doc/unstable-book/src/const-indexing.md new file mode 100644 index 00000000000..7490a40dc60 --- /dev/null +++ b/src/doc/unstable-book/src/const-indexing.md @@ -0,0 +1 @@ +# const_indexing diff --git a/src/doc/unstable-book/src/custom-attribute.md b/src/doc/unstable-book/src/custom-attribute.md new file mode 100644 index 00000000000..d1109bad1f4 --- /dev/null +++ b/src/doc/unstable-book/src/custom-attribute.md @@ -0,0 +1 @@ +# custom_attribute diff --git a/src/doc/unstable-book/src/custom-derive.md b/src/doc/unstable-book/src/custom-derive.md new file mode 100644 index 00000000000..36c3b8afe91 --- /dev/null +++ b/src/doc/unstable-book/src/custom-derive.md @@ -0,0 +1 @@ +# custom_derive diff --git a/src/doc/unstable-book/src/default-type-parameter-fallback.md b/src/doc/unstable-book/src/default-type-parameter-fallback.md new file mode 100644 index 00000000000..fa3a3ebbac2 --- /dev/null +++ b/src/doc/unstable-book/src/default-type-parameter-fallback.md @@ -0,0 +1 @@ +# default_type_parameter_fallback diff --git a/src/doc/unstable-book/src/drop-types-in-const.md b/src/doc/unstable-book/src/drop-types-in-const.md new file mode 100644 index 00000000000..bc05cca9c5e --- /dev/null +++ b/src/doc/unstable-book/src/drop-types-in-const.md @@ -0,0 +1 @@ +# drop_types_in_const diff --git a/src/doc/unstable-book/src/dropck-eyepatch.md b/src/doc/unstable-book/src/dropck-eyepatch.md new file mode 100644 index 00000000000..380718a940f --- /dev/null +++ b/src/doc/unstable-book/src/dropck-eyepatch.md @@ -0,0 +1 @@ +# dropck_eyepatch diff --git a/src/doc/unstable-book/src/dropck-parametricity.md b/src/doc/unstable-book/src/dropck-parametricity.md new file mode 100644 index 00000000000..bef2b344e0e --- /dev/null +++ b/src/doc/unstable-book/src/dropck-parametricity.md @@ -0,0 +1 @@ +# dropck_parametricity diff --git a/src/doc/unstable-book/src/exclusive-range-pattern.md b/src/doc/unstable-book/src/exclusive-range-pattern.md new file mode 100644 index 00000000000..b098501e33b --- /dev/null +++ b/src/doc/unstable-book/src/exclusive-range-pattern.md @@ -0,0 +1 @@ +# exclusive_range_pattern diff --git a/src/doc/unstable-book/src/field-init-shorthand.md b/src/doc/unstable-book/src/field-init-shorthand.md new file mode 100644 index 00000000000..12b3b5d3104 --- /dev/null +++ b/src/doc/unstable-book/src/field-init-shorthand.md @@ -0,0 +1 @@ +# field_init_shorthand diff --git a/src/doc/unstable-book/src/fundamental.md b/src/doc/unstable-book/src/fundamental.md new file mode 100644 index 00000000000..f27dcf97f3d --- /dev/null +++ b/src/doc/unstable-book/src/fundamental.md @@ -0,0 +1 @@ +# fundamental diff --git a/src/doc/unstable-book/src/generic-param-attrs.md b/src/doc/unstable-book/src/generic-param-attrs.md new file mode 100644 index 00000000000..c6081f3867e --- /dev/null +++ b/src/doc/unstable-book/src/generic-param-attrs.md @@ -0,0 +1 @@ +# generic_param_attrs diff --git a/src/doc/unstable-book/src/i128-type.md b/src/doc/unstable-book/src/i128-type.md new file mode 100644 index 00000000000..b4ed27e0d12 --- /dev/null +++ b/src/doc/unstable-book/src/i128-type.md @@ -0,0 +1 @@ +# i128_type diff --git a/src/doc/unstable-book/src/inclusive-range-syntax.md b/src/doc/unstable-book/src/inclusive-range-syntax.md new file mode 100644 index 00000000000..401ff66fdb8 --- /dev/null +++ b/src/doc/unstable-book/src/inclusive-range-syntax.md @@ -0,0 +1 @@ +# inclusive_range_syntax diff --git a/src/doc/unstable-book/src/intrinsics.md b/src/doc/unstable-book/src/intrinsics.md new file mode 100644 index 00000000000..8901490c7ad --- /dev/null +++ b/src/doc/unstable-book/src/intrinsics.md @@ -0,0 +1 @@ +# intrinsics diff --git a/src/doc/unstable-book/src/lang-items.md b/src/doc/unstable-book/src/lang-items.md new file mode 100644 index 00000000000..54aaff35841 --- /dev/null +++ b/src/doc/unstable-book/src/lang-items.md @@ -0,0 +1 @@ +# lang_items diff --git a/src/doc/unstable-book/src/link-args.md b/src/doc/unstable-book/src/link-args.md new file mode 100644 index 00000000000..17c66f61dd2 --- /dev/null +++ b/src/doc/unstable-book/src/link-args.md @@ -0,0 +1 @@ +# link_args diff --git a/src/doc/unstable-book/src/link-cfg.md b/src/doc/unstable-book/src/link-cfg.md new file mode 100644 index 00000000000..3ea16dd3a0b --- /dev/null +++ b/src/doc/unstable-book/src/link-cfg.md @@ -0,0 +1 @@ +# link_cfg diff --git a/src/doc/unstable-book/src/link-llvm-intrinsics.md b/src/doc/unstable-book/src/link-llvm-intrinsics.md new file mode 100644 index 00000000000..39224bc68a5 --- /dev/null +++ b/src/doc/unstable-book/src/link-llvm-intrinsics.md @@ -0,0 +1 @@ +# link_llvm_intrinsics diff --git a/src/doc/unstable-book/src/linkage.md b/src/doc/unstable-book/src/linkage.md new file mode 100644 index 00000000000..ff37c815fc5 --- /dev/null +++ b/src/doc/unstable-book/src/linkage.md @@ -0,0 +1 @@ +# linkage diff --git a/src/doc/unstable-book/src/log-syntax.md b/src/doc/unstable-book/src/log-syntax.md new file mode 100644 index 00000000000..7633fff5152 --- /dev/null +++ b/src/doc/unstable-book/src/log-syntax.md @@ -0,0 +1 @@ +# log_syntax diff --git a/src/doc/unstable-book/src/loop-break-value.md b/src/doc/unstable-book/src/loop-break-value.md new file mode 100644 index 00000000000..72ef138c791 --- /dev/null +++ b/src/doc/unstable-book/src/loop-break-value.md @@ -0,0 +1 @@ +# loop_break_value diff --git a/src/doc/unstable-book/src/macro-reexport.md b/src/doc/unstable-book/src/macro-reexport.md new file mode 100644 index 00000000000..2074dafa4e6 --- /dev/null +++ b/src/doc/unstable-book/src/macro-reexport.md @@ -0,0 +1 @@ +# macro_reexport diff --git a/src/doc/unstable-book/src/main.md b/src/doc/unstable-book/src/main.md new file mode 100644 index 00000000000..c693b5e4eb5 --- /dev/null +++ b/src/doc/unstable-book/src/main.md @@ -0,0 +1 @@ +# main diff --git a/src/doc/unstable-book/src/naked-functions.md b/src/doc/unstable-book/src/naked-functions.md new file mode 100644 index 00000000000..85af027cb7d --- /dev/null +++ b/src/doc/unstable-book/src/naked-functions.md @@ -0,0 +1 @@ +# naked_functions diff --git a/src/doc/unstable-book/src/needs-allocator.md b/src/doc/unstable-book/src/needs-allocator.md new file mode 100644 index 00000000000..5a620a885ec --- /dev/null +++ b/src/doc/unstable-book/src/needs-allocator.md @@ -0,0 +1 @@ +# needs_allocator diff --git a/src/doc/unstable-book/src/needs-panic-runtime.md b/src/doc/unstable-book/src/needs-panic-runtime.md new file mode 100644 index 00000000000..c3e91721360 --- /dev/null +++ b/src/doc/unstable-book/src/needs-panic-runtime.md @@ -0,0 +1 @@ +# needs_panic_runtime diff --git a/src/doc/unstable-book/src/never-type.md b/src/doc/unstable-book/src/never-type.md new file mode 100644 index 00000000000..c8e42b7c290 --- /dev/null +++ b/src/doc/unstable-book/src/never-type.md @@ -0,0 +1 @@ +# never_type diff --git a/src/doc/unstable-book/src/no-core.md b/src/doc/unstable-book/src/no-core.md new file mode 100644 index 00000000000..62f4f7cc969 --- /dev/null +++ b/src/doc/unstable-book/src/no-core.md @@ -0,0 +1 @@ +# no_core diff --git a/src/doc/unstable-book/src/no-debug.md b/src/doc/unstable-book/src/no-debug.md new file mode 100644 index 00000000000..041fe685057 --- /dev/null +++ b/src/doc/unstable-book/src/no-debug.md @@ -0,0 +1 @@ +# no_debug diff --git a/src/doc/unstable-book/src/non_ascii-idents.md b/src/doc/unstable-book/src/non_ascii-idents.md new file mode 100644 index 00000000000..2d244f06471 --- /dev/null +++ b/src/doc/unstable-book/src/non_ascii-idents.md @@ -0,0 +1 @@ +# non_ascii_idents diff --git a/src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md b/src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md new file mode 100644 index 00000000000..87ebf6affd7 --- /dev/null +++ b/src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md @@ -0,0 +1 @@ +# omit_gdb_pretty_printer_section diff --git a/src/doc/unstable-book/src/on-unimplemented.md b/src/doc/unstable-book/src/on-unimplemented.md new file mode 100644 index 00000000000..f7f624aef21 --- /dev/null +++ b/src/doc/unstable-book/src/on-unimplemented.md @@ -0,0 +1 @@ +# on_unimplemented diff --git a/src/doc/unstable-book/src/optin-builtin-traits.md b/src/doc/unstable-book/src/optin-builtin-traits.md new file mode 100644 index 00000000000..a3c3dcd709c --- /dev/null +++ b/src/doc/unstable-book/src/optin-builtin-traits.md @@ -0,0 +1 @@ +# optin_builtin_traits diff --git a/src/doc/unstable-book/src/panic-runtime.md b/src/doc/unstable-book/src/panic-runtime.md new file mode 100644 index 00000000000..20f436a7656 --- /dev/null +++ b/src/doc/unstable-book/src/panic-runtime.md @@ -0,0 +1 @@ +# panic_runtime diff --git a/src/doc/unstable-book/src/placement-in-syntax.md b/src/doc/unstable-book/src/placement-in-syntax.md new file mode 100644 index 00000000000..f41e3945bae --- /dev/null +++ b/src/doc/unstable-book/src/placement-in-syntax.md @@ -0,0 +1 @@ +# placement_in_syntax diff --git a/src/doc/unstable-book/src/platform-intrinsics.md b/src/doc/unstable-book/src/platform-intrinsics.md new file mode 100644 index 00000000000..14353b1a505 --- /dev/null +++ b/src/doc/unstable-book/src/platform-intrinsics.md @@ -0,0 +1 @@ +# platform_intrinsics diff --git a/src/doc/unstable-book/src/plugin-registrar.md b/src/doc/unstable-book/src/plugin-registrar.md new file mode 100644 index 00000000000..70892438475 --- /dev/null +++ b/src/doc/unstable-book/src/plugin-registrar.md @@ -0,0 +1 @@ +# plugin_registrar diff --git a/src/doc/unstable-book/src/plugin.md b/src/doc/unstable-book/src/plugin.md new file mode 100644 index 00000000000..e504fb84db1 --- /dev/null +++ b/src/doc/unstable-book/src/plugin.md @@ -0,0 +1 @@ +# plugin diff --git a/src/doc/unstable-book/src/prelude-import.md b/src/doc/unstable-book/src/prelude-import.md new file mode 100644 index 00000000000..72c9d7b5d0d --- /dev/null +++ b/src/doc/unstable-book/src/prelude-import.md @@ -0,0 +1 @@ +# prelude_import diff --git a/src/doc/unstable-book/src/proc-macro.md b/src/doc/unstable-book/src/proc-macro.md new file mode 100644 index 00000000000..d2bdb41b90e --- /dev/null +++ b/src/doc/unstable-book/src/proc-macro.md @@ -0,0 +1 @@ +# proc_macro diff --git a/src/doc/unstable-book/src/pub-restricted.md b/src/doc/unstable-book/src/pub-restricted.md new file mode 100644 index 00000000000..eee0696d6ea --- /dev/null +++ b/src/doc/unstable-book/src/pub-restricted.md @@ -0,0 +1 @@ +# pub_restricted diff --git a/src/doc/unstable-book/src/quote.md b/src/doc/unstable-book/src/quote.md new file mode 100644 index 00000000000..4c851b40b84 --- /dev/null +++ b/src/doc/unstable-book/src/quote.md @@ -0,0 +1 @@ +# quote diff --git a/src/doc/unstable-book/src/relaxed-adts.md b/src/doc/unstable-book/src/relaxed-adts.md new file mode 100644 index 00000000000..3fbbbe8728a --- /dev/null +++ b/src/doc/unstable-book/src/relaxed-adts.md @@ -0,0 +1 @@ +# relaxed_adts diff --git a/src/doc/unstable-book/src/repr-simd.md b/src/doc/unstable-book/src/repr-simd.md new file mode 100644 index 00000000000..c313fbf3649 --- /dev/null +++ b/src/doc/unstable-book/src/repr-simd.md @@ -0,0 +1 @@ +# repr_simd diff --git a/src/doc/unstable-book/src/rustc-attrs.md b/src/doc/unstable-book/src/rustc-attrs.md new file mode 100644 index 00000000000..e021588a717 --- /dev/null +++ b/src/doc/unstable-book/src/rustc-attrs.md @@ -0,0 +1 @@ +# rustc_attrs diff --git a/src/doc/unstable-book/src/rustc-diagnostic-macros.md b/src/doc/unstable-book/src/rustc-diagnostic-macros.md new file mode 100644 index 00000000000..d213cd86192 --- /dev/null +++ b/src/doc/unstable-book/src/rustc-diagnostic-macros.md @@ -0,0 +1 @@ +# rustc_diagnostic_macros diff --git a/src/doc/unstable-book/src/sanitizer-runtime.md b/src/doc/unstable-book/src/sanitizer-runtime.md new file mode 100644 index 00000000000..c0e78d47001 --- /dev/null +++ b/src/doc/unstable-book/src/sanitizer-runtime.md @@ -0,0 +1 @@ +# sanitizer_runtime diff --git a/src/doc/unstable-book/src/simd-ffi.md b/src/doc/unstable-book/src/simd-ffi.md new file mode 100644 index 00000000000..72b9c9f5e68 --- /dev/null +++ b/src/doc/unstable-book/src/simd-ffi.md @@ -0,0 +1 @@ +# simd_ffi diff --git a/src/doc/unstable-book/src/simd.md b/src/doc/unstable-book/src/simd.md new file mode 100644 index 00000000000..1053fb68710 --- /dev/null +++ b/src/doc/unstable-book/src/simd.md @@ -0,0 +1 @@ +# simd diff --git a/src/doc/unstable-book/src/slice-patterns.md b/src/doc/unstable-book/src/slice-patterns.md new file mode 100644 index 00000000000..6a3c9c91f2f --- /dev/null +++ b/src/doc/unstable-book/src/slice-patterns.md @@ -0,0 +1 @@ +# slice_patterns diff --git a/src/doc/unstable-book/src/specialization.md b/src/doc/unstable-book/src/specialization.md new file mode 100644 index 00000000000..3d15a9b650c --- /dev/null +++ b/src/doc/unstable-book/src/specialization.md @@ -0,0 +1 @@ +# specialization diff --git a/src/doc/unstable-book/src/staged-api.md b/src/doc/unstable-book/src/staged-api.md new file mode 100644 index 00000000000..e5ee5216d0d --- /dev/null +++ b/src/doc/unstable-book/src/staged-api.md @@ -0,0 +1 @@ +# staged_api diff --git a/src/doc/unstable-book/src/start.md b/src/doc/unstable-book/src/start.md new file mode 100644 index 00000000000..7513c0aece3 --- /dev/null +++ b/src/doc/unstable-book/src/start.md @@ -0,0 +1 @@ +# start diff --git a/src/doc/unstable-book/src/static-nobundle.md b/src/doc/unstable-book/src/static-nobundle.md new file mode 100644 index 00000000000..138f53e6af9 --- /dev/null +++ b/src/doc/unstable-book/src/static-nobundle.md @@ -0,0 +1 @@ +# static_nobundle diff --git a/src/doc/unstable-book/src/static-recursion.md b/src/doc/unstable-book/src/static-recursion.md new file mode 100644 index 00000000000..07309eb4fb8 --- /dev/null +++ b/src/doc/unstable-book/src/static-recursion.md @@ -0,0 +1 @@ +# static_recursion diff --git a/src/doc/unstable-book/src/stmt-expr-attributes.md b/src/doc/unstable-book/src/stmt-expr-attributes.md new file mode 100644 index 00000000000..033c324af3d --- /dev/null +++ b/src/doc/unstable-book/src/stmt-expr-attributes.md @@ -0,0 +1 @@ +# stmt_expr_attributes diff --git a/src/doc/unstable-book/src/struct-field-attributes.md b/src/doc/unstable-book/src/struct-field-attributes.md new file mode 100644 index 00000000000..9aa5ac35f8e --- /dev/null +++ b/src/doc/unstable-book/src/struct-field-attributes.md @@ -0,0 +1 @@ +# struct_field_attributes diff --git a/src/doc/unstable-book/src/structural-match.md b/src/doc/unstable-book/src/structural-match.md new file mode 100644 index 00000000000..af6e0efdb41 --- /dev/null +++ b/src/doc/unstable-book/src/structural-match.md @@ -0,0 +1 @@ +# structural_match diff --git a/src/doc/unstable-book/src/target-feature.md b/src/doc/unstable-book/src/target-feature.md new file mode 100644 index 00000000000..b2188ea11b1 --- /dev/null +++ b/src/doc/unstable-book/src/target-feature.md @@ -0,0 +1 @@ +# target_feature diff --git a/src/doc/unstable-book/src/the-unstable-book.md b/src/doc/unstable-book/src/the-unstable-book.md new file mode 100644 index 00000000000..92ccbcae920 --- /dev/null +++ b/src/doc/unstable-book/src/the-unstable-book.md @@ -0,0 +1 @@ +# The Unstable Book diff --git a/src/doc/unstable-book/src/thread-local.md b/src/doc/unstable-book/src/thread-local.md new file mode 100644 index 00000000000..acfc7b21af5 --- /dev/null +++ b/src/doc/unstable-book/src/thread-local.md @@ -0,0 +1 @@ +# thread_local diff --git a/src/doc/unstable-book/src/trace-macros.md b/src/doc/unstable-book/src/trace-macros.md new file mode 100644 index 00000000000..daaac68bab3 --- /dev/null +++ b/src/doc/unstable-book/src/trace-macros.md @@ -0,0 +1 @@ +# trace_macros diff --git a/src/doc/unstable-book/src/type-ascription.md b/src/doc/unstable-book/src/type-ascription.md new file mode 100644 index 00000000000..9b7c80c5b92 --- /dev/null +++ b/src/doc/unstable-book/src/type-ascription.md @@ -0,0 +1 @@ +# type_ascription diff --git a/src/doc/unstable-book/src/unboxed-closures.md b/src/doc/unstable-book/src/unboxed-closures.md new file mode 100644 index 00000000000..af14ea15db4 --- /dev/null +++ b/src/doc/unstable-book/src/unboxed-closures.md @@ -0,0 +1 @@ +# unboxed_closures diff --git a/src/doc/unstable-book/src/untagged-unions.md b/src/doc/unstable-book/src/untagged-unions.md new file mode 100644 index 00000000000..b50331aa93d --- /dev/null +++ b/src/doc/unstable-book/src/untagged-unions.md @@ -0,0 +1 @@ +# untagged_unions diff --git a/src/doc/unstable-book/src/unwind-attributes.md b/src/doc/unstable-book/src/unwind-attributes.md new file mode 100644 index 00000000000..3f5dfa43bbb --- /dev/null +++ b/src/doc/unstable-book/src/unwind-attributes.md @@ -0,0 +1 @@ +# unwind_attributes diff --git a/src/doc/unstable-book/src/use-extern-macros.md b/src/doc/unstable-book/src/use-extern-macros.md new file mode 100644 index 00000000000..1d880435f4e --- /dev/null +++ b/src/doc/unstable-book/src/use-extern-macros.md @@ -0,0 +1 @@ +# use_extern_macros diff --git a/src/doc/unstable-book/src/windows-subsystem.md b/src/doc/unstable-book/src/windows-subsystem.md new file mode 100644 index 00000000000..a549acac675 --- /dev/null +++ b/src/doc/unstable-book/src/windows-subsystem.md @@ -0,0 +1 @@ +# windows_subsystem diff --git a/src/libsyntax/feature_gate.rs b/src/libsyntax/feature_gate.rs index 1bed3e27847..b7be084fa0b 100644 --- a/src/libsyntax/feature_gate.rs +++ b/src/libsyntax/feature_gate.rs @@ -91,11 +91,14 @@ macro_rules! declare_features { } } -// If you change this list without updating src/doc/reference.md, @cmr will be sad +// If you change this, please modify src/doc/unstable-book as well. +// // Don't ever remove anything from this list; set them to 'Removed'. +// // The version numbers here correspond to the version in which the current status // was set. This is most important for knowing when a particular feature became // stable (active). +// // NB: The featureck.py script parses this information directly out of the source // so take care when modifying it. @@ -385,7 +388,9 @@ declare_features! ( // Allows field shorthands (`x` meaning `x: x`) in struct literal expressions. (accepted, field_init_shorthand, "1.17.0", Some(37340)), ); -// (changing above list without updating src/doc/reference.md makes @cmr sad) +// If you change this, please modify src/doc/unstable-book as well. You must +// move that documentation into the relevant place in the other docs, and +// remove the chapter on the flag. #[derive(PartialEq, Copy, Clone, Debug)] pub enum AttributeType { -- cgit 1.4.1-3-g733a5 From f16c48e713b321c76b58a225a69c248fe3baee05 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 15 Feb 2017 18:27:16 -0500 Subject: Import basic book contents --- src/doc/unstable-book/src/SUMMARY.md | 2 +- src/doc/unstable-book/src/abi-msp430-interrupt.md | 6 +++++- src/doc/unstable-book/src/abi-ptx.md | 5 ++++- src/doc/unstable-book/src/abi-sysv64.md | 9 ++++++++- src/doc/unstable-book/src/abi-unadjusted.md | 5 ++++- src/doc/unstable-book/src/abi-vectorcall.md | 6 +++++- src/doc/unstable-book/src/advanced-slice-patterns.md | 9 ++++++++- src/doc/unstable-book/src/allocator.md | 9 ++++++++- src/doc/unstable-book/src/allow-internal-unstable.md | 5 ++++- src/doc/unstable-book/src/asm.md | 9 ++++++++- src/doc/unstable-book/src/associated-consts.md | 9 ++++++++- src/doc/unstable-book/src/associated-type-defaults.md | 9 ++++++++- src/doc/unstable-book/src/attr-literals.md | 9 ++++++++- src/doc/unstable-book/src/box-patterns.md | 9 ++++++++- src/doc/unstable-book/src/box-syntax.md | 9 ++++++++- src/doc/unstable-book/src/cfg-target-feature.md | 9 ++++++++- src/doc/unstable-book/src/cfg-target-has-atomic.md | 9 ++++++++- src/doc/unstable-book/src/cfg-target-thread-local.md | 9 ++++++++- src/doc/unstable-book/src/cfg-target-vendor.md | 9 ++++++++- src/doc/unstable-book/src/compiler-builtins.md | 5 ++++- src/doc/unstable-book/src/concat-idents.md | 9 ++++++++- src/doc/unstable-book/src/conservative-impl-trait.md | 9 ++++++++- src/doc/unstable-book/src/const-fn.md | 9 ++++++++- src/doc/unstable-book/src/const-indexing.md | 9 ++++++++- src/doc/unstable-book/src/custom-attribute.md | 9 ++++++++- src/doc/unstable-book/src/custom-derive.md | 9 ++++++++- src/doc/unstable-book/src/default-type-parameter-fallback.md | 9 ++++++++- src/doc/unstable-book/src/drop-types-in-const.md | 9 ++++++++- src/doc/unstable-book/src/dropck-eyepatch.md | 9 ++++++++- src/doc/unstable-book/src/dropck-parametricity.md | 9 ++++++++- src/doc/unstable-book/src/exclusive-range-pattern.md | 9 ++++++++- src/doc/unstable-book/src/field-init-shorthand.md | 9 ++++++++- src/doc/unstable-book/src/fundamental.md | 9 ++++++++- src/doc/unstable-book/src/generic-param-attrs.md | 9 ++++++++- src/doc/unstable-book/src/i128-type.md | 9 ++++++++- src/doc/unstable-book/src/inclusive-range-syntax.md | 9 ++++++++- src/doc/unstable-book/src/intrinsics.md | 4 +++- src/doc/unstable-book/src/lang-items.md | 5 ++++- src/doc/unstable-book/src/link-args.md | 9 ++++++++- src/doc/unstable-book/src/link-cfg.md | 9 ++++++++- src/doc/unstable-book/src/link-llvm-intrinsics.md | 9 ++++++++- src/doc/unstable-book/src/linkage.md | 9 ++++++++- src/doc/unstable-book/src/log-syntax.md | 9 ++++++++- src/doc/unstable-book/src/loop-break-value.md | 9 ++++++++- src/doc/unstable-book/src/macro-reexport.md | 9 ++++++++- src/doc/unstable-book/src/main.md | 9 ++++++++- src/doc/unstable-book/src/naked-functions.md | 9 ++++++++- src/doc/unstable-book/src/needs-allocator.md | 9 ++++++++- src/doc/unstable-book/src/needs-panic-runtime.md | 9 ++++++++- src/doc/unstable-book/src/never-type.md | 9 ++++++++- src/doc/unstable-book/src/no-core.md | 9 ++++++++- src/doc/unstable-book/src/no-debug.md | 9 ++++++++- src/doc/unstable-book/src/non-ascii-idents.md | 8 ++++++++ src/doc/unstable-book/src/non_ascii-idents.md | 1 - src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md | 5 ++++- src/doc/unstable-book/src/on-unimplemented.md | 9 ++++++++- src/doc/unstable-book/src/optin-builtin-traits.md | 9 ++++++++- src/doc/unstable-book/src/panic-runtime.md | 9 ++++++++- src/doc/unstable-book/src/placement-in-syntax.md | 9 ++++++++- src/doc/unstable-book/src/platform-intrinsics.md | 9 ++++++++- src/doc/unstable-book/src/plugin-registrar.md | 9 ++++++++- src/doc/unstable-book/src/plugin.md | 9 ++++++++- src/doc/unstable-book/src/prelude-import.md | 5 ++++- src/doc/unstable-book/src/proc-macro.md | 9 ++++++++- src/doc/unstable-book/src/pub-restricted.md | 9 ++++++++- src/doc/unstable-book/src/quote.md | 9 ++++++++- src/doc/unstable-book/src/relaxed-adts.md | 9 ++++++++- src/doc/unstable-book/src/repr-simd.md | 9 ++++++++- src/doc/unstable-book/src/rustc-attrs.md | 9 ++++++++- src/doc/unstable-book/src/rustc-diagnostic-macros.md | 5 ++++- src/doc/unstable-book/src/sanitizer-runtime.md | 5 ++++- src/doc/unstable-book/src/simd-ffi.md | 9 ++++++++- src/doc/unstable-book/src/simd.md | 9 ++++++++- src/doc/unstable-book/src/slice-patterns.md | 9 ++++++++- src/doc/unstable-book/src/specialization.md | 9 ++++++++- src/doc/unstable-book/src/staged-api.md | 5 ++++- src/doc/unstable-book/src/start.md | 9 ++++++++- src/doc/unstable-book/src/static-nobundle.md | 9 ++++++++- src/doc/unstable-book/src/static-recursion.md | 9 ++++++++- src/doc/unstable-book/src/stmt-expr-attributes.md | 9 ++++++++- src/doc/unstable-book/src/struct-field-attributes.md | 9 ++++++++- src/doc/unstable-book/src/structural-match.md | 9 ++++++++- src/doc/unstable-book/src/target-feature.md | 5 ++++- src/doc/unstable-book/src/the-unstable-book.md | 1 + src/doc/unstable-book/src/thread-local.md | 9 ++++++++- src/doc/unstable-book/src/trace-macros.md | 9 ++++++++- src/doc/unstable-book/src/type-ascription.md | 9 ++++++++- src/doc/unstable-book/src/unboxed-closures.md | 9 ++++++++- src/doc/unstable-book/src/untagged-unions.md | 9 ++++++++- src/doc/unstable-book/src/unwind-attributes.md | 5 ++++- src/doc/unstable-book/src/use-extern-macros.md | 9 ++++++++- src/doc/unstable-book/src/windows-subsystem.md | 9 ++++++++- 92 files changed, 655 insertions(+), 90 deletions(-) create mode 100644 src/doc/unstable-book/src/non-ascii-idents.md delete mode 100644 src/doc/unstable-book/src/non_ascii-idents.md diff --git a/src/doc/unstable-book/src/SUMMARY.md b/src/doc/unstable-book/src/SUMMARY.md index 98fbffcf84d..b0bd28828fa 100644 --- a/src/doc/unstable-book/src/SUMMARY.md +++ b/src/doc/unstable-book/src/SUMMARY.md @@ -4,7 +4,7 @@ - [concat_idents](concat-idents.md) - [link_args](link-args.md) - [log_syntax](log-syntax.md) -- [non_ascii_idents](non_ascii-idents.md) +- [non_ascii_idents](non-ascii-idents.md) - [plugin_registrar](plugin-registrar.md) - [thread_local](thread-local.md) - [trace_macros](trace-macros.md) diff --git a/src/doc/unstable-book/src/abi-msp430-interrupt.md b/src/doc/unstable-book/src/abi-msp430-interrupt.md index ce5090829cb..4d925e73686 100644 --- a/src/doc/unstable-book/src/abi-msp430-interrupt.md +++ b/src/doc/unstable-book/src/abi-msp430-interrupt.md @@ -1 +1,5 @@ -# abi_msp430_interrupt +# `abi_msp430_interrupt` + +The tracking issue for this feature is: [#38487] + +[#38487]: https://github.com/rust-lang/rust/issues/38487 diff --git a/src/doc/unstable-book/src/abi-ptx.md b/src/doc/unstable-book/src/abi-ptx.md index 56ae04a23f7..6695cb0f33c 100644 --- a/src/doc/unstable-book/src/abi-ptx.md +++ b/src/doc/unstable-book/src/abi-ptx.md @@ -1 +1,4 @@ -# abi_ptx +# `abi_ptx` + +The tracking issue for this feature is: None. + diff --git a/src/doc/unstable-book/src/abi-sysv64.md b/src/doc/unstable-book/src/abi-sysv64.md index be00f080fef..2415c8b8d19 100644 --- a/src/doc/unstable-book/src/abi-sysv64.md +++ b/src/doc/unstable-book/src/abi-sysv64.md @@ -1 +1,8 @@ -# abi_sysv64 +# `abi_sysv64` + +The tracking issue for this feature is: [#36167] + +[#36167]: https://github.com/rust-lang/rust/issues/36167 + + + diff --git a/src/doc/unstable-book/src/abi-unadjusted.md b/src/doc/unstable-book/src/abi-unadjusted.md index 6db74ede168..2a941d95632 100644 --- a/src/doc/unstable-book/src/abi-unadjusted.md +++ b/src/doc/unstable-book/src/abi-unadjusted.md @@ -1 +1,4 @@ -# abi_unadjusted +# `abi_unadjusted` + +The tracking issue for this feature is: none. + diff --git a/src/doc/unstable-book/src/abi-vectorcall.md b/src/doc/unstable-book/src/abi-vectorcall.md index 98a919171f2..da9d830c4dc 100644 --- a/src/doc/unstable-book/src/abi-vectorcall.md +++ b/src/doc/unstable-book/src/abi-vectorcall.md @@ -1 +1,5 @@ -# abi_vectorcall +# `abi_vectorcall` + +The tracking issue for this feature is: none. + + diff --git a/src/doc/unstable-book/src/advanced-slice-patterns.md b/src/doc/unstable-book/src/advanced-slice-patterns.md index a9645725e76..b0eee4bc0b8 100644 --- a/src/doc/unstable-book/src/advanced-slice-patterns.md +++ b/src/doc/unstable-book/src/advanced-slice-patterns.md @@ -1 +1,8 @@ -# advanced_slice_patterns +# `advanced_slice_patterns` + +The tracking issue for this feature is: [#23121] + +[#23121]: https://github.com/rust-lang/rust/issues/23121 + + + diff --git a/src/doc/unstable-book/src/allocator.md b/src/doc/unstable-book/src/allocator.md index f01c5bfb110..777efa217d1 100644 --- a/src/doc/unstable-book/src/allocator.md +++ b/src/doc/unstable-book/src/allocator.md @@ -1 +1,8 @@ -# allocator +# `allocator` + +The tracking issue for this feature is: [#27389] + +[#27389]: https://github.com/rust-lang/rust/issues/27389 + + + diff --git a/src/doc/unstable-book/src/allow-internal-unstable.md b/src/doc/unstable-book/src/allow-internal-unstable.md index f79e31ff57f..fe88dfb3f01 100644 --- a/src/doc/unstable-book/src/allow-internal-unstable.md +++ b/src/doc/unstable-book/src/allow-internal-unstable.md @@ -1 +1,4 @@ -# allow_internal_unstable +# `allow_internal_unstable` + +The tracking issue for this feature is: None. + diff --git a/src/doc/unstable-book/src/asm.md b/src/doc/unstable-book/src/asm.md index 394345734ec..d3939b701d2 100644 --- a/src/doc/unstable-book/src/asm.md +++ b/src/doc/unstable-book/src/asm.md @@ -1 +1,8 @@ -# asm +# `asm` + +The tracking issue for this feature is: [#29722] + +[#29722]: https://github.com/rust-lang/rust/issues/29722 + + + diff --git a/src/doc/unstable-book/src/associated-consts.md b/src/doc/unstable-book/src/associated-consts.md index 70d01c05c86..fbd4585cc7d 100644 --- a/src/doc/unstable-book/src/associated-consts.md +++ b/src/doc/unstable-book/src/associated-consts.md @@ -1 +1,8 @@ -# associated_consts +# `associated_consts` + +The tracking issue for this feature is: [#29646] + +[#29646]: https://github.com/rust-lang/rust/issues/29646 + + + diff --git a/src/doc/unstable-book/src/associated-type-defaults.md b/src/doc/unstable-book/src/associated-type-defaults.md index a1ecb4d3207..6a44da41e5f 100644 --- a/src/doc/unstable-book/src/associated-type-defaults.md +++ b/src/doc/unstable-book/src/associated-type-defaults.md @@ -1 +1,8 @@ -# associated_type_defaults +# `associated_type_defaults` + +The tracking issue for this feature is: [#29661] + +[#29661]: https://github.com/rust-lang/rust/issues/29661 + + + diff --git a/src/doc/unstable-book/src/attr-literals.md b/src/doc/unstable-book/src/attr-literals.md index 6a04ee86d30..013191ce017 100644 --- a/src/doc/unstable-book/src/attr-literals.md +++ b/src/doc/unstable-book/src/attr-literals.md @@ -1 +1,8 @@ -# attr_literals +# `attr_literals` + +The tracking issue for this feature is: [#34981] + +[#34981]: https://github.com/rust-lang/rust/issues/34981 + + + diff --git a/src/doc/unstable-book/src/box-patterns.md b/src/doc/unstable-book/src/box-patterns.md index 64d082229f4..27c434f7d27 100644 --- a/src/doc/unstable-book/src/box-patterns.md +++ b/src/doc/unstable-book/src/box-patterns.md @@ -1 +1,8 @@ -# box_patterns +# `box_patterns` + +The tracking issue for this feature is: [#29641] + +[#29641]: https://github.com/rust-lang/rust/issues/29641 + + + diff --git a/src/doc/unstable-book/src/box-syntax.md b/src/doc/unstable-book/src/box-syntax.md index a8c596c1090..881d0140473 100644 --- a/src/doc/unstable-book/src/box-syntax.md +++ b/src/doc/unstable-book/src/box-syntax.md @@ -1 +1,8 @@ -# box_syntax +# `box_syntax` + +The tracking issue for this feature is: [#27779] + +[#27779]: https://github.com/rust-lang/rust/issues/27779 + + + diff --git a/src/doc/unstable-book/src/cfg-target-feature.md b/src/doc/unstable-book/src/cfg-target-feature.md index c7f58a32cf2..930104acc12 100644 --- a/src/doc/unstable-book/src/cfg-target-feature.md +++ b/src/doc/unstable-book/src/cfg-target-feature.md @@ -1 +1,8 @@ -# cfg_target_feature +# `cfg_target_feature` + +The tracking issue for this feature is: [#29717] + +[#29717]: https://github.com/rust-lang/rust/issues/29717 + + + diff --git a/src/doc/unstable-book/src/cfg-target-has-atomic.md b/src/doc/unstable-book/src/cfg-target-has-atomic.md index c33e61817ec..36a0ab0aef7 100644 --- a/src/doc/unstable-book/src/cfg-target-has-atomic.md +++ b/src/doc/unstable-book/src/cfg-target-has-atomic.md @@ -1 +1,8 @@ -# cfg_target_has_atomic +# `cfg_target_has_atomic` + +The tracking issue for this feature is: [#32976] + +[#32976]: https://github.com/rust-lang/rust/issues/32976 + + + diff --git a/src/doc/unstable-book/src/cfg-target-thread-local.md b/src/doc/unstable-book/src/cfg-target-thread-local.md index 90f662f73f4..7f139a733cc 100644 --- a/src/doc/unstable-book/src/cfg-target-thread-local.md +++ b/src/doc/unstable-book/src/cfg-target-thread-local.md @@ -1 +1,8 @@ -# cfg_target_thread_local +# `cfg_target_thread_local` + +The tracking issue for this feature is: [#29594] + +[#29594]: https://github.com/rust-lang/rust/issues/29594 + + + diff --git a/src/doc/unstable-book/src/cfg-target-vendor.md b/src/doc/unstable-book/src/cfg-target-vendor.md index 9f468d2cdc2..930104acc12 100644 --- a/src/doc/unstable-book/src/cfg-target-vendor.md +++ b/src/doc/unstable-book/src/cfg-target-vendor.md @@ -1 +1,8 @@ -# cfg_target_vendor +# `cfg_target_feature` + +The tracking issue for this feature is: [#29717] + +[#29717]: https://github.com/rust-lang/rust/issues/29717 + + + diff --git a/src/doc/unstable-book/src/compiler-builtins.md b/src/doc/unstable-book/src/compiler-builtins.md index 62ad0cdf807..886bd31a0e3 100644 --- a/src/doc/unstable-book/src/compiler-builtins.md +++ b/src/doc/unstable-book/src/compiler-builtins.md @@ -1 +1,4 @@ -# compiler_builtins +# `compiler_builtins` + +The tracking issue for this feature is: None. + diff --git a/src/doc/unstable-book/src/concat-idents.md b/src/doc/unstable-book/src/concat-idents.md index 081c32d7741..e8edc12d663 100644 --- a/src/doc/unstable-book/src/concat-idents.md +++ b/src/doc/unstable-book/src/concat-idents.md @@ -1 +1,8 @@ -# concat_idents +# `concat_idents` + +The tracking issue for this feature is: [#29599] + +[#29599]: https://github.com/rust-lang/rust/issues/29599 + + + diff --git a/src/doc/unstable-book/src/conservative-impl-trait.md b/src/doc/unstable-book/src/conservative-impl-trait.md index 059006978a5..91221aa45b7 100644 --- a/src/doc/unstable-book/src/conservative-impl-trait.md +++ b/src/doc/unstable-book/src/conservative-impl-trait.md @@ -1 +1,8 @@ -# conservative_impl_trait +# `conservative_impl_trait` + +The tracking issue for this feature is: [#34511] + +[#34511]: https://github.com/rust-lang/rust/issues/34511 + + + diff --git a/src/doc/unstable-book/src/const-fn.md b/src/doc/unstable-book/src/const-fn.md index 9c1a9025326..4bd0933f7be 100644 --- a/src/doc/unstable-book/src/const-fn.md +++ b/src/doc/unstable-book/src/const-fn.md @@ -1 +1,8 @@ -# const_fn +# `const_fn` + +The tracking issue for this feature is: [#24111] + +[#24111]: https://github.com/rust-lang/rust/issues/24111 + + + diff --git a/src/doc/unstable-book/src/const-indexing.md b/src/doc/unstable-book/src/const-indexing.md index 7490a40dc60..30e093befd0 100644 --- a/src/doc/unstable-book/src/const-indexing.md +++ b/src/doc/unstable-book/src/const-indexing.md @@ -1 +1,8 @@ -# const_indexing +# `const_indexing` + +The tracking issue for this feature is: [#29947] + +[#29947]: https://github.com/rust-lang/rust/issues/29947 + + + diff --git a/src/doc/unstable-book/src/custom-attribute.md b/src/doc/unstable-book/src/custom-attribute.md index d1109bad1f4..0080bb79a9e 100644 --- a/src/doc/unstable-book/src/custom-attribute.md +++ b/src/doc/unstable-book/src/custom-attribute.md @@ -1 +1,8 @@ -# custom_attribute +# `custom_attribute` + +The tracking issue for this feature is: [#29642] + +[#29642]: https://github.com/rust-lang/rust/issues/29642 + + + diff --git a/src/doc/unstable-book/src/custom-derive.md b/src/doc/unstable-book/src/custom-derive.md index 36c3b8afe91..999cb7bf521 100644 --- a/src/doc/unstable-book/src/custom-derive.md +++ b/src/doc/unstable-book/src/custom-derive.md @@ -1 +1,8 @@ -# custom_derive +# `custom_derive` + +The tracking issue for this feature is: [#29644] + +[#29644]: https://github.com/rust-lang/rust/issues/29644 + + + diff --git a/src/doc/unstable-book/src/default-type-parameter-fallback.md b/src/doc/unstable-book/src/default-type-parameter-fallback.md index fa3a3ebbac2..373d18b7ffb 100644 --- a/src/doc/unstable-book/src/default-type-parameter-fallback.md +++ b/src/doc/unstable-book/src/default-type-parameter-fallback.md @@ -1 +1,8 @@ -# default_type_parameter_fallback +# `default_type_parameter_fallback` + +The tracking issue for this feature is: [#27336] + +[#27336]: https://github.com/rust-lang/rust/issues/27336 + + + diff --git a/src/doc/unstable-book/src/drop-types-in-const.md b/src/doc/unstable-book/src/drop-types-in-const.md index bc05cca9c5e..4b535dfc1da 100644 --- a/src/doc/unstable-book/src/drop-types-in-const.md +++ b/src/doc/unstable-book/src/drop-types-in-const.md @@ -1 +1,8 @@ -# drop_types_in_const +# `drop_types_in_const` + +The tracking issue for this feature is: [#33156] + +[#33156]: https://github.com/rust-lang/rust/issues/33156 + + + diff --git a/src/doc/unstable-book/src/dropck-eyepatch.md b/src/doc/unstable-book/src/dropck-eyepatch.md index 380718a940f..2f1e5936c06 100644 --- a/src/doc/unstable-book/src/dropck-eyepatch.md +++ b/src/doc/unstable-book/src/dropck-eyepatch.md @@ -1 +1,8 @@ -# dropck_eyepatch +# `dropck_eyepatch` + +The tracking issue for this feature is: [#34761] + +[#34761]: https://github.com/rust-lang/rust/issues/34761 + + + diff --git a/src/doc/unstable-book/src/dropck-parametricity.md b/src/doc/unstable-book/src/dropck-parametricity.md index bef2b344e0e..c00cd4c5cf6 100644 --- a/src/doc/unstable-book/src/dropck-parametricity.md +++ b/src/doc/unstable-book/src/dropck-parametricity.md @@ -1 +1,8 @@ -# dropck_parametricity +# `dropck_parametricity` + +The tracking issue for this feature is: [#28498] + +[#28498]: https://github.com/rust-lang/rust/issues/28498 + + + diff --git a/src/doc/unstable-book/src/exclusive-range-pattern.md b/src/doc/unstable-book/src/exclusive-range-pattern.md index b098501e33b..05b8db99bb7 100644 --- a/src/doc/unstable-book/src/exclusive-range-pattern.md +++ b/src/doc/unstable-book/src/exclusive-range-pattern.md @@ -1 +1,8 @@ -# exclusive_range_pattern +# `exclusive_range_pattern` + +The tracking issue for this feature is: [#37854] + +[#37854]: https://github.com/rust-lang/rust/issues/37854 + + + diff --git a/src/doc/unstable-book/src/field-init-shorthand.md b/src/doc/unstable-book/src/field-init-shorthand.md index 12b3b5d3104..20b3d17b085 100644 --- a/src/doc/unstable-book/src/field-init-shorthand.md +++ b/src/doc/unstable-book/src/field-init-shorthand.md @@ -1 +1,8 @@ -# field_init_shorthand +# `field_init_shorthand` + +The tracking issue for this feature is: [#37340] + +[#37340]: https://github.com/rust-lang/rust/issues/37340 + + + diff --git a/src/doc/unstable-book/src/fundamental.md b/src/doc/unstable-book/src/fundamental.md index f27dcf97f3d..2ab978cb648 100644 --- a/src/doc/unstable-book/src/fundamental.md +++ b/src/doc/unstable-book/src/fundamental.md @@ -1 +1,8 @@ -# fundamental +# `fundamental` + +The tracking issue for this feature is: [#29635] + +[#29635]: https://github.com/rust-lang/rust/issues/29635 + + + diff --git a/src/doc/unstable-book/src/generic-param-attrs.md b/src/doc/unstable-book/src/generic-param-attrs.md index c6081f3867e..7c75231a655 100644 --- a/src/doc/unstable-book/src/generic-param-attrs.md +++ b/src/doc/unstable-book/src/generic-param-attrs.md @@ -1 +1,8 @@ -# generic_param_attrs +# `generic_param_attrs` + +The tracking issue for this feature is: [#34761] + +[#34761]: https://github.com/rust-lang/rust/issues/34761 + + + diff --git a/src/doc/unstable-book/src/i128-type.md b/src/doc/unstable-book/src/i128-type.md index b4ed27e0d12..f3f32176546 100644 --- a/src/doc/unstable-book/src/i128-type.md +++ b/src/doc/unstable-book/src/i128-type.md @@ -1 +1,8 @@ -# i128_type +# `i128_type` + +The tracking issue for this feature is: [#35118] + +[#35118]: https://github.com/rust-lang/rust/issues/35118 + + + diff --git a/src/doc/unstable-book/src/inclusive-range-syntax.md b/src/doc/unstable-book/src/inclusive-range-syntax.md index 401ff66fdb8..f7f29f474ae 100644 --- a/src/doc/unstable-book/src/inclusive-range-syntax.md +++ b/src/doc/unstable-book/src/inclusive-range-syntax.md @@ -1 +1,8 @@ -# inclusive_range_syntax +# `inclusive_range_syntax` + +The tracking issue for this feature is: [#28237] + +[#28237]: https://github.com/rust-lang/rust/issues/28237 + + + diff --git a/src/doc/unstable-book/src/intrinsics.md b/src/doc/unstable-book/src/intrinsics.md index 8901490c7ad..65331da8567 100644 --- a/src/doc/unstable-book/src/intrinsics.md +++ b/src/doc/unstable-book/src/intrinsics.md @@ -1 +1,3 @@ -# intrinsics +# `intrinsics` + +The tracking issue for this feature is: None. diff --git a/src/doc/unstable-book/src/lang-items.md b/src/doc/unstable-book/src/lang-items.md index 54aaff35841..de8ff6b076b 100644 --- a/src/doc/unstable-book/src/lang-items.md +++ b/src/doc/unstable-book/src/lang-items.md @@ -1 +1,4 @@ -# lang_items +# `lang_items` + +The tracking issue for this feature is: None. + diff --git a/src/doc/unstable-book/src/link-args.md b/src/doc/unstable-book/src/link-args.md index 17c66f61dd2..a887242f1aa 100644 --- a/src/doc/unstable-book/src/link-args.md +++ b/src/doc/unstable-book/src/link-args.md @@ -1 +1,8 @@ -# link_args +# `link_args` + +The tracking issue for this feature is: [#29596] + +[#29596]: https://github.com/rust-lang/rust/issues/29596 + + + diff --git a/src/doc/unstable-book/src/link-cfg.md b/src/doc/unstable-book/src/link-cfg.md index 3ea16dd3a0b..4d6dd259efe 100644 --- a/src/doc/unstable-book/src/link-cfg.md +++ b/src/doc/unstable-book/src/link-cfg.md @@ -1 +1,8 @@ -# link_cfg +# `link_cfg` + +The tracking issue for this feature is: [#37406] + +[#37406]: https://github.com/rust-lang/rust/issues/37406 + + + diff --git a/src/doc/unstable-book/src/link-llvm-intrinsics.md b/src/doc/unstable-book/src/link-llvm-intrinsics.md index 39224bc68a5..aee4e0a40d5 100644 --- a/src/doc/unstable-book/src/link-llvm-intrinsics.md +++ b/src/doc/unstable-book/src/link-llvm-intrinsics.md @@ -1 +1,8 @@ -# link_llvm_intrinsics +# `link_llvm_intrinsics` + +The tracking issue for this feature is: [#29602] + +[#29602]: https://github.com/rust-lang/rust/issues/29602 + + + diff --git a/src/doc/unstable-book/src/linkage.md b/src/doc/unstable-book/src/linkage.md index ff37c815fc5..3deac364d75 100644 --- a/src/doc/unstable-book/src/linkage.md +++ b/src/doc/unstable-book/src/linkage.md @@ -1 +1,8 @@ -# linkage +# `linkage` + +The tracking issue for this feature is: [#29603] + +[#29603]: https://github.com/rust-lang/rust/issues/29603 + + + diff --git a/src/doc/unstable-book/src/log-syntax.md b/src/doc/unstable-book/src/log-syntax.md index 7633fff5152..f61bb49b78c 100644 --- a/src/doc/unstable-book/src/log-syntax.md +++ b/src/doc/unstable-book/src/log-syntax.md @@ -1 +1,8 @@ -# log_syntax +# `log_syntax` + +The tracking issue for this feature is: [#29598] + +[#29598]: https://github.com/rust-lang/rust/issues/29598 + + + diff --git a/src/doc/unstable-book/src/loop-break-value.md b/src/doc/unstable-book/src/loop-break-value.md index 72ef138c791..16c0618cbe0 100644 --- a/src/doc/unstable-book/src/loop-break-value.md +++ b/src/doc/unstable-book/src/loop-break-value.md @@ -1 +1,8 @@ -# loop_break_value +# `loop_break_value` + +The tracking issue for this feature is: [#37339] + +[#37339]: https://github.com/rust-lang/rust/issues/37339 + + + diff --git a/src/doc/unstable-book/src/macro-reexport.md b/src/doc/unstable-book/src/macro-reexport.md index 2074dafa4e6..0ba5a56fc47 100644 --- a/src/doc/unstable-book/src/macro-reexport.md +++ b/src/doc/unstable-book/src/macro-reexport.md @@ -1 +1,8 @@ -# macro_reexport +# `macro_reexport` + +The tracking issue for this feature is: [#29638] + +[#29638]: https://github.com/rust-lang/rust/issues/29638 + + + diff --git a/src/doc/unstable-book/src/main.md b/src/doc/unstable-book/src/main.md index c693b5e4eb5..795db9bd1ab 100644 --- a/src/doc/unstable-book/src/main.md +++ b/src/doc/unstable-book/src/main.md @@ -1 +1,8 @@ -# main +# `main` + +The tracking issue for this feature is: [#29634] + +[#29634]: https://github.com/rust-lang/rust/issues/29634 + + + diff --git a/src/doc/unstable-book/src/naked-functions.md b/src/doc/unstable-book/src/naked-functions.md index 85af027cb7d..896a83237a5 100644 --- a/src/doc/unstable-book/src/naked-functions.md +++ b/src/doc/unstable-book/src/naked-functions.md @@ -1 +1,8 @@ -# naked_functions +# `naked_functions` + +The tracking issue for this feature is: [#32408] + +[#32408]: https://github.com/rust-lang/rust/issues/32408 + + + diff --git a/src/doc/unstable-book/src/needs-allocator.md b/src/doc/unstable-book/src/needs-allocator.md index 5a620a885ec..14fb4b3782f 100644 --- a/src/doc/unstable-book/src/needs-allocator.md +++ b/src/doc/unstable-book/src/needs-allocator.md @@ -1 +1,8 @@ -# needs_allocator +# `needs_allocator` + +The tracking issue for this feature is: [#27389] + +[#27389]: https://github.com/rust-lang/rust/issues/27389 + + + diff --git a/src/doc/unstable-book/src/needs-panic-runtime.md b/src/doc/unstable-book/src/needs-panic-runtime.md index c3e91721360..ecaeaaab047 100644 --- a/src/doc/unstable-book/src/needs-panic-runtime.md +++ b/src/doc/unstable-book/src/needs-panic-runtime.md @@ -1 +1,8 @@ -# needs_panic_runtime +# `needs_panic_runtime` + +The tracking issue for this feature is: [#32837] + +[#32837]: https://github.com/rust-lang/rust/issues/32837 + + + diff --git a/src/doc/unstable-book/src/never-type.md b/src/doc/unstable-book/src/never-type.md index c8e42b7c290..26db551e850 100644 --- a/src/doc/unstable-book/src/never-type.md +++ b/src/doc/unstable-book/src/never-type.md @@ -1 +1,8 @@ -# never_type +# `never_type` + +The tracking issue for this feature is: [#35121] + +[#35121]: https://github.com/rust-lang/rust/issues/35121 + + + diff --git a/src/doc/unstable-book/src/no-core.md b/src/doc/unstable-book/src/no-core.md index 62f4f7cc969..363d0f37d98 100644 --- a/src/doc/unstable-book/src/no-core.md +++ b/src/doc/unstable-book/src/no-core.md @@ -1 +1,8 @@ -# no_core +# `no_core` + +The tracking issue for this feature is: [#29639] + +[#29639]: https://github.com/rust-lang/rust/issues/29639 + + + diff --git a/src/doc/unstable-book/src/no-debug.md b/src/doc/unstable-book/src/no-debug.md index 041fe685057..5fcf7e142cf 100644 --- a/src/doc/unstable-book/src/no-debug.md +++ b/src/doc/unstable-book/src/no-debug.md @@ -1 +1,8 @@ -# no_debug +# `no_debug` + +The tracking issue for this feature is: [#29721] + +[#29721]: https://github.com/rust-lang/rust/issues/29721 + + + diff --git a/src/doc/unstable-book/src/non-ascii-idents.md b/src/doc/unstable-book/src/non-ascii-idents.md new file mode 100644 index 00000000000..9bd2609aaf7 --- /dev/null +++ b/src/doc/unstable-book/src/non-ascii-idents.md @@ -0,0 +1,8 @@ +# `non_ascii_idents` + +The tracking issue for this feature is: [#28979] + +[#28979]: https://github.com/rust-lang/rust/issues/28979 + + + diff --git a/src/doc/unstable-book/src/non_ascii-idents.md b/src/doc/unstable-book/src/non_ascii-idents.md deleted file mode 100644 index 2d244f06471..00000000000 --- a/src/doc/unstable-book/src/non_ascii-idents.md +++ /dev/null @@ -1 +0,0 @@ -# non_ascii_idents diff --git a/src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md b/src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md index 87ebf6affd7..baa5024357d 100644 --- a/src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md +++ b/src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md @@ -1 +1,4 @@ -# omit_gdb_pretty_printer_section +# `omit_gdb_pretty_printer_section` + +The tracking issue for this feature is: None. + diff --git a/src/doc/unstable-book/src/on-unimplemented.md b/src/doc/unstable-book/src/on-unimplemented.md index f7f624aef21..6b4a4268195 100644 --- a/src/doc/unstable-book/src/on-unimplemented.md +++ b/src/doc/unstable-book/src/on-unimplemented.md @@ -1 +1,8 @@ -# on_unimplemented +# `on_unimplemented` + +The tracking issue for this feature is: [#29628] + +[#29628]: https://github.com/rust-lang/rust/issues/29628 + + + diff --git a/src/doc/unstable-book/src/optin-builtin-traits.md b/src/doc/unstable-book/src/optin-builtin-traits.md index a3c3dcd709c..06d0e553b8b 100644 --- a/src/doc/unstable-book/src/optin-builtin-traits.md +++ b/src/doc/unstable-book/src/optin-builtin-traits.md @@ -1 +1,8 @@ -# optin_builtin_traits +# `optin_builtin_traits` + +The tracking issue for this feature is: [#13231] + +[#13231]: https://github.com/rust-lang/rust/issues/13231 + + + diff --git a/src/doc/unstable-book/src/panic-runtime.md b/src/doc/unstable-book/src/panic-runtime.md index 20f436a7656..1d4cca0bc2f 100644 --- a/src/doc/unstable-book/src/panic-runtime.md +++ b/src/doc/unstable-book/src/panic-runtime.md @@ -1 +1,8 @@ -# panic_runtime +# `panic_runtime` + +The tracking issue for this feature is: [#32837] + +[#32837]: https://github.com/rust-lang/rust/issues/32837 + + + diff --git a/src/doc/unstable-book/src/placement-in-syntax.md b/src/doc/unstable-book/src/placement-in-syntax.md index f41e3945bae..92a56810e22 100644 --- a/src/doc/unstable-book/src/placement-in-syntax.md +++ b/src/doc/unstable-book/src/placement-in-syntax.md @@ -1 +1,8 @@ -# placement_in_syntax +# `placement_in_syntax` + +The tracking issue for this feature is: [#27779] + +[#27779]: https://github.com/rust-lang/rust/issues/27779 + + + diff --git a/src/doc/unstable-book/src/platform-intrinsics.md b/src/doc/unstable-book/src/platform-intrinsics.md index 14353b1a505..e895e0af5c4 100644 --- a/src/doc/unstable-book/src/platform-intrinsics.md +++ b/src/doc/unstable-book/src/platform-intrinsics.md @@ -1 +1,8 @@ -# platform_intrinsics +# `platform_intrinsics` + +The tracking issue for this feature is: [#27731] + +[#27731]: https://github.com/rust-lang/rust/issues/27731 + + + diff --git a/src/doc/unstable-book/src/plugin-registrar.md b/src/doc/unstable-book/src/plugin-registrar.md index 70892438475..024690e87a1 100644 --- a/src/doc/unstable-book/src/plugin-registrar.md +++ b/src/doc/unstable-book/src/plugin-registrar.md @@ -1 +1,8 @@ -# plugin_registrar +# `plugin_registrar` + +The tracking issue for this feature is: [#29597] + +[#29597]: https://github.com/rust-lang/rust/issues/29597 + + + diff --git a/src/doc/unstable-book/src/plugin.md b/src/doc/unstable-book/src/plugin.md index e504fb84db1..f676e9d98c3 100644 --- a/src/doc/unstable-book/src/plugin.md +++ b/src/doc/unstable-book/src/plugin.md @@ -1 +1,8 @@ -# plugin +# `plugin` + +The tracking issue for this feature is: [#29597] + +[#29597]: https://github.com/rust-lang/rust/issues/29597 + + + diff --git a/src/doc/unstable-book/src/prelude-import.md b/src/doc/unstable-book/src/prelude-import.md index 72c9d7b5d0d..6bb093bfbc7 100644 --- a/src/doc/unstable-book/src/prelude-import.md +++ b/src/doc/unstable-book/src/prelude-import.md @@ -1 +1,4 @@ -# prelude_import +# `prelude_import` + +The tracking issue for this feature is: None. + diff --git a/src/doc/unstable-book/src/proc-macro.md b/src/doc/unstable-book/src/proc-macro.md index d2bdb41b90e..845a61eb22e 100644 --- a/src/doc/unstable-book/src/proc-macro.md +++ b/src/doc/unstable-book/src/proc-macro.md @@ -1 +1,8 @@ -# proc_macro +# `proc_macro` + +The tracking issue for this feature is: [#38356] + +[#38356]: https://github.com/rust-lang/rust/issues/38356 + + + diff --git a/src/doc/unstable-book/src/pub-restricted.md b/src/doc/unstable-book/src/pub-restricted.md index eee0696d6ea..c15e5d5fdaf 100644 --- a/src/doc/unstable-book/src/pub-restricted.md +++ b/src/doc/unstable-book/src/pub-restricted.md @@ -1 +1,8 @@ -# pub_restricted +# `pub_restricted` + +The tracking issue for this feature is: [#32409] + +[#32409]: https://github.com/rust-lang/rust/issues/32409 + + + diff --git a/src/doc/unstable-book/src/quote.md b/src/doc/unstable-book/src/quote.md index 4c851b40b84..a596cc9add7 100644 --- a/src/doc/unstable-book/src/quote.md +++ b/src/doc/unstable-book/src/quote.md @@ -1 +1,8 @@ -# quote +# `quote` + +The tracking issue for this feature is: [#29601] + +[#29601]: https://github.com/rust-lang/rust/issues/29601 + + + diff --git a/src/doc/unstable-book/src/relaxed-adts.md b/src/doc/unstable-book/src/relaxed-adts.md index 3fbbbe8728a..274ea08f37a 100644 --- a/src/doc/unstable-book/src/relaxed-adts.md +++ b/src/doc/unstable-book/src/relaxed-adts.md @@ -1 +1,8 @@ -# relaxed_adts +# `relaxed_adts` + +The tracking issue for this feature is: [#35626] + +[#35626]: https://github.com/rust-lang/rust/issues/35626 + + + diff --git a/src/doc/unstable-book/src/repr-simd.md b/src/doc/unstable-book/src/repr-simd.md index c313fbf3649..cfb3c151098 100644 --- a/src/doc/unstable-book/src/repr-simd.md +++ b/src/doc/unstable-book/src/repr-simd.md @@ -1 +1,8 @@ -# repr_simd +# `repr_simd` + +The tracking issue for this feature is: [#27731] + +[#27731]: https://github.com/rust-lang/rust/issues/27731 + + + diff --git a/src/doc/unstable-book/src/rustc-attrs.md b/src/doc/unstable-book/src/rustc-attrs.md index e021588a717..f42d2dcf312 100644 --- a/src/doc/unstable-book/src/rustc-attrs.md +++ b/src/doc/unstable-book/src/rustc-attrs.md @@ -1 +1,8 @@ -# rustc_attrs +# `rustc_attrs` + +The tracking issue for this feature is: [#29642] + +[#29642]: https://github.com/rust-lang/rust/issues/29642 + + + diff --git a/src/doc/unstable-book/src/rustc-diagnostic-macros.md b/src/doc/unstable-book/src/rustc-diagnostic-macros.md index d213cd86192..f48200abd76 100644 --- a/src/doc/unstable-book/src/rustc-diagnostic-macros.md +++ b/src/doc/unstable-book/src/rustc-diagnostic-macros.md @@ -1 +1,4 @@ -# rustc_diagnostic_macros +# `rustc_diagnostic_macros` + +The tracking issue for this feature is: None. + diff --git a/src/doc/unstable-book/src/sanitizer-runtime.md b/src/doc/unstable-book/src/sanitizer-runtime.md index c0e78d47001..a22ed342e20 100644 --- a/src/doc/unstable-book/src/sanitizer-runtime.md +++ b/src/doc/unstable-book/src/sanitizer-runtime.md @@ -1 +1,4 @@ -# sanitizer_runtime +# `sanitizer_runtime` + +The tracking issue for this feature is: None. + diff --git a/src/doc/unstable-book/src/simd-ffi.md b/src/doc/unstable-book/src/simd-ffi.md index 72b9c9f5e68..1519def25c8 100644 --- a/src/doc/unstable-book/src/simd-ffi.md +++ b/src/doc/unstable-book/src/simd-ffi.md @@ -1 +1,8 @@ -# simd_ffi +# `simd_ffi` + +The tracking issue for this feature is: [#27731] + +[#27731]: https://github.com/rust-lang/rust/issues/27731 + + + diff --git a/src/doc/unstable-book/src/simd.md b/src/doc/unstable-book/src/simd.md index 1053fb68710..56b1d3630c7 100644 --- a/src/doc/unstable-book/src/simd.md +++ b/src/doc/unstable-book/src/simd.md @@ -1 +1,8 @@ -# simd +# `simd` + +The tracking issue for this feature is: [#27731] + +[#27731]: https://github.com/rust-lang/rust/issues/27731 + + + diff --git a/src/doc/unstable-book/src/slice-patterns.md b/src/doc/unstable-book/src/slice-patterns.md index 6a3c9c91f2f..e075d0b5eed 100644 --- a/src/doc/unstable-book/src/slice-patterns.md +++ b/src/doc/unstable-book/src/slice-patterns.md @@ -1 +1,8 @@ -# slice_patterns +# `slice_patterns` + +The tracking issue for this feature is: [#23121] + +[#23121]: https://github.com/rust-lang/rust/issues/23121 + + + diff --git a/src/doc/unstable-book/src/specialization.md b/src/doc/unstable-book/src/specialization.md index 3d15a9b650c..37b0d36f7b8 100644 --- a/src/doc/unstable-book/src/specialization.md +++ b/src/doc/unstable-book/src/specialization.md @@ -1 +1,8 @@ -# specialization +# `specialization` + +The tracking issue for this feature is: [#31844] + +[#31844]: https://github.com/rust-lang/rust/issues/31844 + + + diff --git a/src/doc/unstable-book/src/staged-api.md b/src/doc/unstable-book/src/staged-api.md index e5ee5216d0d..c0406a27325 100644 --- a/src/doc/unstable-book/src/staged-api.md +++ b/src/doc/unstable-book/src/staged-api.md @@ -1 +1,4 @@ -# staged_api +# `staged_api` + +The tracking issue for this feature is: None. + diff --git a/src/doc/unstable-book/src/start.md b/src/doc/unstable-book/src/start.md index 7513c0aece3..4f11cf5cae0 100644 --- a/src/doc/unstable-book/src/start.md +++ b/src/doc/unstable-book/src/start.md @@ -1 +1,8 @@ -# start +# `start` + +The tracking issue for this feature is: [#29633] + +[#29633]: https://github.com/rust-lang/rust/issues/29633 + + + diff --git a/src/doc/unstable-book/src/static-nobundle.md b/src/doc/unstable-book/src/static-nobundle.md index 138f53e6af9..9ba4bdee08c 100644 --- a/src/doc/unstable-book/src/static-nobundle.md +++ b/src/doc/unstable-book/src/static-nobundle.md @@ -1 +1,8 @@ -# static_nobundle +# `static_nobundle` + +The tracking issue for this feature is: [#37403] + +[#37403]: https://github.com/rust-lang/rust/issues/37403 + + + diff --git a/src/doc/unstable-book/src/static-recursion.md b/src/doc/unstable-book/src/static-recursion.md index 07309eb4fb8..cc539a9d280 100644 --- a/src/doc/unstable-book/src/static-recursion.md +++ b/src/doc/unstable-book/src/static-recursion.md @@ -1 +1,8 @@ -# static_recursion +# `static_recursion` + +The tracking issue for this feature is: [#29719] + +[#29719]: https://github.com/rust-lang/rust/issues/29719 + + + diff --git a/src/doc/unstable-book/src/stmt-expr-attributes.md b/src/doc/unstable-book/src/stmt-expr-attributes.md index 033c324af3d..66b1af8f16c 100644 --- a/src/doc/unstable-book/src/stmt-expr-attributes.md +++ b/src/doc/unstable-book/src/stmt-expr-attributes.md @@ -1 +1,8 @@ -# stmt_expr_attributes +# `stmt_expr_attributes` + +The tracking issue for this feature is: [#15701] + +[#15701]: https://github.com/rust-lang/rust/issues/15701 + + + diff --git a/src/doc/unstable-book/src/struct-field-attributes.md b/src/doc/unstable-book/src/struct-field-attributes.md index 9aa5ac35f8e..f0f5ecdf04f 100644 --- a/src/doc/unstable-book/src/struct-field-attributes.md +++ b/src/doc/unstable-book/src/struct-field-attributes.md @@ -1 +1,8 @@ -# struct_field_attributes +# `struct_field_attributes` + +The tracking issue for this feature is: [#38814] + +[#38814]: https://github.com/rust-lang/rust/issues/38814 + + + diff --git a/src/doc/unstable-book/src/structural-match.md b/src/doc/unstable-book/src/structural-match.md index af6e0efdb41..6f23278ef27 100644 --- a/src/doc/unstable-book/src/structural-match.md +++ b/src/doc/unstable-book/src/structural-match.md @@ -1 +1,8 @@ -# structural_match +# `structural_match` + +The tracking issue for this feature is: [#31434] + +[#31434]: https://github.com/rust-lang/rust/issues/31434 + + + diff --git a/src/doc/unstable-book/src/target-feature.md b/src/doc/unstable-book/src/target-feature.md index b2188ea11b1..5702bf0e90b 100644 --- a/src/doc/unstable-book/src/target-feature.md +++ b/src/doc/unstable-book/src/target-feature.md @@ -1 +1,4 @@ -# target_feature +# `target_feature` + +The tracking issue for this feature is: None. + diff --git a/src/doc/unstable-book/src/the-unstable-book.md b/src/doc/unstable-book/src/the-unstable-book.md index 92ccbcae920..022f57b7ee5 100644 --- a/src/doc/unstable-book/src/the-unstable-book.md +++ b/src/doc/unstable-book/src/the-unstable-book.md @@ -1 +1,2 @@ # The Unstable Book + diff --git a/src/doc/unstable-book/src/thread-local.md b/src/doc/unstable-book/src/thread-local.md index acfc7b21af5..5109aa0c59c 100644 --- a/src/doc/unstable-book/src/thread-local.md +++ b/src/doc/unstable-book/src/thread-local.md @@ -1 +1,8 @@ -# thread_local +# `thread_local` + +The tracking issue for this feature is: [#29594] + +[#29594]: https://github.com/rust-lang/rust/issues/29594 + + + diff --git a/src/doc/unstable-book/src/trace-macros.md b/src/doc/unstable-book/src/trace-macros.md index daaac68bab3..84efabd8502 100644 --- a/src/doc/unstable-book/src/trace-macros.md +++ b/src/doc/unstable-book/src/trace-macros.md @@ -1 +1,8 @@ -# trace_macros +# `trace_macros` + +The tracking issue for this feature is: [#29598] + +[#29598]: https://github.com/rust-lang/rust/issues/29598 + + + diff --git a/src/doc/unstable-book/src/type-ascription.md b/src/doc/unstable-book/src/type-ascription.md index 9b7c80c5b92..2decf512e91 100644 --- a/src/doc/unstable-book/src/type-ascription.md +++ b/src/doc/unstable-book/src/type-ascription.md @@ -1 +1,8 @@ -# type_ascription +# `type_ascription` + +The tracking issue for this feature is: [#23416] + +[#23416]: https://github.com/rust-lang/rust/issues/23416 + + + diff --git a/src/doc/unstable-book/src/unboxed-closures.md b/src/doc/unstable-book/src/unboxed-closures.md index af14ea15db4..0d1eafb9e1d 100644 --- a/src/doc/unstable-book/src/unboxed-closures.md +++ b/src/doc/unstable-book/src/unboxed-closures.md @@ -1 +1,8 @@ -# unboxed_closures +# `unboxed_closures` + +The tracking issue for this feature is: [#29625] + +[#29625]: https://github.com/rust-lang/rust/issues/29625 + + + diff --git a/src/doc/unstable-book/src/untagged-unions.md b/src/doc/unstable-book/src/untagged-unions.md index b50331aa93d..748f49eec6a 100644 --- a/src/doc/unstable-book/src/untagged-unions.md +++ b/src/doc/unstable-book/src/untagged-unions.md @@ -1 +1,8 @@ -# untagged_unions +# `untagged_unions` + +The tracking issue for this feature is: [#32836] + +[#32836]: https://github.com/rust-lang/rust/issues/32836 + + + diff --git a/src/doc/unstable-book/src/unwind-attributes.md b/src/doc/unstable-book/src/unwind-attributes.md index 3f5dfa43bbb..5ba39afbcf8 100644 --- a/src/doc/unstable-book/src/unwind-attributes.md +++ b/src/doc/unstable-book/src/unwind-attributes.md @@ -1 +1,4 @@ -# unwind_attributes +# `unwind_attributes` + +The tracking issue for this feature is: None. + diff --git a/src/doc/unstable-book/src/use-extern-macros.md b/src/doc/unstable-book/src/use-extern-macros.md index 1d880435f4e..120e00b2551 100644 --- a/src/doc/unstable-book/src/use-extern-macros.md +++ b/src/doc/unstable-book/src/use-extern-macros.md @@ -1 +1,8 @@ -# use_extern_macros +# `use_extern_macros` + +The tracking issue for this feature is: [#35896] + +[#35896]: https://github.com/rust-lang/rust/issues/35896 + + + diff --git a/src/doc/unstable-book/src/windows-subsystem.md b/src/doc/unstable-book/src/windows-subsystem.md index a549acac675..78b040c0f26 100644 --- a/src/doc/unstable-book/src/windows-subsystem.md +++ b/src/doc/unstable-book/src/windows-subsystem.md @@ -1 +1,8 @@ -# windows_subsystem +# `windows_subsystem` + +The tracking issue for this feature is: [#37499] + +[#37499]: https://github.com/rust-lang/rust/issues/37499 + + + -- cgit 1.4.1-3-g733a5 From aba4bf60f5129af31ef7271e3499dadaadd2071d Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 15 Feb 2017 18:32:49 -0500 Subject: write intro --- src/doc/unstable-book/src/the-unstable-book.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/src/doc/unstable-book/src/the-unstable-book.md b/src/doc/unstable-book/src/the-unstable-book.md index 022f57b7ee5..dfbfe4cab97 100644 --- a/src/doc/unstable-book/src/the-unstable-book.md +++ b/src/doc/unstable-book/src/the-unstable-book.md @@ -1,2 +1,22 @@ # The Unstable Book +Welcome to the Unstable Book! This book consists of a number of chapters, +each one organized by a "feature flag." That is, when using an unstable +feature of Rust, you must use a flag, like this: + +```rust +#![feature(box_syntax)] + +fn main() { + let five = box 5; +} +``` + +The `box_syntax` feature [has a chapter][box] describing how to use it. + +[box]: box-syntax.html + +Because this documentation relates to unstable features, we make no guarantees +that what is contained here is accurate or up to date. It's developed on a +best-effort basis. Each page will have a link to its tracking issue with the +latest developments; you might want to check those as well. -- cgit 1.4.1-3-g733a5 From 6fb2545f77b722a8cde5cb87b289cd8b87643a7a Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 15 Feb 2017 20:27:58 -0500 Subject: TRPL Nightly -> Unstable Book Port the chapters from TRPL's "Nightly Rust" section to the Unstable Book, and remove it from TRPL. --- src/doc/book/src/SUMMARY.md | 12 - src/doc/book/src/advanced-linking.md | 145 ------------ src/doc/book/src/associated-constants.md | 79 ------- src/doc/book/src/benchmark-tests.md | 152 ------------ src/doc/book/src/box-syntax-and-patterns.md | 100 -------- src/doc/book/src/custom-allocators.md | 171 -------------- src/doc/book/src/inline-assembly.md | 184 --------------- src/doc/book/src/intrinsics.md | 25 -- src/doc/book/src/lang-items.md | 84 ------- src/doc/book/src/nightly-rust.md | 100 -------- src/doc/book/src/no-stdlib.md | 145 ------------ src/doc/book/src/slice-patterns.md | 42 ---- src/doc/unstable-book/src/SUMMARY.md | 3 + src/doc/unstable-book/src/abi-msp430-interrupt.md | 2 + src/doc/unstable-book/src/abi-ptx.md | 1 + src/doc/unstable-book/src/abi-sysv64.md | 3 +- src/doc/unstable-book/src/abi-unadjusted.md | 2 + src/doc/unstable-book/src/abi-vectorcall.md | 2 + .../unstable-book/src/advanced-slice-patterns.md | 27 +++ src/doc/unstable-book/src/alloc-jemalloc.md | 62 +++++ src/doc/unstable-book/src/alloc-system.md | 62 +++++ src/doc/unstable-book/src/allocator.md | 106 +++++++++ .../unstable-book/src/allow-internal-unstable.md | 2 + src/doc/unstable-book/src/asm.md | 183 +++++++++++++++ src/doc/unstable-book/src/associated-consts.md | 77 +++++++ .../unstable-book/src/associated-type-defaults.md | 2 + src/doc/unstable-book/src/attr-literals.md | 2 + src/doc/unstable-book/src/box-patterns.md | 24 ++ src/doc/unstable-book/src/box-syntax.md | 14 ++ src/doc/unstable-book/src/cfg-target-feature.md | 2 + src/doc/unstable-book/src/cfg-target-has-atomic.md | 2 + .../unstable-book/src/cfg-target-thread-local.md | 2 + src/doc/unstable-book/src/cfg-target-vendor.md | 2 + src/doc/unstable-book/src/compiler-builtins.md | 2 + src/doc/unstable-book/src/concat-idents.md | 2 + .../unstable-book/src/conservative-impl-trait.md | 2 + src/doc/unstable-book/src/const-fn.md | 2 + src/doc/unstable-book/src/const-indexing.md | 2 + src/doc/unstable-book/src/custom-attribute.md | 2 + src/doc/unstable-book/src/custom-derive.md | 2 + .../src/default-type-parameter-fallback.md | 2 + src/doc/unstable-book/src/drop-types-in-const.md | 2 + src/doc/unstable-book/src/dropck-eyepatch.md | 2 + src/doc/unstable-book/src/dropck-parametricity.md | 2 + .../unstable-book/src/exclusive-range-pattern.md | 2 + src/doc/unstable-book/src/field-init-shorthand.md | 2 + src/doc/unstable-book/src/fundamental.md | 2 + src/doc/unstable-book/src/generic-param-attrs.md | 2 + src/doc/unstable-book/src/i128-type.md | 2 + .../unstable-book/src/inclusive-range-syntax.md | 2 + src/doc/unstable-book/src/intrinsics.md | 27 +++ src/doc/unstable-book/src/lang-items.md | 215 +++++++++++++++++ src/doc/unstable-book/src/link-args.md | 24 ++ src/doc/unstable-book/src/link-cfg.md | 2 + src/doc/unstable-book/src/link-llvm-intrinsics.md | 2 + src/doc/unstable-book/src/linkage.md | 2 + src/doc/unstable-book/src/log-syntax.md | 2 + src/doc/unstable-book/src/loop-break-value.md | 2 + src/doc/unstable-book/src/macro-reexport.md | 2 + src/doc/unstable-book/src/main.md | 2 + src/doc/unstable-book/src/naked-functions.md | 2 + src/doc/unstable-book/src/needs-allocator.md | 2 + src/doc/unstable-book/src/needs-panic-runtime.md | 2 + src/doc/unstable-book/src/never-type.md | 2 + src/doc/unstable-book/src/no-core.md | 2 + src/doc/unstable-book/src/no-debug.md | 2 + src/doc/unstable-book/src/non-ascii-idents.md | 2 + .../src/omit-gdb-pretty-printer-section.md | 2 + src/doc/unstable-book/src/on-unimplemented.md | 2 + src/doc/unstable-book/src/optin-builtin-traits.md | 1 + src/doc/unstable-book/src/panic-runtime.md | 2 + src/doc/unstable-book/src/placement-in-syntax.md | 2 + src/doc/unstable-book/src/platform-intrinsics.md | 2 + src/doc/unstable-book/src/plugin-registrar.md | 5 + src/doc/unstable-book/src/plugin.md | 254 +++++++++++++++++++++ src/doc/unstable-book/src/prelude-import.md | 2 + src/doc/unstable-book/src/proc-macro.md | 2 + src/doc/unstable-book/src/pub-restricted.md | 2 + src/doc/unstable-book/src/quote.md | 2 + src/doc/unstable-book/src/relaxed-adts.md | 2 + src/doc/unstable-book/src/repr-simd.md | 2 + src/doc/unstable-book/src/rustc-attrs.md | 2 + .../unstable-book/src/rustc-diagnostic-macros.md | 2 + src/doc/unstable-book/src/sanitizer-runtime.md | 2 + src/doc/unstable-book/src/simd-ffi.md | 2 + src/doc/unstable-book/src/simd.md | 2 + src/doc/unstable-book/src/slice-patterns.md | 19 ++ src/doc/unstable-book/src/specialization.md | 2 +- src/doc/unstable-book/src/staged-api.md | 2 + src/doc/unstable-book/src/start.md | 2 + src/doc/unstable-book/src/static-nobundle.md | 2 + src/doc/unstable-book/src/static-recursion.md | 2 + src/doc/unstable-book/src/stmt-expr-attributes.md | 2 + .../unstable-book/src/struct-field-attributes.md | 2 + src/doc/unstable-book/src/structural-match.md | 2 + src/doc/unstable-book/src/target-feature.md | 2 + src/doc/unstable-book/src/test.md | 158 +++++++++++++ src/doc/unstable-book/src/thread-local.md | 2 + src/doc/unstable-book/src/trace-macros.md | 2 + src/doc/unstable-book/src/type-ascription.md | 2 + src/doc/unstable-book/src/unboxed-closures.md | 2 + src/doc/unstable-book/src/untagged-unions.md | 2 + src/doc/unstable-book/src/unwind-attributes.md | 2 + src/doc/unstable-book/src/use-extern-macros.md | 2 + src/doc/unstable-book/src/windows-subsystem.md | 2 + 105 files changed, 1410 insertions(+), 1242 deletions(-) delete mode 100644 src/doc/book/src/advanced-linking.md delete mode 100644 src/doc/book/src/associated-constants.md delete mode 100644 src/doc/book/src/benchmark-tests.md delete mode 100644 src/doc/book/src/box-syntax-and-patterns.md delete mode 100644 src/doc/book/src/custom-allocators.md delete mode 100644 src/doc/book/src/inline-assembly.md delete mode 100644 src/doc/book/src/intrinsics.md delete mode 100644 src/doc/book/src/lang-items.md delete mode 100644 src/doc/book/src/nightly-rust.md delete mode 100644 src/doc/book/src/no-stdlib.md delete mode 100644 src/doc/book/src/slice-patterns.md create mode 100644 src/doc/unstable-book/src/alloc-jemalloc.md create mode 100644 src/doc/unstable-book/src/alloc-system.md create mode 100644 src/doc/unstable-book/src/test.md diff --git a/src/doc/book/src/SUMMARY.md b/src/doc/book/src/SUMMARY.md index 74b9b7fa5b2..c3763cdf9d6 100644 --- a/src/doc/book/src/SUMMARY.md +++ b/src/doc/book/src/SUMMARY.md @@ -55,18 +55,6 @@ * [Release Channels](release-channels.md) * [Using Rust without the standard library](using-rust-without-the-standard-library.md) * [Procedural Macros (and custom derive)](procedural-macros.md) -* [Nightly Rust](nightly-rust.md) - * [Compiler Plugins](compiler-plugins.md) - * [Inline Assembly](inline-assembly.md) - * [No stdlib](no-stdlib.md) - * [Intrinsics](intrinsics.md) - * [Lang items](lang-items.md) - * [Advanced linking](advanced-linking.md) - * [Benchmark Tests](benchmark-tests.md) - * [Box Syntax and Patterns](box-syntax-and-patterns.md) - * [Slice Patterns](slice-patterns.md) - * [Associated Constants](associated-constants.md) - * [Custom Allocators](custom-allocators.md) * [Glossary](glossary.md) * [Syntax Index](syntax-index.md) * [Bibliography](bibliography.md) diff --git a/src/doc/book/src/advanced-linking.md b/src/doc/book/src/advanced-linking.md deleted file mode 100644 index a882d6d2ebe..00000000000 --- a/src/doc/book/src/advanced-linking.md +++ /dev/null @@ -1,145 +0,0 @@ -# Advanced Linking - -The common cases of linking with Rust have been covered earlier in this book, -but supporting the range of linking possibilities made available by other -languages is important for Rust to achieve seamless interaction with native -libraries. - -# Link args - -There is one other way to tell `rustc` how to customize linking, and that is via -the `link_args` attribute. This attribute is applied to `extern` blocks and -specifies raw flags which need to get passed to the linker when producing an -artifact. An example usage would be: - -```rust,no_run -#![feature(link_args)] - -#[link_args = "-foo -bar -baz"] -extern {} -# fn main() {} -``` - -Note that this feature is currently hidden behind the `feature(link_args)` gate -because this is not a sanctioned way of performing linking. Right now `rustc` -shells out to the system linker (`gcc` on most systems, `link.exe` on MSVC), -so it makes sense to provide extra command line -arguments, but this will not always be the case. In the future `rustc` may use -LLVM directly to link native libraries, in which case `link_args` will have no -meaning. You can achieve the same effect as the `link_args` attribute with the -`-C link-args` argument to `rustc`. - -It is highly recommended to *not* use this attribute, and rather use the more -formal `#[link(...)]` attribute on `extern` blocks instead. - -# Static linking - -Static linking refers to the process of creating output that contains all -required libraries and so doesn't need libraries installed on every system where -you want to use your compiled project. Pure-Rust dependencies are statically -linked by default so you can use created binaries and libraries without -installing Rust everywhere. By contrast, native libraries -(e.g. `libc` and `libm`) are usually dynamically linked, but it is possible to -change this and statically link them as well. - -Linking is a very platform-dependent topic, and static linking may not even be -possible on some platforms! This section assumes some basic familiarity with -linking on your platform of choice. - -## Linux - -By default, all Rust programs on Linux will link to the system `libc` along with -a number of other libraries. Let's look at an example on a 64-bit Linux machine -with GCC and `glibc` (by far the most common `libc` on Linux): - -```text -$ cat example.rs -fn main() {} -$ rustc example.rs -$ ldd example - linux-vdso.so.1 => (0x00007ffd565fd000) - libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007fa81889c000) - libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007fa81867e000) - librt.so.1 => /lib/x86_64-linux-gnu/librt.so.1 (0x00007fa818475000) - libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007fa81825f000) - libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fa817e9a000) - /lib64/ld-linux-x86-64.so.2 (0x00007fa818cf9000) - libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007fa817b93000) -``` - -Dynamic linking on Linux can be undesirable if you wish to use new library -features on old systems or target systems which do not have the required -dependencies for your program to run. - -Static linking is supported via an alternative `libc`, [`musl`](http://www.musl-libc.org). You can compile -your own version of Rust with `musl` enabled and install it into a custom -directory with the instructions below: - -```text -$ mkdir musldist -$ PREFIX=$(pwd)/musldist -$ -$ # Build musl -$ curl -O http://www.musl-libc.org/releases/musl-1.1.10.tar.gz -$ tar xf musl-1.1.10.tar.gz -$ cd musl-1.1.10/ -musl-1.1.10 $ ./configure --disable-shared --prefix=$PREFIX -musl-1.1.10 $ make -musl-1.1.10 $ make install -musl-1.1.10 $ cd .. -$ du -h musldist/lib/libc.a -2.2M musldist/lib/libc.a -$ -$ # Build libunwind.a -$ curl -O http://llvm.org/releases/3.7.0/llvm-3.7.0.src.tar.xz -$ tar xf llvm-3.7.0.src.tar.xz -$ cd llvm-3.7.0.src/projects/ -llvm-3.7.0.src/projects $ curl http://llvm.org/releases/3.7.0/libunwind-3.7.0.src.tar.xz | tar xJf - -llvm-3.7.0.src/projects $ mv libunwind-3.7.0.src libunwind -llvm-3.7.0.src/projects $ mkdir libunwind/build -llvm-3.7.0.src/projects $ cd libunwind/build -llvm-3.7.0.src/projects/libunwind/build $ cmake -DLLVM_PATH=../../.. -DLIBUNWIND_ENABLE_SHARED=0 .. -llvm-3.7.0.src/projects/libunwind/build $ make -llvm-3.7.0.src/projects/libunwind/build $ cp lib/libunwind.a $PREFIX/lib/ -llvm-3.7.0.src/projects/libunwind/build $ cd ../../../../ -$ du -h musldist/lib/libunwind.a -164K musldist/lib/libunwind.a -$ -$ # Build musl-enabled rust -$ git clone https://github.com/rust-lang/rust.git muslrust -$ cd muslrust -muslrust $ ./configure --target=x86_64-unknown-linux-musl --musl-root=$PREFIX --prefix=$PREFIX -muslrust $ make -muslrust $ make install -muslrust $ cd .. -$ du -h musldist/bin/rustc -12K musldist/bin/rustc -``` - -You now have a build of a `musl`-enabled Rust! Because we've installed it to a -custom prefix we need to make sure our system can find the binaries and appropriate -libraries when we try and run it: - -```text -$ export PATH=$PREFIX/bin:$PATH -$ export LD_LIBRARY_PATH=$PREFIX/lib:$LD_LIBRARY_PATH -``` - -Let's try it out! - -```text -$ echo 'fn main() { println!("hi!"); panic!("failed"); }' > example.rs -$ rustc --target=x86_64-unknown-linux-musl example.rs -$ ldd example - not a dynamic executable -$ ./example -hi! -thread 'main' panicked at 'failed', example.rs:1 -``` - -Success! This binary can be copied to almost any Linux machine with the same -machine architecture and run without issues. - -`cargo build` also permits the `--target` option so you should be able to build -your crates as normal. However, you may need to recompile your native libraries -against `musl` before they can be linked against. diff --git a/src/doc/book/src/associated-constants.md b/src/doc/book/src/associated-constants.md deleted file mode 100644 index 61bad3d3948..00000000000 --- a/src/doc/book/src/associated-constants.md +++ /dev/null @@ -1,79 +0,0 @@ -# Associated Constants - -With the `associated_consts` feature, you can define constants like this: - -```rust -#![feature(associated_consts)] - -trait Foo { - const ID: i32; -} - -impl Foo for i32 { - const ID: i32 = 1; -} - -fn main() { - assert_eq!(1, i32::ID); -} -``` - -Any implementor of `Foo` will have to define `ID`. Without the definition: - -```rust,ignore -#![feature(associated_consts)] - -trait Foo { - const ID: i32; -} - -impl Foo for i32 { -} -``` - -gives - -```text -error: not all trait items implemented, missing: `ID` [E0046] - impl Foo for i32 { - } -``` - -A default value can be implemented as well: - -```rust -#![feature(associated_consts)] - -trait Foo { - const ID: i32 = 1; -} - -impl Foo for i32 { -} - -impl Foo for i64 { - const ID: i32 = 5; -} - -fn main() { - assert_eq!(1, i32::ID); - assert_eq!(5, i64::ID); -} -``` - -As you can see, when implementing `Foo`, you can leave it unimplemented, as -with `i32`. It will then use the default value. But, as in `i64`, we can also -add our own definition. - -Associated constants don’t have to be associated with a trait. An `impl` block -for a `struct` or an `enum` works fine too: - -```rust -#![feature(associated_consts)] - -struct Foo; - -impl Foo { - const FOO: u32 = 3; -} -``` diff --git a/src/doc/book/src/benchmark-tests.md b/src/doc/book/src/benchmark-tests.md deleted file mode 100644 index a6ae2b3049a..00000000000 --- a/src/doc/book/src/benchmark-tests.md +++ /dev/null @@ -1,152 +0,0 @@ -# Benchmark tests - -Rust supports benchmark tests, which can test the performance of your -code. Let's make our `src/lib.rs` look like this (comments elided): - -```rust,ignore -#![feature(test)] - -extern crate test; - -pub fn add_two(a: i32) -> i32 { - a + 2 -} - -#[cfg(test)] -mod tests { - use super::*; - use test::Bencher; - - #[test] - fn it_works() { - assert_eq!(4, add_two(2)); - } - - #[bench] - fn bench_add_two(b: &mut Bencher) { - b.iter(|| add_two(2)); - } -} -``` - -Note the `test` feature gate, which enables this unstable feature. - -We've imported the `test` crate, which contains our benchmarking support. -We have a new function as well, with the `bench` attribute. Unlike regular -tests, which take no arguments, benchmark tests take a `&mut Bencher`. This -`Bencher` provides an `iter` method, which takes a closure. This closure -contains the code we'd like to benchmark. - -We can run benchmark tests with `cargo bench`: - -```bash -$ cargo bench - Compiling adder v0.0.1 (file:///home/steve/tmp/adder) - Running target/release/adder-91b3e234d4ed382a - -running 2 tests -test tests::it_works ... ignored -test tests::bench_add_two ... bench: 1 ns/iter (+/- 0) - -test result: ok. 0 passed; 0 failed; 1 ignored; 1 measured -``` - -Our non-benchmark test was ignored. You may have noticed that `cargo bench` -takes a bit longer than `cargo test`. This is because Rust runs our benchmark -a number of times, and then takes the average. Because we're doing so little -work in this example, we have a `1 ns/iter (+/- 0)`, but this would show -the variance if there was one. - -Advice on writing benchmarks: - - -* Move setup code outside the `iter` loop; only put the part you want to measure inside -* Make the code do "the same thing" on each iteration; do not accumulate or change state -* Make the outer function idempotent too; the benchmark runner is likely to run - it many times -* Make the inner `iter` loop short and fast so benchmark runs are fast and the - calibrator can adjust the run-length at fine resolution -* Make the code in the `iter` loop do something simple, to assist in pinpointing - performance improvements (or regressions) - -## Gotcha: optimizations - -There's another tricky part to writing benchmarks: benchmarks compiled with -optimizations activated can be dramatically changed by the optimizer so that -the benchmark is no longer benchmarking what one expects. For example, the -compiler might recognize that some calculation has no external effects and -remove it entirely. - -```rust,ignore -#![feature(test)] - -extern crate test; -use test::Bencher; - -#[bench] -fn bench_xor_1000_ints(b: &mut Bencher) { - b.iter(|| { - (0..1000).fold(0, |old, new| old ^ new); - }); -} -``` - -gives the following results - -```text -running 1 test -test bench_xor_1000_ints ... bench: 0 ns/iter (+/- 0) - -test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured -``` - -The benchmarking runner offers two ways to avoid this. Either, the closure that -the `iter` method receives can return an arbitrary value which forces the -optimizer to consider the result used and ensures it cannot remove the -computation entirely. This could be done for the example above by adjusting the -`b.iter` call to - -```rust -# struct X; -# impl X { fn iter(&self, _: F) where F: FnMut() -> T {} } let b = X; -b.iter(|| { - // Note lack of `;` (could also use an explicit `return`). - (0..1000).fold(0, |old, new| old ^ new) -}); -``` - -Or, the other option is to call the generic `test::black_box` function, which -is an opaque "black box" to the optimizer and so forces it to consider any -argument as used. - -```rust -#![feature(test)] - -extern crate test; - -# fn main() { -# struct X; -# impl X { fn iter(&self, _: F) where F: FnMut() -> T {} } let b = X; -b.iter(|| { - let n = test::black_box(1000); - - (0..n).fold(0, |a, b| a ^ b) -}) -# } -``` - -Neither of these read or modify the value, and are very cheap for small values. -Larger values can be passed indirectly to reduce overhead (e.g. -`black_box(&huge_struct)`). - -Performing either of the above changes gives the following benchmarking results - -```text -running 1 test -test bench_xor_1000_ints ... bench: 131 ns/iter (+/- 3) - -test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured -``` - -However, the optimizer can still modify a testcase in an undesirable manner -even when using either of the above. diff --git a/src/doc/book/src/box-syntax-and-patterns.md b/src/doc/book/src/box-syntax-and-patterns.md deleted file mode 100644 index f03e881f474..00000000000 --- a/src/doc/book/src/box-syntax-and-patterns.md +++ /dev/null @@ -1,100 +0,0 @@ -# Box Syntax and Patterns - -Currently the only stable way to create a `Box` is via the `Box::new` method. -Also it is not possible in stable Rust to destructure a `Box` in a match -pattern. The unstable `box` keyword can be used to both create and destructure -a `Box`. An example usage would be: - -```rust -#![feature(box_syntax, box_patterns)] - -fn main() { - let b = Some(box 5); - match b { - Some(box n) if n < 0 => { - println!("Box contains negative number {}", n); - }, - Some(box n) if n >= 0 => { - println!("Box contains non-negative number {}", n); - }, - None => { - println!("No box"); - }, - _ => unreachable!() - } -} -``` - -Note that these features are currently hidden behind the `box_syntax` (box -creation) and `box_patterns` (destructuring and pattern matching) gates -because the syntax may still change in the future. - -# Returning Pointers - -In many languages with pointers, you'd return a pointer from a function -so as to avoid copying a large data structure. For example: - -```rust -struct BigStruct { - one: i32, - two: i32, - // Etc. - one_hundred: i32, -} - -fn foo(x: Box) -> Box { - Box::new(*x) -} - -fn main() { - let x = Box::new(BigStruct { - one: 1, - two: 2, - one_hundred: 100, - }); - - let y = foo(x); -} -``` - -The idea is that by passing around a box, you're only copying a pointer, rather -than the hundred `i32`s that make up the `BigStruct`. - -This is an antipattern in Rust. Instead, write this: - -```rust -#![feature(box_syntax)] - -struct BigStruct { - one: i32, - two: i32, - // Etc. - one_hundred: i32, -} - -fn foo(x: Box) -> BigStruct { - *x -} - -fn main() { - let x = Box::new(BigStruct { - one: 1, - two: 2, - one_hundred: 100, - }); - - let y: Box = box foo(x); -} -``` - -This gives you flexibility without sacrificing performance. - -You may think that this gives us terrible performance: return a value and then -immediately box it up ?! Isn't this pattern the worst of both worlds? Rust is -smarter than that. There is no copy in this code. `main` allocates enough room -for the `box`, passes a pointer to that memory into `foo` as `x`, and then -`foo` writes the value straight into the `Box`. - -This is important enough that it bears repeating: pointers are not for -optimizing returning values from your code. Allow the caller to choose how they -want to use your output. diff --git a/src/doc/book/src/custom-allocators.md b/src/doc/book/src/custom-allocators.md deleted file mode 100644 index 154b5f0f4e2..00000000000 --- a/src/doc/book/src/custom-allocators.md +++ /dev/null @@ -1,171 +0,0 @@ -# Custom Allocators - -Allocating memory isn't always the easiest thing to do, and while Rust generally -takes care of this by default it often becomes necessary to customize how -allocation occurs. The compiler and standard library currently allow switching -out the default global allocator in use at compile time. The design is currently -spelled out in [RFC 1183][rfc] but this will walk you through how to get your -own allocator up and running. - -[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1183-swap-out-jemalloc.md - -# Default Allocator - -The compiler currently ships two default allocators: `alloc_system` and -`alloc_jemalloc` (some targets don't have jemalloc, however). These allocators -are normal Rust crates and contain an implementation of the routines to -allocate and deallocate memory. The standard library is not compiled assuming -either one, and the compiler will decide which allocator is in use at -compile-time depending on the type of output artifact being produced. - -Binaries generated by the compiler will use `alloc_jemalloc` by default (where -available). In this situation the compiler "controls the world" in the sense of -it has power over the final link. Primarily this means that the allocator -decision can be left up the compiler. - -Dynamic and static libraries, however, will use `alloc_system` by default. Here -Rust is typically a 'guest' in another application or another world where it -cannot authoritatively decide what allocator is in use. As a result it resorts -back to the standard APIs (e.g. `malloc` and `free`) for acquiring and releasing -memory. - -# Switching Allocators - -Although the compiler's default choices may work most of the time, it's often -necessary to tweak certain aspects. Overriding the compiler's decision about -which allocator is in use is done simply by linking to the desired allocator: - -```rust,no_run -#![feature(alloc_system)] - -extern crate alloc_system; - -fn main() { - let a = Box::new(4); // Allocates from the system allocator. - println!("{}", a); -} -``` - -In this example the binary generated will not link to jemalloc by default but -instead use the system allocator. Conversely to generate a dynamic library which -uses jemalloc by default one would write: - -```rust,ignore -#![feature(alloc_jemalloc)] -#![crate_type = "dylib"] - -extern crate alloc_jemalloc; - -pub fn foo() { - let a = Box::new(4); // Allocates from jemalloc. - println!("{}", a); -} -# fn main() {} -``` - -# Writing a custom allocator - -Sometimes even the choices of jemalloc vs the system allocator aren't enough and -an entirely new custom allocator is required. In this you'll write your own -crate which implements the allocator API (e.g. the same as `alloc_system` or -`alloc_jemalloc`). As an example, let's take a look at a simplified and -annotated version of `alloc_system` - -```rust,no_run -# // Only needed for rustdoc --test down below. -# #![feature(lang_items)] -// The compiler needs to be instructed that this crate is an allocator in order -// to realize that when this is linked in another allocator like jemalloc should -// not be linked in. -#![feature(allocator)] -#![allocator] - -// Allocators are not allowed to depend on the standard library which in turn -// requires an allocator in order to avoid circular dependencies. This crate, -// however, can use all of libcore. -#![no_std] - -// Let's give a unique name to our custom allocator: -#![crate_name = "my_allocator"] -#![crate_type = "rlib"] - -// Our system allocator will use the in-tree libc crate for FFI bindings. Note -// that currently the external (crates.io) libc cannot be used because it links -// to the standard library (e.g. `#![no_std]` isn't stable yet), so that's why -// this specifically requires the in-tree version. -#![feature(libc)] -extern crate libc; - -// Listed below are the five allocation functions currently required by custom -// allocators. Their signatures and symbol names are not currently typechecked -// by the compiler, but this is a future extension and are required to match -// what is found below. -// -// Note that the standard `malloc` and `realloc` functions do not provide a way -// to communicate alignment so this implementation would need to be improved -// with respect to alignment in that aspect. - -#[no_mangle] -pub extern fn __rust_allocate(size: usize, _align: usize) -> *mut u8 { - unsafe { libc::malloc(size as libc::size_t) as *mut u8 } -} - -#[no_mangle] -pub extern fn __rust_deallocate(ptr: *mut u8, _old_size: usize, _align: usize) { - unsafe { libc::free(ptr as *mut libc::c_void) } -} - -#[no_mangle] -pub extern fn __rust_reallocate(ptr: *mut u8, _old_size: usize, size: usize, - _align: usize) -> *mut u8 { - unsafe { - libc::realloc(ptr as *mut libc::c_void, size as libc::size_t) as *mut u8 - } -} - -#[no_mangle] -pub extern fn __rust_reallocate_inplace(_ptr: *mut u8, old_size: usize, - _size: usize, _align: usize) -> usize { - old_size // This api is not supported by libc. -} - -#[no_mangle] -pub extern fn __rust_usable_size(size: usize, _align: usize) -> usize { - size -} - -# // Only needed to get rustdoc to test this: -# fn main() {} -# #[lang = "panic_fmt"] fn panic_fmt() {} -# #[lang = "eh_personality"] fn eh_personality() {} -# #[lang = "eh_unwind_resume"] extern fn eh_unwind_resume() {} -# #[no_mangle] pub extern fn rust_eh_register_frames () {} -# #[no_mangle] pub extern fn rust_eh_unregister_frames () {} -``` - -After we compile this crate, it can be used as follows: - -```rust,ignore -extern crate my_allocator; - -fn main() { - let a = Box::new(8); // Allocates memory via our custom allocator crate. - println!("{}", a); -} -``` - -# Custom allocator limitations - -There are a few restrictions when working with custom allocators which may cause -compiler errors: - -* Any one artifact may only be linked to at most one allocator. Binaries, - dylibs, and staticlibs must link to exactly one allocator, and if none have - been explicitly chosen the compiler will choose one. On the other hand rlibs - do not need to link to an allocator (but still can). - -* A consumer of an allocator is tagged with `#![needs_allocator]` (e.g. the - `liballoc` crate currently) and an `#[allocator]` crate cannot transitively - depend on a crate which needs an allocator (e.g. circular dependencies are not - allowed). This basically means that allocators must restrict themselves to - libcore currently. diff --git a/src/doc/book/src/inline-assembly.md b/src/doc/book/src/inline-assembly.md deleted file mode 100644 index 4262289acbf..00000000000 --- a/src/doc/book/src/inline-assembly.md +++ /dev/null @@ -1,184 +0,0 @@ -# Inline Assembly - -For extremely low-level manipulations and performance reasons, one -might wish to control the CPU directly. Rust supports using inline -assembly to do this via the `asm!` macro. - -```rust,ignore -asm!(assembly template - : output operands - : input operands - : clobbers - : options - ); -``` - -Any use of `asm` is feature gated (requires `#![feature(asm)]` on the -crate to allow) and of course requires an `unsafe` block. - -> **Note**: the examples here are given in x86/x86-64 assembly, but -> all platforms are supported. - -## Assembly template - -The `assembly template` is the only required parameter and must be a -literal string (i.e. `""`) - -```rust -#![feature(asm)] - -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -fn foo() { - unsafe { - asm!("NOP"); - } -} - -// Other platforms: -#[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] -fn foo() { /* ... */ } - -fn main() { - // ... - foo(); - // ... -} -``` - -(The `feature(asm)` and `#[cfg]`s are omitted from now on.) - -Output operands, input operands, clobbers and options are all optional -but you must add the right number of `:` if you skip them: - -```rust -# #![feature(asm)] -# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -# fn main() { unsafe { -asm!("xor %eax, %eax" - : - : - : "eax" - ); -# } } -# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] -# fn main() {} -``` - -Whitespace also doesn't matter: - -```rust -# #![feature(asm)] -# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -# fn main() { unsafe { -asm!("xor %eax, %eax" ::: "eax"); -# } } -# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] -# fn main() {} -``` - -## Operands - -Input and output operands follow the same format: `: -"constraints1"(expr1), "constraints2"(expr2), ..."`. Output operand -expressions must be mutable lvalues, or not yet assigned: - -```rust -# #![feature(asm)] -# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -fn add(a: i32, b: i32) -> i32 { - let c: i32; - unsafe { - asm!("add $2, $0" - : "=r"(c) - : "0"(a), "r"(b) - ); - } - c -} -# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] -# fn add(a: i32, b: i32) -> i32 { a + b } - -fn main() { - assert_eq!(add(3, 14159), 14162) -} -``` - -If you would like to use real operands in this position, however, -you are required to put curly braces `{}` around the register that -you want, and you are required to put the specific size of the -operand. This is useful for very low level programming, where -which register you use is important: - -```rust -# #![feature(asm)] -# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -# unsafe fn read_byte_in(port: u16) -> u8 { -let result: u8; -asm!("in %dx, %al" : "={al}"(result) : "{dx}"(port)); -result -# } -``` - -## Clobbers - -Some instructions modify registers which might otherwise have held -different values so we use the clobbers list to indicate to the -compiler not to assume any values loaded into those registers will -stay valid. - -```rust -# #![feature(asm)] -# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -# fn main() { unsafe { -// Put the value 0x200 in eax: -asm!("mov $$0x200, %eax" : /* no outputs */ : /* no inputs */ : "eax"); -# } } -# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] -# fn main() {} -``` - -Input and output registers need not be listed since that information -is already communicated by the given constraints. Otherwise, any other -registers used either implicitly or explicitly should be listed. - -If the assembly changes the condition code register `cc` should be -specified as one of the clobbers. Similarly, if the assembly modifies -memory, `memory` should also be specified. - -## Options - -The last section, `options` is specific to Rust. The format is comma -separated literal strings (i.e. `:"foo", "bar", "baz"`). It's used to -specify some extra info about the inline assembly: - -Current valid options are: - -1. *volatile* - specifying this is analogous to - `__asm__ __volatile__ (...)` in gcc/clang. -2. *alignstack* - certain instructions expect the stack to be - aligned a certain way (i.e. SSE) and specifying this indicates to - the compiler to insert its usual stack alignment code -3. *intel* - use intel syntax instead of the default AT&T. - -```rust -# #![feature(asm)] -# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -# fn main() { -let result: i32; -unsafe { - asm!("mov eax, 2" : "={eax}"(result) : : : "intel") -} -println!("eax is currently {}", result); -# } -# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] -# fn main() {} -``` - -## More Information - -The current implementation of the `asm!` macro is a direct binding to [LLVM's -inline assembler expressions][llvm-docs], so be sure to check out [their -documentation as well][llvm-docs] for more information about clobbers, -constraints, etc. - -[llvm-docs]: http://llvm.org/docs/LangRef.html#inline-assembler-expressions diff --git a/src/doc/book/src/intrinsics.md b/src/doc/book/src/intrinsics.md deleted file mode 100644 index e1edce3e80f..00000000000 --- a/src/doc/book/src/intrinsics.md +++ /dev/null @@ -1,25 +0,0 @@ -# Intrinsics - -> **Note**: intrinsics will forever have an unstable interface, it is -> recommended to use the stable interfaces of libcore rather than intrinsics -> directly. - -These are imported as if they were FFI functions, with the special -`rust-intrinsic` ABI. For example, if one was in a freestanding -context, but wished to be able to `transmute` between types, and -perform efficient pointer arithmetic, one would import those functions -via a declaration like - -```rust -#![feature(intrinsics)] -# fn main() {} - -extern "rust-intrinsic" { - fn transmute(x: T) -> U; - - fn offset(dst: *const T, offset: isize) -> *const T; -} -``` - -As with any other FFI functions, these are always `unsafe` to call. - diff --git a/src/doc/book/src/lang-items.md b/src/doc/book/src/lang-items.md deleted file mode 100644 index 9bd64d38179..00000000000 --- a/src/doc/book/src/lang-items.md +++ /dev/null @@ -1,84 +0,0 @@ -# Lang items - -> **Note**: lang items are often provided by crates in the Rust distribution, -> and lang items themselves have an unstable interface. It is recommended to use -> officially distributed crates instead of defining your own lang items. - -The `rustc` compiler has certain pluggable operations, that is, -functionality that isn't hard-coded into the language, but is -implemented in libraries, with a special marker to tell the compiler -it exists. The marker is the attribute `#[lang = "..."]` and there are -various different values of `...`, i.e. various different 'lang -items'. - -For example, `Box` pointers require two lang items, one for allocation -and one for deallocation. A freestanding program that uses the `Box` -sugar for dynamic allocations via `malloc` and `free`: - -```rust,ignore -#![feature(lang_items, box_syntax, start, libc, core_intrinsics)] -#![no_std] -use core::intrinsics; - -extern crate libc; - -#[lang = "owned_box"] -pub struct Box(*mut T); - -#[lang = "exchange_malloc"] -unsafe fn allocate(size: usize, _align: usize) -> *mut u8 { - let p = libc::malloc(size as libc::size_t) as *mut u8; - - // Check if `malloc` failed: - if p as usize == 0 { - intrinsics::abort(); - } - - p -} - -#[lang = "exchange_free"] -unsafe fn deallocate(ptr: *mut u8, _size: usize, _align: usize) { - libc::free(ptr as *mut libc::c_void) -} - -#[lang = "box_free"] -unsafe fn box_free(ptr: *mut T) { - deallocate(ptr as *mut u8, ::core::mem::size_of_val(&*ptr), ::core::mem::align_of_val(&*ptr)); -} - -#[start] -fn main(argc: isize, argv: *const *const u8) -> isize { - let x = box 1; - - 0 -} - -#[lang = "eh_personality"] extern fn rust_eh_personality() {} -#[lang = "panic_fmt"] extern fn rust_begin_panic() -> ! { unsafe { intrinsics::abort() } } -# #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {} -# #[no_mangle] pub extern fn rust_eh_register_frames () {} -# #[no_mangle] pub extern fn rust_eh_unregister_frames () {} -``` - -Note the use of `abort`: the `exchange_malloc` lang item is assumed to -return a valid pointer, and so needs to do the check internally. - -Other features provided by lang items include: - -- overloadable operators via traits: the traits corresponding to the - `==`, `<`, dereferencing (`*`) and `+` (etc.) operators are all - marked with lang items; those specific four are `eq`, `ord`, - `deref`, and `add` respectively. -- stack unwinding and general failure; the `eh_personality`, - `eh_unwind_resume`, `fail` and `fail_bounds_checks` lang items. -- the traits in `std::marker` used to indicate types of - various kinds; lang items `send`, `sync` and `copy`. -- the marker types and variance indicators found in - `std::marker`; lang items `covariant_type`, - `contravariant_lifetime`, etc. - -Lang items are loaded lazily by the compiler; e.g. if one never uses -`Box` then there is no need to define functions for `exchange_malloc` -and `exchange_free`. `rustc` will emit an error when an item is needed -but not found in the current crate or any that it depends on. diff --git a/src/doc/book/src/nightly-rust.md b/src/doc/book/src/nightly-rust.md deleted file mode 100644 index 5dfaa9e0fa8..00000000000 --- a/src/doc/book/src/nightly-rust.md +++ /dev/null @@ -1,100 +0,0 @@ -# Nightly Rust - -Rust provides three distribution channels for Rust: nightly, beta, and stable. -Unstable features are only available on nightly Rust. For more details on this -process, see [Stability as a deliverable][stability]. - -[stability]: http://blog.rust-lang.org/2014/10/30/Stability.html - -To install nightly Rust, you can use [rustup.rs][rustup]: - -[rustup]: https://rustup.rs - -```bash -$ curl https://sh.rustup.rs -sSf | sh -$ rustup install nightly -``` - -If you're concerned about the [potential insecurity][insecurity] of using `curl -| sh`, please keep reading and see our disclaimer below. And feel free to -use a two-step version of the installation and examine our installation script: - -```bash -$ curl https://sh.rustup.rs -sSf -o rustup.sh -$ sh rustup.sh -$ rustup install nightly -``` - -[insecurity]: http://curlpipesh.tumblr.com - -If you're on Windows, please download the [rustup installer][installer] -and run it. - -[installer]: https://win.rustup.rs - -## Uninstalling - -If you decide you don't want Rust anymore, we'll be a bit sad, but that's okay. -Not every programming language is great for everyone. Just run the uninstall -command: - -```bash -$ rustup self uninstall -``` - -Some people, and somewhat rightfully so, get very upset when we tell you to -`curl | sh`. Basically, when you do this, you are trusting that the good -people who maintain Rust aren't going to hack your computer and do bad things. -That's a good instinct! If you're one of those people, please check out the -documentation on [building Rust from Source][from-source], or [the official -binary downloads][install-page]. - -[from-source]: https://github.com/rust-lang/rust#building-from-source -[install-page]: https://www.rust-lang.org/install.html - -Oh, we should also mention the officially supported platforms: - -* Windows (7+) -* Linux (2.6.18 or later, various distributions), x86 and x86-64 -* OSX 10.7 (Lion) or greater, x86 and x86-64 - -We extensively test Rust on these platforms, and a few others, too, like -Android. But these are the ones most likely to work, as they have the most -testing. - -Finally, a comment about Windows. Rust considers Windows to be a first-class -platform upon release, but if we're honest, the Windows experience isn't as -integrated as the Linux/OS X experience is. We're working on it! If anything -does not work, it is a bug. Please let us know if that happens. Each and every -commit is tested against Windows like any other platform. - -If you've got Rust installed, you can open up a shell, and type this: - -```bash -$ rustc --version -``` - -You should see the version number, commit hash, commit date and build date: - -```bash -rustc 1.0.0-nightly (f11f3e7ba 2015-01-04) (built 2015-01-06) -``` - -If you did, Rust has been installed successfully! Congrats! - -This installer also installs a copy of the documentation locally, so you can -read it offline. On UNIX systems, `/usr/local/share/doc/rust` is the location. -On Windows, it's in a `share/doc` directory, inside wherever you installed Rust -to. - -If not, there are a number of places where you can get help. The easiest is -[the #rust IRC channel on irc.mozilla.org][irc], which you can access through -[Mibbit][mibbit]. Click that link, and you'll be chatting with other Rustaceans -(a silly nickname we call ourselves), and we can help you out. Other great -resources include [the users forum][users], and [Stack Overflow][stackoverflow]. - -[irc]: irc://irc.mozilla.org/#rust -[mibbit]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust -[users]: https://users.rust-lang.org/ -[stackoverflow]: http://stackoverflow.com/questions/tagged/rust - diff --git a/src/doc/book/src/no-stdlib.md b/src/doc/book/src/no-stdlib.md deleted file mode 100644 index dcb0fbc8005..00000000000 --- a/src/doc/book/src/no-stdlib.md +++ /dev/null @@ -1,145 +0,0 @@ -# No stdlib - -Rust’s standard library provides a lot of useful functionality, but assumes -support for various features of its host system: threads, networking, heap -allocation, and others. There are systems that do not have these features, -however, and Rust can work with those too! To do so, we tell Rust that we -don’t want to use the standard library via an attribute: `#![no_std]`. - -> Note: This feature is technically stable, but there are some caveats. For -> one, you can build a `#![no_std]` _library_ on stable, but not a _binary_. -> For details on libraries without the standard library, see [the chapter on -> `#![no_std]`](using-rust-without-the-standard-library.html) - -Obviously there's more to life than just libraries: one can use -`#[no_std]` with an executable. - -### Using libc - -In order to build a `#[no_std]` executable we will need libc as a dependency. We can specify -this using our `Cargo.toml` file: - -```toml -[dependencies] -libc = { version = "0.2.14", default-features = false } -``` - -Note that the default features have been disabled. This is a critical step - -**the default features of libc include the standard library and so must be -disabled.** - -### Writing an executable without stdlib - -Controlling the entry point is possible in two ways: the `#[start]` attribute, -or overriding the default shim for the C `main` function with your own. - -The function marked `#[start]` is passed the command line parameters -in the same format as C: - -```rust,ignore -#![feature(lang_items, core_intrinsics)] -#![feature(start)] -#![no_std] -use core::intrinsics; - -// Pull in the system libc library for what crt0.o likely requires. -extern crate libc; - -// Entry point for this program. -#[start] -fn start(_argc: isize, _argv: *const *const u8) -> isize { - 0 -} - -// These functions are used by the compiler, but not -// for a bare-bones hello world. These are normally -// provided by libstd. -#[lang = "eh_personality"] -#[no_mangle] -pub extern fn rust_eh_personality() { -} - -// This function may be needed based on the compilation target. -#[lang = "eh_unwind_resume"] -#[no_mangle] -pub extern fn rust_eh_unwind_resume() { -} - -#[lang = "panic_fmt"] -#[no_mangle] -pub extern fn rust_begin_panic(_msg: core::fmt::Arguments, - _file: &'static str, - _line: u32) -> ! { - unsafe { intrinsics::abort() } -} -``` - -To override the compiler-inserted `main` shim, one has to disable it -with `#![no_main]` and then create the appropriate symbol with the -correct ABI and the correct name, which requires overriding the -compiler's name mangling too: - -```rust,ignore -#![feature(lang_items, core_intrinsics)] -#![feature(start)] -#![no_std] -#![no_main] -use core::intrinsics; - -// Pull in the system libc library for what crt0.o likely requires. -extern crate libc; - -// Entry point for this program. -#[no_mangle] // ensure that this symbol is called `main` in the output -pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 { - 0 -} - -// These functions are used by the compiler, but not -// for a bare-bones hello world. These are normally -// provided by libstd. -#[lang = "eh_personality"] -#[no_mangle] -pub extern fn rust_eh_personality() { -} - -// This function may be needed based on the compilation target. -#[lang = "eh_unwind_resume"] -#[no_mangle] -pub extern fn rust_eh_unwind_resume() { -} - -#[lang = "panic_fmt"] -#[no_mangle] -pub extern fn rust_begin_panic(_msg: core::fmt::Arguments, - _file: &'static str, - _line: u32) -> ! { - unsafe { intrinsics::abort() } -} -``` - -## More about the language items - -The compiler currently makes a few assumptions about symbols which are -available in the executable to call. Normally these functions are provided by -the standard library, but without it you must define your own. These symbols -are called "language items", and they each have an internal name, and then a -signature that an implementation must conform to. - -The first of these functions, `rust_eh_personality`, is used by the failure -mechanisms of the compiler. This is often mapped to GCC's personality function -(see the [libstd implementation][unwind] for more information), but crates -which do not trigger a panic can be assured that this function is never -called. The language item's name is `eh_personality`. - -[unwind]: https://github.com/rust-lang/rust/blob/master/src/libpanic_unwind/gcc.rs - -The second function, `rust_begin_panic`, is also used by the failure mechanisms of the -compiler. When a panic happens, this controls the message that's displayed on -the screen. While the language item's name is `panic_fmt`, the symbol name is -`rust_begin_panic`. - -A third function, `rust_eh_unwind_resume`, is also needed if the `custom_unwind_resume` -flag is set in the options of the compilation target. It allows customizing the -process of resuming unwind at the end of the landing pads. The language item's name -is `eh_unwind_resume`. diff --git a/src/doc/book/src/slice-patterns.md b/src/doc/book/src/slice-patterns.md deleted file mode 100644 index 3f7398dde5e..00000000000 --- a/src/doc/book/src/slice-patterns.md +++ /dev/null @@ -1,42 +0,0 @@ -# Slice patterns - -If you want to match against a slice or array, you can use `&` with the -`slice_patterns` feature: - -```rust -#![feature(slice_patterns)] - -fn main() { - let v = vec!["match_this", "1"]; - - match &v[..] { - &["match_this", second] => println!("The second element is {}", second), - _ => {}, - } -} -``` - -The `advanced_slice_patterns` gate lets you use `..` to indicate any number of -elements inside a pattern matching a slice. This wildcard can only be used once -for a given array. If there's an identifier before the `..`, the result of the -slice will be bound to that name. For example: - -```rust -#![feature(advanced_slice_patterns, slice_patterns)] - -fn is_symmetric(list: &[u32]) -> bool { - match list { - &[] | &[_] => true, - &[x, ref inside.., y] if x == y => is_symmetric(inside), - _ => false - } -} - -fn main() { - let sym = &[0, 1, 4, 2, 4, 1, 0]; - assert!(is_symmetric(sym)); - - let not_sym = &[0, 1, 7, 2, 4, 1, 0]; - assert!(!is_symmetric(not_sym)); -} -``` diff --git a/src/doc/unstable-book/src/SUMMARY.md b/src/doc/unstable-book/src/SUMMARY.md index b0bd28828fa..ee8ae9a9839 100644 --- a/src/doc/unstable-book/src/SUMMARY.md +++ b/src/doc/unstable-book/src/SUMMARY.md @@ -1,6 +1,9 @@ [The Unstable Book](the-unstable-book.md) - [asm](asm.md) +- [alloc_system](alloc-system.md) +- [alloc_jemalloc](alloc-jemalloc.md) +- [test](test.md) - [concat_idents](concat-idents.md) - [link_args](link-args.md) - [log_syntax](log-syntax.md) diff --git a/src/doc/unstable-book/src/abi-msp430-interrupt.md b/src/doc/unstable-book/src/abi-msp430-interrupt.md index 4d925e73686..9b2c7f29897 100644 --- a/src/doc/unstable-book/src/abi-msp430-interrupt.md +++ b/src/doc/unstable-book/src/abi-msp430-interrupt.md @@ -3,3 +3,5 @@ The tracking issue for this feature is: [#38487] [#38487]: https://github.com/rust-lang/rust/issues/38487 + +------------------------ diff --git a/src/doc/unstable-book/src/abi-ptx.md b/src/doc/unstable-book/src/abi-ptx.md index 6695cb0f33c..9c1b8868ace 100644 --- a/src/doc/unstable-book/src/abi-ptx.md +++ b/src/doc/unstable-book/src/abi-ptx.md @@ -2,3 +2,4 @@ The tracking issue for this feature is: None. +------------------------ diff --git a/src/doc/unstable-book/src/abi-sysv64.md b/src/doc/unstable-book/src/abi-sysv64.md index 2415c8b8d19..27f61d56342 100644 --- a/src/doc/unstable-book/src/abi-sysv64.md +++ b/src/doc/unstable-book/src/abi-sysv64.md @@ -4,5 +4,4 @@ The tracking issue for this feature is: [#36167] [#36167]: https://github.com/rust-lang/rust/issues/36167 - - +------------------------ diff --git a/src/doc/unstable-book/src/abi-unadjusted.md b/src/doc/unstable-book/src/abi-unadjusted.md index 2a941d95632..2e3113abdbf 100644 --- a/src/doc/unstable-book/src/abi-unadjusted.md +++ b/src/doc/unstable-book/src/abi-unadjusted.md @@ -2,3 +2,5 @@ The tracking issue for this feature is: none. +------------------------ + diff --git a/src/doc/unstable-book/src/abi-vectorcall.md b/src/doc/unstable-book/src/abi-vectorcall.md index da9d830c4dc..3e36b1569fd 100644 --- a/src/doc/unstable-book/src/abi-vectorcall.md +++ b/src/doc/unstable-book/src/abi-vectorcall.md @@ -2,4 +2,6 @@ The tracking issue for this feature is: none. +------------------------ + diff --git a/src/doc/unstable-book/src/advanced-slice-patterns.md b/src/doc/unstable-book/src/advanced-slice-patterns.md index b0eee4bc0b8..30d22ca8208 100644 --- a/src/doc/unstable-book/src/advanced-slice-patterns.md +++ b/src/doc/unstable-book/src/advanced-slice-patterns.md @@ -4,5 +4,32 @@ The tracking issue for this feature is: [#23121] [#23121]: https://github.com/rust-lang/rust/issues/23121 +See also [`slice_patterns`](slice-patterns.html). +------------------------ + +The `advanced_slice_patterns` gate lets you use `..` to indicate any number of +elements inside a pattern matching a slice. This wildcard can only be used once +for a given array. If there's an identifier before the `..`, the result of the +slice will be bound to that name. For example: + +```rust +#![feature(advanced_slice_patterns, slice_patterns)] + +fn is_symmetric(list: &[u32]) -> bool { + match list { + &[] | &[_] => true, + &[x, ref inside.., y] if x == y => is_symmetric(inside), + _ => false + } +} + +fn main() { + let sym = &[0, 1, 4, 2, 4, 1, 0]; + assert!(is_symmetric(sym)); + + let not_sym = &[0, 1, 7, 2, 4, 1, 0]; + assert!(!is_symmetric(not_sym)); +} +``` diff --git a/src/doc/unstable-book/src/alloc-jemalloc.md b/src/doc/unstable-book/src/alloc-jemalloc.md new file mode 100644 index 00000000000..47c44ddc374 --- /dev/null +++ b/src/doc/unstable-book/src/alloc-jemalloc.md @@ -0,0 +1,62 @@ +# `alloc_jemalloc` + +The tracking issue for this feature is: [#33082] + +[#33082]: https://github.com/rust-lang/rust/issues/33082 + +See also [`alloc_system`](alloc-system.md). + +------------------------ + +The compiler currently ships two default allocators: `alloc_system` and +`alloc_jemalloc` (some targets don't have jemalloc, however). These allocators +are normal Rust crates and contain an implementation of the routines to +allocate and deallocate memory. The standard library is not compiled assuming +either one, and the compiler will decide which allocator is in use at +compile-time depending on the type of output artifact being produced. + +Binaries generated by the compiler will use `alloc_jemalloc` by default (where +available). In this situation the compiler "controls the world" in the sense of +it has power over the final link. Primarily this means that the allocator +decision can be left up the compiler. + +Dynamic and static libraries, however, will use `alloc_system` by default. Here +Rust is typically a 'guest' in another application or another world where it +cannot authoritatively decide what allocator is in use. As a result it resorts +back to the standard APIs (e.g. `malloc` and `free`) for acquiring and releasing +memory. + +# Switching Allocators + +Although the compiler's default choices may work most of the time, it's often +necessary to tweak certain aspects. Overriding the compiler's decision about +which allocator is in use is done simply by linking to the desired allocator: + +```rust,no_run +#![feature(alloc_system)] + +extern crate alloc_system; + +fn main() { + let a = Box::new(4); // Allocates from the system allocator. + println!("{}", a); +} +``` + +In this example the binary generated will not link to jemalloc by default but +instead use the system allocator. Conversely to generate a dynamic library which +uses jemalloc by default one would write: + +```rust,ignore +#![feature(alloc_jemalloc)] +#![crate_type = "dylib"] + +extern crate alloc_jemalloc; + +pub fn foo() { + let a = Box::new(4); // Allocates from jemalloc. + println!("{}", a); +} +# fn main() {} +``` + diff --git a/src/doc/unstable-book/src/alloc-system.md b/src/doc/unstable-book/src/alloc-system.md new file mode 100644 index 00000000000..f7d648c3759 --- /dev/null +++ b/src/doc/unstable-book/src/alloc-system.md @@ -0,0 +1,62 @@ +# `alloc_system` + +The tracking issue for this feature is: [#33082] + +[#33082]: https://github.com/rust-lang/rust/issues/33082 + +See also [`alloc_jemalloc`](alloc-jemalloc.md). + +------------------------ + +The compiler currently ships two default allocators: `alloc_system` and +`alloc_jemalloc` (some targets don't have jemalloc, however). These allocators +are normal Rust crates and contain an implementation of the routines to +allocate and deallocate memory. The standard library is not compiled assuming +either one, and the compiler will decide which allocator is in use at +compile-time depending on the type of output artifact being produced. + +Binaries generated by the compiler will use `alloc_jemalloc` by default (where +available). In this situation the compiler "controls the world" in the sense of +it has power over the final link. Primarily this means that the allocator +decision can be left up the compiler. + +Dynamic and static libraries, however, will use `alloc_system` by default. Here +Rust is typically a 'guest' in another application or another world where it +cannot authoritatively decide what allocator is in use. As a result it resorts +back to the standard APIs (e.g. `malloc` and `free`) for acquiring and releasing +memory. + +# Switching Allocators + +Although the compiler's default choices may work most of the time, it's often +necessary to tweak certain aspects. Overriding the compiler's decision about +which allocator is in use is done simply by linking to the desired allocator: + +```rust,no_run +#![feature(alloc_system)] + +extern crate alloc_system; + +fn main() { + let a = Box::new(4); // Allocates from the system allocator. + println!("{}", a); +} +``` + +In this example the binary generated will not link to jemalloc by default but +instead use the system allocator. Conversely to generate a dynamic library which +uses jemalloc by default one would write: + +```rust,ignore +#![feature(alloc_jemalloc)] +#![crate_type = "dylib"] + +extern crate alloc_jemalloc; + +pub fn foo() { + let a = Box::new(4); // Allocates from jemalloc. + println!("{}", a); +} +# fn main() {} +``` + diff --git a/src/doc/unstable-book/src/allocator.md b/src/doc/unstable-book/src/allocator.md index 777efa217d1..7261641698f 100644 --- a/src/doc/unstable-book/src/allocator.md +++ b/src/doc/unstable-book/src/allocator.md @@ -4,5 +4,111 @@ The tracking issue for this feature is: [#27389] [#27389]: https://github.com/rust-lang/rust/issues/27389 +------------------------ + +Sometimes even the choices of jemalloc vs the system allocator aren't enough and +an entirely new custom allocator is required. In this you'll write your own +crate which implements the allocator API (e.g. the same as `alloc_system` or +`alloc_jemalloc`). As an example, let's take a look at a simplified and +annotated version of `alloc_system` + +```rust,no_run +# // Only needed for rustdoc --test down below. +# #![feature(lang_items)] +// The compiler needs to be instructed that this crate is an allocator in order +// to realize that when this is linked in another allocator like jemalloc should +// not be linked in. +#![feature(allocator)] +#![allocator] + +// Allocators are not allowed to depend on the standard library which in turn +// requires an allocator in order to avoid circular dependencies. This crate, +// however, can use all of libcore. +#![no_std] + +// Let's give a unique name to our custom allocator: +#![crate_name = "my_allocator"] +#![crate_type = "rlib"] + +// Our system allocator will use the in-tree libc crate for FFI bindings. Note +// that currently the external (crates.io) libc cannot be used because it links +// to the standard library (e.g. `#![no_std]` isn't stable yet), so that's why +// this specifically requires the in-tree version. +#![feature(libc)] +extern crate libc; + +// Listed below are the five allocation functions currently required by custom +// allocators. Their signatures and symbol names are not currently typechecked +// by the compiler, but this is a future extension and are required to match +// what is found below. +// +// Note that the standard `malloc` and `realloc` functions do not provide a way +// to communicate alignment so this implementation would need to be improved +// with respect to alignment in that aspect. + +#[no_mangle] +pub extern fn __rust_allocate(size: usize, _align: usize) -> *mut u8 { + unsafe { libc::malloc(size as libc::size_t) as *mut u8 } +} + +#[no_mangle] +pub extern fn __rust_deallocate(ptr: *mut u8, _old_size: usize, _align: usize) { + unsafe { libc::free(ptr as *mut libc::c_void) } +} + +#[no_mangle] +pub extern fn __rust_reallocate(ptr: *mut u8, _old_size: usize, size: usize, + _align: usize) -> *mut u8 { + unsafe { + libc::realloc(ptr as *mut libc::c_void, size as libc::size_t) as *mut u8 + } +} + +#[no_mangle] +pub extern fn __rust_reallocate_inplace(_ptr: *mut u8, old_size: usize, + _size: usize, _align: usize) -> usize { + old_size // This api is not supported by libc. +} + +#[no_mangle] +pub extern fn __rust_usable_size(size: usize, _align: usize) -> usize { + size +} + +# // Only needed to get rustdoc to test this: +# fn main() {} +# #[lang = "panic_fmt"] fn panic_fmt() {} +# #[lang = "eh_personality"] fn eh_personality() {} +# #[lang = "eh_unwind_resume"] extern fn eh_unwind_resume() {} +# #[no_mangle] pub extern fn rust_eh_register_frames () {} +# #[no_mangle] pub extern fn rust_eh_unregister_frames () {} +``` + +After we compile this crate, it can be used as follows: + +```rust,ignore +extern crate my_allocator; + +fn main() { + let a = Box::new(8); // Allocates memory via our custom allocator crate. + println!("{}", a); +} +``` + +## Custom allocator limitations + +There are a few restrictions when working with custom allocators which may cause +compiler errors: + +* Any one artifact may only be linked to at most one allocator. Binaries, + dylibs, and staticlibs must link to exactly one allocator, and if none have + been explicitly chosen the compiler will choose one. On the other hand rlibs + do not need to link to an allocator (but still can). + +* A consumer of an allocator is tagged with `#![needs_allocator]` (e.g. the + `liballoc` crate currently) and an `#[allocator]` crate cannot transitively + depend on a crate which needs an allocator (e.g. circular dependencies are not + allowed). This basically means that allocators must restrict themselves to + libcore currently. diff --git a/src/doc/unstable-book/src/allow-internal-unstable.md b/src/doc/unstable-book/src/allow-internal-unstable.md index fe88dfb3f01..74709ad5aeb 100644 --- a/src/doc/unstable-book/src/allow-internal-unstable.md +++ b/src/doc/unstable-book/src/allow-internal-unstable.md @@ -2,3 +2,5 @@ The tracking issue for this feature is: None. +------------------------ + diff --git a/src/doc/unstable-book/src/asm.md b/src/doc/unstable-book/src/asm.md index d3939b701d2..032d9d81240 100644 --- a/src/doc/unstable-book/src/asm.md +++ b/src/doc/unstable-book/src/asm.md @@ -4,5 +4,188 @@ The tracking issue for this feature is: [#29722] [#29722]: https://github.com/rust-lang/rust/issues/29722 +------------------------ +For extremely low-level manipulations and performance reasons, one +might wish to control the CPU directly. Rust supports using inline +assembly to do this via the `asm!` macro. + +```rust,ignore +asm!(assembly template + : output operands + : input operands + : clobbers + : options + ); +``` + +Any use of `asm` is feature gated (requires `#![feature(asm)]` on the +crate to allow) and of course requires an `unsafe` block. + +> **Note**: the examples here are given in x86/x86-64 assembly, but +> all platforms are supported. + +## Assembly template + +The `assembly template` is the only required parameter and must be a +literal string (i.e. `""`) + +```rust +#![feature(asm)] + +#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +fn foo() { + unsafe { + asm!("NOP"); + } +} + +// Other platforms: +#[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] +fn foo() { /* ... */ } + +fn main() { + // ... + foo(); + // ... +} +``` + +(The `feature(asm)` and `#[cfg]`s are omitted from now on.) + +Output operands, input operands, clobbers and options are all optional +but you must add the right number of `:` if you skip them: + +```rust +# #![feature(asm)] +# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +# fn main() { unsafe { +asm!("xor %eax, %eax" + : + : + : "eax" + ); +# } } +# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] +# fn main() {} +``` + +Whitespace also doesn't matter: + +```rust +# #![feature(asm)] +# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +# fn main() { unsafe { +asm!("xor %eax, %eax" ::: "eax"); +# } } +# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] +# fn main() {} +``` + +## Operands + +Input and output operands follow the same format: `: +"constraints1"(expr1), "constraints2"(expr2), ..."`. Output operand +expressions must be mutable lvalues, or not yet assigned: + +```rust +# #![feature(asm)] +# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +fn add(a: i32, b: i32) -> i32 { + let c: i32; + unsafe { + asm!("add $2, $0" + : "=r"(c) + : "0"(a), "r"(b) + ); + } + c +} +# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] +# fn add(a: i32, b: i32) -> i32 { a + b } + +fn main() { + assert_eq!(add(3, 14159), 14162) +} +``` + +If you would like to use real operands in this position, however, +you are required to put curly braces `{}` around the register that +you want, and you are required to put the specific size of the +operand. This is useful for very low level programming, where +which register you use is important: + +```rust +# #![feature(asm)] +# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +# unsafe fn read_byte_in(port: u16) -> u8 { +let result: u8; +asm!("in %dx, %al" : "={al}"(result) : "{dx}"(port)); +result +# } +``` + +## Clobbers + +Some instructions modify registers which might otherwise have held +different values so we use the clobbers list to indicate to the +compiler not to assume any values loaded into those registers will +stay valid. + +```rust +# #![feature(asm)] +# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +# fn main() { unsafe { +// Put the value 0x200 in eax: +asm!("mov $$0x200, %eax" : /* no outputs */ : /* no inputs */ : "eax"); +# } } +# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] +# fn main() {} +``` + +Input and output registers need not be listed since that information +is already communicated by the given constraints. Otherwise, any other +registers used either implicitly or explicitly should be listed. + +If the assembly changes the condition code register `cc` should be +specified as one of the clobbers. Similarly, if the assembly modifies +memory, `memory` should also be specified. + +## Options + +The last section, `options` is specific to Rust. The format is comma +separated literal strings (i.e. `:"foo", "bar", "baz"`). It's used to +specify some extra info about the inline assembly: + +Current valid options are: + +1. *volatile* - specifying this is analogous to + `__asm__ __volatile__ (...)` in gcc/clang. +2. *alignstack* - certain instructions expect the stack to be + aligned a certain way (i.e. SSE) and specifying this indicates to + the compiler to insert its usual stack alignment code +3. *intel* - use intel syntax instead of the default AT&T. + +```rust +# #![feature(asm)] +# #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +# fn main() { +let result: i32; +unsafe { + asm!("mov eax, 2" : "={eax}"(result) : : : "intel") +} +println!("eax is currently {}", result); +# } +# #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] +# fn main() {} +``` + +## More Information + +The current implementation of the `asm!` macro is a direct binding to [LLVM's +inline assembler expressions][llvm-docs], so be sure to check out [their +documentation as well][llvm-docs] for more information about clobbers, +constraints, etc. + +[llvm-docs]: http://llvm.org/docs/LangRef.html#inline-assembler-expressions diff --git a/src/doc/unstable-book/src/associated-consts.md b/src/doc/unstable-book/src/associated-consts.md index fbd4585cc7d..d661108e7d9 100644 --- a/src/doc/unstable-book/src/associated-consts.md +++ b/src/doc/unstable-book/src/associated-consts.md @@ -4,5 +4,82 @@ The tracking issue for this feature is: [#29646] [#29646]: https://github.com/rust-lang/rust/issues/29646 +------------------------ +With the `associated_consts` feature, you can define constants like this: +```rust +#![feature(associated_consts)] + +trait Foo { + const ID: i32; +} + +impl Foo for i32 { + const ID: i32 = 1; +} + +fn main() { + assert_eq!(1, i32::ID); +} +``` + +Any implementor of `Foo` will have to define `ID`. Without the definition: + +```rust,ignore +#![feature(associated_consts)] + +trait Foo { + const ID: i32; +} + +impl Foo for i32 { +} +``` + +gives + +```text +error: not all trait items implemented, missing: `ID` [E0046] + impl Foo for i32 { + } +``` + +A default value can be implemented as well: + +```rust +#![feature(associated_consts)] + +trait Foo { + const ID: i32 = 1; +} + +impl Foo for i32 { +} + +impl Foo for i64 { + const ID: i32 = 5; +} + +fn main() { + assert_eq!(1, i32::ID); + assert_eq!(5, i64::ID); +} +``` + +As you can see, when implementing `Foo`, you can leave it unimplemented, as +with `i32`. It will then use the default value. But, as in `i64`, we can also +add our own definition. + +Associated constants don’t have to be associated with a trait. An `impl` block +for a `struct` or an `enum` works fine too: + +```rust +#![feature(associated_consts)] + +struct Foo; + +impl Foo { + const FOO: u32 = 3; +} +``` diff --git a/src/doc/unstable-book/src/associated-type-defaults.md b/src/doc/unstable-book/src/associated-type-defaults.md index 6a44da41e5f..56cc8a5b306 100644 --- a/src/doc/unstable-book/src/associated-type-defaults.md +++ b/src/doc/unstable-book/src/associated-type-defaults.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29661] [#29661]: https://github.com/rust-lang/rust/issues/29661 +------------------------ + diff --git a/src/doc/unstable-book/src/attr-literals.md b/src/doc/unstable-book/src/attr-literals.md index 013191ce017..67eee214a4f 100644 --- a/src/doc/unstable-book/src/attr-literals.md +++ b/src/doc/unstable-book/src/attr-literals.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#34981] [#34981]: https://github.com/rust-lang/rust/issues/34981 +------------------------ + diff --git a/src/doc/unstable-book/src/box-patterns.md b/src/doc/unstable-book/src/box-patterns.md index 27c434f7d27..86346364a71 100644 --- a/src/doc/unstable-book/src/box-patterns.md +++ b/src/doc/unstable-book/src/box-patterns.md @@ -4,5 +4,29 @@ The tracking issue for this feature is: [#29641] [#29641]: https://github.com/rust-lang/rust/issues/29641 +See also [`box_syntax`](box-syntax.html) +------------------------ +Box patterns let you match on `Box`s: + + +```rust +#![feature(box_patterns)] + +fn main() { + let b = Some(Box::new(5)); + match b { + Some(box n) if n < 0 => { + println!("Box contains negative number {}", n); + }, + Some(box n) if n >= 0 => { + println!("Box contains non-negative number {}", n); + }, + None => { + println!("No box"); + }, + _ => unreachable!() + } +} +``` diff --git a/src/doc/unstable-book/src/box-syntax.md b/src/doc/unstable-book/src/box-syntax.md index 881d0140473..47aade0d045 100644 --- a/src/doc/unstable-book/src/box-syntax.md +++ b/src/doc/unstable-book/src/box-syntax.md @@ -4,5 +4,19 @@ The tracking issue for this feature is: [#27779] [#27779]: https://github.com/rust-lang/rust/issues/27779 +See also [`box_patterns`](box-patterns.html) +------------------------ +Currently the only stable way to create a `Box` is via the `Box::new` method. +Also it is not possible in stable Rust to destructure a `Box` in a match +pattern. The unstable `box` keyword can be used to create a `Box`. An example +usage would be: + +```rust +#![feature(box_syntax)] + +fn main() { + let b = box 5; +} +``` diff --git a/src/doc/unstable-book/src/cfg-target-feature.md b/src/doc/unstable-book/src/cfg-target-feature.md index 930104acc12..ddd88bdc2cb 100644 --- a/src/doc/unstable-book/src/cfg-target-feature.md +++ b/src/doc/unstable-book/src/cfg-target-feature.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29717] [#29717]: https://github.com/rust-lang/rust/issues/29717 +------------------------ + diff --git a/src/doc/unstable-book/src/cfg-target-has-atomic.md b/src/doc/unstable-book/src/cfg-target-has-atomic.md index 36a0ab0aef7..7496e42e1cd 100644 --- a/src/doc/unstable-book/src/cfg-target-has-atomic.md +++ b/src/doc/unstable-book/src/cfg-target-has-atomic.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#32976] [#32976]: https://github.com/rust-lang/rust/issues/32976 +------------------------ + diff --git a/src/doc/unstable-book/src/cfg-target-thread-local.md b/src/doc/unstable-book/src/cfg-target-thread-local.md index 7f139a733cc..a5adb38db3d 100644 --- a/src/doc/unstable-book/src/cfg-target-thread-local.md +++ b/src/doc/unstable-book/src/cfg-target-thread-local.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29594] [#29594]: https://github.com/rust-lang/rust/issues/29594 +------------------------ + diff --git a/src/doc/unstable-book/src/cfg-target-vendor.md b/src/doc/unstable-book/src/cfg-target-vendor.md index 930104acc12..ddd88bdc2cb 100644 --- a/src/doc/unstable-book/src/cfg-target-vendor.md +++ b/src/doc/unstable-book/src/cfg-target-vendor.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29717] [#29717]: https://github.com/rust-lang/rust/issues/29717 +------------------------ + diff --git a/src/doc/unstable-book/src/compiler-builtins.md b/src/doc/unstable-book/src/compiler-builtins.md index 886bd31a0e3..3ec3cba257a 100644 --- a/src/doc/unstable-book/src/compiler-builtins.md +++ b/src/doc/unstable-book/src/compiler-builtins.md @@ -2,3 +2,5 @@ The tracking issue for this feature is: None. +------------------------ + diff --git a/src/doc/unstable-book/src/concat-idents.md b/src/doc/unstable-book/src/concat-idents.md index e8edc12d663..c9a48293dba 100644 --- a/src/doc/unstable-book/src/concat-idents.md +++ b/src/doc/unstable-book/src/concat-idents.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29599] [#29599]: https://github.com/rust-lang/rust/issues/29599 +------------------------ + diff --git a/src/doc/unstable-book/src/conservative-impl-trait.md b/src/doc/unstable-book/src/conservative-impl-trait.md index 91221aa45b7..7d8bda439bd 100644 --- a/src/doc/unstable-book/src/conservative-impl-trait.md +++ b/src/doc/unstable-book/src/conservative-impl-trait.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#34511] [#34511]: https://github.com/rust-lang/rust/issues/34511 +------------------------ + diff --git a/src/doc/unstable-book/src/const-fn.md b/src/doc/unstable-book/src/const-fn.md index 4bd0933f7be..9b7942c408a 100644 --- a/src/doc/unstable-book/src/const-fn.md +++ b/src/doc/unstable-book/src/const-fn.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#24111] [#24111]: https://github.com/rust-lang/rust/issues/24111 +------------------------ + diff --git a/src/doc/unstable-book/src/const-indexing.md b/src/doc/unstable-book/src/const-indexing.md index 30e093befd0..bd92b0b1b47 100644 --- a/src/doc/unstable-book/src/const-indexing.md +++ b/src/doc/unstable-book/src/const-indexing.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29947] [#29947]: https://github.com/rust-lang/rust/issues/29947 +------------------------ + diff --git a/src/doc/unstable-book/src/custom-attribute.md b/src/doc/unstable-book/src/custom-attribute.md index 0080bb79a9e..838f09670d2 100644 --- a/src/doc/unstable-book/src/custom-attribute.md +++ b/src/doc/unstable-book/src/custom-attribute.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29642] [#29642]: https://github.com/rust-lang/rust/issues/29642 +------------------------ + diff --git a/src/doc/unstable-book/src/custom-derive.md b/src/doc/unstable-book/src/custom-derive.md index 999cb7bf521..d5fdd2b708b 100644 --- a/src/doc/unstable-book/src/custom-derive.md +++ b/src/doc/unstable-book/src/custom-derive.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29644] [#29644]: https://github.com/rust-lang/rust/issues/29644 +------------------------ + diff --git a/src/doc/unstable-book/src/default-type-parameter-fallback.md b/src/doc/unstable-book/src/default-type-parameter-fallback.md index 373d18b7ffb..fd16dbf8985 100644 --- a/src/doc/unstable-book/src/default-type-parameter-fallback.md +++ b/src/doc/unstable-book/src/default-type-parameter-fallback.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#27336] [#27336]: https://github.com/rust-lang/rust/issues/27336 +------------------------ + diff --git a/src/doc/unstable-book/src/drop-types-in-const.md b/src/doc/unstable-book/src/drop-types-in-const.md index 4b535dfc1da..b3367d0df44 100644 --- a/src/doc/unstable-book/src/drop-types-in-const.md +++ b/src/doc/unstable-book/src/drop-types-in-const.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#33156] [#33156]: https://github.com/rust-lang/rust/issues/33156 +------------------------ + diff --git a/src/doc/unstable-book/src/dropck-eyepatch.md b/src/doc/unstable-book/src/dropck-eyepatch.md index 2f1e5936c06..2f189e9b645 100644 --- a/src/doc/unstable-book/src/dropck-eyepatch.md +++ b/src/doc/unstable-book/src/dropck-eyepatch.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#34761] [#34761]: https://github.com/rust-lang/rust/issues/34761 +------------------------ + diff --git a/src/doc/unstable-book/src/dropck-parametricity.md b/src/doc/unstable-book/src/dropck-parametricity.md index c00cd4c5cf6..c5ae721954b 100644 --- a/src/doc/unstable-book/src/dropck-parametricity.md +++ b/src/doc/unstable-book/src/dropck-parametricity.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#28498] [#28498]: https://github.com/rust-lang/rust/issues/28498 +------------------------ + diff --git a/src/doc/unstable-book/src/exclusive-range-pattern.md b/src/doc/unstable-book/src/exclusive-range-pattern.md index 05b8db99bb7..b669ce83132 100644 --- a/src/doc/unstable-book/src/exclusive-range-pattern.md +++ b/src/doc/unstable-book/src/exclusive-range-pattern.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#37854] [#37854]: https://github.com/rust-lang/rust/issues/37854 +------------------------ + diff --git a/src/doc/unstable-book/src/field-init-shorthand.md b/src/doc/unstable-book/src/field-init-shorthand.md index 20b3d17b085..e737dbaa4ec 100644 --- a/src/doc/unstable-book/src/field-init-shorthand.md +++ b/src/doc/unstable-book/src/field-init-shorthand.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#37340] [#37340]: https://github.com/rust-lang/rust/issues/37340 +------------------------ + diff --git a/src/doc/unstable-book/src/fundamental.md b/src/doc/unstable-book/src/fundamental.md index 2ab978cb648..a068dadf95d 100644 --- a/src/doc/unstable-book/src/fundamental.md +++ b/src/doc/unstable-book/src/fundamental.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29635] [#29635]: https://github.com/rust-lang/rust/issues/29635 +------------------------ + diff --git a/src/doc/unstable-book/src/generic-param-attrs.md b/src/doc/unstable-book/src/generic-param-attrs.md index 7c75231a655..ba49c850e4d 100644 --- a/src/doc/unstable-book/src/generic-param-attrs.md +++ b/src/doc/unstable-book/src/generic-param-attrs.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#34761] [#34761]: https://github.com/rust-lang/rust/issues/34761 +------------------------ + diff --git a/src/doc/unstable-book/src/i128-type.md b/src/doc/unstable-book/src/i128-type.md index f3f32176546..ffcf45feb2a 100644 --- a/src/doc/unstable-book/src/i128-type.md +++ b/src/doc/unstable-book/src/i128-type.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#35118] [#35118]: https://github.com/rust-lang/rust/issues/35118 +------------------------ + diff --git a/src/doc/unstable-book/src/inclusive-range-syntax.md b/src/doc/unstable-book/src/inclusive-range-syntax.md index f7f29f474ae..74d85536399 100644 --- a/src/doc/unstable-book/src/inclusive-range-syntax.md +++ b/src/doc/unstable-book/src/inclusive-range-syntax.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#28237] [#28237]: https://github.com/rust-lang/rust/issues/28237 +------------------------ + diff --git a/src/doc/unstable-book/src/intrinsics.md b/src/doc/unstable-book/src/intrinsics.md index 65331da8567..bc35c2a0305 100644 --- a/src/doc/unstable-book/src/intrinsics.md +++ b/src/doc/unstable-book/src/intrinsics.md @@ -1,3 +1,30 @@ # `intrinsics` The tracking issue for this feature is: None. + +Intrinsics are never intended to be stable directly, but intrinsics are often +exported in some sort of stable manner. Prefer using the stable interfaces to +the intrinsic directly when you can. + +------------------------ + + +These are imported as if they were FFI functions, with the special +`rust-intrinsic` ABI. For example, if one was in a freestanding +context, but wished to be able to `transmute` between types, and +perform efficient pointer arithmetic, one would import those functions +via a declaration like + +```rust +#![feature(intrinsics)] +# fn main() {} + +extern "rust-intrinsic" { + fn transmute(x: T) -> U; + + fn offset(dst: *const T, offset: isize) -> *const T; +} +``` + +As with any other FFI functions, these are always `unsafe` to call. + diff --git a/src/doc/unstable-book/src/lang-items.md b/src/doc/unstable-book/src/lang-items.md index de8ff6b076b..375b8bd6b82 100644 --- a/src/doc/unstable-book/src/lang-items.md +++ b/src/doc/unstable-book/src/lang-items.md @@ -2,3 +2,218 @@ The tracking issue for this feature is: None. +------------------------ + +The `rustc` compiler has certain pluggable operations, that is, +functionality that isn't hard-coded into the language, but is +implemented in libraries, with a special marker to tell the compiler +it exists. The marker is the attribute `#[lang = "..."]` and there are +various different values of `...`, i.e. various different 'lang +items'. + +For example, `Box` pointers require two lang items, one for allocation +and one for deallocation. A freestanding program that uses the `Box` +sugar for dynamic allocations via `malloc` and `free`: + +```rust,ignore +#![feature(lang_items, box_syntax, start, libc, core_intrinsics)] +#![no_std] +use core::intrinsics; + +extern crate libc; + +#[lang = "owned_box"] +pub struct Box(*mut T); + +#[lang = "exchange_malloc"] +unsafe fn allocate(size: usize, _align: usize) -> *mut u8 { + let p = libc::malloc(size as libc::size_t) as *mut u8; + + // Check if `malloc` failed: + if p as usize == 0 { + intrinsics::abort(); + } + + p +} + +#[lang = "exchange_free"] +unsafe fn deallocate(ptr: *mut u8, _size: usize, _align: usize) { + libc::free(ptr as *mut libc::c_void) +} + +#[lang = "box_free"] +unsafe fn box_free(ptr: *mut T) { + deallocate(ptr as *mut u8, ::core::mem::size_of_val(&*ptr), ::core::mem::align_of_val(&*ptr)); +} + +#[start] +fn main(argc: isize, argv: *const *const u8) -> isize { + let x = box 1; + + 0 +} + +#[lang = "eh_personality"] extern fn rust_eh_personality() {} +#[lang = "panic_fmt"] extern fn rust_begin_panic() -> ! { unsafe { intrinsics::abort() } } +# #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {} +# #[no_mangle] pub extern fn rust_eh_register_frames () {} +# #[no_mangle] pub extern fn rust_eh_unregister_frames () {} +``` + +Note the use of `abort`: the `exchange_malloc` lang item is assumed to +return a valid pointer, and so needs to do the check internally. + +Other features provided by lang items include: + +- overloadable operators via traits: the traits corresponding to the + `==`, `<`, dereferencing (`*`) and `+` (etc.) operators are all + marked with lang items; those specific four are `eq`, `ord`, + `deref`, and `add` respectively. +- stack unwinding and general failure; the `eh_personality`, + `eh_unwind_resume`, `fail` and `fail_bounds_checks` lang items. +- the traits in `std::marker` used to indicate types of + various kinds; lang items `send`, `sync` and `copy`. +- the marker types and variance indicators found in + `std::marker`; lang items `covariant_type`, + `contravariant_lifetime`, etc. + +Lang items are loaded lazily by the compiler; e.g. if one never uses +`Box` then there is no need to define functions for `exchange_malloc` +and `exchange_free`. `rustc` will emit an error when an item is needed +but not found in the current crate or any that it depends on. + +Most lang items are defined by `libcore`, but if you're trying to build +an executable without the standard library, you'll run into the need +for lang items. The rest of this page focuses on this use-case, even though +lang items are a bit broader than that. + +### Using libc + +In order to build a `#[no_std]` executable we will need libc as a dependency. +We can specify this using our `Cargo.toml` file: + +```toml +[dependencies] +libc = { version = "0.2.14", default-features = false } +``` + +Note that the default features have been disabled. This is a critical step - +**the default features of libc include the standard library and so must be +disabled.** + +### Writing an executable without stdlib + +Controlling the entry point is possible in two ways: the `#[start]` attribute, +or overriding the default shim for the C `main` function with your own. + +The function marked `#[start]` is passed the command line parameters +in the same format as C: + +```rust,ignore +#![feature(lang_items, core_intrinsics)] +#![feature(start)] +#![no_std] +use core::intrinsics; + +// Pull in the system libc library for what crt0.o likely requires. +extern crate libc; + +// Entry point for this program. +#[start] +fn start(_argc: isize, _argv: *const *const u8) -> isize { + 0 +} + +// These functions are used by the compiler, but not +// for a bare-bones hello world. These are normally +// provided by libstd. +#[lang = "eh_personality"] +#[no_mangle] +pub extern fn rust_eh_personality() { +} + +// This function may be needed based on the compilation target. +#[lang = "eh_unwind_resume"] +#[no_mangle] +pub extern fn rust_eh_unwind_resume() { +} + +#[lang = "panic_fmt"] +#[no_mangle] +pub extern fn rust_begin_panic(_msg: core::fmt::Arguments, + _file: &'static str, + _line: u32) -> ! { + unsafe { intrinsics::abort() } +} +``` + +To override the compiler-inserted `main` shim, one has to disable it +with `#![no_main]` and then create the appropriate symbol with the +correct ABI and the correct name, which requires overriding the +compiler's name mangling too: + +```rust,ignore +#![feature(lang_items, core_intrinsics)] +#![feature(start)] +#![no_std] +#![no_main] +use core::intrinsics; + +// Pull in the system libc library for what crt0.o likely requires. +extern crate libc; + +// Entry point for this program. +#[no_mangle] // ensure that this symbol is called `main` in the output +pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 { + 0 +} + +// These functions are used by the compiler, but not +// for a bare-bones hello world. These are normally +// provided by libstd. +#[lang = "eh_personality"] +#[no_mangle] +pub extern fn rust_eh_personality() { +} + +// This function may be needed based on the compilation target. +#[lang = "eh_unwind_resume"] +#[no_mangle] +pub extern fn rust_eh_unwind_resume() { +} + +#[lang = "panic_fmt"] +#[no_mangle] +pub extern fn rust_begin_panic(_msg: core::fmt::Arguments, + _file: &'static str, + _line: u32) -> ! { + unsafe { intrinsics::abort() } +} +``` + +## More about the language items + +The compiler currently makes a few assumptions about symbols which are +available in the executable to call. Normally these functions are provided by +the standard library, but without it you must define your own. These symbols +are called "language items", and they each have an internal name, and then a +signature that an implementation must conform to. + +The first of these functions, `rust_eh_personality`, is used by the failure +mechanisms of the compiler. This is often mapped to GCC's personality function +(see the [libstd implementation][unwind] for more information), but crates +which do not trigger a panic can be assured that this function is never +called. The language item's name is `eh_personality`. + +[unwind]: https://github.com/rust-lang/rust/blob/master/src/libpanic_unwind/gcc.rs + +The second function, `rust_begin_panic`, is also used by the failure mechanisms of the +compiler. When a panic happens, this controls the message that's displayed on +the screen. While the language item's name is `panic_fmt`, the symbol name is +`rust_begin_panic`. + +A third function, `rust_eh_unwind_resume`, is also needed if the `custom_unwind_resume` +flag is set in the options of the compilation target. It allows customizing the +process of resuming unwind at the end of the landing pads. The language item's name +is `eh_unwind_resume`. diff --git a/src/doc/unstable-book/src/link-args.md b/src/doc/unstable-book/src/link-args.md index a887242f1aa..2507197661a 100644 --- a/src/doc/unstable-book/src/link-args.md +++ b/src/doc/unstable-book/src/link-args.md @@ -4,5 +4,29 @@ The tracking issue for this feature is: [#29596] [#29596]: https://github.com/rust-lang/rust/issues/29596 +------------------------ +You can tell `rustc` how to customize linking, and that is via the `link_args` +attribute. This attribute is applied to `extern` blocks and specifies raw flags +which need to get passed to the linker when producing an artifact. An example +usage would be: +```rust,no_run +#![feature(link_args)] + +#[link_args = "-foo -bar -baz"] +extern {} +# fn main() {} +``` + +Note that this feature is currently hidden behind the `feature(link_args)` gate +because this is not a sanctioned way of performing linking. Right now `rustc` +shells out to the system linker (`gcc` on most systems, `link.exe` on MSVC), so +it makes sense to provide extra command line arguments, but this will not +always be the case. In the future `rustc` may use LLVM directly to link native +libraries, in which case `link_args` will have no meaning. You can achieve the +same effect as the `link_args` attribute with the `-C link-args` argument to +`rustc`. + +It is highly recommended to *not* use this attribute, and rather use the more +formal `#[link(...)]` attribute on `extern` blocks instead. diff --git a/src/doc/unstable-book/src/link-cfg.md b/src/doc/unstable-book/src/link-cfg.md index 4d6dd259efe..7393d0628e4 100644 --- a/src/doc/unstable-book/src/link-cfg.md +++ b/src/doc/unstable-book/src/link-cfg.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#37406] [#37406]: https://github.com/rust-lang/rust/issues/37406 +------------------------ + diff --git a/src/doc/unstable-book/src/link-llvm-intrinsics.md b/src/doc/unstable-book/src/link-llvm-intrinsics.md index aee4e0a40d5..ba639cb57fc 100644 --- a/src/doc/unstable-book/src/link-llvm-intrinsics.md +++ b/src/doc/unstable-book/src/link-llvm-intrinsics.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29602] [#29602]: https://github.com/rust-lang/rust/issues/29602 +------------------------ + diff --git a/src/doc/unstable-book/src/linkage.md b/src/doc/unstable-book/src/linkage.md index 3deac364d75..5773d28a00e 100644 --- a/src/doc/unstable-book/src/linkage.md +++ b/src/doc/unstable-book/src/linkage.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29603] [#29603]: https://github.com/rust-lang/rust/issues/29603 +------------------------ + diff --git a/src/doc/unstable-book/src/log-syntax.md b/src/doc/unstable-book/src/log-syntax.md index f61bb49b78c..b13f5ccfd91 100644 --- a/src/doc/unstable-book/src/log-syntax.md +++ b/src/doc/unstable-book/src/log-syntax.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29598] [#29598]: https://github.com/rust-lang/rust/issues/29598 +------------------------ + diff --git a/src/doc/unstable-book/src/loop-break-value.md b/src/doc/unstable-book/src/loop-break-value.md index 16c0618cbe0..54d6e62ce4c 100644 --- a/src/doc/unstable-book/src/loop-break-value.md +++ b/src/doc/unstable-book/src/loop-break-value.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#37339] [#37339]: https://github.com/rust-lang/rust/issues/37339 +------------------------ + diff --git a/src/doc/unstable-book/src/macro-reexport.md b/src/doc/unstable-book/src/macro-reexport.md index 0ba5a56fc47..32ffa3b4c31 100644 --- a/src/doc/unstable-book/src/macro-reexport.md +++ b/src/doc/unstable-book/src/macro-reexport.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29638] [#29638]: https://github.com/rust-lang/rust/issues/29638 +------------------------ + diff --git a/src/doc/unstable-book/src/main.md b/src/doc/unstable-book/src/main.md index 795db9bd1ab..579aabfff88 100644 --- a/src/doc/unstable-book/src/main.md +++ b/src/doc/unstable-book/src/main.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29634] [#29634]: https://github.com/rust-lang/rust/issues/29634 +------------------------ + diff --git a/src/doc/unstable-book/src/naked-functions.md b/src/doc/unstable-book/src/naked-functions.md index 896a83237a5..e56ce4770aa 100644 --- a/src/doc/unstable-book/src/naked-functions.md +++ b/src/doc/unstable-book/src/naked-functions.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#32408] [#32408]: https://github.com/rust-lang/rust/issues/32408 +------------------------ + diff --git a/src/doc/unstable-book/src/needs-allocator.md b/src/doc/unstable-book/src/needs-allocator.md index 14fb4b3782f..22aa10b2183 100644 --- a/src/doc/unstable-book/src/needs-allocator.md +++ b/src/doc/unstable-book/src/needs-allocator.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#27389] [#27389]: https://github.com/rust-lang/rust/issues/27389 +------------------------ + diff --git a/src/doc/unstable-book/src/needs-panic-runtime.md b/src/doc/unstable-book/src/needs-panic-runtime.md index ecaeaaab047..627c946c1bb 100644 --- a/src/doc/unstable-book/src/needs-panic-runtime.md +++ b/src/doc/unstable-book/src/needs-panic-runtime.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#32837] [#32837]: https://github.com/rust-lang/rust/issues/32837 +------------------------ + diff --git a/src/doc/unstable-book/src/never-type.md b/src/doc/unstable-book/src/never-type.md index 26db551e850..3b3729a4b21 100644 --- a/src/doc/unstable-book/src/never-type.md +++ b/src/doc/unstable-book/src/never-type.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#35121] [#35121]: https://github.com/rust-lang/rust/issues/35121 +------------------------ + diff --git a/src/doc/unstable-book/src/no-core.md b/src/doc/unstable-book/src/no-core.md index 363d0f37d98..6238753447c 100644 --- a/src/doc/unstable-book/src/no-core.md +++ b/src/doc/unstable-book/src/no-core.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29639] [#29639]: https://github.com/rust-lang/rust/issues/29639 +------------------------ + diff --git a/src/doc/unstable-book/src/no-debug.md b/src/doc/unstable-book/src/no-debug.md index 5fcf7e142cf..7536ed9d4e1 100644 --- a/src/doc/unstable-book/src/no-debug.md +++ b/src/doc/unstable-book/src/no-debug.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29721] [#29721]: https://github.com/rust-lang/rust/issues/29721 +------------------------ + diff --git a/src/doc/unstable-book/src/non-ascii-idents.md b/src/doc/unstable-book/src/non-ascii-idents.md index 9bd2609aaf7..f426022ab3a 100644 --- a/src/doc/unstable-book/src/non-ascii-idents.md +++ b/src/doc/unstable-book/src/non-ascii-idents.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#28979] [#28979]: https://github.com/rust-lang/rust/issues/28979 +------------------------ + diff --git a/src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md b/src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md index baa5024357d..d8ac520fcb5 100644 --- a/src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md +++ b/src/doc/unstable-book/src/omit-gdb-pretty-printer-section.md @@ -2,3 +2,5 @@ The tracking issue for this feature is: None. +------------------------ + diff --git a/src/doc/unstable-book/src/on-unimplemented.md b/src/doc/unstable-book/src/on-unimplemented.md index 6b4a4268195..81f284d0a6a 100644 --- a/src/doc/unstable-book/src/on-unimplemented.md +++ b/src/doc/unstable-book/src/on-unimplemented.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29628] [#29628]: https://github.com/rust-lang/rust/issues/29628 +------------------------ + diff --git a/src/doc/unstable-book/src/optin-builtin-traits.md b/src/doc/unstable-book/src/optin-builtin-traits.md index 06d0e553b8b..0b2d60accd5 100644 --- a/src/doc/unstable-book/src/optin-builtin-traits.md +++ b/src/doc/unstable-book/src/optin-builtin-traits.md @@ -4,5 +4,6 @@ The tracking issue for this feature is: [#13231] [#13231]: https://github.com/rust-lang/rust/issues/13231 +------------------------ diff --git a/src/doc/unstable-book/src/panic-runtime.md b/src/doc/unstable-book/src/panic-runtime.md index 1d4cca0bc2f..65b067e8296 100644 --- a/src/doc/unstable-book/src/panic-runtime.md +++ b/src/doc/unstable-book/src/panic-runtime.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#32837] [#32837]: https://github.com/rust-lang/rust/issues/32837 +------------------------ + diff --git a/src/doc/unstable-book/src/placement-in-syntax.md b/src/doc/unstable-book/src/placement-in-syntax.md index 92a56810e22..da12559a01b 100644 --- a/src/doc/unstable-book/src/placement-in-syntax.md +++ b/src/doc/unstable-book/src/placement-in-syntax.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#27779] [#27779]: https://github.com/rust-lang/rust/issues/27779 +------------------------ + diff --git a/src/doc/unstable-book/src/platform-intrinsics.md b/src/doc/unstable-book/src/platform-intrinsics.md index e895e0af5c4..377ac8f7342 100644 --- a/src/doc/unstable-book/src/platform-intrinsics.md +++ b/src/doc/unstable-book/src/platform-intrinsics.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#27731] [#27731]: https://github.com/rust-lang/rust/issues/27731 +------------------------ + diff --git a/src/doc/unstable-book/src/plugin-registrar.md b/src/doc/unstable-book/src/plugin-registrar.md index 024690e87a1..ca3738bd93f 100644 --- a/src/doc/unstable-book/src/plugin-registrar.md +++ b/src/doc/unstable-book/src/plugin-registrar.md @@ -4,5 +4,10 @@ The tracking issue for this feature is: [#29597] [#29597]: https://github.com/rust-lang/rust/issues/29597 +This feature is part of "compiler plugins." It will often be used with the +[`plugin`] and `rustc_private` features as well. For more details, see +their docs. +[`plugin`]: plugin.html +------------------------ diff --git a/src/doc/unstable-book/src/plugin.md b/src/doc/unstable-book/src/plugin.md index f676e9d98c3..1ec28bbcf03 100644 --- a/src/doc/unstable-book/src/plugin.md +++ b/src/doc/unstable-book/src/plugin.md @@ -5,4 +5,258 @@ The tracking issue for this feature is: [#29597] [#29597]: https://github.com/rust-lang/rust/issues/29597 +This feature is part of "compiler plugins." It will often be used with the +[`plugin_registrar`] and `rustc_private` features. +[`plugin_registrar`]: plugin-registrar.html + +------------------------ + +`rustc` can load compiler plugins, which are user-provided libraries that +extend the compiler's behavior with new syntax extensions, lint checks, etc. + +A plugin is a dynamic library crate with a designated *registrar* function that +registers extensions with `rustc`. Other crates can load these extensions using +the crate attribute `#![plugin(...)]`. See the +`rustc_plugin` documentation for more about the +mechanics of defining and loading a plugin. + +If present, arguments passed as `#![plugin(foo(... args ...))]` are not +interpreted by rustc itself. They are provided to the plugin through the +`Registry`'s `args` method. + +In the vast majority of cases, a plugin should *only* be used through +`#![plugin]` and not through an `extern crate` item. Linking a plugin would +pull in all of libsyntax and librustc as dependencies of your crate. This is +generally unwanted unless you are building another plugin. The +`plugin_as_library` lint checks these guidelines. + +The usual practice is to put compiler plugins in their own crate, separate from +any `macro_rules!` macros or ordinary Rust code meant to be used by consumers +of a library. + +# Syntax extensions + +Plugins can extend Rust's syntax in various ways. One kind of syntax extension +is the procedural macro. These are invoked the same way as [ordinary +macros](macros.html), but the expansion is performed by arbitrary Rust +code that manipulates syntax trees at +compile time. + +Let's write a plugin +[`roman_numerals.rs`](https://github.com/rust-lang/rust/blob/master/src/test/run-pass-fulldeps/auxiliary/roman_numerals.rs) +that implements Roman numeral integer literals. + +```rust,ignore +#![crate_type="dylib"] +#![feature(plugin_registrar, rustc_private)] + +extern crate syntax; +extern crate rustc; +extern crate rustc_plugin; + +use syntax::parse::token; +use syntax::tokenstream::TokenTree; +use syntax::ext::base::{ExtCtxt, MacResult, DummyResult, MacEager}; +use syntax::ext::build::AstBuilder; // A trait for expr_usize. +use syntax::ext::quote::rt::Span; +use rustc_plugin::Registry; + +fn expand_rn(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree]) + -> Box { + + static NUMERALS: &'static [(&'static str, usize)] = &[ + ("M", 1000), ("CM", 900), ("D", 500), ("CD", 400), + ("C", 100), ("XC", 90), ("L", 50), ("XL", 40), + ("X", 10), ("IX", 9), ("V", 5), ("IV", 4), + ("I", 1)]; + + if args.len() != 1 { + cx.span_err( + sp, + &format!("argument should be a single identifier, but got {} arguments", args.len())); + return DummyResult::any(sp); + } + + let text = match args[0] { + TokenTree::Token(_, token::Ident(s)) => s.to_string(), + _ => { + cx.span_err(sp, "argument should be a single identifier"); + return DummyResult::any(sp); + } + }; + + let mut text = &*text; + let mut total = 0; + while !text.is_empty() { + match NUMERALS.iter().find(|&&(rn, _)| text.starts_with(rn)) { + Some(&(rn, val)) => { + total += val; + text = &text[rn.len()..]; + } + None => { + cx.span_err(sp, "invalid Roman numeral"); + return DummyResult::any(sp); + } + } + } + + MacEager::expr(cx.expr_usize(sp, total)) +} + +#[plugin_registrar] +pub fn plugin_registrar(reg: &mut Registry) { + reg.register_macro("rn", expand_rn); +} +``` + +Then we can use `rn!()` like any other macro: + +```rust,ignore +#![feature(plugin)] +#![plugin(roman_numerals)] + +fn main() { + assert_eq!(rn!(MMXV), 2015); +} +``` + +The advantages over a simple `fn(&str) -> u32` are: + +* The (arbitrarily complex) conversion is done at compile time. +* Input validation is also performed at compile time. +* It can be extended to allow use in patterns, which effectively gives + a way to define new literal syntax for any data type. + +In addition to procedural macros, you can define new +[`derive`](../reference.html#derive)-like attributes and other kinds of +extensions. See `Registry::register_syntax_extension` and the `SyntaxExtension` +enum. For a more involved macro example, see +[`regex_macros`](https://github.com/rust-lang/regex/blob/master/regex_macros/src/lib.rs). + + +## Tips and tricks + +Some of the [macro debugging tips](macros.html#Debugging%20macro%20code) are applicable. + +You can use `syntax::parse` to turn token trees into +higher-level syntax elements like expressions: + +```rust,ignore +fn expand_foo(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree]) + -> Box { + + let mut parser = cx.new_parser_from_tts(args); + + let expr: P = parser.parse_expr(); +``` + +Looking through [`libsyntax` parser +code](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/parser.rs) +will give you a feel for how the parsing infrastructure works. + +Keep the `Span`s of everything you parse, for better error reporting. You can +wrap `Spanned` around your custom data structures. + +Calling `ExtCtxt::span_fatal` will immediately abort compilation. It's better to +instead call `ExtCtxt::span_err` and return `DummyResult` so that the compiler +can continue and find further errors. + +To print syntax fragments for debugging, you can use `span_note` together with +`syntax::print::pprust::*_to_string`. + +The example above produced an integer literal using `AstBuilder::expr_usize`. +As an alternative to the `AstBuilder` trait, `libsyntax` provides a set of +quasiquote macros. They are undocumented and very rough around the edges. +However, the implementation may be a good starting point for an improved +quasiquote as an ordinary plugin library. + + +# Lint plugins + +Plugins can extend [Rust's lint +infrastructure](../reference.html#lint-check-attributes) with additional checks for +code style, safety, etc. Now let's write a plugin +[`lint_plugin_test.rs`](https://github.com/rust-lang/rust/blob/master/src/test/run-pass-fulldeps/auxiliary/lint_plugin_test.rs) +that warns about any item named `lintme`. + +```rust,ignore +#![feature(plugin_registrar)] +#![feature(box_syntax, rustc_private)] + +extern crate syntax; + +// Load rustc as a plugin to get macros +#[macro_use] +extern crate rustc; +extern crate rustc_plugin; + +use rustc::lint::{EarlyContext, LintContext, LintPass, EarlyLintPass, + EarlyLintPassObject, LintArray}; +use rustc_plugin::Registry; +use syntax::ast; + +declare_lint!(TEST_LINT, Warn, "Warn about items named 'lintme'"); + +struct Pass; + +impl LintPass for Pass { + fn get_lints(&self) -> LintArray { + lint_array!(TEST_LINT) + } +} + +impl EarlyLintPass for Pass { + fn check_item(&mut self, cx: &EarlyContext, it: &ast::Item) { + if it.ident.name.as_str() == "lintme" { + cx.span_lint(TEST_LINT, it.span, "item is named 'lintme'"); + } + } +} + +#[plugin_registrar] +pub fn plugin_registrar(reg: &mut Registry) { + reg.register_early_lint_pass(box Pass as EarlyLintPassObject); +} +``` + +Then code like + +```rust,ignore +#![plugin(lint_plugin_test)] + +fn lintme() { } +``` + +will produce a compiler warning: + +```txt +foo.rs:4:1: 4:16 warning: item is named 'lintme', #[warn(test_lint)] on by default +foo.rs:4 fn lintme() { } + ^~~~~~~~~~~~~~~ +``` + +The components of a lint plugin are: + +* one or more `declare_lint!` invocations, which define static `Lint` structs; + +* a struct holding any state needed by the lint pass (here, none); + +* a `LintPass` + implementation defining how to check each syntax element. A single + `LintPass` may call `span_lint` for several different `Lint`s, but should + register them all through the `get_lints` method. + +Lint passes are syntax traversals, but they run at a late stage of compilation +where type information is available. `rustc`'s [built-in +lints](https://github.com/rust-lang/rust/blob/master/src/librustc/lint/builtin.rs) +mostly use the same infrastructure as lint plugins, and provide examples of how +to access type information. + +Lints defined by plugins are controlled by the usual [attributes and compiler +flags](../reference.html#lint-check-attributes), e.g. `#[allow(test_lint)]` or +`-A test-lint`. These identifiers are derived from the first argument to +`declare_lint!`, with appropriate case and punctuation conversion. + +You can run `rustc -W help foo.rs` to see a list of lints known to `rustc`, +including those provided by plugins loaded by `foo.rs`. diff --git a/src/doc/unstable-book/src/prelude-import.md b/src/doc/unstable-book/src/prelude-import.md index 6bb093bfbc7..75dae5cfb74 100644 --- a/src/doc/unstable-book/src/prelude-import.md +++ b/src/doc/unstable-book/src/prelude-import.md @@ -2,3 +2,5 @@ The tracking issue for this feature is: None. +------------------------ + diff --git a/src/doc/unstable-book/src/proc-macro.md b/src/doc/unstable-book/src/proc-macro.md index 845a61eb22e..f8b53bd5a2f 100644 --- a/src/doc/unstable-book/src/proc-macro.md +++ b/src/doc/unstable-book/src/proc-macro.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#38356] [#38356]: https://github.com/rust-lang/rust/issues/38356 +------------------------ + diff --git a/src/doc/unstable-book/src/pub-restricted.md b/src/doc/unstable-book/src/pub-restricted.md index c15e5d5fdaf..730461813cb 100644 --- a/src/doc/unstable-book/src/pub-restricted.md +++ b/src/doc/unstable-book/src/pub-restricted.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#32409] [#32409]: https://github.com/rust-lang/rust/issues/32409 +------------------------ + diff --git a/src/doc/unstable-book/src/quote.md b/src/doc/unstable-book/src/quote.md index a596cc9add7..b4e078d920c 100644 --- a/src/doc/unstable-book/src/quote.md +++ b/src/doc/unstable-book/src/quote.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29601] [#29601]: https://github.com/rust-lang/rust/issues/29601 +------------------------ + diff --git a/src/doc/unstable-book/src/relaxed-adts.md b/src/doc/unstable-book/src/relaxed-adts.md index 274ea08f37a..170570e06a2 100644 --- a/src/doc/unstable-book/src/relaxed-adts.md +++ b/src/doc/unstable-book/src/relaxed-adts.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#35626] [#35626]: https://github.com/rust-lang/rust/issues/35626 +------------------------ + diff --git a/src/doc/unstable-book/src/repr-simd.md b/src/doc/unstable-book/src/repr-simd.md index cfb3c151098..c6f051e4fff 100644 --- a/src/doc/unstable-book/src/repr-simd.md +++ b/src/doc/unstable-book/src/repr-simd.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#27731] [#27731]: https://github.com/rust-lang/rust/issues/27731 +------------------------ + diff --git a/src/doc/unstable-book/src/rustc-attrs.md b/src/doc/unstable-book/src/rustc-attrs.md index f42d2dcf312..d1f18cead06 100644 --- a/src/doc/unstable-book/src/rustc-attrs.md +++ b/src/doc/unstable-book/src/rustc-attrs.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29642] [#29642]: https://github.com/rust-lang/rust/issues/29642 +------------------------ + diff --git a/src/doc/unstable-book/src/rustc-diagnostic-macros.md b/src/doc/unstable-book/src/rustc-diagnostic-macros.md index f48200abd76..0df6ca12089 100644 --- a/src/doc/unstable-book/src/rustc-diagnostic-macros.md +++ b/src/doc/unstable-book/src/rustc-diagnostic-macros.md @@ -2,3 +2,5 @@ The tracking issue for this feature is: None. +------------------------ + diff --git a/src/doc/unstable-book/src/sanitizer-runtime.md b/src/doc/unstable-book/src/sanitizer-runtime.md index a22ed342e20..f19504de58e 100644 --- a/src/doc/unstable-book/src/sanitizer-runtime.md +++ b/src/doc/unstable-book/src/sanitizer-runtime.md @@ -2,3 +2,5 @@ The tracking issue for this feature is: None. +------------------------ + diff --git a/src/doc/unstable-book/src/simd-ffi.md b/src/doc/unstable-book/src/simd-ffi.md index 1519def25c8..d85779c3d3d 100644 --- a/src/doc/unstable-book/src/simd-ffi.md +++ b/src/doc/unstable-book/src/simd-ffi.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#27731] [#27731]: https://github.com/rust-lang/rust/issues/27731 +------------------------ + diff --git a/src/doc/unstable-book/src/simd.md b/src/doc/unstable-book/src/simd.md index 56b1d3630c7..13c9722c524 100644 --- a/src/doc/unstable-book/src/simd.md +++ b/src/doc/unstable-book/src/simd.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#27731] [#27731]: https://github.com/rust-lang/rust/issues/27731 +------------------------ + diff --git a/src/doc/unstable-book/src/slice-patterns.md b/src/doc/unstable-book/src/slice-patterns.md index e075d0b5eed..1e9e1eaafda 100644 --- a/src/doc/unstable-book/src/slice-patterns.md +++ b/src/doc/unstable-book/src/slice-patterns.md @@ -4,5 +4,24 @@ The tracking issue for this feature is: [#23121] [#23121]: https://github.com/rust-lang/rust/issues/23121 +See also [`advanced_slice_patterns`](advanced-slice-patterns.html). +------------------------ + + +If you want to match against a slice or array, you can use `&` with the +`slice_patterns` feature: + +```rust +#![feature(slice_patterns)] + +fn main() { + let v = vec!["match_this", "1"]; + + match &v[..] { + &["match_this", second] => println!("The second element is {}", second), + _ => {}, + } +} +``` diff --git a/src/doc/unstable-book/src/specialization.md b/src/doc/unstable-book/src/specialization.md index 37b0d36f7b8..59f27343b66 100644 --- a/src/doc/unstable-book/src/specialization.md +++ b/src/doc/unstable-book/src/specialization.md @@ -2,7 +2,7 @@ The tracking issue for this feature is: [#31844] -[#31844]: https://github.com/rust-lang/rust/issues/31844 +------------------------ diff --git a/src/doc/unstable-book/src/staged-api.md b/src/doc/unstable-book/src/staged-api.md index c0406a27325..1409e570e88 100644 --- a/src/doc/unstable-book/src/staged-api.md +++ b/src/doc/unstable-book/src/staged-api.md @@ -2,3 +2,5 @@ The tracking issue for this feature is: None. +------------------------ + diff --git a/src/doc/unstable-book/src/start.md b/src/doc/unstable-book/src/start.md index 4f11cf5cae0..1ea6d59c78d 100644 --- a/src/doc/unstable-book/src/start.md +++ b/src/doc/unstable-book/src/start.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29633] [#29633]: https://github.com/rust-lang/rust/issues/29633 +------------------------ + diff --git a/src/doc/unstable-book/src/static-nobundle.md b/src/doc/unstable-book/src/static-nobundle.md index 9ba4bdee08c..97b9d71d433 100644 --- a/src/doc/unstable-book/src/static-nobundle.md +++ b/src/doc/unstable-book/src/static-nobundle.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#37403] [#37403]: https://github.com/rust-lang/rust/issues/37403 +------------------------ + diff --git a/src/doc/unstable-book/src/static-recursion.md b/src/doc/unstable-book/src/static-recursion.md index cc539a9d280..d419ea41c6f 100644 --- a/src/doc/unstable-book/src/static-recursion.md +++ b/src/doc/unstable-book/src/static-recursion.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29719] [#29719]: https://github.com/rust-lang/rust/issues/29719 +------------------------ + diff --git a/src/doc/unstable-book/src/stmt-expr-attributes.md b/src/doc/unstable-book/src/stmt-expr-attributes.md index 66b1af8f16c..71092fcf290 100644 --- a/src/doc/unstable-book/src/stmt-expr-attributes.md +++ b/src/doc/unstable-book/src/stmt-expr-attributes.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#15701] [#15701]: https://github.com/rust-lang/rust/issues/15701 +------------------------ + diff --git a/src/doc/unstable-book/src/struct-field-attributes.md b/src/doc/unstable-book/src/struct-field-attributes.md index f0f5ecdf04f..1a94562968d 100644 --- a/src/doc/unstable-book/src/struct-field-attributes.md +++ b/src/doc/unstable-book/src/struct-field-attributes.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#38814] [#38814]: https://github.com/rust-lang/rust/issues/38814 +------------------------ + diff --git a/src/doc/unstable-book/src/structural-match.md b/src/doc/unstable-book/src/structural-match.md index 6f23278ef27..b3ca26e6474 100644 --- a/src/doc/unstable-book/src/structural-match.md +++ b/src/doc/unstable-book/src/structural-match.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#31434] [#31434]: https://github.com/rust-lang/rust/issues/31434 +------------------------ + diff --git a/src/doc/unstable-book/src/target-feature.md b/src/doc/unstable-book/src/target-feature.md index 5702bf0e90b..85ab1ab39ef 100644 --- a/src/doc/unstable-book/src/target-feature.md +++ b/src/doc/unstable-book/src/target-feature.md @@ -2,3 +2,5 @@ The tracking issue for this feature is: None. +------------------------ + diff --git a/src/doc/unstable-book/src/test.md b/src/doc/unstable-book/src/test.md new file mode 100644 index 00000000000..6b4a3a677db --- /dev/null +++ b/src/doc/unstable-book/src/test.md @@ -0,0 +1,158 @@ +# `test` + +The tracking issue for this feature is: None. + +------------------------ + +The internals of the `test` crate are unstable, behind the `test` flag. The +most widely used part of the `test` crate are benchmark tests, which can test +the performance of your code. Let's make our `src/lib.rs` look like this +(comments elided): + +```rust,ignore +#![feature(test)] + +extern crate test; + +pub fn add_two(a: i32) -> i32 { + a + 2 +} + +#[cfg(test)] +mod tests { + use super::*; + use test::Bencher; + + #[test] + fn it_works() { + assert_eq!(4, add_two(2)); + } + + #[bench] + fn bench_add_two(b: &mut Bencher) { + b.iter(|| add_two(2)); + } +} +``` + +Note the `test` feature gate, which enables this unstable feature. + +We've imported the `test` crate, which contains our benchmarking support. +We have a new function as well, with the `bench` attribute. Unlike regular +tests, which take no arguments, benchmark tests take a `&mut Bencher`. This +`Bencher` provides an `iter` method, which takes a closure. This closure +contains the code we'd like to benchmark. + +We can run benchmark tests with `cargo bench`: + +```bash +$ cargo bench + Compiling adder v0.0.1 (file:///home/steve/tmp/adder) + Running target/release/adder-91b3e234d4ed382a + +running 2 tests +test tests::it_works ... ignored +test tests::bench_add_two ... bench: 1 ns/iter (+/- 0) + +test result: ok. 0 passed; 0 failed; 1 ignored; 1 measured +``` + +Our non-benchmark test was ignored. You may have noticed that `cargo bench` +takes a bit longer than `cargo test`. This is because Rust runs our benchmark +a number of times, and then takes the average. Because we're doing so little +work in this example, we have a `1 ns/iter (+/- 0)`, but this would show +the variance if there was one. + +Advice on writing benchmarks: + + +* Move setup code outside the `iter` loop; only put the part you want to measure inside +* Make the code do "the same thing" on each iteration; do not accumulate or change state +* Make the outer function idempotent too; the benchmark runner is likely to run + it many times +* Make the inner `iter` loop short and fast so benchmark runs are fast and the + calibrator can adjust the run-length at fine resolution +* Make the code in the `iter` loop do something simple, to assist in pinpointing + performance improvements (or regressions) + +## Gotcha: optimizations + +There's another tricky part to writing benchmarks: benchmarks compiled with +optimizations activated can be dramatically changed by the optimizer so that +the benchmark is no longer benchmarking what one expects. For example, the +compiler might recognize that some calculation has no external effects and +remove it entirely. + +```rust,ignore +#![feature(test)] + +extern crate test; +use test::Bencher; + +#[bench] +fn bench_xor_1000_ints(b: &mut Bencher) { + b.iter(|| { + (0..1000).fold(0, |old, new| old ^ new); + }); +} +``` + +gives the following results + +```text +running 1 test +test bench_xor_1000_ints ... bench: 0 ns/iter (+/- 0) + +test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured +``` + +The benchmarking runner offers two ways to avoid this. Either, the closure that +the `iter` method receives can return an arbitrary value which forces the +optimizer to consider the result used and ensures it cannot remove the +computation entirely. This could be done for the example above by adjusting the +`b.iter` call to + +```rust +# struct X; +# impl X { fn iter(&self, _: F) where F: FnMut() -> T {} } let b = X; +b.iter(|| { + // Note lack of `;` (could also use an explicit `return`). + (0..1000).fold(0, |old, new| old ^ new) +}); +``` + +Or, the other option is to call the generic `test::black_box` function, which +is an opaque "black box" to the optimizer and so forces it to consider any +argument as used. + +```rust +#![feature(test)] + +extern crate test; + +# fn main() { +# struct X; +# impl X { fn iter(&self, _: F) where F: FnMut() -> T {} } let b = X; +b.iter(|| { + let n = test::black_box(1000); + + (0..n).fold(0, |a, b| a ^ b) +}) +# } +``` + +Neither of these read or modify the value, and are very cheap for small values. +Larger values can be passed indirectly to reduce overhead (e.g. +`black_box(&huge_struct)`). + +Performing either of the above changes gives the following benchmarking results + +```text +running 1 test +test bench_xor_1000_ints ... bench: 131 ns/iter (+/- 3) + +test result: ok. 0 passed; 0 failed; 0 ignored; 1 measured +``` + +However, the optimizer can still modify a testcase in an undesirable manner +even when using either of the above. diff --git a/src/doc/unstable-book/src/thread-local.md b/src/doc/unstable-book/src/thread-local.md index 5109aa0c59c..83de2f9cd4b 100644 --- a/src/doc/unstable-book/src/thread-local.md +++ b/src/doc/unstable-book/src/thread-local.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29594] [#29594]: https://github.com/rust-lang/rust/issues/29594 +------------------------ + diff --git a/src/doc/unstable-book/src/trace-macros.md b/src/doc/unstable-book/src/trace-macros.md index 84efabd8502..856f1b0a7bb 100644 --- a/src/doc/unstable-book/src/trace-macros.md +++ b/src/doc/unstable-book/src/trace-macros.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29598] [#29598]: https://github.com/rust-lang/rust/issues/29598 +------------------------ + diff --git a/src/doc/unstable-book/src/type-ascription.md b/src/doc/unstable-book/src/type-ascription.md index 2decf512e91..3ebd0d87ccf 100644 --- a/src/doc/unstable-book/src/type-ascription.md +++ b/src/doc/unstable-book/src/type-ascription.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#23416] [#23416]: https://github.com/rust-lang/rust/issues/23416 +------------------------ + diff --git a/src/doc/unstable-book/src/unboxed-closures.md b/src/doc/unstable-book/src/unboxed-closures.md index 0d1eafb9e1d..2cbb436ce0b 100644 --- a/src/doc/unstable-book/src/unboxed-closures.md +++ b/src/doc/unstable-book/src/unboxed-closures.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#29625] [#29625]: https://github.com/rust-lang/rust/issues/29625 +------------------------ + diff --git a/src/doc/unstable-book/src/untagged-unions.md b/src/doc/unstable-book/src/untagged-unions.md index 748f49eec6a..6fe4f088ac2 100644 --- a/src/doc/unstable-book/src/untagged-unions.md +++ b/src/doc/unstable-book/src/untagged-unions.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#32836] [#32836]: https://github.com/rust-lang/rust/issues/32836 +------------------------ + diff --git a/src/doc/unstable-book/src/unwind-attributes.md b/src/doc/unstable-book/src/unwind-attributes.md index 5ba39afbcf8..0167a33b081 100644 --- a/src/doc/unstable-book/src/unwind-attributes.md +++ b/src/doc/unstable-book/src/unwind-attributes.md @@ -2,3 +2,5 @@ The tracking issue for this feature is: None. +------------------------ + diff --git a/src/doc/unstable-book/src/use-extern-macros.md b/src/doc/unstable-book/src/use-extern-macros.md index 120e00b2551..bc614911502 100644 --- a/src/doc/unstable-book/src/use-extern-macros.md +++ b/src/doc/unstable-book/src/use-extern-macros.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#35896] [#35896]: https://github.com/rust-lang/rust/issues/35896 +------------------------ + diff --git a/src/doc/unstable-book/src/windows-subsystem.md b/src/doc/unstable-book/src/windows-subsystem.md index 78b040c0f26..80583352fbf 100644 --- a/src/doc/unstable-book/src/windows-subsystem.md +++ b/src/doc/unstable-book/src/windows-subsystem.md @@ -4,5 +4,7 @@ The tracking issue for this feature is: [#37499] [#37499]: https://github.com/rust-lang/rust/issues/37499 +------------------------ + -- cgit 1.4.1-3-g733a5 From 5f325e918df85472a5919c373e9aed0605fb51c8 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 20 Feb 2017 17:25:33 -0500 Subject: fix some links --- src/doc/book/src/README.md | 2 -- src/doc/book/src/casting-between-types.md | 9 +++------ src/doc/book/src/conditional-compilation.md | 5 +---- src/doc/book/src/macros.md | 9 --------- src/doc/book/src/unsafe.md | 2 +- src/doc/book/src/using-rust-without-the-standard-library.md | 2 +- src/doc/unstable-book/src/alloc-jemalloc.md | 2 +- src/doc/unstable-book/src/alloc-system.md | 2 +- src/doc/unstable-book/src/plugin.md | 4 ++-- 9 files changed, 10 insertions(+), 27 deletions(-) diff --git a/src/doc/book/src/README.md b/src/doc/book/src/README.md index 9162642b1cc..ade4d52c1eb 100644 --- a/src/doc/book/src/README.md +++ b/src/doc/book/src/README.md @@ -21,7 +21,6 @@ is the first. After this: * [Tutorial: Guessing Game][gg] - Learn some Rust with a small project. * [Syntax and Semantics][ss] - Each bit of Rust, broken down into small chunks. * [Effective Rust][er] - Higher-level concepts for writing excellent Rust code. -* [Nightly Rust][nr] - Cutting-edge features that aren’t in stable builds yet. * [Glossary][gl] - A reference of terms used in the book. * [Bibliography][bi] - Background on Rust's influences, papers about Rust. @@ -29,7 +28,6 @@ is the first. After this: [gg]: guessing-game.html [er]: effective-rust.html [ss]: syntax-and-semantics.html -[nr]: nightly-rust.html [gl]: glossary.html [bi]: bibliography.html diff --git a/src/doc/book/src/casting-between-types.md b/src/doc/book/src/casting-between-types.md index 853fb1ec254..26cd718475e 100644 --- a/src/doc/book/src/casting-between-types.md +++ b/src/doc/book/src/casting-between-types.md @@ -151,12 +151,9 @@ elements of the array. These kinds of casts are very dangerous, because they make assumptions about the way that multiple underlying structures are implemented. For this, we need something more dangerous. -The `transmute` function is provided by a [compiler intrinsic][intrinsics], and -what it does is very simple, but very scary. It tells Rust to treat a value of -one type as though it were another type. It does this regardless of the -typechecking system, and completely trusts you. - -[intrinsics]: intrinsics.html +The `transmute` function is very simple, but very scary. It tells Rust to treat +a value of one type as though it were another type. It does this regardless of +the typechecking system, and completely trusts you. In our previous example, we know that an array of four `u8`s represents a `u32` properly, and so we want to do the cast. Using `transmute` instead of `as`, diff --git a/src/doc/book/src/conditional-compilation.md b/src/doc/book/src/conditional-compilation.md index 938c1c51326..0562e9fc430 100644 --- a/src/doc/book/src/conditional-compilation.md +++ b/src/doc/book/src/conditional-compilation.md @@ -79,8 +79,7 @@ Will be the same as `#[b]` if `a` is set by `cfg` attribute, and nothing otherwi # cfg! -The `cfg!` [syntax extension][compilerplugins] lets you use these kinds of flags -elsewhere in your code, too: +The `cfg!` macro lets you use these kinds of flags elsewhere in your code, too: ```rust if cfg!(target_os = "macos") || cfg!(target_os = "ios") { @@ -88,7 +87,5 @@ if cfg!(target_os = "macos") || cfg!(target_os = "ios") { } ``` -[compilerplugins]: compiler-plugins.html - These will be replaced by a `true` or `false` at compile-time, depending on the configuration settings. diff --git a/src/doc/book/src/macros.md b/src/doc/book/src/macros.md index 93f63ddc0a5..fa8e8975a5b 100644 --- a/src/doc/book/src/macros.md +++ b/src/doc/book/src/macros.md @@ -761,12 +761,3 @@ to typecheck, and don’t want to worry about writing out the body of the function. One example of this situation is implementing a trait with multiple required methods, where you want to tackle one at a time. Define the others as `unimplemented!` until you’re ready to write them. - -# Procedural macros - -If Rust’s macro system can’t do what you need, you may want to write a -[compiler plugin](compiler-plugins.html) instead. Compared to `macro_rules!` -macros, this is significantly more work, the interfaces are much less stable, -and bugs can be much harder to track down. In exchange you get the -flexibility of running arbitrary Rust code within the compiler. Syntax -extension plugins are sometimes called ‘procedural macros’ for this reason. diff --git a/src/doc/book/src/unsafe.md b/src/doc/book/src/unsafe.md index e90a4b1c268..9bf59fe2abd 100644 --- a/src/doc/book/src/unsafe.md +++ b/src/doc/book/src/unsafe.md @@ -139,4 +139,4 @@ I’ll repeat again: even though you _can_ do arbitrary things in unsafe blocks and functions doesn’t mean you should. The compiler will act as though you’re upholding its invariants, so be careful! -[intrinsics]: intrinsics.html +[intrinsics]: ../unstable-book/intrinsics.html diff --git a/src/doc/book/src/using-rust-without-the-standard-library.md b/src/doc/book/src/using-rust-without-the-standard-library.md index 8458f9314f9..709d10f4e47 100644 --- a/src/doc/book/src/using-rust-without-the-standard-library.md +++ b/src/doc/book/src/using-rust-without-the-standard-library.md @@ -9,7 +9,7 @@ don’t want to use the standard library via an attribute: `#![no_std]`. > Note: This feature is technically stable, but there are some caveats. For > one, you can build a `#![no_std]` _library_ on stable, but not a _binary_. > For details on binaries without the standard library, see [the nightly -> chapter on `#![no_std]`](no-stdlib.html) +> chapter on 'lang items'](../unstable-book/lang-items.html#using-libc) To use `#![no_std]`, add it to your crate root: diff --git a/src/doc/unstable-book/src/alloc-jemalloc.md b/src/doc/unstable-book/src/alloc-jemalloc.md index 47c44ddc374..9bffa2ff99b 100644 --- a/src/doc/unstable-book/src/alloc-jemalloc.md +++ b/src/doc/unstable-book/src/alloc-jemalloc.md @@ -4,7 +4,7 @@ The tracking issue for this feature is: [#33082] [#33082]: https://github.com/rust-lang/rust/issues/33082 -See also [`alloc_system`](alloc-system.md). +See also [`alloc_system`](alloc-system.html). ------------------------ diff --git a/src/doc/unstable-book/src/alloc-system.md b/src/doc/unstable-book/src/alloc-system.md index f7d648c3759..6fa89179d8e 100644 --- a/src/doc/unstable-book/src/alloc-system.md +++ b/src/doc/unstable-book/src/alloc-system.md @@ -4,7 +4,7 @@ The tracking issue for this feature is: [#33082] [#33082]: https://github.com/rust-lang/rust/issues/33082 -See also [`alloc_jemalloc`](alloc-jemalloc.md). +See also [`alloc_jemalloc`](alloc-jemalloc.html). ------------------------ diff --git a/src/doc/unstable-book/src/plugin.md b/src/doc/unstable-book/src/plugin.md index 1ec28bbcf03..313ef2ec91d 100644 --- a/src/doc/unstable-book/src/plugin.md +++ b/src/doc/unstable-book/src/plugin.md @@ -39,7 +39,7 @@ of a library. Plugins can extend Rust's syntax in various ways. One kind of syntax extension is the procedural macro. These are invoked the same way as [ordinary -macros](macros.html), but the expansion is performed by arbitrary Rust +macros](../book/macros.html), but the expansion is performed by arbitrary Rust code that manipulates syntax trees at compile time. @@ -137,7 +137,7 @@ enum. For a more involved macro example, see ## Tips and tricks -Some of the [macro debugging tips](macros.html#Debugging%20macro%20code) are applicable. +Some of the [macro debugging tips](../book/macros.html#debugging-macro-code) are applicable. You can use `syntax::parse` to turn token trees into higher-level syntax elements like expressions: -- cgit 1.4.1-3-g733a5 From 06e311b66a833cc99bddbf3b7afaed609230e463 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 21 Feb 2017 17:30:00 -0500 Subject: get linkcheck clean --- src/doc/guide-plugins.md | 2 +- src/doc/reference/src/attributes.md | 2 +- src/doc/reference/src/macros.md | 2 +- src/doc/unstable-book/src/plugin.md | 17 +++++++++-------- 4 files changed, 12 insertions(+), 11 deletions(-) diff --git a/src/doc/guide-plugins.md b/src/doc/guide-plugins.md index 742433b99ac..1ba28c0117d 100644 --- a/src/doc/guide-plugins.md +++ b/src/doc/guide-plugins.md @@ -1,4 +1,4 @@ % The (old) Rust Compiler Plugins Guide This content has moved into -[the Rust Programming Language book](book/compiler-plugins.html). +[the Unstable Book](unstable-book/plugin.html). diff --git a/src/doc/reference/src/attributes.md b/src/doc/reference/src/attributes.md index da43e1cc057..8f3fdbf3679 100644 --- a/src/doc/reference/src/attributes.md +++ b/src/doc/reference/src/attributes.md @@ -317,7 +317,7 @@ For any lint check `C`: The lint checks supported by the compiler can be found via `rustc -W help`, along with their default settings. [Compiler -plugins](../book/compiler-plugins.html#lint-plugins) can provide additional +plugins](../unstable-book/plugin.html#lint-plugins) can provide additional lint checks. ```{.ignore} diff --git a/src/doc/reference/src/macros.md b/src/doc/reference/src/macros.md index 9ec5f2d6945..d64c40dcad8 100644 --- a/src/doc/reference/src/macros.md +++ b/src/doc/reference/src/macros.md @@ -14,4 +14,4 @@ And one unstable way: [compiler plugins]. [Macros]: ../book/macros.html [Procedural Macros]: ../book/procedural-macros.html -[compiler plugins]: ../book/compiler-plugins.html +[compiler plugins]: ../unstable-book/plugin.html diff --git a/src/doc/unstable-book/src/plugin.md b/src/doc/unstable-book/src/plugin.md index 313ef2ec91d..ca69b7084d3 100644 --- a/src/doc/unstable-book/src/plugin.md +++ b/src/doc/unstable-book/src/plugin.md @@ -129,9 +129,9 @@ The advantages over a simple `fn(&str) -> u32` are: a way to define new literal syntax for any data type. In addition to procedural macros, you can define new -[`derive`](../reference.html#derive)-like attributes and other kinds of -extensions. See `Registry::register_syntax_extension` and the `SyntaxExtension` -enum. For a more involved macro example, see +[`derive`](../reference/attributes.html#derive)-like attributes and other kinds +of extensions. See `Registry::register_syntax_extension` and the +`SyntaxExtension` enum. For a more involved macro example, see [`regex_macros`](https://github.com/rust-lang/regex/blob/master/regex_macros/src/lib.rs). @@ -175,8 +175,8 @@ quasiquote as an ordinary plugin library. # Lint plugins Plugins can extend [Rust's lint -infrastructure](../reference.html#lint-check-attributes) with additional checks for -code style, safety, etc. Now let's write a plugin +infrastructure](../reference/attributes.html#lint-check-attributes) with +additional checks for code style, safety, etc. Now let's write a plugin [`lint_plugin_test.rs`](https://github.com/rust-lang/rust/blob/master/src/test/run-pass-fulldeps/auxiliary/lint_plugin_test.rs) that warns about any item named `lintme`. @@ -254,9 +254,10 @@ mostly use the same infrastructure as lint plugins, and provide examples of how to access type information. Lints defined by plugins are controlled by the usual [attributes and compiler -flags](../reference.html#lint-check-attributes), e.g. `#[allow(test_lint)]` or -`-A test-lint`. These identifiers are derived from the first argument to -`declare_lint!`, with appropriate case and punctuation conversion. +flags](../reference/attributes.html#lint-check-attributes), e.g. +`#[allow(test_lint)]` or `-A test-lint`. These identifiers are derived from the +first argument to `declare_lint!`, with appropriate case and punctuation +conversion. You can run `rustc -W help foo.rs` to see a list of lints known to `rustc`, including those provided by plugins loaded by `foo.rs`. -- cgit 1.4.1-3-g733a5