diff --git a/src/SUMMARY.md b/src/SUMMARY.md index b5f1bba25..b65ba4c74 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -23,6 +23,8 @@ - [Coding conventions](./conventions.md) - [crates.io Dependencies](./crates-io.md) - [Emitting Errors and other Diagnostics](diagnostics.md) + - [ICE-breaker teams](ice-breaker/about.md) + - [LLVM ICE-breakers](ice-breaker/llvm.md) - [Part 2: How rustc works](./part-2-intro.md) - [High-level overview of the compiler source](./high-level-overview.md) - [The Rustc Driver and Interface](./rustc-driver.md) diff --git a/src/codegen/debugging.md b/src/codegen/debugging.md index a6ad91dd1..1f38c9eee 100644 --- a/src/codegen/debugging.md +++ b/src/codegen/debugging.md @@ -94,6 +94,36 @@ $ ./build/$TRIPLE/llvm/bin/llvm-extract \ > extracted.ll ``` +### Getting help and asking questions + +If you have some questions, head over to the [rust-lang Zulip] and +specifically the `#t-compiler/wg-llvm` stream. + +[rust-lang Zulip]: https://rust-lang.zulipchat.com/ + +### Compiler options to know and love + +The `-Chelp` and `-Zhelp` compiler switches will list out a variety +of interesting options you may find useful. Here are a few of the most +common that pertain to LLVM development (some of them are employed in the +tutorial above): + +- The `--emit llvm-ir` option emits a `.ll` file with LLVM IR in textual format + - The `--emit llvm-bc` option emits in bytecode format (`.bc`) +- Passing `-Cllvm-arg=` allows passing pretty much all the + options that tools like llc and opt would accept; + e.g. `-Cllvm-arg=-print-before-all` to print IR before every LLVM + pass. +- The `-Cno-prepopulate-passes` will avoid pre-populate the LLVM pass + manager with a list of passes. This will allow you to view the LLVM + IR that rustc generates, not the LLVM IR after optimizations. +- The `-Cpasses=val` option allows you to supply a (space seprated) list of extra LLVM passes to run +- The `-Csave-temps` option saves all temporary output files during compilation +- The `-Zprint-llvm-passes` option will print out LLVM optimization passes being run +- The `-Ztime-llvm-passes` option measures the time of each LLVM pass +- The `-Zverify-llvm-ir` option will verify the LLVM IR for correctness +- The `-Zno-parallel-llvm` will disable parallel compilation of distinct compilation units + ### Filing LLVM bug reports When filing an LLVM bug report, you will probably want some sort of minimal @@ -119,4 +149,18 @@ create a minimal working example with Godbolt. Go to optimizations transform it. 5. Once you have a godbolt link demonstrating the issue, it is pretty easy to - fill in an LLVM bug. + fill in an LLVM bug. Just visit [bugs.llvm.org](https://bugs.llvm.org/). + +### Porting bug fixes from LLVM + +Once you've identified the bug as an LLVM bug, you will sometimes +find that it has already been reported and fixed in LLVM, but we haven't +gotten the fix yet (or perhaps you are familiar enough with LLVM to fix it yourself). + +In that case, we can sometimes opt to port the fix for the bug +directly to our own LLVM fork, so that rustc can use it more easily. +Our fork of LLVM is maintained in [rust-lang/llvm-project]. Once +you've landed the fix there, you'll also need to land a PR modifying +our submodule commits -- ask around on Zulip for help. + +[rust-lang/llvm-project]: https://github.com/rust-lang/llvm-project/ diff --git a/src/ice-breaker/about.md b/src/ice-breaker/about.md new file mode 100644 index 000000000..ab9c66789 --- /dev/null +++ b/src/ice-breaker/about.md @@ -0,0 +1,37 @@ +# ICE-breakers + +The **ICE-breaker groups** are an easy way to help out with rustc in a +"piece-meal" fashion, without committing to a larger project. +ICE-breaker groups are **[easy to join](#join)** (just submit a PR!) +and joining does not entail any particular commitment. + +Once you [join an ICE ICE-breaker group](#join), you will be added to +a list that receives pings on github whenever a new issue is found +that fits the ICE-breaker group's criteria. If you are interested, you +can then [claim the issue] and start working on it. + +Of course, you don't have to wait for new issues to be tagged! If you +prefer, you can use the Github label for an ICE-breaker group to +search for existing issues that haven't been claimed yet. + +## What issues are a good fit for ICE-breaker groups? + +"ICE-breaker issues" are intended to be **isolated** bugs of **middle +priority**: + +- By **isolated**, we mean that we do not expect large-scale refactoring + to be required to fix the bug. +- By **middle priority**, we mean that we'd like to see the bug fixed, + but it's not such a burning problem that we are dropping everything + else to fix it. The danger with such bugs, of course, is that they + can accumulate over time, and the role of the ICE-breaker groups is + to try and stop that from happening! + + + +## Joining an ICE-breaker group + +TBD -- we are building this mechanism right now! In the meantime, drop +in on Zulip and leave your github name in [this topic][topic]. + +[topic]: https://rust-lang.zulipchat.com/#narrow/stream/187780-t-compiler.2Fwg-llvm/topic/llvm.20ice-breaker.20registration diff --git a/src/ice-breaker/llvm.md b/src/ice-breaker/llvm.md new file mode 100644 index 000000000..e0c90fdaf --- /dev/null +++ b/src/ice-breaker/llvm.md @@ -0,0 +1,31 @@ +# LLVM ICE-breakers + +**Github Label:** [ICEBreaker-LLVM] + +[ICEBreaker-LLVM]: https://github.com/rust-lang/rust/labels/ICEBreaker-LLVM + +The "LLVM ICE-breakers" are focused on bugs that center around LLVM. +These bugs often arise because of LLVM optimizations gone awry, or as +the result of an LLVM upgrade. The goal here is: + +- to determine whether the bug is a result of us generating invalid LLVM IR, + or LLVM misoptimizing; +- if the former, to fix our IR; +- if the latter, to try and file a bug on LLVM (or identify an existing bug). + +## Helpful tips and options + +The ["Debugging LLVM"][d] section of the +rustc-guide gives a step-by-step process for how to help debug bugs +caused by LLVM. In particular, it discusses how to emit LLVM IR, run +the LLVM IR optimization pipeliness, and so forth. You may also find +it useful to look at the various codegen options listed under `-Chelp` +and the internal options under `-Zhelp` -- there are a number that +pertain to LLVM (just search for LLVM). + +[d]: ../codegen/debugging.md + +## If you do narrow to an LLVM bug + +The ["Debugging LLVM"][d] section also describes what to do once +you've identified the bug.