diff options
Diffstat (limited to 'src/doc')
| -rw-r--r-- | src/doc/index.md | 228 | ||||
| -rw-r--r-- | src/doc/rustc/src/platform-support/fuchsia.md | 94 |
2 files changed, 245 insertions, 77 deletions
diff --git a/src/doc/index.md b/src/doc/index.md index bf08960f338..7c97c16c20b 100644 --- a/src/doc/index.md +++ b/src/doc/index.md @@ -4,6 +4,20 @@ nav { display: none; } +body { + font-family: serif; +} +h1, h2, h3, h4, h5, h6 { + font-family: sans-serif; +} +h3 { + font-size: 1.35rem; +} +h4 { + font-size: 1.1rem; +} + +/* Formatting for docs search bar */ #search-input { width: calc(100% - 58px); } @@ -21,53 +35,74 @@ nav { #search-but:hover, #search-input:focus { border-color: #55a9ff; } -h2 { - font-size: 18px; + +/* Formatting for external link icon */ +svg.external-link { + display: inline-block; + position: relative; + vertical-align: super; + width: 0.7rem; + height: 0.7rem; + padding-left: 2px; + top: 3px; } </style> -Welcome to an overview of the documentation provided by the [Rust project]. -All of these projects are managed by the Docs Team; there are other -unofficial documentation resources as well! +Welcome to an overview of the documentation provided by the [Rust +project]. This page contains links to various helpful references, +most of which are available offline (if opened with `rustup doc`). Many of these +resources take the form of "books"; we collectively call these "The Rust +Bookshelf." Some are large, some are small. -Many of these resources take the form of "books"; we collectively call these -"The Rust Bookshelf." Some are large, some are small. +All of these books are managed by the Rust Organization, but other unofficial +documentation resources are included here as well! -# Learn Rust +If you're just looking for the standard library reference, here it is: +[Rust API documentation](std/index.html) -If you'd like to learn Rust, this is the spot for you! All of these resources + +## Learning Rust + +If you'd like to learn Rust, this is the section for you! All of these resources assume that you have programmed before, but not in any specific language: -## The Rust Programming Language +### The Rust Programming Language -Affectionately nicknamed "the book," [The Rust Programming -Language](book/index.html) will give you an overview of the language from -first principles. You'll build a few projects along the way, and by the end, -you'll have a solid grasp of the language. +Affectionately nicknamed "the book," [The Rust Programming Language](book/index.html) +will give you an overview of the language from first principles. You'll build a +few projects along the way, and by the end, you'll have a solid grasp of how to +use the language. -## Rust By Example +### Rust By Example If reading multiple hundreds of pages about a language isn't your style, then -[Rust By Example](rust-by-example/index.html) has you covered. While the book talks about code with -a lot of words, RBE shows off a bunch of code, and keeps the talking to a -minimum. It also includes exercises! +[Rust By Example](rust-by-example/index.html) has you covered. RBE shows off a +bunch of code without using a lot of words. It also includes exercises! + +### Rustlings + +[Rustlings](https://github.com/rust-lang/rustlings) guides you +through downloading and setting up the Rust toolchain, then provides an +interactive tool that teaches you how to solve coding challenges in Rust. + +### Rust Playground -## Rustlings +The [Rust Playground](https://play.rust-lang.org) is a great place +to try out and share small bits of code, or experiment with some of the most +popular crates. -[Rustlings](https://github.com/rust-lang/rustlings) guides you through downloading and setting up the Rust toolchain, -and teaches you the basics of reading and writing Rust syntax. It's an -alternative to Rust by Example that works with your own environment. -# Use Rust +## Using Rust -Once you've gotten familiar with the language, these resources can help you -when you're actually using it day-to-day. +Once you've gotten familiar with the language, these resources can help you put +it to work. -## The Standard Library +### The Standard Library -Rust's standard library has [extensive API documentation](std/index.html), -with explanations of how to use various things, as well as example code for -accomplishing various tasks. +Rust's standard library has [extensive API documentation](std/index.html), with +explanations of how to use various things, as well as example code for +accomplishing various tasks. Code examples have a "Run" button on hover that +opens the sample in the playground. <div> <form action="std/index.html" method="get"> @@ -77,76 +112,143 @@ accomplishing various tasks. </form> </div> -## The Edition Guide +### Your Personal Documentation -[The Edition Guide](edition-guide/index.html) describes the Rust editions. +Whenever you are working in a crate, `cargo doc --open` will generate +documentation for your project _and_ all its dependencies in their correct +version, and open it in your browser. Add the flag `--document-private-items` to +also show items not marked `pub`. -## The Rustc Book +### The Edition Guide -[The Rustc Book](rustc/index.html) describes the Rust compiler, `rustc`. +[The Edition Guide](edition-guide/index.html) describes the Rust editions and +their differences. -## The Cargo Book +### The `rustc` Book -[The Cargo Book](cargo/index.html) is a guide to Cargo, Rust's build tool and dependency manager. +[The `rustc` Book](rustc/index.html) describes the Rust compiler, `rustc`. -## The Rustdoc Book +### The Cargo Book + +[The Cargo Book](cargo/index.html) is a guide to Cargo, Rust's build tool and +dependency manager. + +### The Rustdoc Book [The Rustdoc Book](rustdoc/index.html) describes our documentation tool, `rustdoc`. -## The Clippy Book +### The Clippy Book [The Clippy Book](clippy/index.html) describes our static analyzer, Clippy. -## Extended Error Listing +### Extended Error Listing Many of Rust's errors come with error codes, and you can request extended -diagnostics from the compiler on those errors. You can also [read them -here](error_codes/index.html), if you prefer to read them that way. +diagnostics from the compiler on those errors (with `rustc --explain`). You can +also read them here if you prefer: [rustc error codes](error_codes/index.html) + -# Master Rust +## Mastering Rust Once you're quite familiar with the language, you may find these advanced resources useful. -## The Reference +### The Reference -[The Reference](reference/index.html) is not a formal spec, but is more detailed and -comprehensive than the book. +[The Reference](reference/index.html) is not a formal spec, but is more detailed +and comprehensive than the book. -## The Style Guide +### The Style Guide -[The Rust Style Guide](style-guide/index.html) describes the standard formatting of Rust -code. Most developers use rustfmt to format their code, and rustfmt's default -formatting matches this style guide. +[The Rust Style Guide](style-guide/index.html) describes the standard formatting +of Rust code. Most developers use `cargo fmt` to invoke `rustfmt` and format the +code automatically (the result matches this style guide). -## The Rustonomicon +### The Rustonomicon -[The Rustonomicon](nomicon/index.html) is your guidebook to the dark arts of unsafe -Rust. It's also sometimes called "the 'nomicon." +[The Rustonomicon](nomicon/index.html) is your guidebook to the dark arts of +unsafe Rust. It's also sometimes called "the 'nomicon." -## The Unstable Book +### The Unstable Book -[The Unstable Book](unstable-book/index.html) has documentation for unstable features. +[The Unstable Book](unstable-book/index.html) has documentation for unstable +features. -## The `rustc` Contribution Guide +### The `rustc` Contribution Guide -[The `rustc` Guide](https://rustc-dev-guide.rust-lang.org/) documents how -the compiler works and how to contribute to it. This is useful if you want to build -or modify the Rust compiler from source (e.g. to target something non-standard). +[The `rustc` Guide](https://rustc-dev-guide.rust-lang.org/) +documents how the compiler works and how to contribute to it. This is useful if +you want to build or modify the Rust compiler from source (e.g. to target +something non-standard). -# Specialize Rust -When using Rust in specific domain areas, consider using the following resources tailored to each domain. +## Specialized Rust -## Embedded Systems +When using Rust in specific domains, consider using the following resources +tailored to each area. -When developing for Bare Metal or Embedded Linux systems, you may find these resources maintained by the [Embedded Working Group] useful. +### Embedded Systems + +When developing for Bare Metal or Embedded Linux systems, you may find these +resources maintained by the [Embedded Working Group] useful. [Embedded Working Group]: https://github.com/rust-embedded -### The Embedded Rust Book +#### The Embedded Rust Book -[The Embedded Rust Book] is targeted at developers familiar with embedded development and familiar with Rust, but have not used Rust for embedded development. +[The Embedded Rust Book] is targeted at developers familiar with embedded +development and familiar with Rust, but have not used Rust for embedded +development. [The Embedded Rust Book]: embedded-book/index.html [Rust project]: https://www.rust-lang.org + +<script> +// check if a given link is external +function isExternalLink(url) { + const tmp = document.createElement('a'); + tmp.href = url; + return tmp.host !== window.location.host; +} + +// Add the `external` class to all <a> tags with external links and append the external link SVG +function updateExternalAnchors() { + /* + External link SVG from Font-Awesome + CC BY-SA 3.0 https://creativecommons.org/licenses/by-sa/3.0 + via Wikimedia Commons + */ + const svgText = `<svg + class='external-link' + xmlns='http://www.w3.org/2000/svg' + viewBox='0 -256 1850 1850' + width='100%' + height='100%'> + <g transform='matrix(1,0,0,-1,30,1427)'> + <path d='M 1408,608 V 288 Q 1408,169 1323.5,84.5 1239,0 1120, + 0 H 288 Q 169,0 84.5,84.5 0,169 0,288 v 832 Q 0,1239 84.5,1323.5 169, + 1408 288,1408 h 704 q 14,0 23,-9 9,-9 9,-23 v -64 q 0,-14 -9,-23 -9, + -9 -23,-9 H 288 q -66,0 -113,-47 -47,-47 -47,-113 V 288 q 0,-66 47, + -113 47,-47 113,-47 h 832 q 66,0 113,47 47,47 47,113 v 320 q 0,14 9, + 23 9,9 23,9 h 64 q 14,0 23,-9 9,-9 9,-23 z m 384,864 V 960 q 0, + -26 -19,-45 -19,-19 -45,-19 -26,0 -45,19 L 1507,1091 855,439 q -10, + -10 -23,-10 -13,0 -23,10 L 695,553 q -10,10 -10,23 0,13 10,23 l 652, + 652 -176,176 q -19,19 -19,45 0,26 19,45 19,19 45,19 h 512 q 26,0 45, + -19 19,-19 19,-45 z' style='fill:currentColor' /> + </g> + </svg>`; + let allAnchors = document.getElementsByTagName("a"); + + for (var i = 0; i < allAnchors.length; ++i) { + let anchor = allAnchors[i]; + if (isExternalLink(anchor.href)) { + anchor.classList.add("external"); + anchor.innerHTML += svgText; + } + } +} + +// on page load, update external anchors +document.addEventListener("DOMContentLoaded", updateExternalAnchors); + +</script> diff --git a/src/doc/rustc/src/platform-support/fuchsia.md b/src/doc/rustc/src/platform-support/fuchsia.md index 0f165b268ba..63dde2aaedd 100644 --- a/src/doc/rustc/src/platform-support/fuchsia.md +++ b/src/doc/rustc/src/platform-support/fuchsia.md @@ -687,7 +687,9 @@ Rust compiler locally. See "[Targeting Fuchsia with a compiler built from source for the steps to build locally. You'll also need to download a copy of the Fuchsia SDK. The current minimum -supported SDK version is [9.20220726.1.1](https://chrome-infra-packages.appspot.com/p/fuchsia/sdk/core/linux-amd64/+/version:9.20220726.1.1). +supported SDK version is [10.20221207.2.89][minimum_supported_sdk_version]. + +[minimum_supported_sdk_version]: https://chrome-infra-packages.appspot.com/p/fuchsia/sdk/core/linux-amd64/+/version:10.20221207.2.89 Fuchsia's test runner interacts with the Fuchsia emulator and is located at `src/ci/docker/scripts/fuchsia-test-runner.py`. We can use it to start our @@ -697,7 +699,7 @@ test environment with: src/ci/docker/scripts/fuchsia-test-runner.py start --rust ${RUST_SRC_PATH}/install --sdk ${SDK_PATH} - --target-triple {x86_64-unknown-fuchsia|aarch64-unknown-fuchsia} + --target {x86_64-unknown-fuchsia|aarch64-unknown-fuchsia} ``` Where `${RUST_SRC_PATH}/install` is the `prefix` set in `config.toml` and @@ -717,17 +719,11 @@ run the full `tests/ui` test suite: --target x86_64-unknown-fuchsia \ --run=always --jobs 1 \ --test-args --target-rustcflags \ - --test-args -L \ - --test-args --target-rustcflags \ - --test-args ${SDK_PATH}/arch/{x64|arm64}/sysroot/lib \ - --test-args --target-rustcflags \ - --test-args -L \ + --test-args -Lnative=${SDK_PATH}/arch/{x64|arm64}/sysroot/lib \ --test-args --target-rustcflags \ - --test-args ${SDK_PATH}/arch/{x64|arm64}/lib \ + --test-args -Lnative=${SDK_PATH}/arch/{x64|arm64}/lib \ --test-args --target-rustcflags \ - --test-args -Cpanic=abort \ - --test-args --target-rustcflags \ - --test-args -Zpanic_abort_tests \ + --test-args -Clink-arg=--undefined-version \ --test-args --remote-test-client \ --test-args src/ci/docker/scripts/fuchsia-test-runner.py \ ) @@ -736,7 +732,18 @@ run the full `tests/ui` test suite: *Note: The test suite cannot be run in parallel at the moment, so `x.py` must be run with `--jobs 1` to ensure only one test runs at a time.* -When finished, the test runner can be used to stop the test environment: +By default, `x.py` compiles test binaries with `panic=unwind`. If you built your +Rust toolchain with `-Cpanic=abort`, you need to tell `x.py` to compile test +binaries with `panic=abort` as well: + +```sh + --test-args --target-rustcflags \ + --test-args -Cpanic=abort \ + --test-args --target-rustcflags \ + --test-args -Zpanic_abort_tests \ +``` + +When finished testing, the test runner can be used to stop the test environment: ```sh src/ci/docker/scripts/fuchsia-test-runner.py stop @@ -764,8 +771,9 @@ ${SDK_PATH}/tools/${ARCH}/ffx debug connect -- \ * `--symbol-path` gets required symbol paths, which are necessary for stepping through your program. -The "[displaying source code in `zxdb`](#displaying-source-code-in-zxdb)" section describes how you can -display Rust and/or Fuchsia source code in your debugging session. +The "[displaying source code in `zxdb`](#displaying-source-code-in-zxdb)" +section describes how you can display Rust and/or Fuchsia source code in your +debugging session. ### Using `zxdb` @@ -866,6 +874,64 @@ ${SDK_PATH}/tools/${ARCH}/ffx debug connect -- \ Linking to a Fuchsia checkout can help with debugging Fuchsia libraries, such as [fdio]. +### Debugging the compiler test suite + +Debugging the compiler test suite requires some special configuration: + +First, we have to properly configure zxdb so it will be able to find debug +symbols and source information for our test. The test runner can do this for us +with: + +```sh +src/ci/docker/scripts/fuchsia-test-runner.py debug \ + --rust-src ${RUST_SRC_PATH} \ + --fuchsia-src ${FUCHSIA_SRC_PATH} \ + --test ${TEST} +``` + +where `${TEST}` is relative to Rust's `tests` directory (e.g. `ui/abi/...`). + +This will start a zxdb session that is properly configured for the specific test +being run. All three arguments are optional, so you can omit `--fuchsia-src` if +you don't have it downloaded. Now is a good time to set any desired breakpoints, +like `b main`. + +Next, we have to tell `x.py` not to optimize or strip debug symbols from our +test suite binaries. We can do this by passing some new arguments to `rustc` +through our `x.py` invocation. The full invocation is: + +```sh +( \ + source config-env.sh && \ + ./x.py \ + --config config.toml \ + --stage=2 \ + test tests/${TEST} \ + --target x86_64-unknown-fuchsia \ + --run=always --jobs 1 \ + --test-args --target-rustcflags \ + --test-args -Lnative=${SDK_PATH}/arch/{x64|arm64}/sysroot/lib \ + --test-args --target-rustcflags \ + --test-args -Lnative=${SDK_PATH}/arch/{x64|arm64}/lib \ + --test-args --target-rustcflags \ + --test-args -Clink-arg=--undefined-version \ + --test-args --target-rustcflags \ + --test-args -Cdebuginfo=2 \ + --test-args --target-rustcflags \ + --test-args -Copt-level=0 \ + --test-args --target-rustcflags \ + --test-args -Cstrip=none \ + --test-args --remote-test-client \ + --test-args src/ci/docker/scripts/fuchsia-test-runner.py \ +) +``` + +*If you built your Rust toolchain with `panic=abort`, make sure to include the +previous flags so your test binaries are also compiled with `panic=abort`.* + +Upon running this command, the test suite binary will be run and zxdb will +attach and load any relevant debug symbols. + [Fuchsia team]: https://team-api.infra.rust-lang.org/v1/teams/fuchsia.json [Fuchsia]: https://fuchsia.dev/ [source tree]: https://fuchsia.dev/fuchsia-src/get-started/learn/build |