Skip to content

Commit bd5b21e

Browse files
borsbors
committed
Auto merge of #6405 - ehuss:new-man, r=alexcrichton
New man pages. This is a rewrite and update of the man pages. This also adds them to the website documentation. They are now in Asciidoc format to make it easy to output multiple formats and have decent formatting. There is a Makefile with instructions on how to rebuild the man pages. Closes #5729.
2 parents d8ff8ed + d931a95 commit bd5b21e

File tree

155 files changed

+21961
-2231
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

155 files changed

+21961
-2231
lines changed

‎src/doc/Makefile

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# This Makefile is used to build the Cargo man pages.
2+
#
3+
# The source for the man pages are located in src/doc/man in Asciidoctor
4+
# format. See https://asciidoctor.org/ for more information.
5+
#
6+
# Just run `make` and it will generate the man pages in src/etc/man and the
7+
# HTML pages in src/doc/src/commands/generated.
8+
#
9+
# There are some Asciidoctor extensions, see the file `asciidoc-extensions.rb`
10+
# for the documentation.
11+
12+
MAN_SOURCE = $(sort $(wildcard man/cargo*.adoc))
13+
COMMANDS = $(notdir $(MAN_SOURCE))
14+
HTML = $(patsubst %.adoc,src/commands/generated/%.html,$(COMMANDS))
15+
MAN_LOCATION = ../etc/man
16+
MAN = $(patsubst %.adoc,$(MAN_LOCATION)/%.1,$(COMMANDS))
17+
ASCIIDOCOPTS = -r ./asciidoc-extension.rb
18+
OTHER_DEPS = asciidoc-extension.rb $(filter-out $(MAN_SOURCE),$(sort $(wildcard man/*.adoc)))
19+
20+
all: commands-html man
21+
commands-html: $(HTML)
22+
man: $(MAN)
23+
24+
$(HTML): src/commands/generated/%.html : man/%.adoc asciidoc-extension.rb $(OTHER_DEPS)
25+
asciidoctor $(ASCIIDOCOPTS) -s $< -o $@
26+
27+
$(MAN): $(MAN_LOCATION)/%.1 : man/%.adoc $(OTHER_DEPS)
28+
asciidoctor $(ASCIIDOCOPTS) -b manpage $< -o $@

‎src/doc/asciidoc-extension.rb

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
2+
3+
include Asciidoctor
4+
5+
# An inline macro that generates links to related man pages.
6+
#
7+
# Usage
8+
#
9+
# man:gittutorial[7]
10+
#
11+
class ManInlineMacro < Extensions::InlineMacroProcessor
12+
use_dsl
13+
14+
named :man
15+
name_positional_attributes 'volnum'
16+
17+
def process parent, target, attrs
18+
manname = target
19+
suffix = if (volnum = attrs['volnum'])
20+
"(#{volnum})"
21+
else
22+
nil
23+
end
24+
text = %(#{manname}#{suffix})
25+
if parent.document.basebackend? 'html'
26+
parent.document.register :links, target
27+
if manname == 'rustc'
28+
html_target = 'https://doc.rust-lang.org/rustc/index.html'
29+
elsif manname == 'rustdoc'
30+
html_target = 'https://doc.rust-lang.org/rustdoc/index.html'
31+
elsif manname == 'cargo'
32+
html_target = 'commands/index.html'
33+
else
34+
html_target = %(commands/#{manname}.html)
35+
end
36+
%(#{(create_anchor parent, text, type: :link, target: html_target).render})
37+
elsif parent.document.backend == 'manpage'
38+
%(\x1b\\fB#{manname}\x1b\\fP#{suffix})
39+
else
40+
text
41+
end
42+
end
43+
end
44+
45+
# Creates a link to something in the cargo documentation.
46+
#
47+
# For HTML this creates a relative link (using mdbook's 0.1's base-style
48+
# links). For the man page it gives a direct link to doc.rust-lang.org.
49+
#
50+
# Usage
51+
#
52+
# linkcargo:reference/manifest.html[the manifest]
53+
#
54+
class LinkCargoInlineMacro < Extensions::InlineMacroProcessor
55+
use_dsl
56+
57+
named :linkcargo
58+
name_positional_attributes 'text'
59+
60+
def process parent, target, attrs
61+
text = attrs['text']
62+
if parent.document.basebackend? 'html'
63+
parent.document.register :links, target
64+
%(#{(create_anchor parent, text, type: :link, target: target).render})
65+
elsif parent.document.backend == 'manpage'
66+
target = %(https://doc.rust-lang.org/cargo/#{target})
67+
%(#{(create_anchor parent, text, type: :link, target: target).render})
68+
else
69+
%(#{text} <#{target}>)
70+
end
71+
end
72+
end
73+
74+
# Backticks in the manpage renderer use the CR font (courier), but in most
75+
# cases in a terminal this doesn't look any different. Instead, use bold which
76+
# should follow man page conventions better.
77+
class MonoPostprocessor < Extensions::Postprocessor
78+
def process document, output
79+
if document.basebackend? 'manpage'
80+
output = output.gsub(/\\f\(CR/, '\\fB')
81+
end
82+
output
83+
end
84+
end
85+
86+
# General utility for converting text. Example:
87+
#
88+
# convert:lowercase[{somevar}]
89+
class ConvertInlineMacro < Extensions::InlineMacroProcessor
90+
use_dsl
91+
92+
named :convert
93+
name_positional_attributes 'text'
94+
95+
def process parent, target, attrs
96+
text = attrs['text']
97+
case target
98+
when 'lowercase'
99+
text.downcase
100+
end
101+
end
102+
end
103+
104+
Extensions.register :uri_schemes do
105+
inline_macro ManInlineMacro
106+
inline_macro LinkCargoInlineMacro
107+
inline_macro ConvertInlineMacro
108+
postprocessor MonoPostprocessor
109+
end

‎src/doc/man/cargo-bench.adoc

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
= cargo-bench(1)
2+
:doctype: manpage
3+
:actionverb: Benchmark
4+
:nouns: benchmarks
5+
6+
== NAME
7+
8+
cargo-bench - Execute benchmarks of a package
9+
10+
== SYNOPSIS
11+
12+
`cargo bench [_OPTIONS_] [BENCHNAME] [-- _BENCH-OPTIONS_]`
13+
14+
== DESCRIPTION
15+
16+
Compile and execute benchmarks.
17+
18+
The benchmark filtering argument `BENCHNAME` and all the arguments following
19+
the two dashes (`--`) are passed to the benchmark binaries and thus to
20+
_libtest_ (rustc's built in unit-test and micro-benchmarking framework). If
21+
you're passing arguments to both Cargo and the binary, the ones after `--` go
22+
to the binary, the ones before go to Cargo. For details about libtest's
23+
arguments see the output of `cargo bench -- --help`. As an example, this will
24+
run only the benchmark named `foo` (and skip other similarly named benchmarks
25+
like `foobar`):
26+
27+
cargo bench -- foo --exact
28+
29+
Benchmarks are built with the `--test` option to `rustc` which creates an
30+
executable with a `main` function that automatically runs all functions
31+
annotated with the `#[bench]` attribute. The libtest harness may be disabled
32+
by setting `harness = false` in the target manifest settings, in which case
33+
your code will need to provide its own `main` function to handle running
34+
benchmarks.
35+
36+
== OPTIONS
37+
38+
=== Benchmark Options
39+
40+
include::options-test.adoc[]
41+
42+
=== Package Selection
43+
44+
include::options-packages.adoc[]
45+
46+
=== Target Selection
47+
48+
When no target selection options are given, `cargo bench` will build the
49+
following targets of the selected packages:
50+
51+
- lib – used to link with binaries and benchmarks
52+
- bins (only if benchmark targets are built and required features are
53+
available)
54+
- lib as a benchmark
55+
- bins as benchmarks
56+
- benchmark targets
57+
58+
The default behavior can be changed by setting the `bench` flag for the target
59+
in the manifest settings. Setting examples to `bench = true` will build and
60+
run the example as a benchmark. Setting targets to `bench = false` will stop
61+
them from being benchmarked by default. Target selection options that take a
62+
target by name ignore the `bench` flag and will always benchmark the given
63+
target.
64+
65+
include::options-targets.adoc[]
66+
67+
include::options-features.adoc[]
68+
69+
=== Compilation Options
70+
71+
include::options-target-triple.adoc[]
72+
73+
=== Output Options
74+
75+
include::options-target-dir.adoc[]
76+
77+
=== Display Options
78+
79+
By default the Rust test harness hides output from benchmark execution to keep
80+
results readable. Benchmark output can be recovered (e.g. for debugging) by
81+
passing `--nocapture` to the benchmark binaries:
82+
83+
cargo bench -- --nocapture
84+
85+
include::options-display.adoc[]
86+
87+
include::options-message-format.adoc[]
88+
89+
=== Manifest Options
90+
91+
include::options-manifest-path.adoc[]
92+
93+
include::options-locked.adoc[]
94+
95+
=== Common Options
96+
97+
include::options-common.adoc[]
98+
99+
=== Miscellaneous Options
100+
101+
The `--jobs` argument affects the building of the benchmark executable but
102+
does not affect how many threads are used when running the benchmarks. The
103+
Rust test harness runs benchmarks serially in a single thread.
104+
105+
include::options-jobs.adoc[]
106+
107+
== PROFILES
108+
109+
Profiles may be used to configure compiler options such as optimization levels
110+
and debug settings. See
111+
linkcargo:reference/manifest.html#the-profile-sections[the reference]
112+
for more details.
113+
114+
Benchmarks are always built with the `bench` profile. Binary and lib targets
115+
are built separately as benchmarks with the `bench` profile. Library targets
116+
are built with the `release` profiles when linked to binaries and benchmarks.
117+
Dependencies use the `release` profile.
118+
119+
If you need a debug build of a benchmark, try building it with
120+
man:cargo-build[1] which will use the `test` profile which is by default
121+
unoptimized and includes debug information. You can then run the debug-enabled
122+
benchmark manually.
123+
124+
include::section-environment.adoc[]
125+
126+
include::section-exit-status.adoc[]
127+
128+
== EXAMPLES
129+
130+
. Build and execute all the benchmarks of the current package:
131+
132+
cargo bench
133+
134+
. Run only a specific benchmark within a specific benchmark target:
135+
136+
cargo bench --bench bench_name -- modname::some_benchmark
137+
138+
== SEE ALSO
139+
man:cargo[1], man:cargo-test[1]

‎src/doc/man/cargo-build.adoc

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
= cargo-build(1)
2+
:doctype: manpage
3+
:actionverb: Build
4+
5+
== NAME
6+
7+
cargo-build - Compile the current package
8+
9+
== SYNOPSIS
10+
11+
`cargo build [_OPTIONS_]`
12+
13+
== DESCRIPTION
14+
15+
Compile local packages and all of their dependencies.
16+
17+
== OPTIONS
18+
19+
=== Package Selection
20+
21+
include::options-packages.adoc[]
22+
23+
=== Target Selection
24+
25+
When no target selection options are given, `cargo build` will build all
26+
binary and library targets of the selected packages. Binaries are skipped if
27+
they have `required-features` that are missing.
28+
29+
include::options-targets.adoc[]
30+
31+
include::options-features.adoc[]
32+
33+
=== Compilation Options
34+
35+
include::options-target-triple.adoc[]
36+
37+
include::options-release.adoc[]
38+
39+
=== Output Options
40+
41+
include::options-target-dir.adoc[]
42+
43+
*--out-dir* _DIRECTORY_::
44+
Copy final artifacts to this directory.
45+
+
46+
This option is unstable and available only on the nightly channel and requires
47+
the `-Z unstable-options` flag to enable.
48+
49+
=== Display Options
50+
51+
include::options-display.adoc[]
52+
53+
include::options-message-format.adoc[]
54+
55+
*--build-plan*::
56+
Outputs a series of JSON messages to stdout that indicate the commands to
57+
run the build.
58+
+
59+
This option is unstable and available only on the nightly channel and requires
60+
the `-Z unstable-options` flag to enable.
61+
62+
=== Manifest Options
63+
64+
include::options-manifest-path.adoc[]
65+
66+
include::options-locked.adoc[]
67+
68+
=== Common Options
69+
70+
include::options-common.adoc[]
71+
72+
=== Miscellaneous Options
73+
74+
include::options-jobs.adoc[]
75+
76+
include::section-profiles.adoc[]
77+
78+
include::section-environment.adoc[]
79+
80+
include::section-exit-status.adoc[]
81+
82+
== EXAMPLES
83+
84+
. Build the local package and all of its dependencies:
85+
86+
cargo build
87+
88+
. Build with optimizations:
89+
90+
cargo build --release
91+
92+
== SEE ALSO
93+
man:cargo[1], man:cargo-rustc[1]

0 commit comments

Comments
 (0)