@@ -19,15 +19,15 @@ <h1>Builds</h1>
19
19
{%- endif -%}
20
20
</ p >
21
21
22
- < h3 id ="notes-on-docsrs "> Notes on using Docs.rs</ h3 >
22
+ < h3 id ="notes-on-docsrs "> < a href =" #notes-on-docsrs " > Notes on using Docs.rs</ a > </ h3 >
23
23
24
- < h4 id ="setting-a-readme "> Setting a README</ h4 >
24
+ < h4 id ="setting-a-readme "> < a href =" #setting-a-readme " > Setting a README</ a > </ h4 >
25
25
< p >
26
26
The README of a crate is taken from the < code > readme</ code > field defined in
27
27
< code > Cargo.toml</ code > . If this field is not set, no README will be displayed.
28
28
</ p >
29
29
30
- < h4 id ="detecting-docsrs "> Detecting Docs.rs</ h4 >
30
+ < h4 id ="detecting-docsrs "> < a href =" #detecting-docsrs " > Detecting Docs.rs</ a > </ h4 >
31
31
< p >
32
32
To recognize Docs.rs from < code > build.rs</ code > files, you can test for the environment variable < code > DOCS_RS</ code > , e.g.:
33
33
{% filter dedent(levels=4) -%}
@@ -42,7 +42,7 @@ <h4 id="detecting-docsrs">Detecting Docs.rs</h4>
42
42
This approach can be helpful if you need dependencies for building the library, but not for building the documentation.
43
43
</ p >
44
44
45
- < h4 id ="cross-compiling "> Cross-compiling</ h4 >
45
+ < h4 id ="cross-compiling "> < a href =" #cross-compiling " > Cross-compiling</ a > </ h4 >
46
46
< p >
47
47
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.
48
48
</ p >
@@ -61,32 +61,32 @@ <h4 id="cross-compiling">Cross-compiling</h4>
61
61
This approach is also useful for setting < a href ="https://doc.rust-lang.org/cargo/reference/features.html "> cargo features</ a > .
62
62
</ p >
63
63
64
- < h4 id ="testing-builds-locally "> Testing documentation builds locally</ h4 >
64
+ < h4 id ="testing-builds-locally "> < a href =" #testing-builds-locally " > Testing documentation builds locally</ a > </ h4 >
65
65
{%- set build_subcommand = docsrs_repo ~ "/blob/master/README.md#build-subcommand" -%}
66
66
< p >
67
67
The Docs.rs < a href ="{{ build_subcommand | safe }} "> README</ a > describes how to build
68
68
unpublished crate documentation locally using the same build environment as the Docs.rs build agent.
69
69
</ p >
70
70
71
- < h3 id ="diagnosing-failed-builds "> Diagnosing failed builds</ h3 >
71
+ < h3 id ="diagnosing-failed-builds "> < a href =" #diagnosing-failed-builds " > Diagnosing failed builds</ a > </ h3 >
72
72
73
- < h4 id ="missing-dependencies "> Missing dependencies</ h4 >
73
+ < h4 id ="missing-dependencies "> < a href =" #missing-dependencies " > Missing dependencies</ a > </ h4 >
74
74
< p >
75
75
Missing dependencies are a common reason for failed builds.
76
76
Docs.rs dependencies are managed through
77
77
< a href ="https://github.com/rust-lang/crates-build-env "> crates-build-env</ a > .
78
78
See < a href ="https://forge.rust-lang.org/docs-rs/add-dependencies.html "> Forge</ a > for how to add a dependency.
79
79
</ p >
80
80
81
- < h4 id ="read-only-directories "> Write attempt on read-only directories</ h4 >
81
+ < h4 id ="read-only-directories "> < a href =" #read-only-directories " > Write attempt on read-only directories</ a > </ h4 >
82
82
< p >
83
83
Most of the sandbox is a read-only file system, including the source directory of your crate and its dependencies.
84
84
If your < code > build.rs</ code > generates files that are relevant for documentation, consider writing to the
85
85
< a href ="https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates "> cargo output directory</ a > ,
86
86
passed in the environment variable < code > OUT_DIR</ code > .
87
87
</ p >
88
88
89
- < h4 id ="hitting-resource-limits "> Hitting resource limits</ h4 >
89
+ < h4 id ="hitting-resource-limits "> < a href =" #hitting-resource-limits " > Hitting resource limits</ a > </ h4 >
90
90
< p >
91
91
All the builds are executed inside a sandbox with limited resources. The current limits are:
92
92
</ p >
@@ -104,7 +104,7 @@ <h4 id="hitting-resource-limits">Hitting resource limits</h4>
104
104
</ ul >
105
105
</ p >
106
106
107
- < h4 id ="failures-and-rebuilds "> Other failures and requesting rebuilds</ h4 >
107
+ < h4 id ="failures-and-rebuilds "> < a href =" #failures-and-rebuilds " > Other failures and requesting rebuilds</ a > </ h4 >
108
108
< p >
109
109
If your crate fails to build for a reason not listed here, please < a href ="{{ docsrs_repo | safe }}/issues "> file an issue</ a > .
110
110
Some build failures can be fixed by Docs.rs, e.g., by issuing a rebuild after a bug in Docs.rs has been fixed.
0 commit comments