325 lines
19 KiB
HTML
325 lines
19 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="light sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Using external repositories - 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/external-repos.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="using-external-repositories"><a class="header" href="#using-external-repositories">Using External Repositories</a></h1>
|
|
<p>The <code>rust-lang/rust</code> git repository depends on several other repos in the <code>rust-lang</code> organization.
|
|
There are three main ways we use dependencies:</p>
|
|
<ol>
|
|
<li>As a Cargo dependency through crates.io (e.g. <code>rustc-rayon</code>)</li>
|
|
<li>As a git (e.g. <code>clippy</code>) or a <a href="https://josh-project.github.io/josh/intro.html">josh</a> (e.g. <code>miri</code>) subtree</li>
|
|
<li>As a git submodule (e.g. <code>cargo</code>)</li>
|
|
</ol>
|
|
<p>As a general rule:</p>
|
|
<ul>
|
|
<li>Use crates.io for libraries that could be useful for others in the ecosystem</li>
|
|
<li>Use subtrees for tools that depend on compiler internals and need to be updated if there are breaking
|
|
changes</li>
|
|
<li>Use submodules for tools that are independent of the compiler</li>
|
|
</ul>
|
|
<h2 id="external-dependencies-subtrees"><a class="header" href="#external-dependencies-subtrees">External Dependencies (subtrees)</a></h2>
|
|
<p>The following external projects are managed using some form of a <code>subtree</code>:</p>
|
|
<ul>
|
|
<li><a href="https://github.com/rust-lang/rust-clippy">clippy</a></li>
|
|
<li><a href="https://github.com/rust-lang/miri">miri</a></li>
|
|
<li><a href="https://github.com/rust-lang/portable-simd">portable-simd</a></li>
|
|
<li><a href="https://github.com/rust-lang/rustfmt">rustfmt</a></li>
|
|
<li><a href="https://github.com/rust-lang/rust-analyzer">rust-analyzer</a></li>
|
|
<li><a href="https://github.com/rust-lang/rustc_codegen_cranelift">rustc_codegen_cranelift</a></li>
|
|
<li><a href="https://github.com/rust-lang/rustc-dev-guide">rustc-dev-guide</a></li>
|
|
</ul>
|
|
<p>In contrast to <code>submodule</code> dependencies
|
|
(see below for those), the <code>subtree</code> dependencies are just regular files and directories which can
|
|
be updated in tree. However, if possible, enhancements, bug fixes, etc. specific
|
|
to these tools should be filed against the tools directly in their respective
|
|
upstream repositories. The exception is that when rustc changes are required to
|
|
implement a new tool feature or test, that should happen in one collective rustc PR.</p>
|
|
<p><code>subtree</code> dependencies are currently managed by two distinct approaches:</p>
|
|
<ul>
|
|
<li>Using <code>git subtree</code>
|
|
<ul>
|
|
<li><code>clippy</code> (<a href="https://doc.rust-lang.org/nightly/clippy/development/infrastructure/sync.html#performing-the-sync-from-rust-langrust-to-clippy">sync guide</a>)</li>
|
|
<li><code>portable-simd</code> (<a href="https://github.com/rust-lang/portable-simd/blob/master/subtree-sync.sh">sync script</a>)</li>
|
|
<li><code>rustfmt</code></li>
|
|
<li><code>rustc_codegen_cranelift</code> (<a href="https://github.com/rust-lang/rustc_codegen_cranelift/blob/113af154d459e41b3dc2c5d7d878e3d3a8f33c69/scripts/rustup.sh#L7">sync script</a>)</li>
|
|
</ul>
|
|
</li>
|
|
<li>Using the <a href="https://josh-project.github.io/josh/intro.html">josh</a> tool
|
|
<ul>
|
|
<li><code>miri</code> (<a href="https://github.com/rust-lang/miri/blob/master/CONTRIBUTING.md#advanced-topic-syncing-with-the-rustc-repo">sync guide</a>)</li>
|
|
<li><code>rust-analyzer</code> (<a href="https://github.com/rust-lang/rust-analyzer/blob/2e13684be123eca7181aa48e043e185d8044a84a/xtask/src/release.rs#L147">sync script</a>)</li>
|
|
<li><code>rustc-dev-guide</code> (<a href="https://github.com/rust-lang/rustc-dev-guide#synchronizing-josh-subtree-with-rustc">sync guide</a>)</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>The <a href="https://josh-project.github.io/josh/intro.html">josh</a> tool is an alternative to git subtrees, which manages git history in a different way and scales better to larger repositories. Specific tooling is required to work with josh, you can check out the <code>miri</code> or <code>rust-analyzer</code> scripts linked above for inspiration. If you want to migrate a repository dependency from <code>git subtree</code> or <code>git submodule</code> to josh, you can check out <a href="https://hackmd.io/7pOuxnkdQDaL1Y1FQr65xg">this guide</a>.</p>
|
|
<p>Below you can find a guide on how to perform push and pull synchronization with the main rustc repo using <code>git subtree</code>, although these instructions might differ repo from repo.</p>
|
|
<h3 id="synchronizing-a-subtree"><a class="header" href="#synchronizing-a-subtree">Synchronizing a subtree</a></h3>
|
|
<p>Periodically the changes made to subtree based dependencies need to be synchronized between this
|
|
repository and the upstream tool repositories.</p>
|
|
<p>Subtree synchronizations are typically handled by the respective tool maintainers. Other users
|
|
are welcome to submit synchronization PRs, however, in order to do so you will need to modify
|
|
your local git installation and follow a very precise set of instructions.
|
|
These instructions are documented, along with several useful tips and tricks, in the
|
|
<a href="https://doc.rust-lang.org/nightly/clippy/development/infrastructure/sync.html">syncing subtree changes</a> section in Clippy's Contributing guide.
|
|
The instructions are applicable for use with any subtree based tool, just be sure to
|
|
use the correct corresponding subtree directory and remote repository.</p>
|
|
<p>The synchronization process goes in two directions: <code>subtree push</code> and <code>subtree pull</code>.</p>
|
|
<p>A <code>subtree push</code> takes all the changes that happened to the copy in this repo and creates commits
|
|
on the remote repo that match the local changes. Every local
|
|
commit that touched the subtree causes a commit on the remote repo, but
|
|
is modified to move the files from the specified directory to the tool repo root.</p>
|
|
<p>A <code>subtree pull</code> takes all changes since the last <code>subtree pull</code>
|
|
from the tool repo and adds these commits to the rustc repo along with a merge commit that moves
|
|
the tool changes into the specified directory in the Rust repository.</p>
|
|
<p>It is recommended that you always do a push first and get that merged to the tool master branch.
|
|
Then, when you do a pull, the merge works without conflicts.
|
|
While it's definitely possible to resolve conflicts during a pull, you may have to redo the conflict
|
|
resolution if your PR doesn't get merged fast enough and there are new conflicts. Do not try to
|
|
rebase the result of a <code>git subtree pull</code>, rebasing merge commits is a bad idea in general.</p>
|
|
<p>You always need to specify the <code>-P</code> prefix to the subtree directory and the corresponding remote
|
|
repository. If you specify the wrong directory or repository
|
|
you'll get very fun merges that try to push the wrong directory to the wrong remote repository.
|
|
Luckily you can just abort this without any consequences by throwing away either the pulled commits
|
|
in rustc or the pushed branch on the remote and try again. It is usually fairly obvious
|
|
that this is happening because you suddenly get thousands of commits that want to be synchronized.</p>
|
|
<h3 id="creating-a-new-subtree-dependency"><a class="header" href="#creating-a-new-subtree-dependency">Creating a new subtree dependency</a></h3>
|
|
<p>If you want to create a new subtree dependency from an existing repository, call (from this
|
|
repository's root directory!)</p>
|
|
<pre><code>git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master
|
|
</code></pre>
|
|
<p>This will create a new commit, which you may not rebase under any circumstances! Delete the commit
|
|
and redo the operation if you need to rebase.</p>
|
|
<p>Now you're done, the <code>src/tools/clippy</code> directory behaves as if Clippy were
|
|
part of the rustc monorepo, so no one but you (or others that synchronize
|
|
subtrees) actually needs to use <code>git subtree</code>.</p>
|
|
<h2 id="external-dependencies-submodules"><a class="header" href="#external-dependencies-submodules">External Dependencies (submodules)</a></h2>
|
|
<p>Building Rust will also use external git repositories tracked using <a href="https://git-scm.com/book/en/v2/Git-Tools-Submodules">git
|
|
submodules</a>. The complete list may be found in the <a href="https://github.com/rust-lang/rust/blob/master/.gitmodules"><code>.gitmodules</code></a> file. Some
|
|
of these projects are required (like <code>stdarch</code> for the standard library) and
|
|
some of them are optional (like <code>src/doc/book</code>).</p>
|
|
<p>Usage of submodules is discussed more in the <a href="git.html#git-submodules">Using Git chapter</a>.</p>
|
|
<p>Some of the submodules are allowed to be in a "broken" state where they
|
|
either don't build or their tests don't pass, e.g. the documentation books
|
|
like <a href="https://github.com/rust-lang/reference/">The Rust Reference</a>. Maintainers of these projects will be notified
|
|
when the project is in a broken state, and they should fix them as soon
|
|
as possible. The current status is tracked on the <a href="https://rust-lang-nursery.github.io/rust-toolstate/">toolstate website</a>.
|
|
More information may be found on the Forge <a href="https://forge.rust-lang.org/infra/toolstate.html">Toolstate chapter</a>.
|
|
In practice, it is very rare for documentation to have broken toolstate.</p>
|
|
<p>Breakage is not allowed in the beta and stable channels, and must be addressed
|
|
before the PR is merged. They are also not allowed to be broken on master in
|
|
the week leading up to the beta cut.</p>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="bug-fix-procedure.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="fuzzing.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="prev" href="bug-fix-procedure.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="fuzzing.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>
|