Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Redirecting to... https://doc.rust-lang.org/nightly/nightly-rustc/cargo/.
+ + diff --git a/contrib/architecture/codebase.html b/contrib/architecture/codebase.html new file mode 100644 index 000000000000..c58230b100eb --- /dev/null +++ b/contrib/architecture/codebase.html @@ -0,0 +1,12 @@ + + + + +Redirecting to... https://doc.rust-lang.org/nightly/nightly-rustc/cargo.
+ + diff --git a/contrib/architecture/compilation.html b/contrib/architecture/compilation.html new file mode 100644 index 000000000000..c58230b100eb --- /dev/null +++ b/contrib/architecture/compilation.html @@ -0,0 +1,12 @@ + + + + +Redirecting to... https://doc.rust-lang.org/nightly/nightly-rustc/cargo.
+ + diff --git a/contrib/architecture/console.html b/contrib/architecture/console.html new file mode 100644 index 000000000000..0569edb6dd6f --- /dev/null +++ b/contrib/architecture/console.html @@ -0,0 +1,12 @@ + + + + +Redirecting to... ../implementation/console.html.
+ + diff --git a/contrib/architecture/files.html b/contrib/architecture/files.html new file mode 100644 index 000000000000..c58230b100eb --- /dev/null +++ b/contrib/architecture/files.html @@ -0,0 +1,12 @@ + + + + +Redirecting to... https://doc.rust-lang.org/nightly/nightly-rustc/cargo.
+ + diff --git a/contrib/architecture/index.html b/contrib/architecture/index.html new file mode 100644 index 000000000000..4d9943461a8c --- /dev/null +++ b/contrib/architecture/index.html @@ -0,0 +1,12 @@ + + + + +Redirecting to... ../implementation/architecture.html.
+ + diff --git a/contrib/architecture/packages.html b/contrib/architecture/packages.html new file mode 100644 index 000000000000..c58230b100eb --- /dev/null +++ b/contrib/architecture/packages.html @@ -0,0 +1,12 @@ + + + + +Redirecting to... https://doc.rust-lang.org/nightly/nightly-rustc/cargo.
+ + diff --git a/contrib/architecture/subcommands.html b/contrib/architecture/subcommands.html new file mode 100644 index 000000000000..49723c765b93 --- /dev/null +++ b/contrib/architecture/subcommands.html @@ -0,0 +1,12 @@ + + + + +Redirecting to... ../implementation/subcommands.html.
+ + diff --git a/contrib/ayu-highlight.css b/contrib/ayu-highlight.css new file mode 100644 index 000000000000..32c9432224be --- /dev/null +++ b/contrib/ayu-highlight.css @@ -0,0 +1,78 @@ +/* +Based off of the Ayu theme +Original by Dempfi (https://github.com/dempfi/ayu) +*/ + +.hljs { + display: block; + overflow-x: auto; + background: #191f26; + color: #e6e1cf; +} + +.hljs-comment, +.hljs-quote { + color: #5c6773; + font-style: italic; +} + +.hljs-variable, +.hljs-template-variable, +.hljs-attribute, +.hljs-attr, +.hljs-regexp, +.hljs-link, +.hljs-selector-id, +.hljs-selector-class { + color: #ff7733; +} + +.hljs-number, +.hljs-meta, +.hljs-builtin-name, +.hljs-literal, +.hljs-type, +.hljs-params { + color: #ffee99; +} + +.hljs-string, +.hljs-bullet { + color: #b8cc52; +} + +.hljs-title, +.hljs-built_in, +.hljs-section { + color: #ffb454; +} + +.hljs-keyword, +.hljs-selector-tag, +.hljs-symbol { + color: #ff7733; +} + +.hljs-name { + color: #36a3d9; +} + +.hljs-tag { + color: #00568d; +} + +.hljs-emphasis { + font-style: italic; +} + +.hljs-strong { + font-weight: bold; +} + +.hljs-addition { + color: #91b362; +} + +.hljs-deletion { + color: #d96c75; +} diff --git a/contrib/book.js b/contrib/book.js new file mode 100644 index 000000000000..aa12e7eccfdb --- /dev/null +++ b/contrib/book.js @@ -0,0 +1,697 @@ +"use strict"; + +// Fix back button cache problem +window.onunload = function () { }; + +// Global variable, shared between modules +function playground_text(playground, hidden = true) { + let code_block = playground.querySelector("code"); + + if (window.ace && code_block.classList.contains("editable")) { + let editor = window.ace.edit(code_block); + return editor.getValue(); + } else if (hidden) { + return code_block.textContent; + } else { + return code_block.innerText; + } +} + +(function codeSnippets() { + function fetch_with_timeout(url, options, timeout = 6000) { + return Promise.race([ + fetch(url, options), + new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout)) + ]); + } + + var playgrounds = Array.from(document.querySelectorAll(".playground")); + if (playgrounds.length > 0) { + fetch_with_timeout("https://play.rust-lang.org/meta/crates", { + headers: { + 'Content-Type': "application/json", + }, + method: 'POST', + mode: 'cors', + }) + .then(response => response.json()) + .then(response => { + // get list of crates available in the rust playground + let playground_crates = response.crates.map(item => item["id"]); + playgrounds.forEach(block => handle_crate_list_update(block, playground_crates)); + }); + } + + function handle_crate_list_update(playground_block, playground_crates) { + // update the play buttons after receiving the response + update_play_button(playground_block, playground_crates); + + // and install on change listener to dynamically update ACE editors + if (window.ace) { + let code_block = playground_block.querySelector("code"); + if (code_block.classList.contains("editable")) { + let editor = window.ace.edit(code_block); + editor.addEventListener("change", function (e) { + update_play_button(playground_block, playground_crates); + }); + // add Ctrl-Enter command to execute rust code + editor.commands.addCommand({ + name: "run", + bindKey: { + win: "Ctrl-Enter", + mac: "Ctrl-Enter" + }, + exec: _editor => run_rust_code(playground_block) + }); + } + } + } + + // updates the visibility of play button based on `no_run` class and + // used crates vs ones available on https://play.rust-lang.org + function update_play_button(pre_block, playground_crates) { + var play_button = pre_block.querySelector(".play-button"); + + // skip if code is `no_run` + if (pre_block.querySelector('code').classList.contains("no_run")) { + play_button.classList.add("hidden"); + return; + } + + // get list of `extern crate`'s from snippet + var txt = playground_text(pre_block); + var re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g; + var snippet_crates = []; + var item; + while (item = re.exec(txt)) { + snippet_crates.push(item[1]); + } + + // check if all used crates are available on play.rust-lang.org + var all_available = snippet_crates.every(function (elem) { + return playground_crates.indexOf(elem) > -1; + }); + + if (all_available) { + play_button.classList.remove("hidden"); + } else { + play_button.classList.add("hidden"); + } + } + + function run_rust_code(code_block) { + var result_block = code_block.querySelector(".result"); + if (!result_block) { + result_block = document.createElement('code'); + result_block.className = 'result hljs language-bash'; + + code_block.append(result_block); + } + + let text = playground_text(code_block); + let classes = code_block.querySelector('code').classList; + let edition = "2015"; + if(classes.contains("edition2018")) { + edition = "2018"; + } else if(classes.contains("edition2021")) { + edition = "2021"; + } + var params = { + version: "stable", + optimize: "0", + code: text, + edition: edition + }; + + if (text.indexOf("#![feature") !== -1) { + params.version = "nightly"; + } + + result_block.innerText = "Running..."; + + fetch_with_timeout("https://play.rust-lang.org/evaluate.json", { + headers: { + 'Content-Type': "application/json", + }, + method: 'POST', + mode: 'cors', + body: JSON.stringify(params) + }) + .then(response => response.json()) + .then(response => { + if (response.result.trim() === '') { + result_block.innerText = "No output"; + result_block.classList.add("result-no-output"); + } else { + result_block.innerText = response.result; + result_block.classList.remove("result-no-output"); + } + }) + .catch(error => result_block.innerText = "Playground Communication: " + error.message); + } + + // Syntax highlighting Configuration + hljs.configure({ + tabReplace: ' ', // 4 spaces + languages: [], // Languages used for auto-detection + }); + + let code_nodes = Array + .from(document.querySelectorAll('code')) + // Don't highlight `inline code` blocks in headers. + .filter(function (node) {return !node.parentElement.classList.contains("header"); }); + + if (window.ace) { + // language-rust class needs to be removed for editable + // blocks or highlightjs will capture events + code_nodes + .filter(function (node) {return node.classList.contains("editable"); }) + .forEach(function (block) { block.classList.remove('language-rust'); }); + + code_nodes + .filter(function (node) {return !node.classList.contains("editable"); }) + .forEach(function (block) { hljs.highlightBlock(block); }); + } else { + code_nodes.forEach(function (block) { hljs.highlightBlock(block); }); + } + + // Adding the hljs class gives code blocks the color css + // even if highlighting doesn't apply + code_nodes.forEach(function (block) { block.classList.add('hljs'); }); + + Array.from(document.querySelectorAll("code.hljs")).forEach(function (block) { + + var lines = Array.from(block.querySelectorAll('.boring')); + // If no lines were hidden, return + if (!lines.length) { return; } + block.classList.add("hide-boring"); + + var buttons = document.createElement('div'); + buttons.className = 'buttons'; + buttons.innerHTML = ""; + + // add expand button + var pre_block = block.parentNode; + pre_block.insertBefore(buttons, pre_block.firstChild); + + pre_block.querySelector('.buttons').addEventListener('click', function (e) { + if (e.target.classList.contains('fa-eye')) { + e.target.classList.remove('fa-eye'); + e.target.classList.add('fa-eye-slash'); + e.target.title = 'Hide lines'; + e.target.setAttribute('aria-label', e.target.title); + + block.classList.remove('hide-boring'); + } else if (e.target.classList.contains('fa-eye-slash')) { + e.target.classList.remove('fa-eye-slash'); + e.target.classList.add('fa-eye'); + e.target.title = 'Show hidden lines'; + e.target.setAttribute('aria-label', e.target.title); + + block.classList.add('hide-boring'); + } + }); + }); + + if (window.playground_copyable) { + Array.from(document.querySelectorAll('pre code')).forEach(function (block) { + var pre_block = block.parentNode; + if (!pre_block.classList.contains('playground')) { + var buttons = pre_block.querySelector(".buttons"); + if (!buttons) { + buttons = document.createElement('div'); + buttons.className = 'buttons'; + pre_block.insertBefore(buttons, pre_block.firstChild); + } + + var clipButton = document.createElement('button'); + clipButton.className = 'fa fa-copy clip-button'; + clipButton.title = 'Copy to clipboard'; + clipButton.setAttribute('aria-label', clipButton.title); + clipButton.innerHTML = ''; + + buttons.insertBefore(clipButton, buttons.firstChild); + } + }); + } + + // Process playground code blocks + Array.from(document.querySelectorAll(".playground")).forEach(function (pre_block) { + // Add play button + var buttons = pre_block.querySelector(".buttons"); + if (!buttons) { + buttons = document.createElement('div'); + buttons.className = 'buttons'; + pre_block.insertBefore(buttons, pre_block.firstChild); + } + + var runCodeButton = document.createElement('button'); + runCodeButton.className = 'fa fa-play play-button'; + runCodeButton.hidden = true; + runCodeButton.title = 'Run this code'; + runCodeButton.setAttribute('aria-label', runCodeButton.title); + + buttons.insertBefore(runCodeButton, buttons.firstChild); + runCodeButton.addEventListener('click', function (e) { + run_rust_code(pre_block); + }); + + if (window.playground_copyable) { + var copyCodeClipboardButton = document.createElement('button'); + copyCodeClipboardButton.className = 'fa fa-copy clip-button'; + copyCodeClipboardButton.innerHTML = ''; + copyCodeClipboardButton.title = 'Copy to clipboard'; + copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title); + + buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild); + } + + let code_block = pre_block.querySelector("code"); + if (window.ace && code_block.classList.contains("editable")) { + var undoChangesButton = document.createElement('button'); + undoChangesButton.className = 'fa fa-history reset-button'; + undoChangesButton.title = 'Undo changes'; + undoChangesButton.setAttribute('aria-label', undoChangesButton.title); + + buttons.insertBefore(undoChangesButton, buttons.firstChild); + + undoChangesButton.addEventListener('click', function () { + let editor = window.ace.edit(code_block); + editor.setValue(editor.originalCode); + editor.clearSelection(); + }); + } + }); +})(); + +(function themes() { + var html = document.querySelector('html'); + var themeToggleButton = document.getElementById('theme-toggle'); + var themePopup = document.getElementById('theme-list'); + var themeColorMetaTag = document.querySelector('meta[name="theme-color"]'); + var stylesheets = { + ayuHighlight: document.querySelector("[href$='ayu-highlight.css']"), + tomorrowNight: document.querySelector("[href$='tomorrow-night.css']"), + highlight: document.querySelector("[href$='highlight.css']"), + }; + + function showThemes() { + themePopup.style.display = 'block'; + themeToggleButton.setAttribute('aria-expanded', true); + themePopup.querySelector("button#" + get_theme()).focus(); + } + + function updateThemeSelected() { + themePopup.querySelectorAll('.theme-selected').forEach(function (el) { + el.classList.remove('theme-selected'); + }); + themePopup.querySelector("button#" + get_theme()).classList.add('theme-selected'); + } + + function hideThemes() { + themePopup.style.display = 'none'; + themeToggleButton.setAttribute('aria-expanded', false); + themeToggleButton.focus(); + } + + function get_theme() { + var theme; + try { theme = localStorage.getItem('mdbook-theme'); } catch (e) { } + if (theme === null || theme === undefined) { + return default_theme; + } else { + return theme; + } + } + + function set_theme(theme, store = true) { + let ace_theme; + + if (theme == 'coal' || theme == 'navy') { + stylesheets.ayuHighlight.disabled = true; + stylesheets.tomorrowNight.disabled = false; + stylesheets.highlight.disabled = true; + + ace_theme = "ace/theme/tomorrow_night"; + } else if (theme == 'ayu') { + stylesheets.ayuHighlight.disabled = false; + stylesheets.tomorrowNight.disabled = true; + stylesheets.highlight.disabled = true; + ace_theme = "ace/theme/tomorrow_night"; + } else { + stylesheets.ayuHighlight.disabled = true; + stylesheets.tomorrowNight.disabled = true; + stylesheets.highlight.disabled = false; + ace_theme = "ace/theme/dawn"; + } + + setTimeout(function () { + themeColorMetaTag.content = getComputedStyle(document.documentElement).backgroundColor; + }, 1); + + if (window.ace && window.editors) { + window.editors.forEach(function (editor) { + editor.setTheme(ace_theme); + }); + } + + var previousTheme = get_theme(); + + if (store) { + try { localStorage.setItem('mdbook-theme', theme); } catch (e) { } + } + + html.classList.remove(previousTheme); + html.classList.add(theme); + updateThemeSelected(); + } + + // Set theme + var theme = get_theme(); + + set_theme(theme, false); + + themeToggleButton.addEventListener('click', function () { + if (themePopup.style.display === 'block') { + hideThemes(); + } else { + showThemes(); + } + }); + + themePopup.addEventListener('click', function (e) { + var theme; + if (e.target.className === "theme") { + theme = e.target.id; + } else if (e.target.parentElement.className === "theme") { + theme = e.target.parentElement.id; + } else { + return; + } + set_theme(theme); + }); + + themePopup.addEventListener('focusout', function(e) { + // e.relatedTarget is null in Safari and Firefox on macOS (see workaround below) + if (!!e.relatedTarget && !themeToggleButton.contains(e.relatedTarget) && !themePopup.contains(e.relatedTarget)) { + hideThemes(); + } + }); + + // Should not be needed, but it works around an issue on macOS & iOS: https://github.com/rust-lang/mdBook/issues/628 + document.addEventListener('click', function(e) { + if (themePopup.style.display === 'block' && !themeToggleButton.contains(e.target) && !themePopup.contains(e.target)) { + hideThemes(); + } + }); + + document.addEventListener('keydown', function (e) { + if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; } + if (!themePopup.contains(e.target)) { return; } + + switch (e.key) { + case 'Escape': + e.preventDefault(); + hideThemes(); + break; + case 'ArrowUp': + e.preventDefault(); + var li = document.activeElement.parentElement; + if (li && li.previousElementSibling) { + li.previousElementSibling.querySelector('button').focus(); + } + break; + case 'ArrowDown': + e.preventDefault(); + var li = document.activeElement.parentElement; + if (li && li.nextElementSibling) { + li.nextElementSibling.querySelector('button').focus(); + } + break; + case 'Home': + e.preventDefault(); + themePopup.querySelector('li:first-child button').focus(); + break; + case 'End': + e.preventDefault(); + themePopup.querySelector('li:last-child button').focus(); + break; + } + }); +})(); + +(function sidebar() { + var body = document.querySelector("body"); + var sidebar = document.getElementById("sidebar"); + var sidebarLinks = document.querySelectorAll('#sidebar a'); + var sidebarToggleButton = document.getElementById("sidebar-toggle"); + var sidebarResizeHandle = document.getElementById("sidebar-resize-handle"); + var firstContact = null; + + function showSidebar() { + body.classList.remove('sidebar-hidden') + body.classList.add('sidebar-visible'); + Array.from(sidebarLinks).forEach(function (link) { + link.setAttribute('tabIndex', 0); + }); + sidebarToggleButton.setAttribute('aria-expanded', true); + sidebar.setAttribute('aria-hidden', false); + try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { } + } + + + var sidebarAnchorToggles = document.querySelectorAll('#sidebar a.toggle'); + + function toggleSection(ev) { + ev.currentTarget.parentElement.classList.toggle('expanded'); + } + + Array.from(sidebarAnchorToggles).forEach(function (el) { + el.addEventListener('click', toggleSection); + }); + + function hideSidebar() { + body.classList.remove('sidebar-visible') + body.classList.add('sidebar-hidden'); + Array.from(sidebarLinks).forEach(function (link) { + link.setAttribute('tabIndex', -1); + }); + sidebarToggleButton.setAttribute('aria-expanded', false); + sidebar.setAttribute('aria-hidden', true); + try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { } + } + + // Toggle sidebar + sidebarToggleButton.addEventListener('click', function sidebarToggle() { + if (body.classList.contains("sidebar-hidden")) { + var current_width = parseInt( + document.documentElement.style.getPropertyValue('--sidebar-width'), 10); + if (current_width < 150) { + document.documentElement.style.setProperty('--sidebar-width', '150px'); + } + showSidebar(); + } else if (body.classList.contains("sidebar-visible")) { + hideSidebar(); + } else { + if (getComputedStyle(sidebar)['transform'] === 'none') { + hideSidebar(); + } else { + showSidebar(); + } + } + }); + + sidebarResizeHandle.addEventListener('mousedown', initResize, false); + + function initResize(e) { + window.addEventListener('mousemove', resize, false); + window.addEventListener('mouseup', stopResize, false); + body.classList.add('sidebar-resizing'); + } + function resize(e) { + var pos = (e.clientX - sidebar.offsetLeft); + if (pos < 20) { + hideSidebar(); + } else { + if (body.classList.contains("sidebar-hidden")) { + showSidebar(); + } + pos = Math.min(pos, window.innerWidth - 100); + document.documentElement.style.setProperty('--sidebar-width', pos + 'px'); + } + } + //on mouseup remove windows functions mousemove & mouseup + function stopResize(e) { + body.classList.remove('sidebar-resizing'); + window.removeEventListener('mousemove', resize, false); + window.removeEventListener('mouseup', stopResize, false); + } + + document.addEventListener('touchstart', function (e) { + firstContact = { + x: e.touches[0].clientX, + time: Date.now() + }; + }, { passive: true }); + + document.addEventListener('touchmove', function (e) { + if (!firstContact) + return; + + var curX = e.touches[0].clientX; + var xDiff = curX - firstContact.x, + tDiff = Date.now() - firstContact.time; + + if (tDiff < 250 && Math.abs(xDiff) >= 150) { + if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300)) + showSidebar(); + else if (xDiff < 0 && curX < 300) + hideSidebar(); + + firstContact = null; + } + }, { passive: true }); +})(); + +(function chapterNavigation() { + document.addEventListener('keydown', function (e) { + if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; } + if (window.search && window.search.hasFocus()) { return; } + var html = document.querySelector('html'); + + function next() { + var nextButton = document.querySelector('.nav-chapters.next'); + if (nextButton) { + window.location.href = nextButton.href; + } + } + function prev() { + var previousButton = document.querySelector('.nav-chapters.previous'); + if (previousButton) { + window.location.href = previousButton.href; + } + } + switch (e.key) { + case 'ArrowRight': + e.preventDefault(); + if (html.dir == 'rtl') { + prev(); + } else { + next(); + } + break; + case 'ArrowLeft': + e.preventDefault(); + if (html.dir == 'rtl') { + next(); + } else { + prev(); + } + break; + } + }); +})(); + +(function clipboard() { + var clipButtons = document.querySelectorAll('.clip-button'); + + function hideTooltip(elem) { + elem.firstChild.innerText = ""; + elem.className = 'fa fa-copy clip-button'; + } + + function showTooltip(elem, msg) { + elem.firstChild.innerText = msg; + elem.className = 'fa fa-copy tooltipped'; + } + + var clipboardSnippets = new ClipboardJS('.clip-button', { + text: function (trigger) { + hideTooltip(trigger); + let playground = trigger.closest("pre"); + return playground_text(playground, false); + } + }); + + Array.from(clipButtons).forEach(function (clipButton) { + clipButton.addEventListener('mouseout', function (e) { + hideTooltip(e.currentTarget); + }); + }); + + clipboardSnippets.on('success', function (e) { + e.clearSelection(); + showTooltip(e.trigger, "Copied!"); + }); + + clipboardSnippets.on('error', function (e) { + showTooltip(e.trigger, "Clipboard error!"); + }); +})(); + +(function scrollToTop () { + var menuTitle = document.querySelector('.menu-title'); + + menuTitle.addEventListener('click', function () { + document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' }); + }); +})(); + +(function controllMenu() { + var menu = document.getElementById('menu-bar'); + + (function controllPosition() { + var scrollTop = document.scrollingElement.scrollTop; + var prevScrollTop = scrollTop; + var minMenuY = -menu.clientHeight - 50; + // When the script loads, the page can be at any scroll (e.g. if you reforesh it). + menu.style.top = scrollTop + 'px'; + // Same as parseInt(menu.style.top.slice(0, -2), but faster + var topCache = menu.style.top.slice(0, -2); + menu.classList.remove('sticky'); + var stickyCache = false; // Same as menu.classList.contains('sticky'), but faster + document.addEventListener('scroll', function () { + scrollTop = Math.max(document.scrollingElement.scrollTop, 0); + // `null` means that it doesn't need to be updated + var nextSticky = null; + var nextTop = null; + var scrollDown = scrollTop > prevScrollTop; + var menuPosAbsoluteY = topCache - scrollTop; + if (scrollDown) { + nextSticky = false; + if (menuPosAbsoluteY > 0) { + nextTop = prevScrollTop; + } + } else { + if (menuPosAbsoluteY > 0) { + nextSticky = true; + } else if (menuPosAbsoluteY < minMenuY) { + nextTop = prevScrollTop + minMenuY; + } + } + if (nextSticky === true && stickyCache === false) { + menu.classList.add('sticky'); + stickyCache = true; + } else if (nextSticky === false && stickyCache === true) { + menu.classList.remove('sticky'); + stickyCache = false; + } + if (nextTop !== null) { + menu.style.top = nextTop + 'px'; + topCache = nextTop; + } + prevScrollTop = scrollTop; + }, { passive: true }); + })(); + (function controllBorder() { + function updateBorder() { + if (menu.offsetTop === 0) { + menu.classList.remove('bordered'); + } else { + menu.classList.add('bordered'); + } + } + updateBorder(); + document.addEventListener('scroll', updateBorder, { passive: true }); + })(); +})(); diff --git a/contrib/clipboard.min.js b/contrib/clipboard.min.js new file mode 100644 index 000000000000..02c549e35c86 --- /dev/null +++ b/contrib/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.4 + * https://zenorocha.github.io/clipboard.js + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return function(n){var o={};function r(t){if(o[t])return o[t].exports;var e=o[t]={i:t,l:!1,exports:{}};return n[t].call(e.exports,e,e.exports,r),e.l=!0,e.exports}return r.m=n,r.c=o,r.d=function(t,e,n){r.o(t,e)||Object.defineProperty(t,e,{enumerable:!0,get:n})},r.r=function(t){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(t,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(t,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(r.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(n,o,function(t){return e[t]}.bind(null,o));return n},r.n=function(t){var e=t&&t.__esModule?function(){return t.default}:function(){return t};return r.d(e,"a",e),e},r.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},r.p="",r(r.s=0)}([function(t,e,n){"use strict";var r="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t},i=function(){function o(t,e){for(var n=0;nThe purpose of Cargo is to formalize a canonical Rust workflow, by automating +the standard tasks associated with distributing software. Cargo simplifies +structuring a new project, adding dependencies, writing and running unit +tests, and more.
+Cargo is not intended to be a general-purpose build tool. Ideally, it should +be easy to integrate it within another build tool, though admittedly that is +not as seamless as desired.
+Cargo strives to remain backwards compatible with projects created in previous +versions. The CLI interface also strives to remain backwards compatible, such +that the commands and options behave the same. That being said, changes in +behavior, and even outright breakage are sometimes done in limited situations. +The following outlines some situations where backwards-incompatible changes are +made:
+None of these changes should be taken lightly, and should be avoided if +possible, or possibly with some transition period to alert the user of the +potential change.
+Behavior is sometimes changed in ways that have a high confidence that it +won’t break existing workflows. Almost every change carries this risk, so it +is often a judgment call balancing the benefit of the change with the +perceived possibility of its negative consequences.
+At times, some changes fall in the gray area, where the current behavior is +undocumented, or not working as intended. These are more difficult judgment +calls. The general preference is to balance towards avoiding breaking existing +workflows.
+Support for older registry APIs and index formats may be dropped, if there is +high confidence that there aren’t any active registries that may be affected. +This has never (to my knowledge) happened so far, and is unlikely to happen in +the future, but remains a possibility.
+In all of the above, a transition period may be employed if a change is known +to cause breakage. A warning can be issued to alert the user that something +will change, and provide them with an alternative to resolve the issue +(preferably in a way that is compatible across versions if possible).
+Cargo is only expected to work with the version of the related Rust tools
+(rustc, rustdoc, etc.) that it is released with. As a matter of choice,
+the latest nightly works with the most recent stable release, but that is
+mostly to accommodate development of Cargo itself, and should not be expected
+by users.
Additionally, Cargo strives a limited degree of forwards compatibility. +Changes should not egregiously prevent older versions from working. This is +mostly relevant for persistent data, such as on-disk files and the registry +interface and index. It also applies to a lesser degree to the registry API.
+Changes to Cargo.lock require a transition time, where the new format is not
+automatically written when the lock file is updated. The transition time
+should not be less than 6 months, though preferably longer. New projects may
+use the new format in a shorter time frame.
Changes to Cargo.toml can be made in any release. This is because the user
+must manually modify the file, and opt-in to any new changes. Additionally,
+Cargo will usually only issue a warning about new fields it doesn’t
+understand, but otherwise continue to function.
Changes to cache files (such as artifacts in the target directory, or cached
+data in Cargo’s home directory) should not prevent older versions from
+running, but they may cause older versions to recreate the cache, which may
+result in a performance impact.
Changes to the registry index should not prevent older versions from working. +Generally, older versions ignore new fields, so the format should be easily +extensible. Changes to the format or interpretation of existing fields should +be done very carefully to avoid preventing older versions of Cargo from +working. In some cases, this may mean that older versions of Cargo will not be +able to select a newly published crate, but it shouldn’t prevent them from +working at all. This level of compatibility may not last forever, but the +exact time frame for such a change has not yet been decided.
+The registry API may be changed in such a way to prevent older versions of +Cargo from working. Generally, compatibility should be retained for as long as +possible, but the exact length of time is not specified.
+Standard workflows should be easy and consistent. Each knob that is added has +a high cost, regardless if it is intended for a small audience. Layering and +defaults can help avoid the surface area that the user needs to be concerned +with. Try to avoid small functionalities that may have complex interactions +with one another.
+ +See the
+nightly docs
+for an overview of cargos architecture and links out to further details.
All of Cargo’s output should go through the Shell struct. You can normally
+obtain the Shell instance from the GlobalContext struct. Do not use
+the std println! macros.
Most of Cargo’s output goes to stderr. When running in JSON mode, the output +goes to stdout.
+It is important to properly handle errors when writing to the console.
+Informational commands, like cargo list, should ignore any errors writing
+the output. There are some drop_print macros that are intended to make
+this easier.
Messages written during compilation should handle errors, and abort the build
+if they are unable to be displayed. This is generally automatically handled in
+the JobQueue as it processes each message.
Cargo uses anyhow for managing errors. This makes it convenient to “chain”
+errors together, so that Cargo can report how an error originated, and what it
+was trying to do at the time.
Error helpers are implemented in the errors module. Use the
+InternalError error type for errors that are not expected to happen. This
+will print a message to the user to file a bug report.
The binary side of Cargo uses the CliError struct to wrap the process exit
+code. Usually Cargo exits with 101 for an error, but some commands like cargo test will exit with different codes.
Some guidelines for Cargo’s output:
+std::fs, always add error
+context about what it is doing. For example, reading from a file should
+include context about which file is being read if there is an error.Cargo uses the tracing crate to display debug log messages.
+The CARGO_LOG environment variable can be set to enable debug logging, with a value such as trace, debug, or warn.
+It also supports filtering for specific modules with comma-separated [directives].
+Feel free to use shorthand macros to help with diagnosing problems.
+We’re looking forward to making Cargo logging mechanism more structural!
# Outputs all logs with levels debug and higher
+CARGO_LOG=debug cargo generate-lockfile
+
+# Don't forget that you can filter by module as well
+CARGO_LOG=cargo::core::resolver=trace cargo generate-lockfile
+
+# This will print lots of info about the download process. `trace` prints even more.
+CARGO_HTTP_DEBUG=true CARGO_LOG=network=debug cargo fetch
+
+# This is an important command for diagnosing fingerprint issues.
+CARGO_LOG=cargo::core::compiler::fingerprint=trace cargo build
+Cargo tends to get run on a very wide array of file systems. Different file +systems can have a wide range of capabilities, and Cargo should strive to do +its best to handle them. Some examples of issues to deal with:
+fs::canonicalize function doesn’t work on all file systems
+(particularly some Windows file systems). If that function is used, there
+should be a fallback if it fails. This function will also return \\?\
+style paths on Windows, which can have some issues (such as some tools not
+supporting them, or having issues with relative paths).fingerprint module has a deeper
+discussion of this. One example is that Docker cache layers will erase the
+fractional part of the time stamp.When modifying user files, like Cargo.toml, we should not change other
+sections of the file,
+preserving the general formatting.
+This includes the table, inline-table, or array that a field is being edited in.
When adding new entries, they do not need to match the canonical style of the +document but can use the default formatting. +If the entry is already sorted, preserving the sort order is preferred.
+When removing entries, +comments on the same line should be removed but comments on following lines +should be preserved.
+Inconsistencies in style after making a change are left to the user and their +preferred auto-formatter.
+ +This chapter gives an overview of what you need to know in making a change to cargo.
+If you feel something is missing that would help you, feel free to ask on +Zulip.
+ +This chapter sketches out how to add a new package to the cargo workspace.
+Choose the relevant parent directory
+credential/ for credential-process related packagesbenches/ for benchmarking of cargo itselfcrates/ for everything elseRun cargo new <name>
<name>:
+- over _cargo-util- prefixxtask- prefixpackage.rust-version
+# MSRV:1 comment# MSRV:3 commentIf its an xtask,
+.cargo/config.tomls [alias] tablepackage.publish = falseIf needed to be published with cargo,
+add the package to publish.py in the repo root,
+in dependency order.
Note: by adding the package to the workspace, you automatically get
+cargo testcargo doc warningsOur MSRV policies are
+We proactively update the MSRV
+To proactively update the MSRV, we use RenovateBot
+with the configuration file in .github/renovatebot.json5.
+To know what MSRV policy to use,
+it looks for comments of the form # MSRV:N,
+where N is the number of supported rust versions.
Cargo is a single binary composed of a set of clap subcommands. All
+subcommands live in src/bin/cargo/commands directory.
+src/bin/cargo/main.rs is the entry point.
Each subcommand, such as src/bin/cargo/commands/build.rs, usually performs
+the following:
command_prelude module for some helpers to make this easier.src/cargo/ops.If the subcommand is not found in the built-in list, then Cargo will
+automatically search for a subcommand named cargo-{NAME} in the users PATH
+to execute the subcommand.
Thank you for your interest in contributing to Cargo! This guide provides an +overview of how to contribute to Cargo, how to dive into the code, and how the +testing infrastructure works.
+There are many ways to contribute, such as helping other users, filing +issues, improving the documentation, triaging issues, fixing bugs, and +working on small and large features.
+If you have a general question about Cargo or its internals, feel free to ask +on Zulip.
+This guide assumes you have some familiarity with Rust, and how to use Cargo, +rustup, and general development tools like git.
+Please also read the Rust Code of Conduct.
+ +Cargo’s issue tracker is located at +https://github.com/rust-lang/cargo/issues/. This is the primary spot where +we track bugs and small feature requests. See Process for more about our +process for proposing changes.
+We can’t fix what we don’t know about, so please report problems liberally. +This includes problems with understanding the documentation, unhelpful error +messages, and unexpected behavior.
+If you think that you have identified an issue with Cargo that might +compromise its users’ security, please do not open a public issue on GitHub. +Instead, we ask you to refer to Rust’s security policy.
+Opening an issue is as easy as following this link. There are +several templates for different issue kinds, but if none of them fit your +issue, don’t hesitate to modify one of the templates, or click the Open a +blank issue link.
+The Rust tools are spread across multiple repositories in the Rust +organization. It may not always be clear where to file an issue. No worries! +If you file in the wrong tracker, someone will either transfer it to the +correct one or ask you to move it. Some other repositories that may be +relevant are:
+rust-lang/rust — Home for the rustc compiler and rustdoc.rust-lang/rustup — Home for the rustup toolchain installer.rust-lang/rustfmt — Home for the rustfmt tool, which also includes cargo fmt.rust-lang/rust-clippy — Home for the clippy tool, which also includes cargo clippy.rust-lang/crates.io — Home for the crates.io website.Issues with cargo fix can be tricky to know where they should be filed,
+since the fixes are driven by rustc, and the front-interface is implemented
+in Cargo. Feel free to file in the Cargo issue tracker, and it will get moved
+to the rust-lang/rust issue tracker if necessary.
Issue labels are very helpful to identify the types of issues and which +category they are related to.
+Anyone can apply most labels by posting comments with a form such as:
+@rustbot label: +A-doctests, -A-dependency-resolution
+This example will add the A-doctests label and remove the
+A-dependency-resolution label.
The labels use a naming convention with short prefixes and colors to indicate +the kind of label:
+ +| Labels | Color | Description |
|---|---|---|
| A- | Yellow | The area of the project an issue relates to. |
| beta- | Dark Blue | Tracks changes which need to be backported to beta |
| C- | Light Purple | The category of an issue. |
| Command- | Dark Purple | The cargo command it is related to. |
| E- | Green | The experience level necessary to fix an issue. |
| I- | Red | The importance of the issue. |
| O- | Purple Grey | The operating system or platform that the issue is specific to. |
| P- | Orange | The issue priority. |
| regression- | Pink | Tracks regressions from a stable release. |
| relnotes | Light Orange | Marks issues or PRs that should be highlighted in the Rust release notes of the next release. |
| S- | Varies | Tracks the status of issues and pull requests (see Issue status labels) |
| Z- | Dark Blue | Unstable, nightly features. |
The S- prefixed status labels are the primary mechanism we use to track
+what is happening with an issue and what it is waiting on. The following is a
+list of the status labels and what they mean. This is listed roughly in the
+order that an issue might go through, though issues will often jump to
+different steps, or in rare cases have multiple statuses.
S-triage — New issues get this label automatically assigned to them +to indicate that nobody has yet looked at them, and they need someone to +assign other labels and decide what the next step is.
+S-needs-info — Needs more info, such as a reproduction or more +background for a feature request.
+Anyone is welcome to help with providing additional info to help reproduce +or provide more detail on use cases and such. But usually this is a request +to the initial author.
+When adding this label, there should also usually be a comment that goes +along with it stating the information requested.
+S-needs-team-input — Needs input from team on whether/how to +proceed.
+Here it is essentially blocked waiting for a team member to move it to the +next stage.
+S-needs-design — Needs someone to work further on the design for the +feature or fix.
+Anyone is welcome to help at this stage, but it should be clear that it is +not yet accepted. It is expected that people should contribute comments and +ideas to the issue which furthers the process of fleshing out what is +needed, or alternate ideas. This may also require reaching out to the wider +community via forums and such.
+S-needs-rfc — Needs an RFC before this can make more progress.
+Anyone is welcome to help at this stage, but it should be clear that it is +not yet accepted. +See Before creating an RFC +for next steps.
+S-needs-mentor — Needs a Cargo team member to commit to helping and +reviewing.
+This is for something that is accepted, such as after an RFC or a team +discussion, or an obvious issue that just needs fixing, but no team member +is available to help or review.
+S-accepted — Issue or feature is accepted, and has a team member +available to help mentor or review.
+S-waiting-on-feedback — An implemented feature is waiting on +community feedback for bugs or design concerns.
+This is typically used on a tracking issue after it has been implemented +to indicate what it is waiting on.
+Triaging issues involves processing issues to assign appropriate labels, make +sure the issue has sufficient information, and to decide the next steps. +When new issues are filed, they should automatically get the S-triage label +assuming the author uses one of the templates. This helps identify which +issues have not yet been triaged.
+There are several things to consider when triaging an issue:
+Is this a duplicate? Search the issue tracker (including closed issues) to +see if there is an issue with a similar or identical root cause to what is reported. +We generally focus issues around root causes so alternative solutions can be +discussed and evaluated together. +If it is obviously a duplicate, write a comment that it is a duplicate of the +other issue, and close the issue. +If it isn’t obvious that it is a duplicate, leave a comment asking the author +if the other issue covers what they reported.
+For a bug, check if the report contains enough information to reproduce it. +If you can’t reproduce it, solicit more information from the author to +better understand the issue. +Change the label from S-triage to S-needs-info if this is the case.
+Add labels that describe what the issue is related to.
+Assuming the issue looks valid, switch the S-triage label for one of the following:
+Anyone is welcome to help with the triaging process. You can help with
+reproducing issues, checking for duplicates, gathering more information from
+the reporter, assigning labels using @rustbot comments, and
+creating a test using Cargo’s testsuite (example).
Thank you for your interest in contributing to Cargo! This guide provides an +overview of how to contribute to Cargo, how to dive into the code, and how the +testing infrastructure works.
+There are many ways to contribute, such as helping other users, filing +issues, improving the documentation, triaging issues, fixing bugs, and +working on small and large features.
+If you have a general question about Cargo or its internals, feel free to ask +on Zulip.
+This guide assumes you have some familiarity with Rust, and how to use Cargo, +rustup, and general development tools like git.
+Please also read the Rust Code of Conduct.
+Cargo’s issue tracker is located at +https://github.com/rust-lang/cargo/issues/. This is the primary spot where +we track bugs and small feature requests. See Process for more about our +process for proposing changes.
+We can’t fix what we don’t know about, so please report problems liberally. +This includes problems with understanding the documentation, unhelpful error +messages, and unexpected behavior.
+If you think that you have identified an issue with Cargo that might +compromise its users’ security, please do not open a public issue on GitHub. +Instead, we ask you to refer to Rust’s security policy.
+Opening an issue is as easy as following this link. There are +several templates for different issue kinds, but if none of them fit your +issue, don’t hesitate to modify one of the templates, or click the Open a +blank issue link.
+The Rust tools are spread across multiple repositories in the Rust +organization. It may not always be clear where to file an issue. No worries! +If you file in the wrong tracker, someone will either transfer it to the +correct one or ask you to move it. Some other repositories that may be +relevant are:
+rust-lang/rust — Home for the rustc compiler and rustdoc.rust-lang/rustup — Home for the rustup toolchain installer.rust-lang/rustfmt — Home for the rustfmt tool, which also includes cargo fmt.rust-lang/rust-clippy — Home for the clippy tool, which also includes cargo clippy.rust-lang/crates.io — Home for the crates.io website.Issues with cargo fix can be tricky to know where they should be filed,
+since the fixes are driven by rustc, and the front-interface is implemented
+in Cargo. Feel free to file in the Cargo issue tracker, and it will get moved
+to the rust-lang/rust issue tracker if necessary.
Issue labels are very helpful to identify the types of issues and which +category they are related to.
+Anyone can apply most labels by posting comments with a form such as:
+@rustbot label: +A-doctests, -A-dependency-resolution
+This example will add the A-doctests label and remove the
+A-dependency-resolution label.
The labels use a naming convention with short prefixes and colors to indicate +the kind of label:
+ +| Labels | Color | Description |
|---|---|---|
| A- | Yellow | The area of the project an issue relates to. |
| beta- | Dark Blue | Tracks changes which need to be backported to beta |
| C- | Light Purple | The category of an issue. |
| Command- | Dark Purple | The cargo command it is related to. |
| E- | Green | The experience level necessary to fix an issue. |
| I- | Red | The importance of the issue. |
| O- | Purple Grey | The operating system or platform that the issue is specific to. |
| P- | Orange | The issue priority. |
| regression- | Pink | Tracks regressions from a stable release. |
| relnotes | Light Orange | Marks issues or PRs that should be highlighted in the Rust release notes of the next release. |
| S- | Varies | Tracks the status of issues and pull requests (see Issue status labels) |
| Z- | Dark Blue | Unstable, nightly features. |
The S- prefixed status labels are the primary mechanism we use to track
+what is happening with an issue and what it is waiting on. The following is a
+list of the status labels and what they mean. This is listed roughly in the
+order that an issue might go through, though issues will often jump to
+different steps, or in rare cases have multiple statuses.
S-triage — New issues get this label automatically assigned to them +to indicate that nobody has yet looked at them, and they need someone to +assign other labels and decide what the next step is.
+S-needs-info — Needs more info, such as a reproduction or more +background for a feature request.
+Anyone is welcome to help with providing additional info to help reproduce +or provide more detail on use cases and such. But usually this is a request +to the initial author.
+When adding this label, there should also usually be a comment that goes +along with it stating the information requested.
+S-needs-team-input — Needs input from team on whether/how to +proceed.
+Here it is essentially blocked waiting for a team member to move it to the +next stage.
+S-needs-design — Needs someone to work further on the design for the +feature or fix.
+Anyone is welcome to help at this stage, but it should be clear that it is +not yet accepted. It is expected that people should contribute comments and +ideas to the issue which furthers the process of fleshing out what is +needed, or alternate ideas. This may also require reaching out to the wider +community via forums and such.
+S-needs-rfc — Needs an RFC before this can make more progress.
+Anyone is welcome to help at this stage, but it should be clear that it is +not yet accepted. +See Before creating an RFC +for next steps.
+S-needs-mentor — Needs a Cargo team member to commit to helping and +reviewing.
+This is for something that is accepted, such as after an RFC or a team +discussion, or an obvious issue that just needs fixing, but no team member +is available to help or review.
+S-accepted — Issue or feature is accepted, and has a team member +available to help mentor or review.
+S-waiting-on-feedback — An implemented feature is waiting on +community feedback for bugs or design concerns.
+This is typically used on a tracking issue after it has been implemented +to indicate what it is waiting on.
+Triaging issues involves processing issues to assign appropriate labels, make +sure the issue has sufficient information, and to decide the next steps. +When new issues are filed, they should automatically get the S-triage label +assuming the author uses one of the templates. This helps identify which +issues have not yet been triaged.
+There are several things to consider when triaging an issue:
+Is this a duplicate? Search the issue tracker (including closed issues) to +see if there is an issue with a similar or identical root cause to what is reported. +We generally focus issues around root causes so alternative solutions can be +discussed and evaluated together. +If it is obviously a duplicate, write a comment that it is a duplicate of the +other issue, and close the issue. +If it isn’t obvious that it is a duplicate, leave a comment asking the author +if the other issue covers what they reported.
+For a bug, check if the report contains enough information to reproduce it. +If you can’t reproduce it, solicit more information from the author to +better understand the issue. +Change the label from S-triage to S-needs-info if this is the case.
+Add labels that describe what the issue is related to.
+Assuming the issue looks valid, switch the S-triage label for one of the following:
+Anyone is welcome to help with the triaging process. You can help with
+reproducing issues, checking for duplicates, gathering more information from
+the reporter, assigning labels using @rustbot comments, and
+creating a test using Cargo’s testsuite (example).
The Cargo Team is a group of volunteers that support the Rust community in developing and maintaining Cargo, the Rust package manager and build tool. +The team is responsible for deciding how Cargo and its related libraries operate and evolve. +The team has a shared responsibility with the crates.io team for the design and usage of Cargo’s index format and its registry API as it relates to the crates.io service.
+The team is expected to keep Cargo in an operational state, to support Rust’s 6-week release cycle, and to uphold the Design Principles of Cargo.
+The Cargo Team consists of team members with one serving as a team leader. +The team leader is responsible for coordinating the team and providing a contact point with other teams. +The leader is selected by consensus of the existing members with no objections.
+Membership is maintained in the Rust team database.
+Team members are expected to participate in voting on RFCs and major change proposals
+Team members are expected to regularly participate in at least some of the following membership-related activities. +Members are not expected to participate in all of these activities, but exhibit some interest and involvement in the project that covers some of these activities.
+Breaks and vacations are welcome and encouraged. +If a member is no longer participating after a few months, they may be asked to step down.
+Members are required to always:
+Members are given privileges, such as:
+The team meets on a weekly basis on a video chat. +If you are interested in participating, feel free to contact us on Zulip.
+Minutes for all meetings are recorded on HackMD.
+A contributor can become a member of the Cargo Team by requesting a review or being nominated by one of the existing members. +They can be added by unanimous consent of the team. +The team lead or another member of the team will also confirm with the moderation team that there are no concerns involving the proposed team member.
+Contributors who wish to join the team should exhibit an interest in carrying the design principles of Cargo and participate in some of the activities listed above in Membership Expectations.
+Members may leave at any time, preferably by letting the team know ahead of time.
+The Cargo team has several streams on Zulip:
+#t-cargo — General public channel for discussing any topics related to Cargo.#t-cargo/build-integration — Discussions about integration with build systems.#t-cargo/PubGrub — Discussions about the PubGrub project.The following are private streams for the Cargo team. The team should avoid using this unless necessary (for example, discussing a security issue or team and meeting organization).
+#t-cargo/private — Private channel for discussions among the team.#t-cargo/meetings — Private channel for discussions about team meetings, including non-members who regularly attend the meetings.The Cargo team has a shared, public workspace on HackMD at https://hackmd.io/@rust-cargo-team for drafting documents and recording meeting minutes.
+Since this HackMD workspace is using the free service, it does not support private documents. If you need to draft a private document, create it in your personal workspace and use private channels to share the link.
+The team uses a consensus-driven process for making decisions ranging from new features and major changes to management of the team itself. +The degree of process is correlated with the degree of change being proposed:
+Bug fixes, refactorings, documentation updates, and other small changes are usually delegated to a single team member (who is not the author) to approve based on their judgement. +Team members may also solicit feedback from other members or the whole team for any change should they want to gather other perspectives from the team.
+Some examples of what this might cover are:
+Small features or changes, large refactorings, or major changes to Cargo’s codebase or process require an approval by the team via consensus. +These decisions can be done via the FCP process of rfcbot, or in an ad-hoc manner such as during a team meeting. +rfcbot FCP requests do not require waiting for the 10-day feedback window if there is a complete team consensus, as this process is mostly aimed at polling the team rather than publicly soliciting feedback. +Though, public feedback is welcome at any time.
+Some examples of what this might cover are:
+Larger features should usually go through the RFC process. +This usually involves first soliciting feedback from the Cargo team and the rest of the community, often via the Rust Internals discussion board, Cargo’s issue tracker, and the Zulip channel. +If there is positive feedback to the idea, the next step is to formally post an RFC on the RFC repo. +The community and the Cargo team will have an opportunity to provide feedback on the proposal. +After some period of time, the Cargo team may decide to either accept, postpone, or close a proposal based on the interest in the proposal and the team’s availability.
+Some examples of what this might cover are:
+Cargo.toml or the config files.cargo commands that are not trivial.
+In some cases, the team may decide to adopt a pre-existing external command without an RFC if the command has already been broadly adopted.Stabilization of Unstable features requires an approval via the FCP process of rfcbot. +This provides a final opportunity to solicit feedback from the public, and for the Cargo team to agree via consensus.
+The team may decide to experiment with larger features without starting the RFC process if it is an initiative that the team has consensus that it is something they want to pursue. +This is usually reserved for something that has an unclear path that the RFC process is not expected to provide feedback that would substantially move the process forward. +Such experiments are expected to be nightly-only (see the Unstable chapter), and involve efforts to shape the final result via exploration, testing, and public involvement. +Any such features must ultimately have an RFC approved before they can be stabilized.
+The team may be contacted through several channels:
+t-cargo Zulip channel stream is the chat platform the Cargo Team uses to coordinate on.This chapter gives an overview of how Cargo comes together, and how you can be +a part of that process.
+See the Working on Cargo chapter for an overview of the contribution +process.
+Please read the guidelines below before working on an issue or new feature.
+Some Cargo team members are available to directly mentor contributions to Cargo. +See the office hours page for more information.
+The Roadmap Project Board is used for tracking major initiatives. This gives +an overview of the things the team is interested in and thinking about.
+The RFC Project Board is used for tracking RFCs.
+Issues labeled with the S-accepted label are typically issues that the +Cargo team wants to see addressed. If you are interested in one of those, and +it has not already been assigned to someone, leave a comment. See Issue +assignment below for assigning yourself.
+When possible, the Cargo team will try to also include E-easy, E-medium, +or E-hard labels to try to give an estimate of the difficulty involved with +the issue.
+If there is a specific issue that you are interested in, but it is not marked +as S-accepted, leave a comment on the issue. If a Cargo team member has the +time to help out, they will respond to help with the next steps.
+Small feature requests are typically managed on the issue +tracker. Features that the Cargo team have approved +will have the S-accepted label.
+If there is a feature request that you are interested in, but it is not marked +as S-accepted, feel free to leave a comment expressing your interest. If a +Cargo team member has the time to help out, they will respond to help with the +next steps. Keep in mind that the Cargo team has limited time, and may not be +able to help with every feature request. Most of them require some design +work, which can be difficult. Check out the design principles chapter for +some guidance.
+Cargo follows the Rust model of evolution. Major features usually go through +an RFC process. Therefore, before opening a feature request issue create a +Pre-RFC thread on the internals forum to get preliminary feedback.
+Implementing a feature as a custom subcommand is encouraged as +it helps demonstrate the demand for the functionality and is a great way to +deliver a working solution faster as it can iterate outside of Cargo’s release +cadence.
+See the unstable chapter for how new major features are typically +implemented.
+The Cargo project uses several bots:
+Normally, if you plan to work on an issue that has been marked with the
+S-accepted label, it is sufficient just to leave a comment that you are
+working on it. We also have a bot that allows you to formally claim an issue
+by entering the text @rustbot claim in a comment. See the Issue Assignment docs
+on how this works.
This chapter gives an overview of how to build Cargo, make a change, and +submit a Pull Request.
+We encourage people to discuss their design before hacking on code. This gives +the Cargo team a chance to know your idea more. Sometimes after a discussion, +we even find a way to solve the problem without coding! Typically, you +file an issue or start a thread on the internals forum before submitting a +pull request.
+Please read the process of how features and bugs are managed in Cargo. +Only issues that have been explicitly marked as accepted will be reviewed.
+We use the “fork and pull” model described here, where +contributors push changes to their personal fork and create pull requests to +bring those changes into the source repository. Cargo uses git and GitHub +for all development.
+rust-lang/cargo repository on GitHub to your personal account
+(see GitHub docs).git clone (see GitHub
+docs)Cargo is built by…running cargo! There are a few prerequisites that you
+need to have installed:
rustc and cargo need to be installed. Cargo is expected to build and
+test with the current stable, beta, and nightly releases. It is your choice
+which to use. Nightly is recommended, since some nightly-specific tests are
+disabled when using the stable release. But using stable is fine if you
+aren’t working on those.libssl-dev on Ubuntu, openssl-devel on Fedora)openssl package)If you can successfully run cargo build, you should be good to go!
You can use cargo run to run cargo itself, or you can use the path directly
+to the cargo binary, such as target/debug/cargo.
If you are using rustup, beware that running the binary directly can cause
+issues with rustup overrides. Usually, when cargo is executed as part of
+rustup, the toolchain becomes sticky (via an environment variable), and all
+calls to rustc will use the same toolchain. But when cargo is not run via
+rustup, the toolchain may change based on the directory. Since Cargo changes
+the directory for each compilation, this can cause different calls to rustc
+to use different versions. There are a few workarounds:
rustup run target/debug/cargo to execute cargo.RUSTC environment variable to a specific rustc executable (not
+the rustup wrapper).toolchains directory, and create symlinks for all
+the files and directories in there to your toolchain of choice (such as
+nightly), except for the cargo binary, which you can symlink to your
+target/debug/cargo binary in your project directory.Normally, all development is done by running Cargo’s test suite, so running +it directly usually isn’t required. But it can be useful for testing Cargo on +more complex projects.
+Some guidelines on working on a change:
+rustfmt. You can use rustup component add rustfmt to install rustfmt
+and use cargo fmt to automatically format your code.After you have committed your work, and pushed it to GitHub, you can +open a Pull Request
+master branch.Closes #1234 will link issue
+#1234 to the PR. When the PR is merged, GitHub will automatically close the
+issue.@rustbot will automatically assign a reviewer for the PR. It
+may take at least a few days for someone to respond. If you don’t get a
+response in over a week, feel free to ping the assigned reviewer.
When your PR is submitted, GitHub automatically runs all tests. The GitHub +interface will show a green checkmark if it passes, or a red X if it fails. +There are links to the logs on the PR page to diagnose any issues. The tests +typically finish in under 30 minutes.
+The reviewer might point out changes deemed necessary. Large or tricky changes +may require several passes of review and changes.
+++tip: Prefer atomic commits where each commit is a single, complete, and coherent unit of work. +For example, if your feature work leads to renaming a module, make the rename its own commit. +However, adding an internal function that is unused is not complete or coherent.
+As part of your atomic commits, prefer adding tests as their own commit before any functionality changes. +The tests should pass in each commit, demonstrating the behavior before your +change and how each commit affects behavior. +This makes it easier for reviewers and community members to understand the +precise details of the side effects of your change and gives you confidence +that your tests are verifying the right behavior.
+Examples:
+ +
PRs will get marked with labels like S-waiting-on-review or S-waiting-on-author to indicate their status.
+The @rustbot bot can be used by anyone to adjust the labels.
+If a PR gets marked as S-waiting-on-author, and you have pushed new changes that you would like to be reviewed, you can write a comment on the PR with the text @rustbot ready.
+The bot will switch the labels on the PR.
More information about these commands can be found at the shortcuts documentation.
+After a reviewer has approved your PR, they will issue a command to the bors
+bot (also known as “Homu”, the software that powers @bors). Bors will
+create a temporary branch with your PR, and run all tests. Only if all tests
+pass will it merge the PR to master. If it fails, the bot will leave a comment
+on the PR. This system ensures that the master branch is always in a good
+state, and that merges are processed one at a time. The Homu queue
+dashboard shows the current merge queue. Cargo’s queue is rarely
+busy, but a busy project like the rust repo is constantly full.
Assuming everything works, congratulations! It may take at least a week for +the changes to arrive on the nightly channel. See the release chapter for +more information on how Cargo releases are made.
+Cargo is released with rustc using a “train model”. After a
+change lands in Cargo’s master branch, it will be synced with the
+rust-lang/rust repository by a Cargo team member, which happens about once a
+week. If there are complications, it can take longer. After it is synced and
+merged, the changes will appear in the next nightly release, which is usually
+published around 00:30 UTC.
After changes are in the nightly release, they will make their way to the +stable release anywhere from 6 to 12 weeks later, depending on when during the +cycle it landed.
+The current release schedule is posted on the Rust Forge. See the release +process for more details on how Rust’s releases are created. Rust releases +are managed by the Release team.
+The build process for Cargo is handled as part of building Rust. Every PR on
+the rust-lang/rust repository creates a full collection of release artifacts
+for every platform. The code for this is in the dist bootstrap module.
+Every night at 00:00 UTC, the artifacts from the most recently merged PR are
+promoted to the nightly release channel. A similar process happens for beta
+and stable releases.
Cargo is tracked in the rust-lang/rust repository using a git submodule. +It is updated manually about once a week by a Cargo team member. +However, anyone is welcome to update it as needed.
+@ehuss has a tool called subup to automate the process of updating the submodule, updating the lockfile, running tests, and creating a PR. +Running the tests ahead-of-time helps avoid long cycle times waiting for bors if there are any errors. +Subup will also provide a message to include in the PR with a list of all PRs it covers. +Posting this in the PR message also helps create reference links on each Cargo PR to the submodule update PR to help track when it gets merged.
+The following is an example of the command to run in a local clone of rust-lang/rust to run a certain set of tests of things that are likely to get broken by a Cargo update:
+subup --up-branch update-cargo \
+ --commit-message "Update cargo" \
+ --test="src/tools/linkchecker tidy \
+ src/tools/cargo \
+ src/tools/rustfmt" \
+ src/tools/cargo
+If doing a beta backport, the command is similar, but needs to point to the correct branches:
+subup --up-branch update-beta-cargo \
+ --rust-branch beta \
+ --set-config rust.channel=beta \
+ --commit-message "[beta] Update cargo" \
+ --test="src/tools/linkchecker tidy \
+ src/tools/cargo \
+ src/tools/rustfmt" \
+ rust-1.66.0:src/tools/cargo
+Shortly after each major release, a Cargo team member will post a PR to update
+Cargo’s version in Cargo.toml. Cargo’s library is permanently unstable, so
+its version number starts with a 0. The minor version is always 1 greater
+than the Rust release it is a part of, so cargo 0.49.0 is part of the 1.48
+Rust release. The CHANGELOG is also usually updated at this time.
Also, any version-specific checks that are no longer needed can be removed. +For example, some tests are disabled on stable if they require some nightly +behavior. Once that behavior is available on the new stable release, the +checks are no longer necessary. (I usually search for the word “nightly” in +the testsuite directory, and read the comments to see if any of those nightly +checks can be removed.)
+Sometimes Cargo will have a runtime check to probe rustc if it supports a
+specific feature. This is usually stored in the TargetInfo struct. If this
+behavior is now stable, those checks should be removed.
Cargo has several other packages in the crates/ directory. If any of these
+packages have changed, the version should be bumped before the beta
+release. It is rare that these get updated. Bumping these as-needed helps
+avoid churning incompatible version numbers. This process should be improved
+in the future!
@ehuss has a tool called cargo-new-release to automate the process of doing a version bump. +It runs through several steps:
+It opens a browser tab for every PR in order to review each change. +It places each PR in the changelog with its title, but usually every PR should be rewritten to explain the change from the user’s perspective. +Each PR should also be categorized as an Addition, Change, Fix, or Nightly-only change. +Most PRs are deleted, since they are not relevant to users of Cargo. +For example, remove all PRs related to Cargo internals, infrastructure, documentation, error changes, refactorings, etc. +Usually about half of the PRs get removed. +This process usually takes @ehuss about an hour to finish.
+Docs are automatically published during the Rust release process. The nightly +channel’s docs appear at https://doc.rust-lang.org/nightly/cargo/. Once +nightly is promoted to beta, those docs will appear at +https://doc.rust-lang.org/beta/cargo/. Once the stable release is made, it +will appear on https://doc.rust-lang.org/cargo/ (which is the “current” +stable) and the release-specific URL such as +https://doc.rust-lang.org/1.46.0/cargo/.
+The code that builds the documentation is located in the doc bootstrap
+module.
Cargo’s library and its related dependencies (like cargo-util) are published
+to crates.io as part of the 6-week stable release process by the Release
+team. There is a publish.py script that is used by the Release team’s
+automation scripts (see https://github.com/rust-lang/simpleinfra/) to handle
+determining which packages to publish. The build tool crates aren’t published.
+This runs on the specific git commit associated with the cargo submodule in the
+stable branch in rust-lang/rust at the time of release.
On very rare cases, the Cargo team may decide to manually publish a new
+release to crates.io. For example, this may be necessary if there is a
+problem with the current version that only affects API users, and does not
+affect the cargo binary shipped in the stable release. In this situation,
+PRs should be merged to the associated stable release branch in the cargo repo
+(like rust-1.70.0) that fix the issue and bump the patch version of the
+affected package. Then someone with permissions (currently a subset of the
+Cargo team, or the Release team) should publish it manually using cargo publish.
Some packages are not published automatically because they are not part of the
+Rust release train. This currently only includes the home package. These
+are published manually on an as-needed or as-requested basis by whoever has
+permissions (currently @ehuss or the Release/Infra team).
In the future, these manual publishing options should be integrated with +GitHub Actions so that any team member can trigger them. Likely that should +involve getting Infra to create scoped tokens that can be added as GitHub +Secrets, and setting up GitHub Actions workflows with the appropriate +permissions which can be manually triggered to launch a release.
+If there is a regression or major problem detected during the beta phase, it +may be necessary to backport a fix to beta. The process is documented in the +Beta Backporting page.
+In (hopefully!) very rare cases, a major regression or problem may be reported +after the stable release. Decisions about this are usually coordinated between +the Release team and the Cargo team. There is usually a high bar for making +a stable patch release, and the decision may be influenced by whether or not +there are other changes that need a new stable release.
+The process here is similar to the beta-backporting process. The
+rust-lang/cargo branch is the same as beta (rust-1.XX.0). The
+rust-lang/rust branch is called stable.
Most new features should go through the unstable process. This means that the +feature will only be usable on the nightly channel, and requires a specific +opt-in by the user. Small changes can skip this process, but please consult +with the Cargo team first.
+For features that require behavior changes or new syntax in Cargo.toml, then
+it will need a cargo-features value placed at the top of Cargo.toml to
+enable it. The process for adding a new feature is described in the
+features module. Code that implements the feature will need to manually
+check that the feature is enabled for the current manifest.
For features that add new command-line flags, config options, or environment
+variables, then the -Z flags will be needed to enable them. The features
+module also describes how to add these. New flags should use the
+fail_if_stable_opt method to check if the -Z unstable-options flag has
+been passed.
Every unstable feature should have a section added to the unstable chapter +describing how to use the feature.
+Each unstable feature should get a tracking issue. These issues are +typically created when a PR is close to being merged, or soon after it is +merged. Use the tracking issue template when creating a tracking issue.
+Larger features should also get a new label in the issue tracker so that when
+issues are filed, they can be easily tied together. Typically this would be
+one of the Z- prefixed labels for nightly features.
When opening a tracking issue, be sure to also add an S- status label to
+indicate what needs to happen for it to move forward:
Tracking issues may have multiple status labels if necessary, for example if +something is only partially implemented, it may have both +S-waiting-on-feedback (for what is implemented) and S-needs-mentor or +S-accepted to finish the rest of the work.
+Once an unstable feature is “complete”, the search for users to test
+and give feedback begins. Testing notes should be written up to give users an
+idea of how to test the new feature. An example being the
+workspace inheritance testing notes for workspace inheritance. Once testing
+notes have been written up you should make posts in various rust communities
+(rust subreddit, users, internals, etc). Example posts made for workspace
+inheritance: reddit post, users post, internals post. The unstable feature
+should also be added to This Week in Rust. This should be done by adding the
+label call-for-testing to the RFC for the feature and making a comment with a
+link to the testing notes and the tracking issue (as needed). If there is not an
+RFC, a pull request should be made to the TWiR repo adding the feature to the
+Call for Testing section (example).
After some period of time, typically measured in months, the feature can be +considered to be stabilized. The feature should not have any significant known +bugs or issues, and any design concerns should be resolved.
+The stabilization process depends on the kind of feature. For smaller +features, you can leave a comment on the tracking issue expressing interest in +stabilizing it. It can usually help to indicate that the feature has received +some real-world testing, and has exhibited some demand for broad use.
+For larger features that have not gone through the RFC process, then an RFC +to call for stabilization might be warranted. This gives the community a final +chance to provide feedback about the proposed design.
+For a small feature, or one that has already gone through the RFC process, a +Cargo Team member may decide to call for a “final comment period” using +rfcbot. This is a public signal that a major change is being made, and gives +the Cargo Team members an opportunity to confirm or block the change. This +process can take a few days or weeks, or longer if a concern is raised.
+Once the stabilization has been approved, the person who called for +stabilization should prepare a PR to stabilize the feature. This PR should:
+features module.-Z flags and help message if applicable.Issues involving reporting a security vulnerability in cargo usually start by following the Rust security policy. +The Security Response Working Group (“the WG”) is responsible for running the process of handling the response to a security issue. +Their process is documented at Handling Reports. +This document gives an overview of the process from a Cargo team member’s perspective.
+The general order of events happens as follows:
+The “reporter” (even if it is a Cargo team member) reports an issue to security@rust-lang.org.
+The WG will evaluate if the report is credible, and manages responses to the reporter.
+The WG will start a private Zulip stream to coordinate discussion and plans for a fix.
+The WG will pull in one or more team members into the Zulip stream (“responders”).
+A discussion then starts to evaluate the severity of the issue and what possible solutions should be considered. +This includes figuring out who will volunteer to actually develop the patches to resolve the issue, and who will review it.
+The WG will create a temporary private fork of the rust-lang/cargo repo using GitHub’s repository security advisory system.
+This provides a space where changes can be securely posted, and the security advisory can be drafted.
+See “Collaborating in a temporary private fork” for some screenshots of what this looks like.
+GitHub includes instructions on how to work with the fork.
Beware that the private fork has some limitations, such as not supporting CI, or (for some weird reason) not supporting syntax highlighting.
+Someone will need to review the patches and make sure everyone agrees on the solution. +This may also involve the WG conferring with the reporter to validate the fix.
+Create a rollout plan. +This includes deciding if there will be a new patch release of Rust, or if it should wait for the next stable release, or whether to remove the embargo on the fix.
+The WG will handle drafting a Security Advisory using GitHub’s Security Advisory (“GHSA”) system. +GHSA-r5w3-xm58-jv6j is an example of what this looks like. +This process also involves reserving a CVE number, where the report will eventually be posted.
+The responders should carefully review the report to make sure it is correct.
+This process may also involve deciding on the CVSS score. +There are a bunch of calculators on the web where you can see how this works (such as the FIRST CVSS Calculator, or you can view GitHub’s calculator by drafting a security advisory in one of your personal repos). +FIRST has a user guide for deciding how to score each characteristic.
+If it is decided to do a patch release of Rust, the general overview of steps is:
+rust-lang/rust to prepare the point release.
+This usually includes changes for stable, beta, and nightly.rust-lang/rust to incorporate the fix and prepare a new release.Sometimes it may be necessary to make changes to external dependencies to support a fix. +This can make things complicated. +If the change is by itself benign and not directly related to the security issue, +then it may be safe to publicly propose the change (but not giving context) and try to get a new release of the dependency made (though confer with the WG first!). +However, if the issue is directly related to the dependency, then it becomes significantly more awkward.
+The general process for GHSA-r5w3-xm58-jv6j which involved a fix in git2-rs was handled by the responders because it is a dependency owned by the rust-lang org.
+The general outline of how we managed this is:
rust-lang/git2-rs just like we did for rust-lang/cargo.
+git2-rs also had its own Security Advisory just like cargo did.rust-lang/cargo private fork had to have a temporary [patch] git dependency on the git2-rs private fork.[patch], and pretend as-if git2-rs had already been published.Cargo.lock to pick up the new git2 dependencies.If the change is in a crate not managed by any responder, then confer with the WG on a strategy. +One option is to create a temporary fork used for the security response that will be removed as soon as the security advisory is released and a new public release of the dependency is made with the fix.
+There are a lot of details to handle, and it can be a bit of a challenge under time pressure. +The following is a checklist of some items to pay attention to during the process.
+Pre-release:
+Cargo.toml is updated correctly on the stable branch private PR.Cargo.lock is updated (stable, beta, master branches).CHANGELOG.md on cargo’s master branch private PR.RELEASES.md on rust’s master branch private PR (and stable and beta?).[patch] table.Showtime:
+Cargo.lock.rust-lang/cargo get updated.rust-lang/rust get updated, pointing to the correct submodule versions.Post release:
+rust-lang/cargo got a new tag.rust-lang/cargo repository (stable, beta, and master).rust-lang/rust repository (stable, beta, and master).The purpose of Cargo is to formalize a canonical Rust workflow, by automating +the standard tasks associated with distributing software. Cargo simplifies +structuring a new project, adding dependencies, writing and running unit +tests, and more.
+Cargo is not intended to be a general-purpose build tool. Ideally, it should +be easy to integrate it within another build tool, though admittedly that is +not as seamless as desired.
+Cargo strives to remain backwards compatible with projects created in previous +versions. The CLI interface also strives to remain backwards compatible, such +that the commands and options behave the same. That being said, changes in +behavior, and even outright breakage are sometimes done in limited situations. +The following outlines some situations where backwards-incompatible changes are +made:
+None of these changes should be taken lightly, and should be avoided if +possible, or possibly with some transition period to alert the user of the +potential change.
+Behavior is sometimes changed in ways that have a high confidence that it +won’t break existing workflows. Almost every change carries this risk, so it +is often a judgment call balancing the benefit of the change with the +perceived possibility of its negative consequences.
+At times, some changes fall in the gray area, where the current behavior is +undocumented, or not working as intended. These are more difficult judgment +calls. The general preference is to balance towards avoiding breaking existing +workflows.
+Support for older registry APIs and index formats may be dropped, if there is +high confidence that there aren’t any active registries that may be affected. +This has never (to my knowledge) happened so far, and is unlikely to happen in +the future, but remains a possibility.
+In all of the above, a transition period may be employed if a change is known +to cause breakage. A warning can be issued to alert the user that something +will change, and provide them with an alternative to resolve the issue +(preferably in a way that is compatible across versions if possible).
+Cargo is only expected to work with the version of the related Rust tools
+(rustc, rustdoc, etc.) that it is released with. As a matter of choice,
+the latest nightly works with the most recent stable release, but that is
+mostly to accommodate development of Cargo itself, and should not be expected
+by users.
Additionally, Cargo strives a limited degree of forwards compatibility. +Changes should not egregiously prevent older versions from working. This is +mostly relevant for persistent data, such as on-disk files and the registry +interface and index. It also applies to a lesser degree to the registry API.
+Changes to Cargo.lock require a transition time, where the new format is not
+automatically written when the lock file is updated. The transition time
+should not be less than 6 months, though preferably longer. New projects may
+use the new format in a shorter time frame.
Changes to Cargo.toml can be made in any release. This is because the user
+must manually modify the file, and opt-in to any new changes. Additionally,
+Cargo will usually only issue a warning about new fields it doesn’t
+understand, but otherwise continue to function.
Changes to cache files (such as artifacts in the target directory, or cached
+data in Cargo’s home directory) should not prevent older versions from
+running, but they may cause older versions to recreate the cache, which may
+result in a performance impact.
Changes to the registry index should not prevent older versions from working. +Generally, older versions ignore new fields, so the format should be easily +extensible. Changes to the format or interpretation of existing fields should +be done very carefully to avoid preventing older versions of Cargo from +working. In some cases, this may mean that older versions of Cargo will not be +able to select a newly published crate, but it shouldn’t prevent them from +working at all. This level of compatibility may not last forever, but the +exact time frame for such a change has not yet been decided.
+The registry API may be changed in such a way to prevent older versions of +Cargo from working. Generally, compatibility should be retained for as long as +possible, but the exact length of time is not specified.
+Standard workflows should be easy and consistent. Each knob that is added has +a high cost, regardless if it is intended for a small audience. Layering and +defaults can help avoid the surface area that the user needs to be concerned +with. Try to avoid small functionalities that may have complex interactions +with one another.
+This chapter gives an overview of what you need to know in making a change to cargo.
+If you feel something is missing that would help you, feel free to ask on +Zulip.
+See the
+nightly docs
+for an overview of cargos architecture and links out to further details.
This chapter sketches out how to add a new package to the cargo workspace.
+Choose the relevant parent directory
+credential/ for credential-process related packagesbenches/ for benchmarking of cargo itselfcrates/ for everything elseRun cargo new <name>
<name>:
+- over _cargo-util- prefixxtask- prefixpackage.rust-version
+# MSRV:1 comment# MSRV:3 commentIf its an xtask,
+.cargo/config.tomls [alias] tablepackage.publish = falseIf needed to be published with cargo,
+add the package to publish.py in the repo root,
+in dependency order.
Note: by adding the package to the workspace, you automatically get
+cargo testcargo doc warningsOur MSRV policies are
+We proactively update the MSRV
+To proactively update the MSRV, we use RenovateBot
+with the configuration file in .github/renovatebot.json5.
+To know what MSRV policy to use,
+it looks for comments of the form # MSRV:N,
+where N is the number of supported rust versions.
Cargo is a single binary composed of a set of clap subcommands. All
+subcommands live in src/bin/cargo/commands directory.
+src/bin/cargo/main.rs is the entry point.
Each subcommand, such as src/bin/cargo/commands/build.rs, usually performs
+the following:
command_prelude module for some helpers to make this easier.src/cargo/ops.If the subcommand is not found in the built-in list, then Cargo will
+automatically search for a subcommand named cargo-{NAME} in the users PATH
+to execute the subcommand.
All of Cargo’s output should go through the Shell struct. You can normally
+obtain the Shell instance from the GlobalContext struct. Do not use
+the std println! macros.
Most of Cargo’s output goes to stderr. When running in JSON mode, the output +goes to stdout.
+It is important to properly handle errors when writing to the console.
+Informational commands, like cargo list, should ignore any errors writing
+the output. There are some drop_print macros that are intended to make
+this easier.
Messages written during compilation should handle errors, and abort the build
+if they are unable to be displayed. This is generally automatically handled in
+the JobQueue as it processes each message.
Cargo uses anyhow for managing errors. This makes it convenient to “chain”
+errors together, so that Cargo can report how an error originated, and what it
+was trying to do at the time.
Error helpers are implemented in the errors module. Use the
+InternalError error type for errors that are not expected to happen. This
+will print a message to the user to file a bug report.
The binary side of Cargo uses the CliError struct to wrap the process exit
+code. Usually Cargo exits with 101 for an error, but some commands like cargo test will exit with different codes.
Some guidelines for Cargo’s output:
+std::fs, always add error
+context about what it is doing. For example, reading from a file should
+include context about which file is being read if there is an error.Cargo tends to get run on a very wide array of file systems. Different file +systems can have a wide range of capabilities, and Cargo should strive to do +its best to handle them. Some examples of issues to deal with:
+fs::canonicalize function doesn’t work on all file systems
+(particularly some Windows file systems). If that function is used, there
+should be a fallback if it fails. This function will also return \\?\
+style paths on Windows, which can have some issues (such as some tools not
+supporting them, or having issues with relative paths).fingerprint module has a deeper
+discussion of this. One example is that Docker cache layers will erase the
+fractional part of the time stamp.When modifying user files, like Cargo.toml, we should not change other
+sections of the file,
+preserving the general formatting.
+This includes the table, inline-table, or array that a field is being edited in.
When adding new entries, they do not need to match the canonical style of the +document but can use the default formatting. +If the entry is already sorted, preserving the sort order is preferred.
+When removing entries, +comments on the same line should be removed but comments on following lines +should be preserved.
+Inconsistencies in style after making a change are left to the user and their +preferred auto-formatter.
+Cargo uses the tracing crate to display debug log messages.
+The CARGO_LOG environment variable can be set to enable debug logging, with a value such as trace, debug, or warn.
+It also supports filtering for specific modules with comma-separated [directives].
+Feel free to use shorthand macros to help with diagnosing problems.
+We’re looking forward to making Cargo logging mechanism more structural!
# Outputs all logs with levels debug and higher
+CARGO_LOG=debug cargo generate-lockfile
+
+# Don't forget that you can filter by module as well
+CARGO_LOG=cargo::core::resolver=trace cargo generate-lockfile
+
+# This will print lots of info about the download process. `trace` prints even more.
+CARGO_HTTP_DEBUG=true CARGO_LOG=network=debug cargo fetch
+
+# This is an important command for diagnosing fingerprint issues.
+CARGO_LOG=cargo::core::compiler::fingerprint=trace cargo build
+Cargo has an extensive test suite. Most of it is implemented as integration
+tests in the testsuite directory. There are several other tests:
resolver-tests
+directory.crates directory have their own set of tests.build-std test is for the build-std feature. It is separate since
+it has some special requirements.Using cargo test is usually sufficient for running the full test suite. This
+can take a few minutes, so you may want to use more targeted flags to pick the
+specific test you want to run, such as cargo test --test testsuite -- check::check_success.
Some tests only run on the nightly toolchain, and will be ignored on other +channels. It is recommended that you run tests with both nightly and stable to +ensure everything is working as expected.
+Some of the nightly tests require the rustc-dev and llvm-tools-preview
+rustup components installed. These components include the compiler as a
+library. This may already be installed with your nightly toolchain, but if it
+isn’t, run rustup component add rustc-dev llvm-tools-preview --toolchain=nightly.
Some tests exercise cross compiling to a different target. This will require
+you to install the appropriate target. This typically is the 32-bit target of
+your host platform. For example, if your host is a 64-bit
+x86_64-unknown-linux-gnu, then you should install the 32-bit target with
+rustup target add i686-unknown-linux-gnu. If you don’t have the alternate
+target installed, there should be an error message telling you what to do. You
+may also need to install additional tools for the target. For example, on Ubuntu
+you should install the gcc-multilib package.
If you can’t install an alternate target, you can set the
+CFG_DISABLE_CROSS_TESTS=1 environment variable to disable these tests. The
+Windows cross tests only support the MSVC toolchain.
The build-std tests are disabled by default, but you can run them by setting
+the CARGO_RUN_BUILD_STD_TESTS=1 environment variable and running cargo test --test build-std. This requires the nightly channel, and also requires the
+rust-src component installed with rustup component add rust-src --toolchain=nightly.
gitoxide as default git backend in testsBy default, the git2 backend is used for most git operations. As tests need to explicitly
+opt-in to use nightly features and feature flags, adjusting all tests to run with nightly
+and -Zgitoxide is unfeasible.
This is why the private environment variable named __CARGO_USE_GITOXIDE_INSTEAD_OF_GIT2 can be
+set while running tests to automatically enable the -Zgitoxide flag implicitly, allowing to
+test gitoxide for the entire cargo test suite.
Some (very rare) tests involve connecting to the public internet.
+These tests are disabled by default,
+but you can run them by setting the CARGO_PUBLIC_NETWORK_TESTS=1 environment variable.
+Additionally our CI suite has a smoke test for fetching dependencies.
+For most contributors, you will never need to bother with this.
Tests marked with container_test involve running Docker to test more complex configurations.
+These tests are disabled by default,
+but you can run them by setting the CARGO_CONTAINER_TESTS=1 environment variable.
+You will need to have Docker installed and running to use these.
++Note: Container tests mostly do not work on Windows.
++
+- The SSH tests require ssh-agent, but the two versions of ssh-agent +on Windows are not suitable for testing. +
++
+- The Microsoft version of ssh-agent runs as a global service, and can’t be isolated per test.
+- The mingw/cygwin one can’t be accessed from a Windows executable like cargo.
+- Pageant similarly does not seem to have a way to isolate it (and I’m not certain it can be driven completely from the command-line).
+The tests also can’t run on Windows CI because the Docker that is preinstalled doesn’t support Linux containers, and setting up Windows containers is a pain.
+macOS should work with Docker installed and running, +but unfortunately the tests are not run on CI because Docker is not available.
+
The following focuses on writing an integration test. However, writing unit +tests is also encouraged!
+Cargo has a wide variety of integration tests that execute the cargo binary
+and verify its behavior, located in the testsuite directory. The
+support crate and snapbox contain many helpers to make this process easy.
There are two styles of tests that can roughly be categorized as
+These tests typically work by creating a temporary “project” with a
+Cargo.toml file, executing the cargo binary process, and checking the
+stdout and stderr output against the expected output.
Generally, a functional test will be placed in tests/testsuite/<command>.rs and will look roughly like:
#[cargo_test]
+fn <description>() {
+ let p = project()
+ .file("src/main.rs", r#"fn main() { println!("hi!"); }"#)
+ .build();
+
+ p.cargo("run --bin foo")
+ .with_stderr(
+ "\
+ [COMPILING] foo [..]
+ [FINISHED] [..]
+ [RUNNING] `target/debug/foo`
+ ",
+ )
+ .with_stdout("hi!")
+ .run();
+ }
+}The #[cargo_test] attribute is used in place of #[test] to inject some setup code.
ProjectBuilder via project():
Cargo.toml manifest using file(), one is
+automatically created with a project name of foo using basic_manifest().Execs via p.cargo(...):
support::compare for an explanation of the string pattern matching.
+Patterns are used to make it easier to match against the expected output.#[cargo_test] attributeThe #[cargo_test] attribute injects code which does some setup before starting the test.
+It will create a filesystem “sandbox” under the “cargo integration test” directory for each test, such as /path/to/cargo/target/tmp/cit/t123/.
+The sandbox will contain a home directory that will be used instead of your normal home directory.
The #[cargo_test] attribute takes several options that will affect how the test is generated.
+They are listed in parentheses separated with commas, such as:
#[cargo_test(nightly, reason = "-Zfoo is unstable")]The options it supports are:
+nightly — This will cause the test to be ignored if not running on the nightly toolchain.
+This is useful for tests that use unstable options in rustc or rustdoc.
+These tests are run in Cargo’s CI, but are disabled in rust-lang/rust’s CI due to the difficulty of updating both repos simultaneously.
+A reason field is required to explain why it is nightly-only.build_std_real — This is a “real” -Zbuild-std test (in the build_std integration test).
+This only runs on nightly, and only if the environment variable CARGO_RUN_BUILD_STD_TESTS is set (these tests on run on Linux).build_std_mock — This is a “mock” -Zbuild-std test (which uses a mock standard library).
+This only runs on nightly, and is disabled for windows-gnu.requires_ — This indicates a command that is required to be installed to be run.
+For example, requires_rustfmt means the test will only run if the executable rustfmt is installed.
+These tests are always run on CI.
+This is mainly used to avoid requiring contributors from having every dependency installed.>=1.64 — This indicates that the test will only run with the given version of rustc or newer.
+This can be used when a new rustc feature has been stabilized that the test depends on.
+If this is specified, a reason is required to explain why it is being checked.public_network_test — This tests contacts the public internet.
+These tests are disabled unless the CARGO_PUBLIC_NETWORK_TESTS environment variable is set.
+Use of this should be extremely rare, please avoid using it if possible.
+The hosts it contacts should have a relatively high confidence that they are reliable and stable (such as github.com), especially in CI.
+The tests should be carefully considered for developer security and privacy as well.container_test — This indicates that it is a test that uses Docker.
+These tests are disabled unless the CARGO_CONTAINER_TESTS environment variable is set.
+This requires that you have Docker installed.
+The SSH tests also assume that you have OpenSSH installed.
+These should work on Linux, macOS, and Windows where possible.
+Unfortunately these tests are not run in CI for macOS or Windows (no Docker on macOS, and Windows does not support Linux images).
+See crates/cargo-test-support/src/containers.rs for more on writing these tests.ignore_windows="reason" — Indicates that the test should be ignored on windows for the given reason.If you are testing a Cargo feature that only works on “nightly” Cargo, then
+you need to call masquerade_as_nightly_cargo on the process builder and pass
+the name of the feature as the reason, like this:
p.cargo("build").masquerade_as_nightly_cargo(&["print-im-a-teapot"])If you are testing a feature that only works on nightly rustc (such as
+benchmarks), then you should use the nightly option of the cargo_test
+attribute, like this:
#[cargo_test(nightly, reason = "-Zfoo is unstable")]This will cause the test to be ignored if not running on the nightly toolchain.
+You should not write any tests that use the network such as contacting +crates.io. Typically, simple path dependencies are the easiest way to add a +dependency. Example:
+let p = project()
+ .file("Cargo.toml", r#"
+ [package]
+ name = "foo"
+ version = "1.0.0"
+
+ [dependencies]
+ bar = {path = "bar"}
+ "#)
+ .file("src/lib.rs", "extern crate bar;")
+ .file("bar/Cargo.toml", &basic_manifest("bar", "1.0.0"))
+ .file("bar/src/lib.rs", "")
+ .build();If you need to test with registry dependencies, see
+support::registry::Package for creating packages you can depend on.
If you need to test git dependencies, see support::git to create a git
+dependency.
There are some utilities to help support tests that need to work against a +target other than the host. See Running cross +tests for more an introduction on cross +compilation tests.
+Tests that need to do cross-compilation should include this at the top of the +test to disable it in scenarios where cross compilation isn’t available:
+if cargo_test_support::cross_compile::disabled() {
+ return;
+}The name of the target can be fetched with the cross_compile::alternate()
+function. The name of the host target can be fetched with
+cargo_test_support::rustc_host().
The cross-tests need to distinguish between targets which can build versus
+those which can actually run the resulting executable. Unfortunately, macOS is
+currently unable to run an alternate target (Apple removed 32-bit support a
+long time ago). For building, x86_64-apple-darwin will target
+x86_64-apple-ios as its alternate. However, the iOS target can only execute
+binaries if the iOS simulator is installed and configured. The simulator is
+not available in CI, so all tests that need to run cross-compiled binaries are
+disabled on CI. If you are running on macOS locally, and have the simulator
+installed, then it should be able to run them.
If the test needs to run the cross-compiled binary, then it should have +something like this to exit the test before doing so:
+if cargo_test_support::cross_compile::can_run_on_host() {
+ return;
+}UI Tests are a bit more spread out and generally look like:
+tests/testsuite/<command>/mod.rs:
mod <case>;tests/testsuite/<command>/<case>/mod.rs:
use cargo_test_support::compare::assert_ui;
+use cargo_test_support::current_dir;
+use cargo_test_support::file;
+use cargo_test_support::prelude::*;
+use cargo_test_support::Project;
+
+#[cargo_test]
+fn case() {
+ let project = Project::from_template(current_dir!().join("in"));
+ let project_root = project.root();
+ let cwd = &project_root;
+
+ snapbox::cmd::Command::cargo_ui()
+ .arg("run")
+ .arg_line("--bin foo")
+ .current_dir(cwd)
+ .assert()
+ .success()
+ .stdout_matches(file!("stdout.log"))
+ .stderr_matches(file!("stderr.log"));
+
+ assert_ui().subset_matches(current_dir!().join("out"), &project_root);
+}Then populate
+tests/testsuite/<command>/<case>/in with the project’s directory structuretests/testsuite/<command>/<case>/out with the files you want verifiedtests/testsuite/<command>/<case>/stdout.log with nothingtests/testsuite/<command>/<case>/stderr.log with nothing#[cargo_test]:
#[test]/path/to/cargo/target/cit/t123/home directory that will be used instead of your normal home directoryProject:
Command via Command::cargo_ui():
OutputAssert via Command::assert():
CommandAssert via assert_ui():
The project, stdout, and stderr snapshots can be updated by running with the
+SNAPSHOTS=overwrite environment variable, like:
$ SNAPSHOTS=overwrite cargo test
+Be sure to check the snapshots to make sure they make sense.
+If you are testing a Cargo feature that only works on “nightly” Cargo, then
+you need to call masquerade_as_nightly_cargo on the process builder and pass
+the name of the feature as the reason, like this:
snapbox::cmd::Command::cargo()
+ .masquerade_as_nightly_cargo(&["print-im-a-teapot"])If you are testing a feature that only works on nightly rustc (such as
+benchmarks), then you should use the nightly option of the cargo_test
+attribute, like this:
#[cargo_test(nightly, reason = "-Zfoo is unstable")]This will cause the test to be ignored if not running on the nightly toolchain.
+When checking output, use / for paths even on Windows: the actual output
+of \ on Windows will be replaced with /.
Be careful when executing binaries on Windows. You should not rename, delete, +or overwrite a binary immediately after running it. Under some conditions +Windows will fail with errors like “directory not empty” or “failed to remove” +or “access is denied”.
+In some cases, you may need to dig into a test that is not working as you +expect, or you just generally want to experiment within the sandbox +environment. The general process is:
+Build the sandbox for the test you want to investigate. For example:
+cargo test --test testsuite -- features2::inactivate_targets.
In another terminal, head into the sandbox directory to inspect the files and run cargo directly.
The sandbox directories start with t0 for the first test.
cd target/tmp/cit/t0
Set up the environment so that the sandbox configuration takes effect:
+export CARGO_HOME=$(pwd)/home/.cargo
Most tests create a foo project, so head into that:
cd foo
Run whatever cargo command you want. See Running Cargo for more details
+on running the correct cargo process. Some examples:
/path/to/my/cargo/target/debug/cargo checklldb or gdb:
+lldb /path/to/my/cargo/target/debug/cargob generate_root_unitsr checkCargo leverages tracing +as a basic, hierarchical built-in profiler.
+Environment variables:
+CARGO_LOG_PROFILE=<true|1>: log tracing events to a file in the current working directoryCARGO_LOG_PROFILE_CAPTURE_ARGS=<true|1>: include arguments in the eventsAt process exit, your trace will be in a file like trace-1668480819035032.json.
+Open that file with ui.perfetto.dev (or chrome://tracing) to browse your trace.
Example:
+$ # Output first three levels of profiling info
+$ CARGO_LOG_PROFILE=true cargo generate-lockfile
+Note: This is intended for the development of cargo and there are no compatibility guarantees on this functionality.
+Head over to the benches
+directory for more
+information about the benchmarking suite.
The overhead for starting a build should be kept as low as possible +(preferably, well under 0.5 seconds on most projects and systems). Currently, +the primary parts that affect this are:
+One way to test this is to use hyperfine. This is a tool that can be used to
+measure the difference between different commands and settings. Usually this
+is done by measuring the time it takes for cargo build to finish in a large
+project where the build is fresh (no actual compilation is performed). Just
+run cargo build once before using hyperfine.
Crater is a tool for compiling and running tests for every crate on crates.io (and a few on GitHub). +It is mainly used for checking the extent of breakage when implementing potentially breaking changes and ensuring lack of breakage by running beta vs stable compiler versions.
+Essentially it runs some cargo command on every crate twice; once against the “start” toolchain and again against the “end” toolchain.
+For example, “start” could be the stable release, and “end” could be beta.
+If it passes in “start” but fails with “end”, then that is reported as a regression.
There is a bot called craterbot which is used to run crater on hardware managed by the rust-lang organization.
+Crater is run by the release team during the beta cycle. +If there are any regressions that look like they are caused by Cargo, they should contact the Cargo team to decide how to handle it.
+If you have a change that you want to test before the beta release, or you want to test behavior that is not normally exercised by crater, you can do a manual run of crater. +Roughly the steps are:
+Create a branch with your changes.
+In your clone of cargo, make the changes to incorporate whatever new thing you want to test and push it to a branch on your fork on GitHub.
+Get a clone of https://github.com/rust-lang/rust
+Create a branch in your rust-lang/rust clone to add your changes.
+Change the src/tools/cargo submodule to point to your new branch.
Modify .gitmodules to point to your clone and branch of cargo with the changes you want to test.
+For example:
git submodule set-url src/tools/cargo https://github.com/ehuss/cargo.git
+git submodule set-branch --branch my-awesome-feature src/tools/cargo
+git submodule update --remote src/tools/cargo
+git add .gitmodules src/tools/cargo
+git commit
+Create an PR on rust-lang/rust.
+Push your submodule changes to GitHub and make a PR.
+Start the PR title with [EXPERIMENT] to make it clear what the PR is for and assign yourself or @ghost.
Make a “try” build.
+A “try” build creates a full release of x86_64-unknown-linux-gnu and stores it on rust-lang servers.
+This can be done with a comment @bors try on the PR (all Cargo team members should have permission to do this).
Run crater.
+Look at the craterbot docs to determine the command that you want to run.
+There are different modes like check-only, build-and-test, rustdoc, etc.
You can also choose how many crates to run against.
+If you are uncertain if your cargo changes will work correctly, it might be a good idea to run against top-100 first to check its behavior.
+This will run much faster.
+You can do a full run afterwards.
After the try build finishes (which should take a couple hours), ask someone to make a crater run.
+The Cargo team does not have that permission, so just ask someone on Zulip.
+They will need to write a comment to @craterbot with the command that you have specified.
Wait.
+Crater can take anywhere from a few hours to a few weeks to run depending on how long the craterbot queue is and which mode you picked and the priority of your job. +When the crater run finishes, craterbot will post a comment to the PR with a link to a report of the results.
+Investigate the report.
+Look through the report which contains links to build logs for any regressions or errors.
+Close the PR.
+Whenever you are done doing crater runs, close your PR.
+Crater only has a few built-in modes, such as running cargo check or cargo test.
+You can pass extra flags with +cargoflags.
More complex tests can be accomplished by customizing Cargo to perform whatever actions you want.
+Since crater essentially runs cargo check, you can modify the check command to perform whichever actions you want.
+For example, to test cargo fix --edition, this commit intercepted cargo check and modified it to instead:
cargo fix --edition.cargo check to verify.If you need to compare the before and after of a command that is not part of crater’s built-in modes, that can be more difficult. +Two possible options:
+cargo check command as described above.
+The “start” build should perform whichever action you want with an otherwise unmodified cargo.
+The “end” build should perform whichever action you want with your modified cargo.
+Then, in the @craterbot command, specify the start and end hashes of the two try builds.There are some limitations of crater to consider when running Cargo:
+generate-lockfile and includes -Zno-index-update to prevent index updates (which makes it run much faster).cargo fetch.--frozen or --message-format=json.
+It will sometimes use --all-targets and sometimes not.
+Check the crater source for more details on how it works.This chapter gives an overview of how Cargo comes together, and how you can be +a part of that process.
+See the Working on Cargo chapter for an overview of the contribution +process.
+Please read the guidelines below before working on an issue or new feature.
+Some Cargo team members are available to directly mentor contributions to Cargo. +See the office hours page for more information.
+The Roadmap Project Board is used for tracking major initiatives. This gives +an overview of the things the team is interested in and thinking about.
+The RFC Project Board is used for tracking RFCs.
+Issues labeled with the S-accepted label are typically issues that the +Cargo team wants to see addressed. If you are interested in one of those, and +it has not already been assigned to someone, leave a comment. See Issue +assignment below for assigning yourself.
+When possible, the Cargo team will try to also include E-easy, E-medium, +or E-hard labels to try to give an estimate of the difficulty involved with +the issue.
+If there is a specific issue that you are interested in, but it is not marked +as S-accepted, leave a comment on the issue. If a Cargo team member has the +time to help out, they will respond to help with the next steps.
+Small feature requests are typically managed on the issue +tracker. Features that the Cargo team have approved +will have the S-accepted label.
+If there is a feature request that you are interested in, but it is not marked +as S-accepted, feel free to leave a comment expressing your interest. If a +Cargo team member has the time to help out, they will respond to help with the +next steps. Keep in mind that the Cargo team has limited time, and may not be +able to help with every feature request. Most of them require some design +work, which can be difficult. Check out the design principles chapter for +some guidance.
+Cargo follows the Rust model of evolution. Major features usually go through +an RFC process. Therefore, before opening a feature request issue create a +Pre-RFC thread on the internals forum to get preliminary feedback.
+Implementing a feature as a custom subcommand is encouraged as +it helps demonstrate the demand for the functionality and is a great way to +deliver a working solution faster as it can iterate outside of Cargo’s release +cadence.
+See the unstable chapter for how new major features are typically +implemented.
+The Cargo project uses several bots:
+Normally, if you plan to work on an issue that has been marked with the
+S-accepted label, it is sufficient just to leave a comment that you are
+working on it. We also have a bot that allows you to formally claim an issue
+by entering the text @rustbot claim in a comment. See the Issue Assignment docs
+on how this works.
Cargo is released with rustc using a “train model”. After a
+change lands in Cargo’s master branch, it will be synced with the
+rust-lang/rust repository by a Cargo team member, which happens about once a
+week. If there are complications, it can take longer. After it is synced and
+merged, the changes will appear in the next nightly release, which is usually
+published around 00:30 UTC.
After changes are in the nightly release, they will make their way to the +stable release anywhere from 6 to 12 weeks later, depending on when during the +cycle it landed.
+The current release schedule is posted on the Rust Forge. See the release +process for more details on how Rust’s releases are created. Rust releases +are managed by the Release team.
+The build process for Cargo is handled as part of building Rust. Every PR on
+the rust-lang/rust repository creates a full collection of release artifacts
+for every platform. The code for this is in the dist bootstrap module.
+Every night at 00:00 UTC, the artifacts from the most recently merged PR are
+promoted to the nightly release channel. A similar process happens for beta
+and stable releases.
Cargo is tracked in the rust-lang/rust repository using a git submodule. +It is updated manually about once a week by a Cargo team member. +However, anyone is welcome to update it as needed.
+@ehuss has a tool called subup to automate the process of updating the submodule, updating the lockfile, running tests, and creating a PR. +Running the tests ahead-of-time helps avoid long cycle times waiting for bors if there are any errors. +Subup will also provide a message to include in the PR with a list of all PRs it covers. +Posting this in the PR message also helps create reference links on each Cargo PR to the submodule update PR to help track when it gets merged.
+The following is an example of the command to run in a local clone of rust-lang/rust to run a certain set of tests of things that are likely to get broken by a Cargo update:
+subup --up-branch update-cargo \
+ --commit-message "Update cargo" \
+ --test="src/tools/linkchecker tidy \
+ src/tools/cargo \
+ src/tools/rustfmt" \
+ src/tools/cargo
+If doing a beta backport, the command is similar, but needs to point to the correct branches:
+subup --up-branch update-beta-cargo \
+ --rust-branch beta \
+ --set-config rust.channel=beta \
+ --commit-message "[beta] Update cargo" \
+ --test="src/tools/linkchecker tidy \
+ src/tools/cargo \
+ src/tools/rustfmt" \
+ rust-1.66.0:src/tools/cargo
+Shortly after each major release, a Cargo team member will post a PR to update
+Cargo’s version in Cargo.toml. Cargo’s library is permanently unstable, so
+its version number starts with a 0. The minor version is always 1 greater
+than the Rust release it is a part of, so cargo 0.49.0 is part of the 1.48
+Rust release. The CHANGELOG is also usually updated at this time.
Also, any version-specific checks that are no longer needed can be removed. +For example, some tests are disabled on stable if they require some nightly +behavior. Once that behavior is available on the new stable release, the +checks are no longer necessary. (I usually search for the word “nightly” in +the testsuite directory, and read the comments to see if any of those nightly +checks can be removed.)
+Sometimes Cargo will have a runtime check to probe rustc if it supports a
+specific feature. This is usually stored in the TargetInfo struct. If this
+behavior is now stable, those checks should be removed.
Cargo has several other packages in the crates/ directory. If any of these
+packages have changed, the version should be bumped before the beta
+release. It is rare that these get updated. Bumping these as-needed helps
+avoid churning incompatible version numbers. This process should be improved
+in the future!
@ehuss has a tool called cargo-new-release to automate the process of doing a version bump. +It runs through several steps:
+It opens a browser tab for every PR in order to review each change. +It places each PR in the changelog with its title, but usually every PR should be rewritten to explain the change from the user’s perspective. +Each PR should also be categorized as an Addition, Change, Fix, or Nightly-only change. +Most PRs are deleted, since they are not relevant to users of Cargo. +For example, remove all PRs related to Cargo internals, infrastructure, documentation, error changes, refactorings, etc. +Usually about half of the PRs get removed. +This process usually takes @ehuss about an hour to finish.
+Docs are automatically published during the Rust release process. The nightly +channel’s docs appear at https://doc.rust-lang.org/nightly/cargo/. Once +nightly is promoted to beta, those docs will appear at +https://doc.rust-lang.org/beta/cargo/. Once the stable release is made, it +will appear on https://doc.rust-lang.org/cargo/ (which is the “current” +stable) and the release-specific URL such as +https://doc.rust-lang.org/1.46.0/cargo/.
+The code that builds the documentation is located in the doc bootstrap
+module.
Cargo’s library and its related dependencies (like cargo-util) are published
+to crates.io as part of the 6-week stable release process by the Release
+team. There is a publish.py script that is used by the Release team’s
+automation scripts (see https://github.com/rust-lang/simpleinfra/) to handle
+determining which packages to publish. The build tool crates aren’t published.
+This runs on the specific git commit associated with the cargo submodule in the
+stable branch in rust-lang/rust at the time of release.
On very rare cases, the Cargo team may decide to manually publish a new
+release to crates.io. For example, this may be necessary if there is a
+problem with the current version that only affects API users, and does not
+affect the cargo binary shipped in the stable release. In this situation,
+PRs should be merged to the associated stable release branch in the cargo repo
+(like rust-1.70.0) that fix the issue and bump the patch version of the
+affected package. Then someone with permissions (currently a subset of the
+Cargo team, or the Release team) should publish it manually using cargo publish.
Some packages are not published automatically because they are not part of the
+Rust release train. This currently only includes the home package. These
+are published manually on an as-needed or as-requested basis by whoever has
+permissions (currently @ehuss or the Release/Infra team).
In the future, these manual publishing options should be integrated with +GitHub Actions so that any team member can trigger them. Likely that should +involve getting Infra to create scoped tokens that can be added as GitHub +Secrets, and setting up GitHub Actions workflows with the appropriate +permissions which can be manually triggered to launch a release.
+If there is a regression or major problem detected during the beta phase, it +may be necessary to backport a fix to beta. The process is documented in the +Beta Backporting page.
+In (hopefully!) very rare cases, a major regression or problem may be reported +after the stable release. Decisions about this are usually coordinated between +the Release team and the Cargo team. There is usually a high bar for making +a stable patch release, and the decision may be influenced by whether or not +there are other changes that need a new stable release.
+The process here is similar to the beta-backporting process. The
+rust-lang/cargo branch is the same as beta (rust-1.XX.0). The
+rust-lang/rust branch is called stable.
Issues involving reporting a security vulnerability in cargo usually start by following the Rust security policy. +The Security Response Working Group (“the WG”) is responsible for running the process of handling the response to a security issue. +Their process is documented at Handling Reports. +This document gives an overview of the process from a Cargo team member’s perspective.
+The general order of events happens as follows:
+The “reporter” (even if it is a Cargo team member) reports an issue to security@rust-lang.org.
+The WG will evaluate if the report is credible, and manages responses to the reporter.
+The WG will start a private Zulip stream to coordinate discussion and plans for a fix.
+The WG will pull in one or more team members into the Zulip stream (“responders”).
+A discussion then starts to evaluate the severity of the issue and what possible solutions should be considered. +This includes figuring out who will volunteer to actually develop the patches to resolve the issue, and who will review it.
+The WG will create a temporary private fork of the rust-lang/cargo repo using GitHub’s repository security advisory system.
+This provides a space where changes can be securely posted, and the security advisory can be drafted.
+See “Collaborating in a temporary private fork” for some screenshots of what this looks like.
+GitHub includes instructions on how to work with the fork.
Beware that the private fork has some limitations, such as not supporting CI, or (for some weird reason) not supporting syntax highlighting.
+Someone will need to review the patches and make sure everyone agrees on the solution. +This may also involve the WG conferring with the reporter to validate the fix.
+Create a rollout plan. +This includes deciding if there will be a new patch release of Rust, or if it should wait for the next stable release, or whether to remove the embargo on the fix.
+The WG will handle drafting a Security Advisory using GitHub’s Security Advisory (“GHSA”) system. +GHSA-r5w3-xm58-jv6j is an example of what this looks like. +This process also involves reserving a CVE number, where the report will eventually be posted.
+The responders should carefully review the report to make sure it is correct.
+This process may also involve deciding on the CVSS score. +There are a bunch of calculators on the web where you can see how this works (such as the FIRST CVSS Calculator, or you can view GitHub’s calculator by drafting a security advisory in one of your personal repos). +FIRST has a user guide for deciding how to score each characteristic.
+If it is decided to do a patch release of Rust, the general overview of steps is:
+rust-lang/rust to prepare the point release.
+This usually includes changes for stable, beta, and nightly.rust-lang/rust to incorporate the fix and prepare a new release.Sometimes it may be necessary to make changes to external dependencies to support a fix. +This can make things complicated. +If the change is by itself benign and not directly related to the security issue, +then it may be safe to publicly propose the change (but not giving context) and try to get a new release of the dependency made (though confer with the WG first!). +However, if the issue is directly related to the dependency, then it becomes significantly more awkward.
+The general process for GHSA-r5w3-xm58-jv6j which involved a fix in git2-rs was handled by the responders because it is a dependency owned by the rust-lang org.
+The general outline of how we managed this is:
rust-lang/git2-rs just like we did for rust-lang/cargo.
+git2-rs also had its own Security Advisory just like cargo did.rust-lang/cargo private fork had to have a temporary [patch] git dependency on the git2-rs private fork.[patch], and pretend as-if git2-rs had already been published.Cargo.lock to pick up the new git2 dependencies.If the change is in a crate not managed by any responder, then confer with the WG on a strategy. +One option is to create a temporary fork used for the security response that will be removed as soon as the security advisory is released and a new public release of the dependency is made with the fix.
+There are a lot of details to handle, and it can be a bit of a challenge under time pressure. +The following is a checklist of some items to pay attention to during the process.
+Pre-release:
+Cargo.toml is updated correctly on the stable branch private PR.Cargo.lock is updated (stable, beta, master branches).CHANGELOG.md on cargo’s master branch private PR.RELEASES.md on rust’s master branch private PR (and stable and beta?).[patch] table.Showtime:
+Cargo.lock.rust-lang/cargo get updated.rust-lang/rust get updated, pointing to the correct submodule versions.Post release:
+rust-lang/cargo got a new tag.rust-lang/cargo repository (stable, beta, and master).rust-lang/rust repository (stable, beta, and master).Most new features should go through the unstable process. This means that the +feature will only be usable on the nightly channel, and requires a specific +opt-in by the user. Small changes can skip this process, but please consult +with the Cargo team first.
+For features that require behavior changes or new syntax in Cargo.toml, then
+it will need a cargo-features value placed at the top of Cargo.toml to
+enable it. The process for adding a new feature is described in the
+features module. Code that implements the feature will need to manually
+check that the feature is enabled for the current manifest.
For features that add new command-line flags, config options, or environment
+variables, then the -Z flags will be needed to enable them. The features
+module also describes how to add these. New flags should use the
+fail_if_stable_opt method to check if the -Z unstable-options flag has
+been passed.
Every unstable feature should have a section added to the unstable chapter +describing how to use the feature.
+Each unstable feature should get a tracking issue. These issues are +typically created when a PR is close to being merged, or soon after it is +merged. Use the tracking issue template when creating a tracking issue.
+Larger features should also get a new label in the issue tracker so that when
+issues are filed, they can be easily tied together. Typically this would be
+one of the Z- prefixed labels for nightly features.
When opening a tracking issue, be sure to also add an S- status label to
+indicate what needs to happen for it to move forward:
Tracking issues may have multiple status labels if necessary, for example if +something is only partially implemented, it may have both +S-waiting-on-feedback (for what is implemented) and S-needs-mentor or +S-accepted to finish the rest of the work.
+Once an unstable feature is “complete”, the search for users to test
+and give feedback begins. Testing notes should be written up to give users an
+idea of how to test the new feature. An example being the
+workspace inheritance testing notes for workspace inheritance. Once testing
+notes have been written up you should make posts in various rust communities
+(rust subreddit, users, internals, etc). Example posts made for workspace
+inheritance: reddit post, users post, internals post. The unstable feature
+should also be added to This Week in Rust. This should be done by adding the
+label call-for-testing to the RFC for the feature and making a comment with a
+link to the testing notes and the tracking issue (as needed). If there is not an
+RFC, a pull request should be made to the TWiR repo adding the feature to the
+Call for Testing section (example).
After some period of time, typically measured in months, the feature can be +considered to be stabilized. The feature should not have any significant known +bugs or issues, and any design concerns should be resolved.
+The stabilization process depends on the kind of feature. For smaller +features, you can leave a comment on the tracking issue expressing interest in +stabilizing it. It can usually help to indicate that the feature has received +some real-world testing, and has exhibited some demand for broad use.
+For larger features that have not gone through the RFC process, then an RFC +to call for stabilization might be warranted. This gives the community a final +chance to provide feedback about the proposed design.
+For a small feature, or one that has already gone through the RFC process, a +Cargo Team member may decide to call for a “final comment period” using +rfcbot. This is a public signal that a major change is being made, and gives +the Cargo Team members an opportunity to confirm or block the change. This +process can take a few days or weeks, or longer if a concern is raised.
+Once the stabilization has been approved, the person who called for +stabilization should prepare a PR to stabilize the feature. This PR should:
+features module.-Z flags and help message if applicable.This chapter gives an overview of how to build Cargo, make a change, and +submit a Pull Request.
+We encourage people to discuss their design before hacking on code. This gives +the Cargo team a chance to know your idea more. Sometimes after a discussion, +we even find a way to solve the problem without coding! Typically, you +file an issue or start a thread on the internals forum before submitting a +pull request.
+Please read the process of how features and bugs are managed in Cargo. +Only issues that have been explicitly marked as accepted will be reviewed.
+We use the “fork and pull” model described here, where +contributors push changes to their personal fork and create pull requests to +bring those changes into the source repository. Cargo uses git and GitHub +for all development.
+rust-lang/cargo repository on GitHub to your personal account
+(see GitHub docs).git clone (see GitHub
+docs)Cargo is built by…running cargo! There are a few prerequisites that you
+need to have installed:
rustc and cargo need to be installed. Cargo is expected to build and
+test with the current stable, beta, and nightly releases. It is your choice
+which to use. Nightly is recommended, since some nightly-specific tests are
+disabled when using the stable release. But using stable is fine if you
+aren’t working on those.libssl-dev on Ubuntu, openssl-devel on Fedora)openssl package)If you can successfully run cargo build, you should be good to go!
You can use cargo run to run cargo itself, or you can use the path directly
+to the cargo binary, such as target/debug/cargo.
If you are using rustup, beware that running the binary directly can cause
+issues with rustup overrides. Usually, when cargo is executed as part of
+rustup, the toolchain becomes sticky (via an environment variable), and all
+calls to rustc will use the same toolchain. But when cargo is not run via
+rustup, the toolchain may change based on the directory. Since Cargo changes
+the directory for each compilation, this can cause different calls to rustc
+to use different versions. There are a few workarounds:
rustup run target/debug/cargo to execute cargo.RUSTC environment variable to a specific rustc executable (not
+the rustup wrapper).toolchains directory, and create symlinks for all
+the files and directories in there to your toolchain of choice (such as
+nightly), except for the cargo binary, which you can symlink to your
+target/debug/cargo binary in your project directory.Normally, all development is done by running Cargo’s test suite, so running +it directly usually isn’t required. But it can be useful for testing Cargo on +more complex projects.
+Some guidelines on working on a change:
+rustfmt. You can use rustup component add rustfmt to install rustfmt
+and use cargo fmt to automatically format your code.After you have committed your work, and pushed it to GitHub, you can +open a Pull Request
+master branch.Closes #1234 will link issue
+#1234 to the PR. When the PR is merged, GitHub will automatically close the
+issue.@rustbot will automatically assign a reviewer for the PR. It
+may take at least a few days for someone to respond. If you don’t get a
+response in over a week, feel free to ping the assigned reviewer.
When your PR is submitted, GitHub automatically runs all tests. The GitHub +interface will show a green checkmark if it passes, or a red X if it fails. +There are links to the logs on the PR page to diagnose any issues. The tests +typically finish in under 30 minutes.
+The reviewer might point out changes deemed necessary. Large or tricky changes +may require several passes of review and changes.
+++tip: Prefer atomic commits where each commit is a single, complete, and coherent unit of work. +For example, if your feature work leads to renaming a module, make the rename its own commit. +However, adding an internal function that is unused is not complete or coherent.
+As part of your atomic commits, prefer adding tests as their own commit before any functionality changes. +The tests should pass in each commit, demonstrating the behavior before your +change and how each commit affects behavior. +This makes it easier for reviewers and community members to understand the +precise details of the side effects of your change and gives you confidence +that your tests are verifying the right behavior.
+Examples:
+ +
PRs will get marked with labels like S-waiting-on-review or S-waiting-on-author to indicate their status.
+The @rustbot bot can be used by anyone to adjust the labels.
+If a PR gets marked as S-waiting-on-author, and you have pushed new changes that you would like to be reviewed, you can write a comment on the PR with the text @rustbot ready.
+The bot will switch the labels on the PR.
More information about these commands can be found at the shortcuts documentation.
+After a reviewer has approved your PR, they will issue a command to the bors
+bot (also known as “Homu”, the software that powers @bors). Bors will
+create a temporary branch with your PR, and run all tests. Only if all tests
+pass will it merge the PR to master. If it fails, the bot will leave a comment
+on the PR. This system ensures that the master branch is always in a good
+state, and that merges are processed one at a time. The Homu queue
+dashboard shows the current merge queue. Cargo’s queue is rarely
+busy, but a busy project like the rust repo is constantly full.
Assuming everything works, congratulations! It may take at least a week for +the changes to arrive on the nightly channel. See the release chapter for +more information on how Cargo releases are made.
+ +The Cargo Team is a group of volunteers that support the Rust community in developing and maintaining Cargo, the Rust package manager and build tool. +The team is responsible for deciding how Cargo and its related libraries operate and evolve. +The team has a shared responsibility with the crates.io team for the design and usage of Cargo’s index format and its registry API as it relates to the crates.io service.
+The team is expected to keep Cargo in an operational state, to support Rust’s 6-week release cycle, and to uphold the Design Principles of Cargo.
+The Cargo Team consists of team members with one serving as a team leader. +The team leader is responsible for coordinating the team and providing a contact point with other teams. +The leader is selected by consensus of the existing members with no objections.
+Membership is maintained in the Rust team database.
+Team members are expected to participate in voting on RFCs and major change proposals
+Team members are expected to regularly participate in at least some of the following membership-related activities. +Members are not expected to participate in all of these activities, but exhibit some interest and involvement in the project that covers some of these activities.
+Breaks and vacations are welcome and encouraged. +If a member is no longer participating after a few months, they may be asked to step down.
+Members are required to always:
+Members are given privileges, such as:
+The team meets on a weekly basis on a video chat. +If you are interested in participating, feel free to contact us on Zulip.
+Minutes for all meetings are recorded on HackMD.
+A contributor can become a member of the Cargo Team by requesting a review or being nominated by one of the existing members. +They can be added by unanimous consent of the team. +The team lead or another member of the team will also confirm with the moderation team that there are no concerns involving the proposed team member.
+Contributors who wish to join the team should exhibit an interest in carrying the design principles of Cargo and participate in some of the activities listed above in Membership Expectations.
+Members may leave at any time, preferably by letting the team know ahead of time.
+The Cargo team has several streams on Zulip:
+#t-cargo — General public channel for discussing any topics related to Cargo.#t-cargo/build-integration — Discussions about integration with build systems.#t-cargo/PubGrub — Discussions about the PubGrub project.The following are private streams for the Cargo team. The team should avoid using this unless necessary (for example, discussing a security issue or team and meeting organization).
+#t-cargo/private — Private channel for discussions among the team.#t-cargo/meetings — Private channel for discussions about team meetings, including non-members who regularly attend the meetings.The Cargo team has a shared, public workspace on HackMD at https://hackmd.io/@rust-cargo-team for drafting documents and recording meeting minutes.
+Since this HackMD workspace is using the free service, it does not support private documents. If you need to draft a private document, create it in your personal workspace and use private channels to share the link.
+The team uses a consensus-driven process for making decisions ranging from new features and major changes to management of the team itself. +The degree of process is correlated with the degree of change being proposed:
+Bug fixes, refactorings, documentation updates, and other small changes are usually delegated to a single team member (who is not the author) to approve based on their judgement. +Team members may also solicit feedback from other members or the whole team for any change should they want to gather other perspectives from the team.
+Some examples of what this might cover are:
+Small features or changes, large refactorings, or major changes to Cargo’s codebase or process require an approval by the team via consensus. +These decisions can be done via the FCP process of rfcbot, or in an ad-hoc manner such as during a team meeting. +rfcbot FCP requests do not require waiting for the 10-day feedback window if there is a complete team consensus, as this process is mostly aimed at polling the team rather than publicly soliciting feedback. +Though, public feedback is welcome at any time.
+Some examples of what this might cover are:
+Larger features should usually go through the RFC process. +This usually involves first soliciting feedback from the Cargo team and the rest of the community, often via the Rust Internals discussion board, Cargo’s issue tracker, and the Zulip channel. +If there is positive feedback to the idea, the next step is to formally post an RFC on the RFC repo. +The community and the Cargo team will have an opportunity to provide feedback on the proposal. +After some period of time, the Cargo team may decide to either accept, postpone, or close a proposal based on the interest in the proposal and the team’s availability.
+Some examples of what this might cover are:
+Cargo.toml or the config files.cargo commands that are not trivial.
+In some cases, the team may decide to adopt a pre-existing external command without an RFC if the command has already been broadly adopted.Stabilization of Unstable features requires an approval via the FCP process of rfcbot. +This provides a final opportunity to solicit feedback from the public, and for the Cargo team to agree via consensus.
+The team may decide to experiment with larger features without starting the RFC process if it is an initiative that the team has consensus that it is something they want to pursue. +This is usually reserved for something that has an unclear path that the RFC process is not expected to provide feedback that would substantially move the process forward. +Such experiments are expected to be nightly-only (see the Unstable chapter), and involve efforts to shape the final result via exploration, testing, and public involvement. +Any such features must ultimately have an RFC approved before they can be stabilized.
+The team may be contacted through several channels:
+t-cargo Zulip channel stream is the chat platform the Cargo Team uses to coordinate on.Crater is a tool for compiling and running tests for every crate on crates.io (and a few on GitHub). +It is mainly used for checking the extent of breakage when implementing potentially breaking changes and ensuring lack of breakage by running beta vs stable compiler versions.
+Essentially it runs some cargo command on every crate twice; once against the “start” toolchain and again against the “end” toolchain.
+For example, “start” could be the stable release, and “end” could be beta.
+If it passes in “start” but fails with “end”, then that is reported as a regression.
There is a bot called craterbot which is used to run crater on hardware managed by the rust-lang organization.
+Crater is run by the release team during the beta cycle. +If there are any regressions that look like they are caused by Cargo, they should contact the Cargo team to decide how to handle it.
+If you have a change that you want to test before the beta release, or you want to test behavior that is not normally exercised by crater, you can do a manual run of crater. +Roughly the steps are:
+Create a branch with your changes.
+In your clone of cargo, make the changes to incorporate whatever new thing you want to test and push it to a branch on your fork on GitHub.
+Get a clone of https://github.com/rust-lang/rust
+Create a branch in your rust-lang/rust clone to add your changes.
+Change the src/tools/cargo submodule to point to your new branch.
Modify .gitmodules to point to your clone and branch of cargo with the changes you want to test.
+For example:
git submodule set-url src/tools/cargo https://github.com/ehuss/cargo.git
+git submodule set-branch --branch my-awesome-feature src/tools/cargo
+git submodule update --remote src/tools/cargo
+git add .gitmodules src/tools/cargo
+git commit
+Create an PR on rust-lang/rust.
+Push your submodule changes to GitHub and make a PR.
+Start the PR title with [EXPERIMENT] to make it clear what the PR is for and assign yourself or @ghost.
Make a “try” build.
+A “try” build creates a full release of x86_64-unknown-linux-gnu and stores it on rust-lang servers.
+This can be done with a comment @bors try on the PR (all Cargo team members should have permission to do this).
Run crater.
+Look at the craterbot docs to determine the command that you want to run.
+There are different modes like check-only, build-and-test, rustdoc, etc.
You can also choose how many crates to run against.
+If you are uncertain if your cargo changes will work correctly, it might be a good idea to run against top-100 first to check its behavior.
+This will run much faster.
+You can do a full run afterwards.
After the try build finishes (which should take a couple hours), ask someone to make a crater run.
+The Cargo team does not have that permission, so just ask someone on Zulip.
+They will need to write a comment to @craterbot with the command that you have specified.
Wait.
+Crater can take anywhere from a few hours to a few weeks to run depending on how long the craterbot queue is and which mode you picked and the priority of your job. +When the crater run finishes, craterbot will post a comment to the PR with a link to a report of the results.
+Investigate the report.
+Look through the report which contains links to build logs for any regressions or errors.
+Close the PR.
+Whenever you are done doing crater runs, close your PR.
+Crater only has a few built-in modes, such as running cargo check or cargo test.
+You can pass extra flags with +cargoflags.
More complex tests can be accomplished by customizing Cargo to perform whatever actions you want.
+Since crater essentially runs cargo check, you can modify the check command to perform whichever actions you want.
+For example, to test cargo fix --edition, this commit intercepted cargo check and modified it to instead:
cargo fix --edition.cargo check to verify.If you need to compare the before and after of a command that is not part of crater’s built-in modes, that can be more difficult. +Two possible options:
+cargo check command as described above.
+The “start” build should perform whichever action you want with an otherwise unmodified cargo.
+The “end” build should perform whichever action you want with your modified cargo.
+Then, in the @craterbot command, specify the start and end hashes of the two try builds.There are some limitations of crater to consider when running Cargo:
+generate-lockfile and includes -Zno-index-update to prevent index updates (which makes it run much faster).cargo fetch.--frozen or --message-format=json.
+It will sometimes use --all-targets and sometimes not.
+Check the crater source for more details on how it works.Cargo has an extensive test suite. Most of it is implemented as integration
+tests in the testsuite directory. There are several other tests:
resolver-tests
+directory.crates directory have their own set of tests.build-std test is for the build-std feature. It is separate since
+it has some special requirements.Cargo leverages tracing +as a basic, hierarchical built-in profiler.
+Environment variables:
+CARGO_LOG_PROFILE=<true|1>: log tracing events to a file in the current working directoryCARGO_LOG_PROFILE_CAPTURE_ARGS=<true|1>: include arguments in the eventsAt process exit, your trace will be in a file like trace-1668480819035032.json.
+Open that file with ui.perfetto.dev (or chrome://tracing) to browse your trace.
Example:
+$ # Output first three levels of profiling info
+$ CARGO_LOG_PROFILE=true cargo generate-lockfile
+Note: This is intended for the development of cargo and there are no compatibility guarantees on this functionality.
+Head over to the benches
+directory for more
+information about the benchmarking suite.
The overhead for starting a build should be kept as low as possible +(preferably, well under 0.5 seconds on most projects and systems). Currently, +the primary parts that affect this are:
+One way to test this is to use hyperfine. This is a tool that can be used to
+measure the difference between different commands and settings. Usually this
+is done by measuring the time it takes for cargo build to finish in a large
+project where the build is fresh (no actual compilation is performed). Just
+run cargo build once before using hyperfine.
Using cargo test is usually sufficient for running the full test suite. This
+can take a few minutes, so you may want to use more targeted flags to pick the
+specific test you want to run, such as cargo test --test testsuite -- check::check_success.
Some tests only run on the nightly toolchain, and will be ignored on other +channels. It is recommended that you run tests with both nightly and stable to +ensure everything is working as expected.
+Some of the nightly tests require the rustc-dev and llvm-tools-preview
+rustup components installed. These components include the compiler as a
+library. This may already be installed with your nightly toolchain, but if it
+isn’t, run rustup component add rustc-dev llvm-tools-preview --toolchain=nightly.
Some tests exercise cross compiling to a different target. This will require
+you to install the appropriate target. This typically is the 32-bit target of
+your host platform. For example, if your host is a 64-bit
+x86_64-unknown-linux-gnu, then you should install the 32-bit target with
+rustup target add i686-unknown-linux-gnu. If you don’t have the alternate
+target installed, there should be an error message telling you what to do. You
+may also need to install additional tools for the target. For example, on Ubuntu
+you should install the gcc-multilib package.
If you can’t install an alternate target, you can set the
+CFG_DISABLE_CROSS_TESTS=1 environment variable to disable these tests. The
+Windows cross tests only support the MSVC toolchain.
The build-std tests are disabled by default, but you can run them by setting
+the CARGO_RUN_BUILD_STD_TESTS=1 environment variable and running cargo test --test build-std. This requires the nightly channel, and also requires the
+rust-src component installed with rustup component add rust-src --toolchain=nightly.
gitoxide as default git backend in testsBy default, the git2 backend is used for most git operations. As tests need to explicitly
+opt-in to use nightly features and feature flags, adjusting all tests to run with nightly
+and -Zgitoxide is unfeasible.
This is why the private environment variable named __CARGO_USE_GITOXIDE_INSTEAD_OF_GIT2 can be
+set while running tests to automatically enable the -Zgitoxide flag implicitly, allowing to
+test gitoxide for the entire cargo test suite.
Some (very rare) tests involve connecting to the public internet.
+These tests are disabled by default,
+but you can run them by setting the CARGO_PUBLIC_NETWORK_TESTS=1 environment variable.
+Additionally our CI suite has a smoke test for fetching dependencies.
+For most contributors, you will never need to bother with this.
Tests marked with container_test involve running Docker to test more complex configurations.
+These tests are disabled by default,
+but you can run them by setting the CARGO_CONTAINER_TESTS=1 environment variable.
+You will need to have Docker installed and running to use these.
++ +Note: Container tests mostly do not work on Windows.
++
+- The SSH tests require ssh-agent, but the two versions of ssh-agent +on Windows are not suitable for testing. +
++
+- The Microsoft version of ssh-agent runs as a global service, and can’t be isolated per test.
+- The mingw/cygwin one can’t be accessed from a Windows executable like cargo.
+- Pageant similarly does not seem to have a way to isolate it (and I’m not certain it can be driven completely from the command-line).
+The tests also can’t run on Windows CI because the Docker that is preinstalled doesn’t support Linux containers, and setting up Windows containers is a pain.
+macOS should work with Docker installed and running, +but unfortunately the tests are not run on CI because Docker is not available.
+
The following focuses on writing an integration test. However, writing unit +tests is also encouraged!
+Cargo has a wide variety of integration tests that execute the cargo binary
+and verify its behavior, located in the testsuite directory. The
+support crate and snapbox contain many helpers to make this process easy.
There are two styles of tests that can roughly be categorized as
+These tests typically work by creating a temporary “project” with a
+Cargo.toml file, executing the cargo binary process, and checking the
+stdout and stderr output against the expected output.
Generally, a functional test will be placed in tests/testsuite/<command>.rs and will look roughly like:
#[cargo_test]
+fn <description>() {
+ let p = project()
+ .file("src/main.rs", r#"fn main() { println!("hi!"); }"#)
+ .build();
+
+ p.cargo("run --bin foo")
+ .with_stderr(
+ "\
+ [COMPILING] foo [..]
+ [FINISHED] [..]
+ [RUNNING] `target/debug/foo`
+ ",
+ )
+ .with_stdout("hi!")
+ .run();
+ }
+}The #[cargo_test] attribute is used in place of #[test] to inject some setup code.
ProjectBuilder via project():
Cargo.toml manifest using file(), one is
+automatically created with a project name of foo using basic_manifest().Execs via p.cargo(...):
support::compare for an explanation of the string pattern matching.
+Patterns are used to make it easier to match against the expected output.#[cargo_test] attributeThe #[cargo_test] attribute injects code which does some setup before starting the test.
+It will create a filesystem “sandbox” under the “cargo integration test” directory for each test, such as /path/to/cargo/target/tmp/cit/t123/.
+The sandbox will contain a home directory that will be used instead of your normal home directory.
The #[cargo_test] attribute takes several options that will affect how the test is generated.
+They are listed in parentheses separated with commas, such as:
#[cargo_test(nightly, reason = "-Zfoo is unstable")]The options it supports are:
+nightly — This will cause the test to be ignored if not running on the nightly toolchain.
+This is useful for tests that use unstable options in rustc or rustdoc.
+These tests are run in Cargo’s CI, but are disabled in rust-lang/rust’s CI due to the difficulty of updating both repos simultaneously.
+A reason field is required to explain why it is nightly-only.build_std_real — This is a “real” -Zbuild-std test (in the build_std integration test).
+This only runs on nightly, and only if the environment variable CARGO_RUN_BUILD_STD_TESTS is set (these tests on run on Linux).build_std_mock — This is a “mock” -Zbuild-std test (which uses a mock standard library).
+This only runs on nightly, and is disabled for windows-gnu.requires_ — This indicates a command that is required to be installed to be run.
+For example, requires_rustfmt means the test will only run if the executable rustfmt is installed.
+These tests are always run on CI.
+This is mainly used to avoid requiring contributors from having every dependency installed.>=1.64 — This indicates that the test will only run with the given version of rustc or newer.
+This can be used when a new rustc feature has been stabilized that the test depends on.
+If this is specified, a reason is required to explain why it is being checked.public_network_test — This tests contacts the public internet.
+These tests are disabled unless the CARGO_PUBLIC_NETWORK_TESTS environment variable is set.
+Use of this should be extremely rare, please avoid using it if possible.
+The hosts it contacts should have a relatively high confidence that they are reliable and stable (such as github.com), especially in CI.
+The tests should be carefully considered for developer security and privacy as well.container_test — This indicates that it is a test that uses Docker.
+These tests are disabled unless the CARGO_CONTAINER_TESTS environment variable is set.
+This requires that you have Docker installed.
+The SSH tests also assume that you have OpenSSH installed.
+These should work on Linux, macOS, and Windows where possible.
+Unfortunately these tests are not run in CI for macOS or Windows (no Docker on macOS, and Windows does not support Linux images).
+See crates/cargo-test-support/src/containers.rs for more on writing these tests.ignore_windows="reason" — Indicates that the test should be ignored on windows for the given reason.If you are testing a Cargo feature that only works on “nightly” Cargo, then
+you need to call masquerade_as_nightly_cargo on the process builder and pass
+the name of the feature as the reason, like this:
p.cargo("build").masquerade_as_nightly_cargo(&["print-im-a-teapot"])If you are testing a feature that only works on nightly rustc (such as
+benchmarks), then you should use the nightly option of the cargo_test
+attribute, like this:
#[cargo_test(nightly, reason = "-Zfoo is unstable")]This will cause the test to be ignored if not running on the nightly toolchain.
+You should not write any tests that use the network such as contacting +crates.io. Typically, simple path dependencies are the easiest way to add a +dependency. Example:
+let p = project()
+ .file("Cargo.toml", r#"
+ [package]
+ name = "foo"
+ version = "1.0.0"
+
+ [dependencies]
+ bar = {path = "bar"}
+ "#)
+ .file("src/lib.rs", "extern crate bar;")
+ .file("bar/Cargo.toml", &basic_manifest("bar", "1.0.0"))
+ .file("bar/src/lib.rs", "")
+ .build();If you need to test with registry dependencies, see
+support::registry::Package for creating packages you can depend on.
If you need to test git dependencies, see support::git to create a git
+dependency.
There are some utilities to help support tests that need to work against a +target other than the host. See Running cross +tests for more an introduction on cross +compilation tests.
+Tests that need to do cross-compilation should include this at the top of the +test to disable it in scenarios where cross compilation isn’t available:
+if cargo_test_support::cross_compile::disabled() {
+ return;
+}The name of the target can be fetched with the cross_compile::alternate()
+function. The name of the host target can be fetched with
+cargo_test_support::rustc_host().
The cross-tests need to distinguish between targets which can build versus
+those which can actually run the resulting executable. Unfortunately, macOS is
+currently unable to run an alternate target (Apple removed 32-bit support a
+long time ago). For building, x86_64-apple-darwin will target
+x86_64-apple-ios as its alternate. However, the iOS target can only execute
+binaries if the iOS simulator is installed and configured. The simulator is
+not available in CI, so all tests that need to run cross-compiled binaries are
+disabled on CI. If you are running on macOS locally, and have the simulator
+installed, then it should be able to run them.
If the test needs to run the cross-compiled binary, then it should have +something like this to exit the test before doing so:
+if cargo_test_support::cross_compile::can_run_on_host() {
+ return;
+}UI Tests are a bit more spread out and generally look like:
+tests/testsuite/<command>/mod.rs:
mod <case>;tests/testsuite/<command>/<case>/mod.rs:
use cargo_test_support::compare::assert_ui;
+use cargo_test_support::current_dir;
+use cargo_test_support::file;
+use cargo_test_support::prelude::*;
+use cargo_test_support::Project;
+
+#[cargo_test]
+fn case() {
+ let project = Project::from_template(current_dir!().join("in"));
+ let project_root = project.root();
+ let cwd = &project_root;
+
+ snapbox::cmd::Command::cargo_ui()
+ .arg("run")
+ .arg_line("--bin foo")
+ .current_dir(cwd)
+ .assert()
+ .success()
+ .stdout_matches(file!("stdout.log"))
+ .stderr_matches(file!("stderr.log"));
+
+ assert_ui().subset_matches(current_dir!().join("out"), &project_root);
+}Then populate
+tests/testsuite/<command>/<case>/in with the project’s directory structuretests/testsuite/<command>/<case>/out with the files you want verifiedtests/testsuite/<command>/<case>/stdout.log with nothingtests/testsuite/<command>/<case>/stderr.log with nothing#[cargo_test]:
#[test]/path/to/cargo/target/cit/t123/home directory that will be used instead of your normal home directoryProject:
Command via Command::cargo_ui():
OutputAssert via Command::assert():
CommandAssert via assert_ui():
The project, stdout, and stderr snapshots can be updated by running with the
+SNAPSHOTS=overwrite environment variable, like:
$ SNAPSHOTS=overwrite cargo test
+Be sure to check the snapshots to make sure they make sense.
+If you are testing a Cargo feature that only works on “nightly” Cargo, then
+you need to call masquerade_as_nightly_cargo on the process builder and pass
+the name of the feature as the reason, like this:
snapbox::cmd::Command::cargo()
+ .masquerade_as_nightly_cargo(&["print-im-a-teapot"])If you are testing a feature that only works on nightly rustc (such as
+benchmarks), then you should use the nightly option of the cargo_test
+attribute, like this:
#[cargo_test(nightly, reason = "-Zfoo is unstable")]This will cause the test to be ignored if not running on the nightly toolchain.
+When checking output, use / for paths even on Windows: the actual output
+of \ on Windows will be replaced with /.
Be careful when executing binaries on Windows. You should not rename, delete, +or overwrite a binary immediately after running it. Under some conditions +Windows will fail with errors like “directory not empty” or “failed to remove” +or “access is denied”.
+In some cases, you may need to dig into a test that is not working as you +expect, or you just generally want to experiment within the sandbox +environment. The general process is:
+Build the sandbox for the test you want to investigate. For example:
+cargo test --test testsuite -- features2::inactivate_targets.
In another terminal, head into the sandbox directory to inspect the files and run cargo directly.
The sandbox directories start with t0 for the first test.
cd target/tmp/cit/t0
Set up the environment so that the sandbox configuration takes effect:
+export CARGO_HOME=$(pwd)/home/.cargo
Most tests create a foo project, so head into that:
cd foo
Run whatever cargo command you want. See Running Cargo for more details
+on running the correct cargo process. Some examples:
/path/to/my/cargo/target/debug/cargo checklldb or gdb:
+lldb /path/to/my/cargo/target/debug/cargob generate_root_unitsr check