CINXE.COM
Builds
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="generator" content="docs.rs 0.6.0 (ee9a3fe6 2025-03-28)"><link rel="stylesheet" href="/-/static/vendored.css?0-6-0-ee9a3fe6-2025-03-28" media="all" /> <link rel="stylesheet" href="/-/static/style.css?0-6-0-ee9a3fe6-2025-03-28" media="all" /> <link rel="stylesheet" href="/-/static/font-awesome.css?0-6-0-ee9a3fe6-2025-03-28" media="all" /> <link rel="search" href="/-/static/opensearch.xml" type="application/opensearchdescription+xml" title="Docs.rs" /> <title>Builds</title> <script nonce="Rn7AB0eG13u1V90HmTB1v1fcttJf0i+Dbvh2IAIYzdORDfbA">(function() { function applyTheme(theme) { if (theme) { document.documentElement.dataset.docsRsTheme = theme; } } window.addEventListener("storage", ev => { if (ev.key === "rustdoc-theme") { applyTheme(ev.newValue); } }); // see ./storage-change-detection.html for details window.addEventListener("message", ev => { if (ev.data && ev.data.storage && ev.data.storage.key === "rustdoc-theme") { applyTheme(ev.data.storage.value); } }); applyTheme(window.localStorage.getItem("rustdoc-theme")); })();</script><script defer type="text/javascript" nonce="Rn7AB0eG13u1V90HmTB1v1fcttJf0i+Dbvh2IAIYzdORDfbA" src="/-/static/menu.js?0-6-0-ee9a3fe6-2025-03-28"></script> <script defer type="text/javascript" nonce="Rn7AB0eG13u1V90HmTB1v1fcttJf0i+Dbvh2IAIYzdORDfbA" src="/-/static/index.js?0-6-0-ee9a3fe6-2025-03-28"></script> </head> <body class="centered"> <div class="nav-container"> <div class="container"> <div class="pure-menu pure-menu-horizontal" role="navigation" aria-label="Main navigation"> <form action="/releases/search" method="GET" id="nav-search-form" class="landing-search-form-nav "> <a href="/" class="pure-menu-heading pure-menu-link docsrs-logo" aria-label="Docs.rs"> <span title="Docs.rs"><span class="fa fa-solid fa-cubes " aria-hidden="true"></span></span> <span class="title">Docs.rs</span> </a><div class="spacer"></div> <ul class="pure-menu-list"> <li class="pure-menu-item pure-menu-has-children"> <a href="#" class="pure-menu-link" aria-label="Rust">Rust</a> <ul class="pure-menu-children"> <li class="pure-menu-item"> <a class="pure-menu-link" href="/about" > About docs.rs </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link" href="https://foundation.rust-lang.org/policies/privacy-policy/#docs.rs" target="_blank"> Privacy policy </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link" href="https://www.rust-lang.org/" target="_blank"> Rust website </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link" href="https://doc.rust-lang.org/book/" target="_blank"> The Book </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link" href="https://doc.rust-lang.org/std/" target="_blank"> Standard Library API Reference </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link" href="https://doc.rust-lang.org/rust-by-example/" target="_blank"> Rust by Example </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link" href="https://doc.rust-lang.org/cargo/guide/" target="_blank"> The Cargo Guide </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link" href="https://doc.rust-lang.org/nightly/clippy" target="_blank"> Clippy Documentation </a> </li> </ul> </li> </ul> <div id="search-input-nav"> <label for="nav-search"> <span class="fa fa-solid fa-magnifying-glass " aria-hidden="true"></span> </label> <input id="nav-search" name="query" type="text" aria-label="Find crate by search query" tabindex="-1" placeholder="Find crate" > </div> </form> </div> </div> </div> <div class="docsrs-package-container"> <div class="container"> <div class="description-container"> <h1 id="crate-title" class="no-description">Docs.rs documentation</h1> <div class="pure-menu pure-menu-horizontal"> <ul class="pure-menu-list"> <li class="pure-menu-item"> <a class="pure-menu-link " href="/about"> <span class="fa fa-solid fa-circle-info " aria-hidden="true"></span> <span class='title'>About</span> </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link " href="/about/badges"> <span class="fa fa-brands fa-fonticons " aria-hidden="true"></span> <span class='title'>Badges</span> </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link pure-menu-active " href="/about/builds"> <span class="fa fa-solid fa-gears " aria-hidden="true"></span> <span class='title'>Builds</span> </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link " href="/about/metadata"> <span class="fa fa-solid fa-table " aria-hidden="true"></span> <span class='title'>Metadata</span> </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link " href="/about/redirections"> <span class="fa fa-solid fa-road " aria-hidden="true"></span> <span class='title'>Shorthand URLs</span> </a> </li> <li class="pure-menu-item"> <a class="pure-menu-link " href="/about/download"> <span class="fa fa-solid fa-download " aria-hidden="true"></span> <span class='title'>Download</span> </a> </li> </ul> </div> </div> </div> </div> <h1>Builds</h1> <div class="about-page"> <div class="container pure-u-5-6 about"> <p> Docs.rs automatically builds documentation for crates released on <a href="https://crates.io/">crates.io</a>. It may take a while to build your crate, depending on how many crates are in <a href="/releases/queue">the queue</a>. </p> <p> All crates are built in a sandbox using the nightly release of the Rust compiler. The current version in use is <code>rustc 1.88.0-nightly (e643f59f6 2025-04-07)</code>.</p> <h3 id="notes-on-docsrs"> <a href="#notes-on-docsrs">Notes on using Docs.rs</a> </h3> <h4 id="setting-a-readme"> <a href="#setting-a-readme">Setting a README</a> </h4> <p> The README of a crate is taken from the <code>readme</code> field defined in <code>Cargo.toml</code>. If this field is not set, no README will be displayed. </p> <h4 id="detecting-docsrs"> <a href="#detecting-docsrs">Detecting Docs.rs</a> </h4> <p> To recognize Docs.rs from your Rust code, you can test for the <code>docsrs</code> cfg, e.g.: <pre><code><span class="syntax-source syntax-rust"><span class="syntax-meta syntax-annotation syntax-rust"><span class="syntax-punctuation syntax-definition syntax-annotation syntax-rust">#</span><span class="syntax-punctuation syntax-section syntax-group syntax-begin syntax-rust">[</span><span class="syntax-variable syntax-annotation syntax-rust">cfg</span><span class="syntax-meta syntax-annotation syntax-parameters syntax-rust"><span class="syntax-meta syntax-group syntax-rust"><span class="syntax-punctuation syntax-section syntax-group syntax-begin syntax-rust">(</span></span></span><span class="syntax-meta syntax-annotation syntax-parameters syntax-rust"><span class="syntax-meta syntax-group syntax-rust">docsrs</span></span><span class="syntax-meta syntax-annotation syntax-parameters syntax-rust"><span class="syntax-meta syntax-group syntax-rust"><span class="syntax-punctuation syntax-section syntax-group syntax-end syntax-rust">)</span></span></span><span class="syntax-punctuation syntax-section syntax-group syntax-end syntax-rust">]</span></span> <span class="syntax-meta syntax-module syntax-rust"><span class="syntax-storage syntax-type syntax-module syntax-rust">mod</span> <span class="syntax-entity syntax-name syntax-module syntax-rust">documentation</span><span class="syntax-punctuation syntax-terminator syntax-rust">;</span></span></span></code></pre> The `docsrs` cfg only applies to the final rustdoc invocation (i.e. the crate currently being documented). It does not apply to dependencies (including workspace ones). </p> <p> To recognize Docs.rs from <code>build.rs</code> files, you can test for the environment variable <code>DOCS_RS</code>, e.g.: <pre><code><span class="syntax-source syntax-rust"><span class="syntax-keyword syntax-control syntax-rust">if</span> <span class="syntax-meta syntax-path syntax-rust">std<span class="syntax-punctuation syntax-accessor syntax-rust">::</span></span><span class="syntax-meta syntax-path syntax-rust">env<span class="syntax-punctuation syntax-accessor syntax-rust">::</span></span>var<span class="syntax-meta syntax-group syntax-rust"><span class="syntax-punctuation syntax-section syntax-group syntax-begin syntax-rust">(</span><span class="syntax-string syntax-quoted syntax-double syntax-rust"><span class="syntax-punctuation syntax-definition syntax-string syntax-begin syntax-rust">"</span>DOCS_RS<span class="syntax-punctuation syntax-definition syntax-string syntax-end syntax-rust">"</span></span></span><span class="syntax-meta syntax-group syntax-rust"><span class="syntax-punctuation syntax-section syntax-group syntax-end syntax-rust">)</span></span><span class="syntax-punctuation syntax-accessor syntax-dot syntax-rust">.</span><span class="syntax-support syntax-function syntax-rust">is_ok</span><span class="syntax-meta syntax-group syntax-rust"><span class="syntax-punctuation syntax-section syntax-group syntax-begin syntax-rust">(</span></span><span class="syntax-meta syntax-group syntax-rust"><span class="syntax-punctuation syntax-section syntax-group syntax-end syntax-rust">)</span></span> <span class="syntax-meta syntax-block syntax-rust"><span class="syntax-punctuation syntax-section syntax-block syntax-begin syntax-rust">{</span> <span class="syntax-comment syntax-line syntax-double-slash syntax-rust"><span class="syntax-punctuation syntax-definition syntax-comment syntax-rust">//</span> ... your code here ... </span></span><span class="syntax-meta syntax-block syntax-rust"><span class="syntax-punctuation syntax-section syntax-block syntax-end syntax-rust">}</span></span></span></code></pre> This approach can be helpful if you need dependencies for building the library, but not for building the documentation. </p> <h4 id="cross-compiling"> <a href="#cross-compiling">Cross-compiling</a> </h4> <p> All targets other than <code>x86_64-unknown-linux-gnu</code> are cross-compiled. For implementation reasons, this is unlikely to change for the foreseeable future. </p> <p> You can configure how your crate is built by adding <a href="metadata">package metadata</a> to your <code>Cargo.toml</code>, e.g.: <pre><code><span class="syntax-source syntax-toml"><span class="syntax-punctuation syntax-definition syntax-table syntax-begin syntax-toml">[</span><span class="syntax-meta syntax-tag syntax-table syntax-toml"><span class="syntax-entity syntax-name syntax-table syntax-toml">package</span><span class="syntax-punctuation syntax-separator syntax-table syntax-toml">.</span><span class="syntax-entity syntax-name syntax-table syntax-toml">metadata</span><span class="syntax-punctuation syntax-separator syntax-table syntax-toml">.</span><span class="syntax-entity syntax-name syntax-table syntax-toml">docs</span><span class="syntax-punctuation syntax-separator syntax-table syntax-toml">.</span><span class="syntax-entity syntax-name syntax-table syntax-toml">rs</span></span><span class="syntax-punctuation syntax-definition syntax-table syntax-end syntax-toml">]</span> <span class="syntax-meta syntax-tag syntax-key syntax-toml"><span class="syntax-entity syntax-name syntax-tag syntax-toml">rustc-args</span></span> <span class="syntax-punctuation syntax-definition syntax-key-value syntax-toml">=</span> <span class="syntax-punctuation syntax-definition syntax-array syntax-begin syntax-toml">[</span><span class="syntax-string syntax-quoted syntax-double syntax-basic syntax-toml"><span class="syntax-punctuation syntax-definition syntax-string syntax-begin syntax-toml">"</span>--cfg<span class="syntax-punctuation syntax-definition syntax-string syntax-end syntax-toml">"</span></span><span class="syntax-punctuation syntax-separator syntax-array syntax-toml">,</span> <span class="syntax-string syntax-quoted syntax-double syntax-basic syntax-toml"><span class="syntax-punctuation syntax-definition syntax-string syntax-begin syntax-toml">"</span>my_cfg<span class="syntax-punctuation syntax-definition syntax-string syntax-end syntax-toml">"</span></span><span class="syntax-punctuation syntax-definition syntax-array syntax-end syntax-toml">]</span></span></code></pre> Here, the compiler arguments are set so that <code>#[cfg(my_cfg)]</code> (not to be confused with <code>#[cfg(doc)]</code>) can be used for conditional compilation. This approach is also useful for setting <a href="https://doc.rust-lang.org/cargo/reference/features.html">cargo features</a>. </p> <h4 id="testing-builds-locally"> <a href="#testing-builds-locally">Testing documentation builds locally</a> </h4><p> The Docs.rs <a href="https://github.com/rust-lang/docs.rs/blob/master/README.md#build-subcommand">README</a> describes how to build unpublished crate documentation locally using the same build environment as the Docs.rs build agent. </p> <h3 id="diagnosing-failed-builds"> <a href="#diagnosing-failed-builds">Diagnosing failed builds</a> </h3> <h4 id="missing-dependencies"> <a href="#missing-dependencies">Missing dependencies</a> </h4> <p> Missing dependencies are a common reason for failed builds. Docs.rs dependencies are managed through <a href="https://github.com/rust-lang/crates-build-env">crates-build-env</a>. See <a href="https://forge.rust-lang.org/docs-rs/add-dependencies.html">Forge</a> for how to add a dependency. </p> <h4 id="read-only-directories"> <a href="#read-only-directories">Write attempt on read-only directories</a> </h4> <p> Most of the sandbox is a read-only file system, including the source directory of your crate and its dependencies. If your <code>build.rs</code> generates files that are relevant for documentation, consider writing to the <a href="https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates">cargo output directory</a>, passed in the environment variable <code>OUT_DIR</code>. </p> <h4 id="hitting-resource-limits"> <a href="#hitting-resource-limits">Hitting resource limits</a> </h4> <p> All the builds are executed inside a sandbox with limited resources. The current limits are: </p> <table class="pure-table pure-table-horizontal"> <tbody> <tr> <td>Available RAM</td> <td>6.44 GB</td> </tr> <tr> <td>Maximum rustdoc execution time</td> <td>15 minutes</td> </tr> <tr> <td>Maximum size of a build log</td> <td>102.40 kB</td> </tr> <tr> <td>Network access</td> <td>blocked</td> </tr> <tr> <td>Maximum number of build targets</td> <td>10</td> </tr> </tbody> </table> <p> If your build fails because it hit one of these limits, please <a href="https://github.com/rust-lang/docs.rs/issues/new/choose">open an issue</a> to get them increased for your crate. Since our build agent has finite resources, we have to consider each case individually. However, there are a few general policies: <ul> <li>Network access will not be enabled for any crate.</li> <li>Any crate that requests a time extension will be limited to one target.</li> </ul> </p> <h4 id="failures-and-rebuilds"> <a href="#failures-and-rebuilds">Other failures and requesting rebuilds</a> </h4> <p> If your crate fails to build for a reason not listed here, please <a href="https://github.com/rust-lang/docs.rs/issues">file an issue</a>. Some build failures can be fixed by Docs.rs, e.g., by issuing a rebuild after a bug in Docs.rs has been fixed. </p> </div> <br /> </div></body> </html>