backend/updating-llvm.html - rust-lang/rustc-dev-guide - Git at Google

 <!DOCTYPE HTML>
 <html lang="en" class="light sidebar-visible" dir="ltr">
     <head>
         <!-- Book generated using mdBook -->
         <meta charset="UTF-8">
         <title>Updating LLVM - 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 -->
         <link rel="stylesheet" href="../pagetoc.css">


         <!-- 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/backend/updating-llvm.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="updating-llvm"><a class="header" href="#updating-llvm">Updating LLVM</a></h1>
 <!-- date-check: Aug 2024 -->
 <p>Rust supports building against multiple LLVM versions:</p>
 <ul>
 <li>Tip-of-tree for the current LLVM development branch is usually supported
 within a few days. PRs for such fixes are tagged with <code>llvm-main</code>.</li>
 <li>The latest released major version is always supported.</li>
 <li>The one or two preceding major versions are usually supported.</li>
 </ul>
 <p>By default, Rust uses its own fork in the <a href="https://github.com/rust-lang/llvm-project">rust-lang/llvm-project repository</a>.
 This fork is based on a <code>release/$N.x</code> branch of the upstream project, where
 <code>$N</code> is either the latest released major version, or the current major version
 in release candidate phase. The fork is never based on the <code>main</code> development
 branch.</p>
 <p>Our LLVM fork only accepts:</p>
 <ul>
 <li>Backports of changes that have already landed upstream.</li>
 <li>Workarounds for build issues affecting our CI environment.</li>
 </ul>
 <p>With the exception of one grandfathered-in patch for SGX enablement, we do not
 accept functional patches that have not been upstreamed first.</p>
 <p>There are three types of LLVM updates, with different procedures:</p>
 <ul>
 <li>Backports while the current major LLVM version is supported.</li>
 <li>Backports while the current major LLVM version is no longer supported (or
 the change is not eligible for upstream backport).</li>
 <li>Update to a new major LLVM version.</li>
 </ul>
 <h2 id="backports-upstream-supported"><a class="header" href="#backports-upstream-supported">Backports (upstream supported)</a></h2>
 <p>While the current major LLVM version is supported upstream, fixes should be
 backported upstream first, and the release branch then merged back into the
 Rust fork.</p>
 <ol>
 <li>Make sure the bugfix is in upstream LLVM.</li>
 <li>If this hasn't happened already, request a backport to the upstream release
 branch. If you have LLVM commit access, follow the <a href="https://llvm.org/docs/GitHub.html#backporting-fixes-to-the-release-branches">backport process</a>.
 Otherwise, open an issue requesting the backport. Continue once the
 backport has been approved and merged.</li>
 <li>Identify the branch that rustc is currently using. The <code>src/llvm-project</code>
 submodule is always pinned to a branch of the
 <a href="https://github.com/rust-lang/llvm-project">rust-lang/llvm-project repository</a>.</li>
 <li>Fork the rust-lang/llvm-project repository.</li>
 <li>Check out the appropriate branch (typically named <code>rustc/a.b-yyyy-mm-dd</code>).</li>
 <li>Add a remote for the upstream repository using
 <code>git remote add upstream https://github.com/llvm/llvm-project.git</code> and
 fetch it using <code>git fetch upstream</code>.</li>
 <li>Merge the <code>upstream/release/$N.x</code> branch.</li>
 <li>Push this branch to your fork.</li>
 <li>Send a Pull Request to rust-lang/llvm-project to the same branch as before.
 Be sure to reference the Rust and/or LLVM issue that you're fixing in the PR
 description.</li>
 <li>Wait for the PR to be merged.</li>
 <li>Send a PR to rust-lang/rust updating the <code>src/llvm-project</code> submodule with
 your bugfix. This can be done locally with <code>git submodule update --remote src/llvm-project</code> typically.</li>
 <li>Wait for PR to be merged.</li>
 </ol>
 <p>An example PR:
 <a href="https://github.com/rust-lang/rust/pull/59089">#59089</a></p>
 <h2 id="backports-upstream-not-supported"><a class="header" href="#backports-upstream-not-supported">Backports (upstream not supported)</a></h2>
 <p>Upstream LLVM releases are only supported for two to three months after the
 GA release. Once upstream backports are no longer accepted, changes should be
 cherry-picked directly to our fork.</p>
 <ol>
 <li>Make sure the bugfix is in upstream LLVM.</li>
 <li>Identify the branch that rustc is currently using. The <code>src/llvm-project</code>
 submodule is always pinned to a branch of the
 <a href="https://github.com/rust-lang/llvm-project">rust-lang/llvm-project repository</a>.</li>
 <li>Fork the rust-lang/llvm-project repository.</li>
 <li>Check out the appropriate branch (typically named <code>rustc/a.b-yyyy-mm-dd</code>).</li>
 <li>Add a remote for the upstream repository using
 <code>git remote add upstream https://github.com/llvm/llvm-project.git</code> and
 fetch it using <code>git fetch upstream</code>.</li>
 <li>Cherry-pick the relevant commit(s) using <code>git cherry-pick -x</code>.</li>
 <li>Push this branch to your fork.</li>
 <li>Send a Pull Request to rust-lang/llvm-project to the same branch as before.
 Be sure to reference the Rust and/or LLVM issue that you're fixing in the PR
 description.</li>
 <li>Wait for the PR to be merged.</li>
 <li>Send a PR to rust-lang/rust updating the <code>src/llvm-project</code> submodule with
 your bugfix. This can be done locally with <code>git submodule update --remote src/llvm-project</code> typically.</li>
 <li>Wait for PR to be merged.</li>
 </ol>
 <p>An example PR:
 <a href="https://github.com/rust-lang/rust/pull/59089">#59089</a></p>
 <h2 id="new-llvm-release-updates"><a class="header" href="#new-llvm-release-updates">New LLVM Release Updates</a></h2>
 <!-- date-check: Jul 2023 -->
 <p>Unlike bugfixes,
 updating to a new release of LLVM typically requires a lot more work.
 This is where we can't reasonably cherry-pick commits backwards,
 so we need to do a full update.
 There's a lot of stuff to do here,
 so let's go through each in detail.</p>
 <ol>
 <li>
 <p>LLVM announces that its latest release version has branched.
 This will show up as a branch in the <a href="https://github.com/llvm/llvm-project">llvm/llvm-project repository</a>,
 typically named <code>release/$N.x</code>,
 where <code>$N</code> is the version of LLVM that's being released.</p>
 </li>
 <li>
 <p>Create a new branch in the <a href="https://github.com/rust-lang/llvm-project">rust-lang/llvm-project repository</a>
 from this <code>release/$N.x</code> branch,
 and name it <code>rustc/a.b-yyyy-mm-dd</code>,
 where <code>a.b</code> is the current version number of LLVM in-tree
 at the time of the branch,
 and the remaining part is the current date.</p>
 </li>
 <li>
 <p>Apply Rust-specific patches to the llvm-project repository.
 All features and bugfixes are upstream,
 but there's often some weird build-related patches
 that don't make sense to upstream.
 These patches are typically the latest patches in the
 rust-lang/llvm-project branch that rustc is currently using.</p>
 </li>
 <li>
 <p>Build the new LLVM in the <code>rust</code> repository.
 To do this,
 you'll want to update the <code>src/llvm-project</code> repository to your branch,
 and the revision you've created.
 It's also typically a good idea to update <code>.gitmodules</code> with the new
 branch name of the LLVM submodule.
 Make sure you've committed changes to
 <code>src/llvm-project</code> to ensure submodule updates aren't reverted.
 Some commands you should execute are:</p>
 <ul>
 <li><code>./x build src/llvm-project</code> - test that LLVM still builds</li>
 <li><code>./x build</code> - build the rest of rustc</li>
 </ul>
 <p>You'll likely need to update <a href="https://github.com/rust-lang/rust/tree/master/compiler/rustc_llvm/llvm-wrapper"><code>llvm-wrapper/*.cpp</code></a>
 to compile with updated LLVM bindings.
 Note that you should use <code>#ifdef</code> and such to ensure
 that the bindings still compile on older LLVM versions.</p>
 <p>Note that <code>profile = "compiler"</code> and other defaults set by <code>./x setup</code>
 download LLVM from CI instead of building it from source.
 You should disable this temporarily to make sure your changes are being used.
 This is done by having the following setting in <code>bootstrap.toml</code>:</p>
 <pre><code class="language-toml">[llvm]
 download-ci-llvm = false
 </code></pre>
 </li>
 <li>
 <p>Test for regressions across other platforms. LLVM often has at least one bug
 for non-tier-1 architectures, so it's good to do some more testing before
 sending this to bors! If you're low on resources you can send the PR as-is
 now to bors, though, and it'll get tested anyway.</p>
 <p>Ideally, build LLVM and test it on a few platforms:</p>
 <ul>
 <li>Linux</li>
 <li>macOS</li>
 <li>Windows</li>
 </ul>
 <p>Afterwards, run some docker containers that CI also does:</p>
 <ul>
 <li><code>./src/ci/docker/run.sh wasm32</code></li>
 <li><code>./src/ci/docker/run.sh arm-android</code></li>
 <li><code>./src/ci/docker/run.sh dist-various-1</code></li>
 <li><code>./src/ci/docker/run.sh dist-various-2</code></li>
 <li><code>./src/ci/docker/run.sh armhf-gnu</code></li>
 </ul>
 </li>
 <li>
 <p>Prepare a PR to <code>rust-lang/rust</code>. Work with maintainers of
 <code>rust-lang/llvm-project</code> to get your commit in a branch of that repository,
 and then you can send a PR to <code>rust-lang/rust</code>. You'll change at least
 <code>src/llvm-project</code> and will likely also change <a href="https://github.com/rust-lang/rust/tree/master/compiler/rustc_llvm/llvm-wrapper"><code>llvm-wrapper</code></a> as well.</p>
 <!-- date-check: mar 2025 -->
 <blockquote>
 <p>For prior art, here are some previous LLVM updates:</p>
 <ul>
 <li><a href="https://github.com/rust-lang/rust/pull/115959">LLVM 17</a></li>
 <li><a href="https://github.com/rust-lang/rust/pull/120055">LLVM 18</a></li>
 <li><a href="https://github.com/rust-lang/rust/pull/127513">LLVM 19</a></li>
 <li><a href="https://github.com/rust-lang/rust/pull/135763">LLVM 20</a></li>
 </ul>
 </blockquote>
 <p>Note that sometimes it's easiest to land <a href="https://github.com/rust-lang/rust/tree/master/compiler/rustc_llvm/llvm-wrapper"><code>llvm-wrapper</code></a> compatibility as a PR
 before actually updating <code>src/llvm-project</code>.
 This way,
 while you're working through LLVM issues,
 others interested in trying out the new LLVM can benefit from work you've done
 to update the C++ bindings.</p>
 </li>
 <li>
 <p>Over the next few months,
 LLVM will continually push commits to its <code>release/a.b</code> branch.
 We will often want to have those bug fixes as well.
 The merge process for that is to use <code>git merge</code> itself to merge LLVM's
 <code>release/a.b</code> branch with the branch created in step 2.
 This is typically
 done multiple times when necessary while LLVM's release branch is baking.</p>
 </li>
 <li>
 <p>LLVM then announces the release of version <code>a.b</code>.</p>
 </li>
 <li>
 <p>After LLVM's official release,
 we follow the process of creating a new branch on the
 rust-lang/llvm-project repository again,
 this time with a new date.
 It is only then that the PR to update Rust to use that version is merged.</p>
 <p>The commit history of <code>rust-lang/llvm-project</code>
 should look much cleaner as a <code>git rebase</code> is done,
 where just a few Rust-specific commits are stacked on top of stock LLVM's release branch.</p>
 </li>
 </ol>
 <h3 id="caveats-and-gotchas"><a class="header" href="#caveats-and-gotchas">Caveats and gotchas</a></h3>
 <p>Ideally the above instructions are pretty smooth, but here's some caveats to
 keep in mind while going through them:</p>
 <ul>
 <li>LLVM bugs are hard to find, don't hesitate to ask for help!
 Bisection is definitely your friend here
 (yes LLVM takes forever to build, yet bisection is still your friend).
 Note that you can make use of <a href="https://forge.rust-lang.org/infra/docs/dev-desktop.html">Dev Desktops</a>,
 which is an initiative to provide the contributors with remote access to powerful hardware.</li>
 <li>If you've got general questions, <a href="https://rust-lang.zulipchat.com/#narrow/stream/187780-t-compiler.2Fwg-llvm">wg-llvm</a> can help you out.</li>
 <li>Creating branches is a privileged operation on GitHub, so you'll need someone
 with write access to create the branches for you most likely.</li>
 </ul>

                     </main>

                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
                             <a rel="prev" href="../backend/codegen.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="../backend/debugging.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="../backend/codegen.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="../backend/debugging.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>
         <script src="../pagetoc.js"></script>


     </div>
     </body>
 </html>
	<!DOCTYPE HTML>
	<html lang="en" class="light sidebar-visible" dir="ltr">
	<head>
	<!-- Book generated using mdBook -->
	<meta charset="UTF-8">
	<title>Updating LLVM - 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 -->
	<link rel="stylesheet" href="../pagetoc.css">


	<!-- 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/backend/updating-llvm.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="updating-llvm"><a class="header" href="#updating-llvm">Updating LLVM</a></h1>
	<!-- date-check: Aug 2024 -->
	<p>Rust supports building against multiple LLVM versions:</p>
	<ul>
	<li>Tip-of-tree for the current LLVM development branch is usually supported
	within a few days. PRs for such fixes are tagged with <code>llvm-main</code>.</li>
	<li>The latest released major version is always supported.</li>
	<li>The one or two preceding major versions are usually supported.</li>
	</ul>
	<p>By default, Rust uses its own fork in the <a href="https://github.com/rust-lang/llvm-project">rust-lang/llvm-project repository</a>.
	This fork is based on a <code>release/$N.x</code> branch of the upstream project, where
	<code>$N</code> is either the latest released major version, or the current major version
	in release candidate phase. The fork is never based on the <code>main</code> development
	branch.</p>
	<p>Our LLVM fork only accepts:</p>
	<ul>
	<li>Backports of changes that have already landed upstream.</li>
	<li>Workarounds for build issues affecting our CI environment.</li>
	</ul>
	<p>With the exception of one grandfathered-in patch for SGX enablement, we do not
	accept functional patches that have not been upstreamed first.</p>
	<p>There are three types of LLVM updates, with different procedures:</p>
	<ul>
	<li>Backports while the current major LLVM version is supported.</li>
	<li>Backports while the current major LLVM version is no longer supported (or
	the change is not eligible for upstream backport).</li>
	<li>Update to a new major LLVM version.</li>
	</ul>
	<h2 id="backports-upstream-supported"><a class="header" href="#backports-upstream-supported">Backports (upstream supported)</a></h2>
	<p>While the current major LLVM version is supported upstream, fixes should be
	backported upstream first, and the release branch then merged back into the
	Rust fork.</p>
	<ol>
	<li>Make sure the bugfix is in upstream LLVM.</li>
	<li>If this hasn't happened already, request a backport to the upstream release
	branch. If you have LLVM commit access, follow the <a href="https://llvm.org/docs/GitHub.html#backporting-fixes-to-the-release-branches">backport process</a>.
	Otherwise, open an issue requesting the backport. Continue once the
	backport has been approved and merged.</li>
	<li>Identify the branch that rustc is currently using. The <code>src/llvm-project</code>
	submodule is always pinned to a branch of the
	<a href="https://github.com/rust-lang/llvm-project">rust-lang/llvm-project repository</a>.</li>
	<li>Fork the rust-lang/llvm-project repository.</li>
	<li>Check out the appropriate branch (typically named <code>rustc/a.b-yyyy-mm-dd</code>).</li>
	<li>Add a remote for the upstream repository using
	<code>git remote add upstream https://github.com/llvm/llvm-project.git</code> and
	fetch it using <code>git fetch upstream</code>.</li>
	<li>Merge the <code>upstream/release/$N.x</code> branch.</li>
	<li>Push this branch to your fork.</li>
	<li>Send a Pull Request to rust-lang/llvm-project to the same branch as before.
	Be sure to reference the Rust and/or LLVM issue that you're fixing in the PR
	description.</li>
	<li>Wait for the PR to be merged.</li>
	<li>Send a PR to rust-lang/rust updating the <code>src/llvm-project</code> submodule with
	your bugfix. This can be done locally with <code>git submodule update --remote src/llvm-project</code> typically.</li>
	<li>Wait for PR to be merged.</li>
	</ol>
	<p>An example PR:
	<a href="https://github.com/rust-lang/rust/pull/59089">#59089</a></p>
	<h2 id="backports-upstream-not-supported"><a class="header" href="#backports-upstream-not-supported">Backports (upstream not supported)</a></h2>
	<p>Upstream LLVM releases are only supported for two to three months after the
	GA release. Once upstream backports are no longer accepted, changes should be
	cherry-picked directly to our fork.</p>
	<ol>
	<li>Make sure the bugfix is in upstream LLVM.</li>
	<li>Identify the branch that rustc is currently using. The <code>src/llvm-project</code>
	submodule is always pinned to a branch of the
	<a href="https://github.com/rust-lang/llvm-project">rust-lang/llvm-project repository</a>.</li>
	<li>Fork the rust-lang/llvm-project repository.</li>
	<li>Check out the appropriate branch (typically named <code>rustc/a.b-yyyy-mm-dd</code>).</li>
	<li>Add a remote for the upstream repository using
	<code>git remote add upstream https://github.com/llvm/llvm-project.git</code> and
	fetch it using <code>git fetch upstream</code>.</li>
	<li>Cherry-pick the relevant commit(s) using <code>git cherry-pick -x</code>.</li>
	<li>Push this branch to your fork.</li>
	<li>Send a Pull Request to rust-lang/llvm-project to the same branch as before.
	Be sure to reference the Rust and/or LLVM issue that you're fixing in the PR
	description.</li>
	<li>Wait for the PR to be merged.</li>
	<li>Send a PR to rust-lang/rust updating the <code>src/llvm-project</code> submodule with
	your bugfix. This can be done locally with <code>git submodule update --remote src/llvm-project</code> typically.</li>
	<li>Wait for PR to be merged.</li>
	</ol>
	<p>An example PR:
	<a href="https://github.com/rust-lang/rust/pull/59089">#59089</a></p>
	<h2 id="new-llvm-release-updates"><a class="header" href="#new-llvm-release-updates">New LLVM Release Updates</a></h2>
	<!-- date-check: Jul 2023 -->
	<p>Unlike bugfixes,
	updating to a new release of LLVM typically requires a lot more work.
	This is where we can't reasonably cherry-pick commits backwards,
	so we need to do a full update.
	There's a lot of stuff to do here,
	so let's go through each in detail.</p>
	<ol>
	<li>
	<p>LLVM announces that its latest release version has branched.
	This will show up as a branch in the <a href="https://github.com/llvm/llvm-project">llvm/llvm-project repository</a>,
	typically named <code>release/$N.x</code>,
	where <code>$N</code> is the version of LLVM that's being released.</p>
	</li>
	<li>
	<p>Create a new branch in the <a href="https://github.com/rust-lang/llvm-project">rust-lang/llvm-project repository</a>
	from this <code>release/$N.x</code> branch,
	and name it <code>rustc/a.b-yyyy-mm-dd</code>,
	where <code>a.b</code> is the current version number of LLVM in-tree
	at the time of the branch,
	and the remaining part is the current date.</p>
	</li>
	<li>
	<p>Apply Rust-specific patches to the llvm-project repository.
	All features and bugfixes are upstream,
	but there's often some weird build-related patches
	that don't make sense to upstream.
	These patches are typically the latest patches in the
	rust-lang/llvm-project branch that rustc is currently using.</p>
	</li>
	<li>
	<p>Build the new LLVM in the <code>rust</code> repository.
	To do this,
	you'll want to update the <code>src/llvm-project</code> repository to your branch,
	and the revision you've created.
	It's also typically a good idea to update <code>.gitmodules</code> with the new
	branch name of the LLVM submodule.
	Make sure you've committed changes to
	<code>src/llvm-project</code> to ensure submodule updates aren't reverted.
	Some commands you should execute are:</p>
	<ul>
	<li><code>./x build src/llvm-project</code> - test that LLVM still builds</li>
	<li><code>./x build</code> - build the rest of rustc</li>
	</ul>
	<p>You'll likely need to update <a href="https://github.com/rust-lang/rust/tree/master/compiler/rustc_llvm/llvm-wrapper"><code>llvm-wrapper/*.cpp</code></a>
	to compile with updated LLVM bindings.
	Note that you should use <code>#ifdef</code> and such to ensure
	that the bindings still compile on older LLVM versions.</p>
	<p>Note that <code>profile = "compiler"</code> and other defaults set by <code>./x setup</code>
	download LLVM from CI instead of building it from source.
	You should disable this temporarily to make sure your changes are being used.
	This is done by having the following setting in <code>bootstrap.toml</code>:</p>
	<pre><code class="language-toml">[llvm]
	download-ci-llvm = false
	</code></pre>
	</li>
	<li>
	<p>Test for regressions across other platforms. LLVM often has at least one bug
	for non-tier-1 architectures, so it's good to do some more testing before
	sending this to bors! If you're low on resources you can send the PR as-is
	now to bors, though, and it'll get tested anyway.</p>
	<p>Ideally, build LLVM and test it on a few platforms:</p>
	<ul>
	<li>Linux</li>
	<li>macOS</li>
	<li>Windows</li>
	</ul>
	<p>Afterwards, run some docker containers that CI also does:</p>
	<ul>
	<li><code>./src/ci/docker/run.sh wasm32</code></li>
	<li><code>./src/ci/docker/run.sh arm-android</code></li>
	<li><code>./src/ci/docker/run.sh dist-various-1</code></li>
	<li><code>./src/ci/docker/run.sh dist-various-2</code></li>
	<li><code>./src/ci/docker/run.sh armhf-gnu</code></li>
	</ul>
	</li>
	<li>
	<p>Prepare a PR to <code>rust-lang/rust</code>. Work with maintainers of
	<code>rust-lang/llvm-project</code> to get your commit in a branch of that repository,
	and then you can send a PR to <code>rust-lang/rust</code>. You'll change at least
	<code>src/llvm-project</code> and will likely also change <a href="https://github.com/rust-lang/rust/tree/master/compiler/rustc_llvm/llvm-wrapper"><code>llvm-wrapper</code></a> as well.</p>
	<!-- date-check: mar 2025 -->
	<blockquote>
	<p>For prior art, here are some previous LLVM updates:</p>
	<ul>
	<li><a href="https://github.com/rust-lang/rust/pull/115959">LLVM 17</a></li>
	<li><a href="https://github.com/rust-lang/rust/pull/120055">LLVM 18</a></li>
	<li><a href="https://github.com/rust-lang/rust/pull/127513">LLVM 19</a></li>
	<li><a href="https://github.com/rust-lang/rust/pull/135763">LLVM 20</a></li>
	</ul>
	</blockquote>
	<p>Note that sometimes it's easiest to land <a href="https://github.com/rust-lang/rust/tree/master/compiler/rustc_llvm/llvm-wrapper"><code>llvm-wrapper</code></a> compatibility as a PR
	before actually updating <code>src/llvm-project</code>.
	This way,
	while you're working through LLVM issues,
	others interested in trying out the new LLVM can benefit from work you've done
	to update the C++ bindings.</p>
	</li>
	<li>
	<p>Over the next few months,
	LLVM will continually push commits to its <code>release/a.b</code> branch.
	We will often want to have those bug fixes as well.
	The merge process for that is to use <code>git merge</code> itself to merge LLVM's
	<code>release/a.b</code> branch with the branch created in step 2.
	This is typically
	done multiple times when necessary while LLVM's release branch is baking.</p>
	</li>
	<li>
	<p>LLVM then announces the release of version <code>a.b</code>.</p>
	</li>
	<li>
	<p>After LLVM's official release,
	we follow the process of creating a new branch on the
	rust-lang/llvm-project repository again,
	this time with a new date.
	It is only then that the PR to update Rust to use that version is merged.</p>
	<p>The commit history of <code>rust-lang/llvm-project</code>
	should look much cleaner as a <code>git rebase</code> is done,
	where just a few Rust-specific commits are stacked on top of stock LLVM's release branch.</p>
	</li>
	</ol>
	<h3 id="caveats-and-gotchas"><a class="header" href="#caveats-and-gotchas">Caveats and gotchas</a></h3>
	<p>Ideally the above instructions are pretty smooth, but here's some caveats to
	keep in mind while going through them:</p>
	<ul>
	<li>LLVM bugs are hard to find, don't hesitate to ask for help!
	Bisection is definitely your friend here
	(yes LLVM takes forever to build, yet bisection is still your friend).
	Note that you can make use of <a href="https://forge.rust-lang.org/infra/docs/dev-desktop.html">Dev Desktops</a>,
	which is an initiative to provide the contributors with remote access to powerful hardware.</li>
	<li>If you've got general questions, <a href="https://rust-lang.zulipchat.com/#narrow/stream/187780-t-compiler.2Fwg-llvm">wg-llvm</a> can help you out.</li>
	<li>Creating branches is a privileged operation on GitHub, so you'll need someone
	with write access to create the branches for you most likely.</li>
	</ul>

	</main>

	<nav class="nav-wrapper" aria-label="Page navigation">
	<!-- Mobile navigation buttons -->
	<a rel="prev" href="../backend/codegen.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="../backend/debugging.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="../backend/codegen.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="../backend/debugging.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>
	<script src="../pagetoc.js"></script>


	</div>
	</body>
	</html>