351 lines
21 KiB
HTML
351 lines
21 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="light sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Getting Started - Rust Compiler Development Guide</title>
|
|
|
|
|
|
<!-- Custom HTML head -->
|
|
|
|
<meta name="description" content="A guide to developing the Rust compiler (rustc)">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff">
|
|
|
|
<link rel="icon" href="favicon.svg">
|
|
<link rel="shortcut icon" href="favicon.png">
|
|
<link rel="stylesheet" href="css/variables.css">
|
|
<link rel="stylesheet" href="css/general.css">
|
|
<link rel="stylesheet" href="css/chrome.css">
|
|
<link rel="stylesheet" href="css/print.css" media="print">
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
|
<link rel="stylesheet" href="fonts/fonts.css">
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" id="highlight-css" href="highlight.css">
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="tomorrow-night.css">
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
|
|
|
|
<!-- Provide site root and default themes to javascript -->
|
|
<script>
|
|
const path_to_root = "";
|
|
const default_light_theme = "light";
|
|
const default_dark_theme = "navy";
|
|
</script>
|
|
<!-- Start loading toc.js asap -->
|
|
<script src="toc.js"></script>
|
|
</head>
|
|
<body>
|
|
<div id="body-container">
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script>
|
|
try {
|
|
let theme = localStorage.getItem('mdbook-theme');
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script>
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
|
let theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
const html = document.documentElement;
|
|
html.classList.remove('light')
|
|
html.classList.add(theme);
|
|
html.classList.add("js");
|
|
</script>
|
|
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script>
|
|
let sidebar = null;
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
} else {
|
|
sidebar = 'hidden';
|
|
}
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<!-- populated by js -->
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|
<noscript>
|
|
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
|
|
</noscript>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|
<div class="sidebar-resize-indicator"></div>
|
|
</div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|
<div class="left-buttons">
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</label>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title">Rust Compiler Development Guide</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
<a href="https://github.com/rust-lang/rustc-dev-guide" title="Git repository" aria-label="Git repository">
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|
</a>
|
|
<a href="https://github.com/rust-lang/rustc-dev-guide/edit/master/src/getting-started.md" title="Suggest an edit" aria-label="Suggest an edit">
|
|
<i id="git-edit-button" class="fa fa-edit"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script>
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1 id="getting-started"><a class="header" href="#getting-started">Getting Started</a></h1>
|
|
<p>Thank you for your interest in contributing to Rust! There are many ways to
|
|
contribute, and we appreciate all of them.</p>
|
|
<ul>
|
|
<li><a href="#asking-questions">Asking Questions</a>
|
|
<ul>
|
|
<li><a href="#experts">Experts</a></li>
|
|
<li><a href="#etiquette">Etiquette</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#what-should-i-work-on">What should I work on?</a>
|
|
<ul>
|
|
<li><a href="#easy-or-mentored-issues">Easy or mentored issues</a></li>
|
|
<li><a href="#recurring-work">Recurring work</a></li>
|
|
<li><a href="#clippy-issues">Clippy issues</a></li>
|
|
<li><a href="#diagnostic-issues">Diagnostic issues</a></li>
|
|
<li><a href="#picking-up-abandoned-pull-requests">Picking up abandoned pull requests</a></li>
|
|
<li><a href="#writing-tests">Writing tests</a></li>
|
|
<li><a href="#contributing-to-std-standard-library">Contributing to std (standard library)</a></li>
|
|
<li><a href="#contributing-code-to-other-rust-projects">Contributing code to other Rust projects</a></li>
|
|
<li><a href="#other-ways-to-contribute">Other ways to contribute</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#cloning-and-building">Cloning and Building</a></li>
|
|
<li><a href="#contributor-procedures">Contributor Procedures</a></li>
|
|
<li><a href="#other-resources">Other Resources</a></li>
|
|
</ul>
|
|
<p>If this is your first time contributing, the <a href="./walkthrough.html">walkthrough</a> chapter can give you a good example of
|
|
how a typical contribution would go.</p>
|
|
<p>This documentation is <em>not</em> intended to be comprehensive; it is meant to be a
|
|
quick guide for the most useful things. For more information, <a href="./building/how-to-build-and-run.html">see this
|
|
chapter on how to build and run the compiler</a>.</p>
|
|
<h2 id="asking-questions"><a class="header" href="#asking-questions">Asking Questions</a></h2>
|
|
<p>If you have questions, please make a post on the <a href="https://rust-lang.zulipchat.com">Rust Zulip server</a> or
|
|
<a href="https://internals.rust-lang.org">internals.rust-lang.org</a>. If you are contributing to Rustup, be aware they are not on
|
|
Zulip - you can ask questions in <code>#wg-rustup</code> <a href="http://discord.gg/rust-lang">on Discord</a>.
|
|
See the <a href="https://www.rust-lang.org/governance">list of teams and working groups</a> and <a href="https://www.rust-lang.org/community">the Community page</a> on the
|
|
official website for more resources.</p>
|
|
<p>As a reminder, all contributors are expected to follow our <a href="https://www.rust-lang.org/policies/code-of-conduct">Code of Conduct</a>.</p>
|
|
<p>The compiler team (or <code>t-compiler</code>) usually hangs out in Zulip <a href="https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler">in this
|
|
"stream"</a>; it will be easiest to get questions answered there.</p>
|
|
<p><strong>Please ask questions!</strong> A lot of people report feeling that they are "wasting
|
|
expert time", but nobody on <code>t-compiler</code> feels this way. Contributors are
|
|
important to us.</p>
|
|
<p>Also, if you feel comfortable, prefer public topics, as this means others can
|
|
see the questions and answers, and perhaps even integrate them back into this
|
|
guide :)</p>
|
|
<h3 id="experts"><a class="header" href="#experts">Experts</a></h3>
|
|
<p>Not all <code>t-compiler</code> members are experts on all parts of <code>rustc</code>; it's a
|
|
pretty large project. To find out who could have some expertise on
|
|
different parts of the compiler, <a href="https://github.com/rust-lang/rust/blob/master/triagebot.toml">consult triagebot assign groups</a>.
|
|
The sections that start with <code>[assign*</code> in <code>triagebot.toml</code> file.
|
|
But also, feel free to ask questions even if you can't figure out who to ping.</p>
|
|
<p>Another way to find experts for a given part of the compiler is to see who has made recent commits.
|
|
For example, to find people who have recently worked on name resolution since the 1.68.2 release,
|
|
you could run <code>git shortlog -n 1.68.2.. compiler/rustc_resolve/</code>. Ignore any commits starting with
|
|
"Rollup merge" or commits by <code>@bors</code> (see <a href="./contributing.html#ci">CI contribution procedures</a> for
|
|
more information about these commits).</p>
|
|
<h3 id="etiquette"><a class="header" href="#etiquette">Etiquette</a></h3>
|
|
<p>We do ask that you be mindful to include as much useful information as you can
|
|
in your question, but we recognize this can be hard if you are unfamiliar with
|
|
contributing to Rust.</p>
|
|
<p>Just pinging someone without providing any context can be a bit annoying and
|
|
just create noise, so we ask that you be mindful of the fact that the
|
|
<code>t-compiler</code> folks get a lot of pings in a day.</p>
|
|
<h2 id="what-should-i-work-on"><a class="header" href="#what-should-i-work-on">What should I work on?</a></h2>
|
|
<p>The Rust project is quite large and it can be difficult to know which parts of the project need
|
|
help, or are a good starting place for beginners. Here are some suggested starting places.</p>
|
|
<h3 id="easy-or-mentored-issues"><a class="header" href="#easy-or-mentored-issues">Easy or mentored issues</a></h3>
|
|
<p>If you're looking for somewhere to start, check out the following <a href="https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3Arust-lang+no%3Aassignee+label%3AE-easy%2C%22good+first+issue%22%2Cgood-first-issue%2CE-medium%2CEasy%2CE-help-wanted%2CE-mentor+-label%3AS-blocked+-linked%3Apr+">issue
|
|
search</a>. See the <a href="./contributing.html#issue-triage">Triage</a> for an explanation of these labels. You can also try
|
|
filtering the search to areas you're interested in. For example:</p>
|
|
<ul>
|
|
<li><code>repo:rust-lang/rust-clippy</code> will only show clippy issues</li>
|
|
<li><code>label:T-compiler</code> will only show issues related to the compiler</li>
|
|
<li><code>label:A-diagnostics</code> will only show diagnostic issues</li>
|
|
</ul>
|
|
<p>Not all important or beginner work has issue labels.
|
|
See below for how to find work that isn't labelled.</p>
|
|
<h3 id="recurring-work"><a class="header" href="#recurring-work">Recurring work</a></h3>
|
|
<p>Some work is too large to be done by a single person. In this case, it's common to have "Tracking
|
|
issues" to co-ordinate the work between contributors. Here are some example tracking issues where
|
|
it's easy to pick up work without a large time commitment:</p>
|
|
<ul>
|
|
<li><a href="https://github.com/rust-lang/rust/issues/73494">Move UI tests to subdirectories</a></li>
|
|
</ul>
|
|
<p>If you find more recurring work, please feel free to add it here!</p>
|
|
<h3 id="clippy-issues"><a class="header" href="#clippy-issues">Clippy issues</a></h3>
|
|
<p>The <a href="https://doc.rust-lang.org/clippy/">Clippy</a> project has spent a long time making its contribution process as friendly to newcomers
|
|
as possible. Consider working on it first to get familiar with the process and the compiler
|
|
internals.</p>
|
|
<p>See <a href="https://github.com/rust-lang/rust-clippy/blob/master/CONTRIBUTING.md">the Clippy contribution guide</a> for instructions on getting started.</p>
|
|
<h3 id="diagnostic-issues"><a class="header" href="#diagnostic-issues">Diagnostic issues</a></h3>
|
|
<p>Many diagnostic issues are self-contained and don't need detailed background knowledge of the
|
|
compiler. You can see a list of diagnostic issues <a href="https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+label%3AA-diagnostics+no%3Aassignee">here</a>.</p>
|
|
<h3 id="picking-up-abandoned-pull-requests"><a class="header" href="#picking-up-abandoned-pull-requests">Picking up abandoned pull requests</a></h3>
|
|
<p>Sometimes, contributors send a pull request, but later find out that they don't have enough
|
|
time to work on it, or they simply are not interested in it anymore. Such PRs are often
|
|
eventually closed and they receive the <code>S-inactive</code> label. You could try to examine some of
|
|
these PRs and pick up the work. You can find the list of such PRs <a href="https://github.com/rust-lang/rust/pulls?q=is%3Apr+label%3AS-inactive+is%3Aclosed">here</a>.</p>
|
|
<p>If the PR has been implemented in some other way in the meantime, the <code>S-inactive</code> label
|
|
should be removed from it. If not, and it seems that there is still interest in the change,
|
|
you can try to rebase the pull request on top of the latest <code>master</code> branch and send a new
|
|
pull request, continuing the work on the feature.</p>
|
|
<h3 id="writing-tests"><a class="header" href="#writing-tests">Writing tests</a></h3>
|
|
<p>Issues that have been resolved but do not have a regression test are marked with the <code>E-needs-test</code> label. Writing unit tests is a low-risk, lower-priority task that offers new contributors a great opportunity to familiarize themselves with the testing infrastructure and contribution workflow.</p>
|
|
<h3 id="contributing-to-std-standard-library"><a class="header" href="#contributing-to-std-standard-library">Contributing to std (standard library)</a></h3>
|
|
<p>See <a href="https://std-dev-guide.rust-lang.org/">std-dev-guide</a>.</p>
|
|
<h3 id="contributing-code-to-other-rust-projects"><a class="header" href="#contributing-code-to-other-rust-projects">Contributing code to other Rust projects</a></h3>
|
|
<p>There are a bunch of other projects that you can contribute to outside of the
|
|
<code>rust-lang/rust</code> repo, including <code>cargo</code>, <code>miri</code>, <code>rustup</code>, and many others.</p>
|
|
<p>These repos might have their own contributing guidelines and procedures. Many
|
|
of them are owned by working groups. For more info, see the documentation in those repos' READMEs.</p>
|
|
<h3 id="other-ways-to-contribute"><a class="header" href="#other-ways-to-contribute">Other ways to contribute</a></h3>
|
|
<p>There are a bunch of other ways you can contribute, especially if you don't
|
|
feel comfortable jumping straight into the large <code>rust-lang/rust</code> codebase.</p>
|
|
<p>The following tasks are doable without much background knowledge but are
|
|
incredibly helpful:</p>
|
|
<ul>
|
|
<li><a href="./contributing.html#writing-documentation">Writing documentation</a>: if you are feeling a bit more intrepid, you could try
|
|
to read a part of the code and write doc comments for it. This will help you
|
|
to learn some part of the compiler while also producing a useful artifact!</li>
|
|
<li><a href="./contributing.html#issue-triage">Triaging issues</a>: categorizing, replicating, and minimizing issues is very helpful to the Rust maintainers.</li>
|
|
<li><a href="https://rust-lang.github.io/compiler-team/working-groups/">Working groups</a>: there are a bunch of working groups on a wide variety
|
|
of rust-related things.</li>
|
|
<li>Answer questions in the <em>Get Help!</em> channels on the <a href="http://discord.gg/rust-lang">Rust Discord
|
|
server</a>, on <a href="https://users.rust-lang.org/">users.rust-lang.org</a>, or on
|
|
<a href="http://stackoverflow.com/questions/tagged/rust">StackOverflow</a>.</li>
|
|
<li>Participate in the <a href="https://github.com/rust-lang/rfcs">RFC process</a>.</li>
|
|
<li>Find a <a href="https://github.com/rust-lang/rfcs/labels/A-community-library">requested community library</a>, build it, and publish
|
|
it to <a href="http://crates.io">Crates.io</a>. Easier said than done, but very, very
|
|
valuable!</li>
|
|
</ul>
|
|
<h2 id="cloning-and-building"><a class="header" href="#cloning-and-building">Cloning and Building</a></h2>
|
|
<p>See <a href="./building/how-to-build-and-run.html">"How to build and run the compiler"</a>.</p>
|
|
<h2 id="contributor-procedures"><a class="header" href="#contributor-procedures">Contributor Procedures</a></h2>
|
|
<p>This section has moved to the <a href="./contributing.html">"Contribution Procedures"</a> chapter.</p>
|
|
<h2 id="other-resources"><a class="header" href="#other-resources">Other Resources</a></h2>
|
|
<p>This section has moved to the <a href="./about-this-guide.html#other-places-to-find-information">"About this guide"</a> chapter.</p>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
|
|
<a rel="next prefetch" href="about-this-guide.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
|
|
<a rel="next prefetch" href="about-this-guide.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<script>
|
|
window.playground_copyable = true;
|
|
</script>
|
|
|
|
|
|
<script src="elasticlunr.min.js"></script>
|
|
<script src="mark.min.js"></script>
|
|
<script src="searcher.js"></script>
|
|
|
|
<script src="clipboard.min.js"></script>
|
|
<script src="highlight.js"></script>
|
|
<script src="book.js"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
<script src="mermaid.min.js"></script>
|
|
<script src="mermaid-init.js"></script>
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|