From ffb7b3efa60add5d36d2c501f05da9374edc5068 Mon Sep 17 00:00:00 2001 From: Christoph Schulz Date: Sun, 9 Aug 2020 18:21:45 +0200 Subject: [PATCH] Rework About/Build. - Added a section covering the read-only sandbox file system - Merge sections regarding detection of Docs.rs, also adding examples - Add section covering other build failures - Discuss rebuilds Thanks to jyn514 and Kixiron for their helpful feedback. --- templates/core/about/builds.html | 171 ++++++++++++++++++------------- 1 file changed, 100 insertions(+), 71 deletions(-) diff --git a/templates/core/about/builds.html b/templates/core/about/builds.html index 41057fdfd..078cc94fb 100644 --- a/templates/core/about/builds.html +++ b/templates/core/about/builds.html @@ -3,77 +3,106 @@ {%- block title -%} Builds {%- endblock title -%} {%- block body -%} - {%- set docsrs_repo = "https://github.com/rust-lang/docs.rs" -%} -

Builds

-
-

- Docs.rs automatically builds crates' documentation released on - crates.io - using the nightly release of the Rust compiler. - Builds can take a while depending how many crates are in the queue. -

- -

- {%- if rustc_version %} - The current version of the Rust compiler in use is {{ rustc_version }}. - {%- endif -%} -

- -

- The README of a crate is taken from the readme field defined in - Cargo.toml. If a crate doesn't have this field, - no README will be displayed. -

- -

Diagnosing a failed build

- -

Missing dependencies

-

- Missing dependencies are a common reason for a failed build. - Docs.rs dependencies are managed through - crates-build-env; - see Forge for instructions - on how to make a PR. You can always file an issue - if you're having trouble. -

- -

Detecting Docs.rs from build.rs

-

- Docs.rs builds crates with the environment variable DOCS_RS set to - 1, which enables the crate to detect docs.rs and build the - crate differently. This can be helpful if you need - dependencies for building the library, but not for building the documentation. -

- -

Detecting Docs.rs from #[cfg] attributes

-

- You can detect Docs.rs by having a feature - which is only set by Docs.rs. See Metadata for more information. -

- -

Global sandbox limits

- -

- All the builds on docs.rs are executed inside a sandbox with limited - resources. The current limits are the following: -

- - {{ macros::crate_limits(limits=limits) }} - -

- If a build fails because it hit one of those limits please - open an issue - to get them increased for your crate. - Note that network access will not be enabled for any crate. -

- -

Test crate documentation build locally

- {%- set build_subcommand = docsrs_repo ~ "/blob/master/README.md#build-subcommand" -%} -

- The docs.rs README describes how to build an - unpublished crate's documentation locally using the same build environment as the build agent. -

-
+ {%- set docsrs_repo = "https://github.com/rust-lang/docs.rs" -%} +

Builds

+
+

+ Docs.rs automatically builds documentation for crates released on crates.io. + + It may take a while to build your crate, depending on how many crates are in the queue. +

+ +

+ All crates are built in a sandbox using the nightly release of the Rust compiler. + {%- if rustc_version %} + The current version in use is {{ rustc_version }}. + {%- endif -%} +

+ +

Notes on using Docs.rs

+ +

Setting a README

+

+ The README of a crate is taken from the readme field defined in + Cargo.toml. If this field is not set, no README will be displayed. +

+ +

Detecting Docs.rs

+

+ To recognize Docs.rs from build.rs files, you can test for the environment variable DOCS_RS, e.g.: + {% filter dedent -%} + 

+            
+                if let Ok(_) = std::env::var("DOCS_RS") {
+                    // ... your code here ...
+                }        
+            
+
+ {%- endfilter %} + This approach can be helpful if you need dependencies for building the library, but not for building the documentation. +

+ +

+ You can configure how your crate is built by adding package metadata to your Cargo.toml, e.g.: + {% filter dedent -%} + 

+            
+                [package.metadata.docs.rs]
+                rustc-args = ["--cfg", "docsrs"]
+            
+
+ {%- endfilter %} + Here, the compiler arguments are set so that #[cfg(docsrs)] (not to be confused with #[cfg(doc)]) can be used for conditional compilation. + This approach is also useful for setting cargo features. +

+ +

Testing documentation builds locally

+ {%- set build_subcommand = docsrs_repo ~ "/blob/master/README.md#build-subcommand" -%} +

+ The Docs.rs README describes how to build + unpublished crate documentation locally using the same build environment as the Docs.rs build agent. +

+ +

Diagnosing failed builds

+ +

Missing dependencies

+

+ Missing dependencies are a common reason for failed builds. + Docs.rs dependencies are managed through + crates-build-env. + See Forge for how to add a dependency. +

+ +

Write attempt on read-only directories

+

+ Most of the sandbox is a read-only file system, including the source directory of your crate and its dependencies. + If your build.rs generates files that are relevant for documentation, consider writing to the + cargo output directory, + passed in the environment variable OUT_DIR. +

+ +

Hitting resource limits

+

+ All the builds are executed inside a sandbox with limited resources. The current limits are: +

+ + {{ macros::crate_limits(limits=limits) }} + +

+ If your build fails because it hit one of these limits, please + open an issue + to get them increased for your crate. + Since our build agent has finite resources, we have to consider each case individually. + However, network access will not be enabled for any crate. +

+ +

Other failures and requesting rebuilds

+

+ If your crate fails to build for a reason not listed here, please file an issue. + Some build failures can be fixed by Docs.rs, e.g., by issuing a rebuild after a bug in Docs.rs has been fixed. +

+ +
{%- endblock body %} {% block css -%}