Mark/Redox-From-Scratch
1
0
Fork 0
Code Issues Releases Activity

Add tools

Browse Source
This commit is contained in:
Mark
2024-12-16 20:57:17 -08:00
parent fbb975674f
commit 3207a2c7ee
3678 changed files with 2074383 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

362
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-add.1 Normal file
View File

@ -0,0 +1,362 @@
'\" t
.TH "CARGO\-ADD" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-add \[em] Add dependencies to a Cargo.toml manifest file
.SH "SYNOPSIS"
\fBcargo add\fR [\fIoptions\fR] \fIcrate\fR\[u2026]
.br
\fBcargo add\fR [\fIoptions\fR] \fB\-\-path\fR \fIpath\fR
.br
\fBcargo add\fR [\fIoptions\fR] \fB\-\-git\fR \fIurl\fR [\fIcrate\fR\[u2026]]
.SH "DESCRIPTION"
This command can add or modify dependencies.
.sp
The source for the dependency can be specified with:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fIcrate\fR\fB@\fR\fIversion\fR: Fetch from a registry with a version constraint of \[lq]\fIversion\fR\[rq]
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB\-\-path\fR \fIpath\fR: Fetch from the specified \fIpath\fR
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB\-\-git\fR \fIurl\fR: Pull from a git repo at \fIurl\fR
.RE
.sp
If no source is specified, then a best effort will be made to select one, including:
.sp
.RS 4
\h'-04'\(bu\h'+02'Existing dependencies in other tables (like \fBdev\-dependencies\fR)
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Workspace members
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Latest release in the registry
.RE
.sp
When you add a package that is already present, the existing entry will be updated with the flags specified.
.sp
Upon successful invocation, the enabled (\fB+\fR) and disabled (\fB\-\fR) \fIfeatures\fR <https://doc.rust\-lang.org/cargo/reference/features.html> of the specified
dependency will be listed in the command\[cq]s output.
.SH "OPTIONS"
.SS "Source options"
.sp
\fB\-\-git\fR \fIurl\fR
.RS 4
\fIGit URL to add the specified crate from\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#specifying\-dependencies\-from\-git\-repositories>\&.
.RE
.sp
\fB\-\-branch\fR \fIbranch\fR
.RS 4
Branch to use when adding from git.
.RE
.sp
\fB\-\-tag\fR \fItag\fR
.RS 4
Tag to use when adding from git.
.RE
.sp
\fB\-\-rev\fR \fIsha\fR
.RS 4
Specific commit to use when adding from git.
.RE
.sp
\fB\-\-path\fR \fIpath\fR
.RS 4
\fIFilesystem path\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#specifying\-path\-dependencies> to local crate to add.
.RE
.sp
\fB\-\-registry\fR \fIregistry\fR
.RS 4
Name of the registry to use. Registry names are defined in \fICargo config
files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used,
which is defined by the \fBregistry.default\fR config key which defaults to
\fBcrates\-io\fR\&.
.RE
.SS "Section options"
.sp
\fB\-\-dev\fR
.RS 4
Add as a \fIdevelopment dependency\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#development\-dependencies>\&.
.RE
.sp
\fB\-\-build\fR
.RS 4
Add as a \fIbuild dependency\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#build\-dependencies>\&.
.RE
.sp
\fB\-\-target\fR \fItarget\fR
.RS 4
Add as a dependency to the \fIgiven target platform\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#platform\-specific\-dependencies>\&.
.sp
To avoid unexpected shell expansions, you may use quotes around each target, e.g., \fB\-\-target 'cfg(unix)'\fR\&.
.RE
.SS "Dependency options"
.sp
\fB\-\-dry\-run\fR
.RS 4
Don\[cq]t actually write the manifest
.RE
.sp
\fB\-\-rename\fR \fIname\fR
.RS 4
\fIRename\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#renaming\-dependencies\-in\-cargotoml> the dependency.
.RE
.sp
\fB\-\-optional\fR
.RS 4
Mark the dependency as \fIoptional\fR <https://doc.rust\-lang.org/cargo/reference/features.html#optional\-dependencies>\&.
.RE
.sp
\fB\-\-no\-optional\fR
.RS 4
Mark the dependency as \fIrequired\fR <https://doc.rust\-lang.org/cargo/reference/features.html#optional\-dependencies>\&.
.RE
.sp
\fB\-\-public\fR
.RS 4
Mark the dependency as public.
.sp
The dependency can be referenced in your library\[cq]s public API.
.sp
\fIUnstable (nightly\-only)\fR <https://doc.rust\-lang.org/cargo/reference/unstable.html#public\-dependency>
.RE
.sp
\fB\-\-no\-public\fR
.RS 4
Mark the dependency as private.
.sp
While you can use the crate in your implementation, it cannot be referenced in your public API.
.sp
\fIUnstable (nightly\-only)\fR <https://doc.rust\-lang.org/cargo/reference/unstable.html#public\-dependency>
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Disable the \fIdefault features\fR <https://doc.rust\-lang.org/cargo/reference/features.html#dependency\-features>\&.
.RE
.sp
\fB\-\-default\-features\fR
.RS 4
Re\-enable the \fIdefault features\fR <https://doc.rust\-lang.org/cargo/reference/features.html#dependency\-features>\&.
.RE
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of \fIfeatures to
activate\fR <https://doc.rust\-lang.org/cargo/reference/features.html#dependency\-features>\&. When adding multiple
crates, the features for a specific crate may be enabled with
\fBpackage\-name/feature\-name\fR syntax. This flag may be specified multiple times,
which enables all specified features.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-p\fR \fIspec\fR,
\fB\-\-package\fR \fIspec\fR
.RS 4
Add dependencies to only the specified package.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Add \fBregex\fR as a dependency
.sp
.RS 4
.nf
cargo add regex
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Add \fBtrybuild\fR as a dev\-dependency
.sp
.RS 4
.nf
cargo add \-\-dev trybuild
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Add an older version of \fBnom\fR as a dependency
.sp
.RS 4
.nf
cargo add nom@5
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 4.\h'+01'Add support for serializing data structures to json with \fBderive\fRs
.sp
.RS 4
.nf
cargo add serde serde_json \-F serde/derive
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 5.\h'+01'Add \fBwindows\fR as a platform specific dependency on \fBcfg(windows)\fR
.sp
.RS 4
.nf
cargo add windows \-\-target 'cfg(windows)'
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-remove\fR(1)

559
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-bench.1 Normal file
View File

@ -0,0 +1,559 @@
'\" t
.TH "CARGO\-BENCH" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-bench \[em] Execute benchmarks of a package
.SH "SYNOPSIS"
\fBcargo bench\fR [\fIoptions\fR] [\fIbenchname\fR] [\fB\-\-\fR \fIbench\-options\fR]
.SH "DESCRIPTION"
Compile and execute benchmarks.
.sp
The benchmark filtering argument \fIbenchname\fR and all the arguments following
the two dashes (\fB\-\-\fR) are passed to the benchmark binaries and thus to
\fIlibtest\fR (rustc\[cq]s built in unit\-test and micro\-benchmarking framework). If
you are passing arguments to both Cargo and the binary, the ones after \fB\-\-\fR go
to the binary, the ones before go to Cargo. For details about libtest\[cq]s
arguments see the output of \fBcargo bench \-\- \-\-help\fR and check out the rustc
book\[cq]s chapter on how tests work at
<https://doc.rust\-lang.org/rustc/tests/index.html>\&.
.sp
As an example, this will run only the benchmark named \fBfoo\fR (and skip other
similarly named benchmarks like \fBfoobar\fR):
.sp
.RS 4
.nf
cargo bench \-\- foo \-\-exact
.fi
.RE
.sp
Benchmarks are built with the \fB\-\-test\fR option to \fBrustc\fR which creates a
special executable by linking your code with libtest. The executable
automatically runs all functions annotated with the \fB#[bench]\fR attribute.
Cargo passes the \fB\-\-bench\fR flag to the test harness to tell it to run
only benchmarks, regardless of whether the harness is libtest or a custom harness.
.sp
The libtest harness may be disabled by setting \fBharness = false\fR in the target
manifest settings, in which case your code will need to provide its own \fBmain\fR
function to handle running benchmarks.
.RS 3
.ll -5
.sp
\fBNote\fR: The
\fI\f(BI#[bench]\fI attribute\fR <https://doc.rust\-lang.org/nightly/unstable\-book/library\-features/test.html>
is currently unstable and only available on the
\fInightly channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>\&.
There are some packages available on
\fIcrates.io\fR <https://crates.io/keywords/benchmark> that may help with
running benchmarks on the stable channel, such as
\fICriterion\fR <https://crates.io/crates/criterion>\&.
.br
.RE
.ll
.sp
By default, \fBcargo bench\fR uses the \fI\f(BIbench\fI profile\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html#bench>, which enables
optimizations and disables debugging information. If you need to debug a
benchmark, you can use the \fB\-\-profile=dev\fR command\-line option to switch to
the dev profile. You can then run the debug\-enabled benchmark within a
debugger.
.SS "Working directory of benchmarks"
The working directory of every benchmark is set to the root directory of the
package the benchmark belongs to.
Setting the working directory of benchmarks to the package\[cq]s root directory
makes it possible for benchmarks to reliably access the package\[cq]s files using
relative paths, regardless from where \fBcargo bench\fR was executed from.
.SH "OPTIONS"
.SS "Benchmark Options"
.sp
\fB\-\-no\-run\fR
.RS 4
Compile, but don\[cq]t run benchmarks.
.RE
.sp
\fB\-\-no\-fail\-fast\fR
.RS 4
Run all benchmarks regardless of failure. Without this flag, Cargo will exit
after the first executable fails. The Rust test harness will run all benchmarks
within the executable to completion, this flag only applies to the executable
as a whole.
.RE
.SS "Package Selection"
By default, when no package selection options are given, the packages selected
depend on the selected manifest file (based on the current working directory if
\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then
the workspaces default members are selected, otherwise only the package defined
by the manifest will be selected.
.sp
The default members of a workspace can be set explicitly with the
\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a
virtual workspace will include all workspace members (equivalent to passing
\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself.
.sp
\fB\-p\fR \fIspec\fR\[u2026],
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Benchmark only the specified packages. See \fBcargo\-pkgid\fR(1) for the
SPEC format. This flag may be specified multiple times and supports common Unix
glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally
expanding glob patterns before Cargo handles them, you must use single quotes or
double quotes around each pattern.
.RE
.sp
\fB\-\-workspace\fR
.RS 4
Benchmark all members in the workspace.
.RE
.sp
\fB\-\-all\fR
.RS 4
Deprecated alias for \fB\-\-workspace\fR\&.
.RE
.sp
\fB\-\-exclude\fR \fISPEC\fR\[u2026]
.RS 4
Exclude the specified packages. Must be used in conjunction with the
\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports
common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell
accidentally expanding glob patterns before Cargo handles them, you must use
single quotes or double quotes around each pattern.
.RE
.SS "Target Selection"
When no target selection options are given, \fBcargo bench\fR will build the
following targets of the selected packages:
.sp
.RS 4
\h'-04'\(bu\h'+02'lib \[em] used to link with binaries and benchmarks
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'bins (only if benchmark targets are built and required features are
available)
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'lib as a benchmark
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'bins as benchmarks
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'benchmark targets
.RE
.sp
The default behavior can be changed by setting the \fBbench\fR flag for the target
in the manifest settings. Setting examples to \fBbench = true\fR will build and
run the example as a benchmark, replacing the example\[cq]s \fBmain\fR function with
the libtest harness.
.sp
Setting targets to \fBbench = false\fR will stop them from being bencharmked by
default. Target selection options that take a target by name (such as
\fB\-\-example foo\fR) ignore the \fBbench\fR flag and will always benchmark the given
target.
.sp
See \fIConfiguring a target\fR <https://doc.rust\-lang.org/cargo/reference/cargo\-targets.html#configuring\-a\-target>
for more information on per\-target settings.
.sp
Binary targets are automatically built if there is an integration test or
benchmark being selected to benchmark. This allows an integration
test to execute the binary to exercise and test its behavior.
The \fBCARGO_BIN_EXE_<name>\fR
\fIenvironment variable\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html#environment\-variables\-cargo\-sets\-for\-crates>
is set when the integration test is built so that it can use the
\fI\f(BIenv\fI macro\fR <https://doc.rust\-lang.org/std/macro.env.html> to locate the
executable.
.sp
Passing target selection flags will benchmark only the specified
targets.
.sp
Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also
support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your
shell accidentally expanding glob patterns before Cargo handles them, you must
use single quotes or double quotes around each glob pattern.
.sp
\fB\-\-lib\fR
.RS 4
Benchmark the package\[cq]s library.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
Benchmark the specified binary. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-bins\fR
.RS 4
Benchmark all binary targets.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
.RS 4
Benchmark the specified example. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-examples\fR
.RS 4
Benchmark all example targets.
.RE
.sp
\fB\-\-test\fR \fIname\fR\[u2026]
.RS 4
Benchmark the specified integration test. This flag may be specified
multiple times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-tests\fR
.RS 4
Benchmark all targets in test mode that have the \fBtest = true\fR manifest
flag set. By default this includes the library and binaries built as
unittests, and integration tests. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
unittest, and once as a dependency for binaries, integration tests, etc.).
Targets may be enabled or disabled by setting the \fBtest\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-bench\fR \fIname\fR\[u2026]
.RS 4
Benchmark the specified benchmark. This flag may be specified multiple
times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-benches\fR
.RS 4
Benchmark all targets in benchmark mode that have the \fBbench = true\fR
manifest flag set. By default this includes the library and binaries built
as benchmarks, and bench targets. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
benchmark, and once as a dependency for binaries, benchmarks, etc.).
Targets may be enabled or disabled by setting the \fBbench\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-all\-targets\fR
.RS 4
Benchmark all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Benchmark for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
Benchmark with the given profile.
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
.RE
.sp
\fB\-\-timings=\fR\fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&.
Specifying an output format (rather than the default) is unstable and requires
\fB\-Zunstable\-options\fR\&. Valid output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the
\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write
a report to the same directory with a timestamp in the filename if you want
to look at older runs. HTML output is suitable for human consumption only,
and does not provide machine\-readable timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.SS "Display Options"
By default the Rust test harness hides output from benchmark execution to keep
results readable. Benchmark output can be recovered (e.g., for debugging) by
passing \fB\-\-nocapture\fR to the benchmark binaries:
.sp
.RS 4
.nf
cargo bench \-\- \-\-nocapture
.fi
.RE
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
The output format for diagnostic messages. Can be specified multiple times
and consists of comma\-separated values. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with
\fBshort\fR and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR
and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See
\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains
the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages
contains embedded ANSI color codes for respecting rustc\[cq]s default color
scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics
in JSON messages printed, but instead Cargo itself should render the
JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others
coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SS "Miscellaneous Options"
The \fB\-\-jobs\fR argument affects the building of the benchmark executable but
does not affect how many threads are used when running the benchmarks. The
Rust test harness runs benchmarks serially in a single thread.
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
While \fBcargo bench\fR involves compilation, it does not provide a \fB\-\-keep\-going\fR
flag. Use \fB\-\-no\-fail\-fast\fR to run as many benchmarks as possible without
stopping at the first failure. To \[lq]compile\[rq] as many benchmarks as possible, use
\fB\-\-benches\fR to build benchmark binaries separately. For example:
.sp
.RS 4
.nf
cargo build \-\-benches \-\-release \-\-keep\-going
cargo bench \-\-no\-fail\-fast
.fi
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Build and execute all the benchmarks of the current package:
.sp
.RS 4
.nf
cargo bench
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Run only a specific benchmark within a specific benchmark target:
.sp
.RS 4
.nf
cargo bench \-\-bench bench_name \-\- modname::some_benchmark
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-test\fR(1)

482
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-build.1 Normal file
View File

@ -0,0 +1,482 @@
'\" t
.TH "CARGO\-BUILD" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-build \[em] Compile the current package
.SH "SYNOPSIS"
\fBcargo build\fR [\fIoptions\fR]
.SH "DESCRIPTION"
Compile local packages and all of their dependencies.
.SH "OPTIONS"
.SS "Package Selection"
By default, when no package selection options are given, the packages selected
depend on the selected manifest file (based on the current working directory if
\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then
the workspaces default members are selected, otherwise only the package defined
by the manifest will be selected.
.sp
The default members of a workspace can be set explicitly with the
\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a
virtual workspace will include all workspace members (equivalent to passing
\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself.
.sp
\fB\-p\fR \fIspec\fR\[u2026],
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Build only the specified packages. See \fBcargo\-pkgid\fR(1) for the
SPEC format. This flag may be specified multiple times and supports common Unix
glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally
expanding glob patterns before Cargo handles them, you must use single quotes or
double quotes around each pattern.
.RE
.sp
\fB\-\-workspace\fR
.RS 4
Build all members in the workspace.
.RE
.sp
\fB\-\-all\fR
.RS 4
Deprecated alias for \fB\-\-workspace\fR\&.
.RE
.sp
\fB\-\-exclude\fR \fISPEC\fR\[u2026]
.RS 4
Exclude the specified packages. Must be used in conjunction with the
\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports
common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell
accidentally expanding glob patterns before Cargo handles them, you must use
single quotes or double quotes around each pattern.
.RE
.SS "Target Selection"
When no target selection options are given, \fBcargo build\fR will build all
binary and library targets of the selected packages. Binaries are skipped if
they have \fBrequired\-features\fR that are missing.
.sp
Binary targets are automatically built if there is an integration test or
benchmark being selected to build. This allows an integration
test to execute the binary to exercise and test its behavior.
The \fBCARGO_BIN_EXE_<name>\fR
\fIenvironment variable\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html#environment\-variables\-cargo\-sets\-for\-crates>
is set when the integration test is built so that it can use the
\fI\f(BIenv\fI macro\fR <https://doc.rust\-lang.org/std/macro.env.html> to locate the
executable.
.sp
Passing target selection flags will build only the specified
targets.
.sp
Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also
support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your
shell accidentally expanding glob patterns before Cargo handles them, you must
use single quotes or double quotes around each glob pattern.
.sp
\fB\-\-lib\fR
.RS 4
Build the package\[cq]s library.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
Build the specified binary. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-bins\fR
.RS 4
Build all binary targets.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
.RS 4
Build the specified example. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-examples\fR
.RS 4
Build all example targets.
.RE
.sp
\fB\-\-test\fR \fIname\fR\[u2026]
.RS 4
Build the specified integration test. This flag may be specified
multiple times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-tests\fR
.RS 4
Build all targets in test mode that have the \fBtest = true\fR manifest
flag set. By default this includes the library and binaries built as
unittests, and integration tests. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
unittest, and once as a dependency for binaries, integration tests, etc.).
Targets may be enabled or disabled by setting the \fBtest\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-bench\fR \fIname\fR\[u2026]
.RS 4
Build the specified benchmark. This flag may be specified multiple
times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-benches\fR
.RS 4
Build all targets in benchmark mode that have the \fBbench = true\fR
manifest flag set. By default this includes the library and binaries built
as benchmarks, and bench targets. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
benchmark, and once as a dependency for binaries, benchmarks, etc.).
Targets may be enabled or disabled by setting the \fBbench\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-all\-targets\fR
.RS 4
Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Build for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-r\fR,
\fB\-\-release\fR
.RS 4
Build optimized artifacts with the \fBrelease\fR profile.
See also the \fB\-\-profile\fR option for choosing a specific profile by name.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
Build with the given profile.
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
.RE
.sp
\fB\-\-timings=\fR\fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&.
Specifying an output format (rather than the default) is unstable and requires
\fB\-Zunstable\-options\fR\&. Valid output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the
\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write
a report to the same directory with a timestamp in the filename if you want
to look at older runs. HTML output is suitable for human consumption only,
and does not provide machine\-readable timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.sp
\fB\-\-out\-dir\fR \fIdirectory\fR
.RS 4
Copy final artifacts to this directory.
.sp
This option is unstable and available only on the
\fInightly channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
and requires the \fB\-Z unstable\-options\fR flag to enable.
See <https://github.com/rust\-lang/cargo/issues/6790> for more information.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
The output format for diagnostic messages. Can be specified multiple times
and consists of comma\-separated values. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with
\fBshort\fR and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR
and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See
\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains
the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages
contains embedded ANSI color codes for respecting rustc\[cq]s default color
scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics
in JSON messages printed, but instead Cargo itself should render the
JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others
coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.RE
.sp
\fB\-\-build\-plan\fR
.RS 4
Outputs a series of JSON messages to stdout that indicate the commands to run
the build.
.sp
This option is unstable and available only on the
\fInightly channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
and requires the \fB\-Z unstable\-options\fR flag to enable.
See <https://github.com/rust\-lang/cargo/issues/5579> for more information.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SS "Miscellaneous Options"
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
\fB\-\-keep\-going\fR
.RS 4
Build as many crates in the dependency graph as possible, rather than aborting
the build on the first one that fails to build.
.sp
For example if the current package depends on dependencies \fBfails\fR and \fBworks\fR,
one of which fails to build, \fBcargo build \-j1\fR may or may not build the
one that succeeds (depending on which one of the two builds Cargo picked to run
first), whereas \fBcargo build \-j1 \-\-keep\-going\fR would definitely run both
builds, even if the one run first fails.
.RE
.sp
\fB\-\-future\-incompat\-report\fR
.RS 4
Displays a future\-incompat report for any future\-incompatible warnings
produced during execution of this command
.sp
See \fBcargo\-report\fR(1)
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Build the local package and all of its dependencies:
.sp
.RS 4
.nf
cargo build
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Build with optimizations:
.sp
.RS 4
.nf
cargo build \-\-release
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-rustc\fR(1)

463
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-check.1 Normal file
View File

@ -0,0 +1,463 @@
'\" t
.TH "CARGO\-CHECK" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-check \[em] Check the current package
.SH "SYNOPSIS"
\fBcargo check\fR [\fIoptions\fR]
.SH "DESCRIPTION"
Check a local package and all of its dependencies for errors. This will
essentially compile the packages without performing the final step of code
generation, which is faster than running \fBcargo build\fR\&. The compiler will save
metadata files to disk so that future runs will reuse them if the source has
not been modified. Some diagnostics and errors are only emitted during code
generation, so they inherently won\[cq]t be reported with \fBcargo check\fR\&.
.SH "OPTIONS"
.SS "Package Selection"
By default, when no package selection options are given, the packages selected
depend on the selected manifest file (based on the current working directory if
\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then
the workspaces default members are selected, otherwise only the package defined
by the manifest will be selected.
.sp
The default members of a workspace can be set explicitly with the
\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a
virtual workspace will include all workspace members (equivalent to passing
\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself.
.sp
\fB\-p\fR \fIspec\fR\[u2026],
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Check only the specified packages. See \fBcargo\-pkgid\fR(1) for the
SPEC format. This flag may be specified multiple times and supports common Unix
glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally
expanding glob patterns before Cargo handles them, you must use single quotes or
double quotes around each pattern.
.RE
.sp
\fB\-\-workspace\fR
.RS 4
Check all members in the workspace.
.RE
.sp
\fB\-\-all\fR
.RS 4
Deprecated alias for \fB\-\-workspace\fR\&.
.RE
.sp
\fB\-\-exclude\fR \fISPEC\fR\[u2026]
.RS 4
Exclude the specified packages. Must be used in conjunction with the
\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports
common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell
accidentally expanding glob patterns before Cargo handles them, you must use
single quotes or double quotes around each pattern.
.RE
.SS "Target Selection"
When no target selection options are given, \fBcargo check\fR will check all
binary and library targets of the selected packages. Binaries are skipped if
they have \fBrequired\-features\fR that are missing.
.sp
Passing target selection flags will check only the specified
targets.
.sp
Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also
support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your
shell accidentally expanding glob patterns before Cargo handles them, you must
use single quotes or double quotes around each glob pattern.
.sp
\fB\-\-lib\fR
.RS 4
Check the package\[cq]s library.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
Check the specified binary. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-bins\fR
.RS 4
Check all binary targets.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
.RS 4
Check the specified example. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-examples\fR
.RS 4
Check all example targets.
.RE
.sp
\fB\-\-test\fR \fIname\fR\[u2026]
.RS 4
Check the specified integration test. This flag may be specified
multiple times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-tests\fR
.RS 4
Check all targets in test mode that have the \fBtest = true\fR manifest
flag set. By default this includes the library and binaries built as
unittests, and integration tests. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
unittest, and once as a dependency for binaries, integration tests, etc.).
Targets may be enabled or disabled by setting the \fBtest\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-bench\fR \fIname\fR\[u2026]
.RS 4
Check the specified benchmark. This flag may be specified multiple
times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-benches\fR
.RS 4
Check all targets in benchmark mode that have the \fBbench = true\fR
manifest flag set. By default this includes the library and binaries built
as benchmarks, and bench targets. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
benchmark, and once as a dependency for binaries, benchmarks, etc.).
Targets may be enabled or disabled by setting the \fBbench\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-all\-targets\fR
.RS 4
Check all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Check for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-r\fR,
\fB\-\-release\fR
.RS 4
Check optimized artifacts with the \fBrelease\fR profile.
See also the \fB\-\-profile\fR option for choosing a specific profile by name.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
Check with the given profile.
.sp
As a special case, specifying the \fBtest\fR profile will also enable checking in
test mode which will enable checking tests and enable the \fBtest\fR cfg option.
See \fIrustc tests\fR <https://doc.rust\-lang.org/rustc/tests/index.html> for more
detail.
.sp
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
.RE
.sp
\fB\-\-timings=\fR\fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&.
Specifying an output format (rather than the default) is unstable and requires
\fB\-Zunstable\-options\fR\&. Valid output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the
\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write
a report to the same directory with a timestamp in the filename if you want
to look at older runs. HTML output is suitable for human consumption only,
and does not provide machine\-readable timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
The output format for diagnostic messages. Can be specified multiple times
and consists of comma\-separated values. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with
\fBshort\fR and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR
and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See
\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains
the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages
contains embedded ANSI color codes for respecting rustc\[cq]s default color
scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics
in JSON messages printed, but instead Cargo itself should render the
JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others
coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SS "Miscellaneous Options"
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
\fB\-\-keep\-going\fR
.RS 4
Build as many crates in the dependency graph as possible, rather than aborting
the build on the first one that fails to build.
.sp
For example if the current package depends on dependencies \fBfails\fR and \fBworks\fR,
one of which fails to build, \fBcargo check \-j1\fR may or may not build the
one that succeeds (depending on which one of the two builds Cargo picked to run
first), whereas \fBcargo check \-j1 \-\-keep\-going\fR would definitely run both
builds, even if the one run first fails.
.RE
.sp
\fB\-\-future\-incompat\-report\fR
.RS 4
Displays a future\-incompat report for any future\-incompatible warnings
produced during execution of this command
.sp
See \fBcargo\-report\fR(1)
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Check the local package for errors:
.sp
.RS 4
.nf
cargo check
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Check all targets, including unit tests:
.sp
.RS 4
.nf
cargo check \-\-all\-targets \-\-profile=test
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-build\fR(1)

231
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-clean.1 Normal file
View File

@ -0,0 +1,231 @@
'\" t
.TH "CARGO\-CLEAN" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-clean \[em] Remove generated artifacts
.SH "SYNOPSIS"
\fBcargo clean\fR [\fIoptions\fR]
.SH "DESCRIPTION"
Remove artifacts from the target directory that Cargo has generated in the
past.
.sp
With no options, \fBcargo clean\fR will delete the entire target directory.
.SH "OPTIONS"
.SS "Package Selection"
When no packages are selected, all packages and all dependencies in the
workspace are cleaned.
.sp
\fB\-p\fR \fIspec\fR\[u2026],
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Clean only the specified packages. This flag may be specified
multiple times. See \fBcargo\-pkgid\fR(1) for the SPEC format.
.RE
.SS "Clean Options"
.sp
\fB\-\-dry\-run\fR
.RS 4
Displays a summary of what would be deleted without deleting anything.
Use with \fB\-\-verbose\fR to display the actual files that would be deleted.
.RE
.sp
\fB\-\-doc\fR
.RS 4
This option will cause \fBcargo clean\fR to remove only the \fBdoc\fR directory in
the target directory.
.RE
.sp
\fB\-\-release\fR
.RS 4
Remove all artifacts in the \fBrelease\fR directory.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
Remove all artifacts in the directory with the given profile name.
.RE
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Clean for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Remove the entire target directory:
.sp
.RS 4
.nf
cargo clean
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Remove only the release artifacts:
.sp
.RS 4
.nf
cargo clean \-\-release
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-build\fR(1)

413
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-doc.1 Normal file
View File

@ -0,0 +1,413 @@
'\" t
.TH "CARGO\-DOC" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-doc \[em] Build a package\[cq]s documentation
.SH "SYNOPSIS"
\fBcargo doc\fR [\fIoptions\fR]
.SH "DESCRIPTION"
Build the documentation for the local package and all dependencies. The output
is placed in \fBtarget/doc\fR in rustdoc\[cq]s usual format.
.SH "OPTIONS"
.SS "Documentation Options"
.sp
\fB\-\-open\fR
.RS 4
Open the docs in a browser after building them. This will use your default
browser unless you define another one in the \fBBROWSER\fR environment variable
or use the \fI\f(BIdoc.browser\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#docbrowser> configuration
option.
.RE
.sp
\fB\-\-no\-deps\fR
.RS 4
Do not build documentation for dependencies.
.RE
.sp
\fB\-\-document\-private\-items\fR
.RS 4
Include non\-public items in the documentation. This will be enabled by default if documenting a binary target.
.RE
.SS "Package Selection"
By default, when no package selection options are given, the packages selected
depend on the selected manifest file (based on the current working directory if
\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then
the workspaces default members are selected, otherwise only the package defined
by the manifest will be selected.
.sp
The default members of a workspace can be set explicitly with the
\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a
virtual workspace will include all workspace members (equivalent to passing
\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself.
.sp
\fB\-p\fR \fIspec\fR\[u2026],
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Document only the specified packages. See \fBcargo\-pkgid\fR(1) for the
SPEC format. This flag may be specified multiple times and supports common Unix
glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally
expanding glob patterns before Cargo handles them, you must use single quotes or
double quotes around each pattern.
.RE
.sp
\fB\-\-workspace\fR
.RS 4
Document all members in the workspace.
.RE
.sp
\fB\-\-all\fR
.RS 4
Deprecated alias for \fB\-\-workspace\fR\&.
.RE
.sp
\fB\-\-exclude\fR \fISPEC\fR\[u2026]
.RS 4
Exclude the specified packages. Must be used in conjunction with the
\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports
common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell
accidentally expanding glob patterns before Cargo handles them, you must use
single quotes or double quotes around each pattern.
.RE
.SS "Target Selection"
When no target selection options are given, \fBcargo doc\fR will document all
binary and library targets of the selected package. The binary will be skipped
if its name is the same as the lib target. Binaries are skipped if they have
\fBrequired\-features\fR that are missing.
.sp
The default behavior can be changed by setting \fBdoc = false\fR for the target in
the manifest settings. Using target selection options will ignore the \fBdoc\fR
flag and will always document the given target.
.sp
\fB\-\-lib\fR
.RS 4
Document the package\[cq]s library.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
Document the specified binary. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-bins\fR
.RS 4
Document all binary targets.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
.RS 4
Document the specified example. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-examples\fR
.RS 4
Document all example targets.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Document for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-r\fR,
\fB\-\-release\fR
.RS 4
Document optimized artifacts with the \fBrelease\fR profile.
See also the \fB\-\-profile\fR option for choosing a specific profile by name.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
Document with the given profile.
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
.RE
.sp
\fB\-\-timings=\fR\fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&.
Specifying an output format (rather than the default) is unstable and requires
\fB\-Zunstable\-options\fR\&. Valid output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the
\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write
a report to the same directory with a timestamp in the filename if you want
to look at older runs. HTML output is suitable for human consumption only,
and does not provide machine\-readable timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
The output format for diagnostic messages. Can be specified multiple times
and consists of comma\-separated values. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with
\fBshort\fR and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR
and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See
\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains
the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages
contains embedded ANSI color codes for respecting rustc\[cq]s default color
scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics
in JSON messages printed, but instead Cargo itself should render the
JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others
coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SS "Miscellaneous Options"
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
\fB\-\-keep\-going\fR
.RS 4
Build as many crates in the dependency graph as possible, rather than aborting
the build on the first one that fails to build.
.sp
For example if the current package depends on dependencies \fBfails\fR and \fBworks\fR,
one of which fails to build, \fBcargo doc \-j1\fR may or may not build the
one that succeeds (depending on which one of the two builds Cargo picked to run
first), whereas \fBcargo doc \-j1 \-\-keep\-going\fR would definitely run both
builds, even if the one run first fails.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Build the local package documentation and its dependencies and output to
\fBtarget/doc\fR\&.
.sp
.RS 4
.nf
cargo doc
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-rustdoc\fR(1), \fBrustdoc\fR(1)

187
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-fetch.1 Normal file
View File

@ -0,0 +1,187 @@
'\" t
.TH "CARGO\-FETCH" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-fetch \[em] Fetch dependencies of a package from the network
.SH "SYNOPSIS"
\fBcargo fetch\fR [\fIoptions\fR]
.SH "DESCRIPTION"
If a \fBCargo.lock\fR file is available, this command will ensure that all of the
git dependencies and/or registry dependencies are downloaded and locally
available. Subsequent Cargo commands will be able to run offline after a \fBcargo fetch\fR unless the lock file changes.
.sp
If the lock file is not available, then this command will generate the lock
file before fetching the dependencies.
.sp
If \fB\-\-target\fR is not specified, then all target dependencies are fetched.
.sp
See also the \fIcargo\-prefetch\fR <https://crates.io/crates/cargo\-prefetch>
plugin which adds a command to download popular crates. This may be useful if
you plan to use Cargo without a network with the \fB\-\-offline\fR flag.
.SH "OPTIONS"
.SS "Fetch options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Fetch for the given architecture. The default is all architectures. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Fetch all dependencies:
.sp
.RS 4
.nf
cargo fetch
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-update\fR(1), \fBcargo\-generate\-lockfile\fR(1)

560
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-fix.1 Normal file
View File

@ -0,0 +1,560 @@
'\" t
.TH "CARGO\-FIX" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-fix \[em] Automatically fix lint warnings reported by rustc
.SH "SYNOPSIS"
\fBcargo fix\fR [\fIoptions\fR]
.SH "DESCRIPTION"
This Cargo subcommand will automatically take rustc\[cq]s suggestions from
diagnostics like warnings and apply them to your source code. This is intended
to help automate tasks that rustc itself already knows how to tell you to fix!
.sp
Executing \fBcargo fix\fR will under the hood execute \fBcargo\-check\fR(1). Any warnings
applicable to your crate will be automatically fixed (if possible) and all
remaining warnings will be displayed when the check process is finished. For
example if you\[cq]d like to apply all fixes to the current package, you can run:
.sp
.RS 4
.nf
cargo fix
.fi
.RE
.sp
which behaves the same as \fBcargo check \-\-all\-targets\fR\&.
.sp
\fBcargo fix\fR is only capable of fixing code that is normally compiled with
\fBcargo check\fR\&. If code is conditionally enabled with optional features, you
will need to enable those features for that code to be analyzed:
.sp
.RS 4
.nf
cargo fix \-\-features foo
.fi
.RE
.sp
Similarly, other \fBcfg\fR expressions like platform\-specific code will need to
pass \fB\-\-target\fR to fix code for the given target.
.sp
.RS 4
.nf
cargo fix \-\-target x86_64\-pc\-windows\-gnu
.fi
.RE
.sp
If you encounter any problems with \fBcargo fix\fR or otherwise have any questions
or feature requests please don\[cq]t hesitate to file an issue at
<https://github.com/rust\-lang/cargo>\&.
.SS "Edition migration"
The \fBcargo fix\fR subcommand can also be used to migrate a package from one
\fIedition\fR <https://doc.rust\-lang.org/edition\-guide/editions/transitioning\-an\-existing\-project\-to\-a\-new\-edition.html> to the next. The general procedure is:
.sp
.RS 4
\h'-04' 1.\h'+01'Run \fBcargo fix \-\-edition\fR\&. Consider also using the \fB\-\-all\-features\fR flag if
your project has multiple features. You may also want to run \fBcargo fix \-\-edition\fR multiple times with different \fB\-\-target\fR flags if your project
has platform\-specific code gated by \fBcfg\fR attributes.
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Modify \fBCargo.toml\fR to set the \fIedition field\fR <https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-edition\-field> to the new edition.
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Run your project tests to verify that everything still works. If new
warnings are issued, you may want to consider running \fBcargo fix\fR again
(without the \fB\-\-edition\fR flag) to apply any suggestions given by the
compiler.
.RE
.sp
And hopefully that\[cq]s it! Just keep in mind of the caveats mentioned above that
\fBcargo fix\fR cannot update code for inactive features or \fBcfg\fR expressions.
Also, in some rare cases the compiler is unable to automatically migrate all
code to the new edition, and this may require manual changes after building
with the new edition.
.SH "OPTIONS"
.SS "Fix options"
.sp
\fB\-\-broken\-code\fR
.RS 4
Fix code even if it already has compiler errors. This is useful if \fBcargo fix\fR
fails to apply the changes. It will apply the changes and leave the broken
code in the working directory for you to inspect and manually fix.
.RE
.sp
\fB\-\-edition\fR
.RS 4
Apply changes that will update the code to the next edition. This will not
update the edition in the \fBCargo.toml\fR manifest, which must be updated
manually after \fBcargo fix \-\-edition\fR has finished.
.RE
.sp
\fB\-\-edition\-idioms\fR
.RS 4
Apply suggestions that will update code to the preferred style for the current
edition.
.RE
.sp
\fB\-\-allow\-no\-vcs\fR
.RS 4
Fix code even if a VCS was not detected.
.RE
.sp
\fB\-\-allow\-dirty\fR
.RS 4
Fix code even if the working directory has changes.
.RE
.sp
\fB\-\-allow\-staged\fR
.RS 4
Fix code even if the working directory has staged changes.
.RE
.SS "Package Selection"
By default, when no package selection options are given, the packages selected
depend on the selected manifest file (based on the current working directory if
\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then
the workspaces default members are selected, otherwise only the package defined
by the manifest will be selected.
.sp
The default members of a workspace can be set explicitly with the
\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a
virtual workspace will include all workspace members (equivalent to passing
\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself.
.sp
\fB\-p\fR \fIspec\fR\[u2026],
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Fix only the specified packages. See \fBcargo\-pkgid\fR(1) for the
SPEC format. This flag may be specified multiple times and supports common Unix
glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally
expanding glob patterns before Cargo handles them, you must use single quotes or
double quotes around each pattern.
.RE
.sp
\fB\-\-workspace\fR
.RS 4
Fix all members in the workspace.
.RE
.sp
\fB\-\-all\fR
.RS 4
Deprecated alias for \fB\-\-workspace\fR\&.
.RE
.sp
\fB\-\-exclude\fR \fISPEC\fR\[u2026]
.RS 4
Exclude the specified packages. Must be used in conjunction with the
\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports
common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell
accidentally expanding glob patterns before Cargo handles them, you must use
single quotes or double quotes around each pattern.
.RE
.SS "Target Selection"
When no target selection options are given, \fBcargo fix\fR will fix all targets
(\fB\-\-all\-targets\fR implied). Binaries are skipped if they have
\fBrequired\-features\fR that are missing.
.sp
Passing target selection flags will fix only the specified
targets.
.sp
Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also
support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your
shell accidentally expanding glob patterns before Cargo handles them, you must
use single quotes or double quotes around each glob pattern.
.sp
\fB\-\-lib\fR
.RS 4
Fix the package\[cq]s library.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
Fix the specified binary. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-bins\fR
.RS 4
Fix all binary targets.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
.RS 4
Fix the specified example. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-examples\fR
.RS 4
Fix all example targets.
.RE
.sp
\fB\-\-test\fR \fIname\fR\[u2026]
.RS 4
Fix the specified integration test. This flag may be specified
multiple times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-tests\fR
.RS 4
Fix all targets in test mode that have the \fBtest = true\fR manifest
flag set. By default this includes the library and binaries built as
unittests, and integration tests. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
unittest, and once as a dependency for binaries, integration tests, etc.).
Targets may be enabled or disabled by setting the \fBtest\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-bench\fR \fIname\fR\[u2026]
.RS 4
Fix the specified benchmark. This flag may be specified multiple
times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-benches\fR
.RS 4
Fix all targets in benchmark mode that have the \fBbench = true\fR
manifest flag set. By default this includes the library and binaries built
as benchmarks, and bench targets. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
benchmark, and once as a dependency for binaries, benchmarks, etc.).
Targets may be enabled or disabled by setting the \fBbench\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-all\-targets\fR
.RS 4
Fix all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Fix for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-r\fR,
\fB\-\-release\fR
.RS 4
Fix optimized artifacts with the \fBrelease\fR profile.
See also the \fB\-\-profile\fR option for choosing a specific profile by name.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
Fix with the given profile.
.sp
As a special case, specifying the \fBtest\fR profile will also enable checking in
test mode which will enable checking tests and enable the \fBtest\fR cfg option.
See \fIrustc tests\fR <https://doc.rust\-lang.org/rustc/tests/index.html> for more
detail.
.sp
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
.RE
.sp
\fB\-\-timings=\fR\fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&.
Specifying an output format (rather than the default) is unstable and requires
\fB\-Zunstable\-options\fR\&. Valid output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the
\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write
a report to the same directory with a timestamp in the filename if you want
to look at older runs. HTML output is suitable for human consumption only,
and does not provide machine\-readable timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
The output format for diagnostic messages. Can be specified multiple times
and consists of comma\-separated values. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with
\fBshort\fR and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR
and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See
\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains
the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages
contains embedded ANSI color codes for respecting rustc\[cq]s default color
scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics
in JSON messages printed, but instead Cargo itself should render the
JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others
coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SS "Miscellaneous Options"
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
\fB\-\-keep\-going\fR
.RS 4
Build as many crates in the dependency graph as possible, rather than aborting
the build on the first one that fails to build.
.sp
For example if the current package depends on dependencies \fBfails\fR and \fBworks\fR,
one of which fails to build, \fBcargo fix \-j1\fR may or may not build the
one that succeeds (depending on which one of the two builds Cargo picked to run
first), whereas \fBcargo fix \-j1 \-\-keep\-going\fR would definitely run both
builds, even if the one run first fails.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Apply compiler suggestions to the local package:
.sp
.RS 4
.nf
cargo fix
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Update a package to prepare it for the next edition:
.sp
.RS 4
.nf
cargo fix \-\-edition
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Apply suggested idioms for the current edition:
.sp
.RS 4
.nf
cargo fix \-\-edition\-idioms
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-check\fR(1)

173
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-generate-lockfile.1 Normal file
View File

@ -0,0 +1,173 @@
'\" t
.TH "CARGO\-GENERATE\-LOCKFILE" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-generate\-lockfile \[em] Generate the lockfile for a package
.SH "SYNOPSIS"
\fBcargo generate\-lockfile\fR [\fIoptions\fR]
.SH "DESCRIPTION"
This command will create the \fBCargo.lock\fR lockfile for the current package or
workspace. If the lockfile already exists, it will be rebuilt with the latest
available version of every package.
.sp
See also \fBcargo\-update\fR(1) which is also capable of creating a \fBCargo.lock\fR
lockfile and has more options for controlling update behavior.
.SH "OPTIONS"
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Create or update the lockfile for the current package or workspace:
.sp
.RS 4
.nf
cargo generate\-lockfile
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-update\fR(1)

34
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-help.1 Normal file
View File

@ -0,0 +1,34 @@
'\" t
.TH "CARGO\-HELP" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-help \[em] Get help for a Cargo command
.SH "SYNOPSIS"
\fBcargo help\fR [\fIsubcommand\fR]
.SH "DESCRIPTION"
Prints a help message for the given command.
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Get help for a command:
.sp
.RS 4
.nf
cargo help build
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Help is also available with the \fB\-\-help\fR flag:
.sp
.RS 4
.nf
cargo build \-\-help
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1)

171
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-init.1 Normal file
View File

@ -0,0 +1,171 @@
'\" t
.TH "CARGO\-INIT" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-init \[em] Create a new Cargo package in an existing directory
.SH "SYNOPSIS"
\fBcargo init\fR [\fIoptions\fR] [\fIpath\fR]
.SH "DESCRIPTION"
This command will create a new Cargo manifest in the current directory. Give a
path as an argument to create in the given directory.
.sp
If there are typically\-named Rust source files already in the directory, those
will be used. If not, then a sample \fBsrc/main.rs\fR file will be created, or
\fBsrc/lib.rs\fR if \fB\-\-lib\fR is passed.
.sp
If the directory is not already in a VCS repository, then a new repository
is created (see \fB\-\-vcs\fR below).
.sp
See \fBcargo\-new\fR(1) for a similar command which will create a new package in
a new directory.
.SH "OPTIONS"
.SS "Init Options"
.sp
\fB\-\-bin\fR
.RS 4
Create a package with a binary target (\fBsrc/main.rs\fR).
This is the default behavior.
.RE
.sp
\fB\-\-lib\fR
.RS 4
Create a package with a library target (\fBsrc/lib.rs\fR).
.RE
.sp
\fB\-\-edition\fR \fIedition\fR
.RS 4
Specify the Rust edition to use. Default is 2021.
Possible values: 2015, 2018, 2021, 2024
.RE
.sp
\fB\-\-name\fR \fIname\fR
.RS 4
Set the package name. Defaults to the directory name.
.RE
.sp
\fB\-\-vcs\fR \fIvcs\fR
.RS 4
Initialize a new VCS repository for the given version control system (git,
hg, pijul, or fossil) or do not initialize any version control at all
(none). If not specified, defaults to \fBgit\fR or the configuration value
\fBcargo\-new.vcs\fR, or \fBnone\fR if already inside a VCS repository.
.RE
.sp
\fB\-\-registry\fR \fIregistry\fR
.RS 4
This sets the \fBpublish\fR field in \fBCargo.toml\fR to the given registry name
which will restrict publishing only to that registry.
.sp
Registry names are defined in \fICargo config files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
If not specified, the default registry defined by the \fBregistry.default\fR
config key is used. If the default registry is not set and \fB\-\-registry\fR is not
used, the \fBpublish\fR field will not be set which means that publishing will not
be restricted.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Create a binary Cargo package in the current directory:
.sp
.RS 4
.nf
cargo init
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-new\fR(1)

530
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-install.1 Normal file
View File

@ -0,0 +1,530 @@
'\" t
.TH "CARGO\-INSTALL" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-install \[em] Build and install a Rust binary
.SH "SYNOPSIS"
\fBcargo install\fR [\fIoptions\fR] \fIcrate\fR[@\fIversion\fR]\[u2026]
.br
\fBcargo install\fR [\fIoptions\fR] \fB\-\-path\fR \fIpath\fR
.br
\fBcargo install\fR [\fIoptions\fR] \fB\-\-git\fR \fIurl\fR [\fIcrate\fR\[u2026]]
.br
\fBcargo install\fR [\fIoptions\fR] \fB\-\-list\fR
.SH "DESCRIPTION"
This command manages Cargo\[cq]s local set of installed binary crates. Only
packages which have executable \fB[[bin]]\fR or \fB[[example]]\fR targets can be
installed, and all executables are installed into the installation root\[cq]s
\fBbin\fR folder. By default only binaries, not examples, are installed.
.sp
The installation root is determined, in order of precedence:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB\-\-root\fR option
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBCARGO_INSTALL_ROOT\fR environment variable
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBinstall.root\fR Cargo \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBCARGO_HOME\fR environment variable
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB$HOME/.cargo\fR
.RE
.sp
There are multiple sources from which a crate can be installed. The default
source location is crates.io but the \fB\-\-git\fR, \fB\-\-path\fR, and \fB\-\-registry\fR flags
can change this source. If the source contains more than one package (such as
crates.io or a git repository with multiple crates) the \fIcrate\fR argument is
required to indicate which crate should be installed.
.sp
Crates from crates.io can optionally specify the version they wish to install
via the \fB\-\-version\fR flags, and similarly packages from git repositories can
optionally specify the branch, tag, or revision that should be installed. If a
crate has multiple binaries, the \fB\-\-bin\fR argument can selectively install only
one of them, and if you\[cq]d rather install examples the \fB\-\-example\fR argument can
be used as well.
.sp
If the package is already installed, Cargo will reinstall it if the installed
version does not appear to be up\-to\-date. If any of the following values
change, then Cargo will reinstall the package:
.sp
.RS 4
\h'-04'\(bu\h'+02'The package version and source.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'The set of binary names installed.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'The chosen features.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'The profile (\fB\-\-profile\fR).
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'The target (\fB\-\-target\fR).
.RE
.sp
Installing with \fB\-\-path\fR will always build and install, unless there are
conflicting binaries from another package. The \fB\-\-force\fR flag may be used to
force Cargo to always reinstall the package.
.sp
If the source is crates.io or \fB\-\-git\fR then by default the crate will be built
in a temporary target directory. To avoid this, the target directory can be
specified by setting the \fBCARGO_TARGET_DIR\fR environment variable to a relative
path. In particular, this can be useful for caching build artifacts on
continuous integration systems.
.SS "Dealing with the Lockfile"
By default, the \fBCargo.lock\fR file that is included with the package will be
ignored. This means that Cargo will recompute which versions of dependencies
to use, possibly using newer versions that have been released since the
package was published. The \fB\-\-locked\fR flag can be used to force Cargo to use
the packaged \fBCargo.lock\fR file if it is available. This may be useful for
ensuring reproducible builds, to use the exact same set of dependencies that
were available when the package was published. It may also be useful if a
newer version of a dependency is published that no longer builds on your
system, or has other problems. The downside to using \fB\-\-locked\fR is that you
will not receive any fixes or updates to any dependency. Note that Cargo did
not start publishing \fBCargo.lock\fR files until version 1.37, which means
packages published with prior versions will not have a \fBCargo.lock\fR file
available.
.SS "Configuration Discovery"
This command operates on system or user level, not project level.
This means that the local \fIconfiguration discovery\fR <https://doc.rust\-lang.org/cargo/reference/config.html#hierarchical\-structure> is ignored.
Instead, the configuration discovery begins at \fB$CARGO_HOME/config.toml\fR\&.
If the package is installed with \fB\-\-path $PATH\fR, the local configuration
will be used, beginning discovery at \fB$PATH/.cargo/config.toml\fR\&.
.SH "OPTIONS"
.SS "Install Options"
.sp
\fB\-\-vers\fR \fIversion\fR,
\fB\-\-version\fR \fIversion\fR
.RS 4
Specify a version to install. This may be a \fIversion
requirement\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html>, like \fB~1.2\fR, to have Cargo
select the newest version from the given requirement. If the version does not
have a requirement operator (such as \fB^\fR or \fB~\fR), then it must be in the form
\fIMAJOR.MINOR.PATCH\fR, and will install exactly that version; it is \fInot\fR
treated as a caret requirement like Cargo dependencies are.
.RE
.sp
\fB\-\-git\fR \fIurl\fR
.RS 4
Git URL to install the specified crate from.
.RE
.sp
\fB\-\-branch\fR \fIbranch\fR
.RS 4
Branch to use when installing from git.
.RE
.sp
\fB\-\-tag\fR \fItag\fR
.RS 4
Tag to use when installing from git.
.RE
.sp
\fB\-\-rev\fR \fIsha\fR
.RS 4
Specific commit to use when installing from git.
.RE
.sp
\fB\-\-path\fR \fIpath\fR
.RS 4
Filesystem path to local crate to install from.
.RE
.sp
\fB\-\-list\fR
.RS 4
List all installed packages and their versions.
.RE
.sp
\fB\-f\fR,
\fB\-\-force\fR
.RS 4
Force overwriting existing crates or binaries. This can be used if a package
has installed a binary with the same name as another package. This is also
useful if something has changed on the system that you want to rebuild with,
such as a newer version of \fBrustc\fR\&.
.RE
.sp
\fB\-\-no\-track\fR
.RS 4
By default, Cargo keeps track of the installed packages with a metadata file
stored in the installation root directory. This flag tells Cargo not to use or
create that file. With this flag, Cargo will refuse to overwrite any existing
files unless the \fB\-\-force\fR flag is used. This also disables Cargo\[cq]s ability to
protect against multiple concurrent invocations of Cargo installing at the
same time.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
Install only the specified binary.
.RE
.sp
\fB\-\-bins\fR
.RS 4
Install all binaries. This is the default behavior.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
.RS 4
Install only the specified example.
.RE
.sp
\fB\-\-examples\fR
.RS 4
Install all examples.
.RE
.sp
\fB\-\-root\fR \fIdir\fR
.RS 4
Directory to install packages into.
.RE
.sp
\fB\-\-registry\fR \fIregistry\fR
.RS 4
Name of the registry to use. Registry names are defined in \fICargo config
files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used,
which is defined by the \fBregistry.default\fR config key which defaults to
\fBcrates\-io\fR\&.
.RE
.sp
\fB\-\-index\fR \fIindex\fR
.RS 4
The URL of the registry index to use.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Install for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to a new temporary folder located in the
temporary directory of the platform.
.sp
When using \fB\-\-path\fR, by default it will use \fBtarget\fR directory in the workspace
of the local crate unless \fB\-\-target\-dir\fR
is specified.
.RE
.sp
\fB\-\-debug\fR
.RS 4
Build with the \fBdev\fR profile instead of the \fBrelease\fR profile.
See also the \fB\-\-profile\fR option for choosing a specific profile by name.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
Install with the given profile.
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
.RE
.sp
\fB\-\-timings=\fR\fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&.
Specifying an output format (rather than the default) is unstable and requires
\fB\-Zunstable\-options\fR\&. Valid output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the
\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write
a report to the same directory with a timestamp in the filename if you want
to look at older runs. HTML output is suitable for human consumption only,
and does not provide machine\-readable timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Manifest Options"
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Miscellaneous Options"
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
\fB\-\-keep\-going\fR
.RS 4
Build as many crates in the dependency graph as possible, rather than aborting
the build on the first one that fails to build.
.sp
For example if the current package depends on dependencies \fBfails\fR and \fBworks\fR,
one of which fails to build, \fBcargo install \-j1\fR may or may not build the
one that succeeds (depending on which one of the two builds Cargo picked to run
first), whereas \fBcargo install \-j1 \-\-keep\-going\fR would definitely run both
builds, even if the one run first fails.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
The output format for diagnostic messages. Can be specified multiple times
and consists of comma\-separated values. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with
\fBshort\fR and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR
and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See
\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains
the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages
contains embedded ANSI color codes for respecting rustc\[cq]s default color
scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics
in JSON messages printed, but instead Cargo itself should render the
JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others
coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Install or upgrade a package from crates.io:
.sp
.RS 4
.nf
cargo install ripgrep
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Install or reinstall the package in the current directory:
.sp
.RS 4
.nf
cargo install \-\-path .
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'View the list of installed packages:
.sp
.RS 4
.nf
cargo install \-\-list
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-uninstall\fR(1), \fBcargo\-search\fR(1), \fBcargo\-publish\fR(1)

150
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-locate-project.1 Normal file
View File

@ -0,0 +1,150 @@
'\" t
.TH "CARGO\-LOCATE\-PROJECT" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-locate\-project \[em] Print a JSON representation of a Cargo.toml file\[cq]s location
.SH "SYNOPSIS"
\fBcargo locate\-project\fR [\fIoptions\fR]
.SH "DESCRIPTION"
This command will print a JSON object to stdout with the full path to the manifest. The
manifest is found by searching upward for a file named \fBCargo.toml\fR starting from the current
working directory.
.sp
If the project happens to be a part of a workspace, the manifest of the project, rather than
the workspace root, is output. This can be overridden by the \fB\-\-workspace\fR flag. The root
workspace is found by traversing further upward or by using the field \fBpackage.workspace\fR after
locating the manifest of a workspace member.
.SH "OPTIONS"
.sp
\fB\-\-workspace\fR
.RS 4
Locate the \fBCargo.toml\fR at the root of the workspace, as opposed to the current
workspace member.
.RE
.SS "Display Options"
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
The representation in which to print the project location. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (default): JSON object with the path under the key \[lq]root\[rq]\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBplain\fR: Just the path.
.RE
.RE
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Display the path to the manifest based on the current directory:
.sp
.RS 4
.nf
cargo locate\-project
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-metadata\fR(1)

154
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-login.1 Normal file
View File

@ -0,0 +1,154 @@
'\" t
.TH "CARGO\-LOGIN" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-login \[em] Log in to a registry
.SH "SYNOPSIS"
\fBcargo login\fR [\fIoptions\fR] [\fItoken\fR] [\fB\-\-\fR \fIargs\fR]
.SH "DESCRIPTION"
This command will run a credential provider to save a token so that commands
that require authentication, such as \fBcargo\-publish\fR(1), will be
automatically authenticated.
.sp
All the arguments following the two dashes (\fB\-\-\fR) are passed to the credential provider.
.sp
For the default \fBcargo:token\fR credential provider, the token is saved
in \fB$CARGO_HOME/credentials.toml\fR\&. \fBCARGO_HOME\fR defaults to \fB\&.cargo\fR
in your home directory.
.sp
If a registry has a credential\-provider specified, it will be used. Otherwise,
the providers from the config value \fBregistry.global\-credential\-providers\fR will
be attempted, starting from the end of the list.
.sp
If the \fItoken\fR argument is not specified, it will be read from stdin.
.sp
The API token for crates.io may be retrieved from <https://crates.io/me>\&.
.sp
Take care to keep the token secret, it should not be shared with anyone else.
.SH "OPTIONS"
.SS "Login Options"
.sp
\fB\-\-registry\fR \fIregistry\fR
.RS 4
Name of the registry to use. Registry names are defined in \fICargo config
files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used,
which is defined by the \fBregistry.default\fR config key which defaults to
\fBcrates\-io\fR\&.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Save the token for the default registry:
.sp
.RS 4
.nf
cargo login
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Save the token for a specific registry:
.sp
.RS 4
.nf
cargo login \-\-registry my\-registry
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-logout\fR(1), \fBcargo\-publish\fR(1)

153
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-logout.1 Normal file
View File

@ -0,0 +1,153 @@
'\" t
.TH "CARGO\-LOGOUT" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-logout \[em] Remove an API token from the registry locally
.SH "SYNOPSIS"
\fBcargo logout\fR [\fIoptions\fR]
.SH "DESCRIPTION"
This command will run a credential provider to remove a saved token.
.sp
For the default \fBcargo:token\fR credential provider, credentials are stored
in \fB$CARGO_HOME/credentials.toml\fR where \fB$CARGO_HOME\fR defaults to \fB\&.cargo\fR
in your home directory.
.sp
If a registry has a credential\-provider specified, it will be used. Otherwise,
the providers from the config value \fBregistry.global\-credential\-providers\fR will
be attempted, starting from the end of the list.
.sp
If \fB\-\-registry\fR is not specified, then the credentials for the default
registry will be removed (configured by
\fI\f(BIregistry.default\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#registrydefault>, which defaults
to <https://crates.io/>).
.sp
This will not revoke the token on the server. If you need to revoke the token,
visit the registry website and follow its instructions (see
<https://crates.io/me> to revoke the token for <https://crates.io/>).
.SH "OPTIONS"
.SS "Logout Options"
.sp
\fB\-\-registry\fR \fIregistry\fR
.RS 4
Name of the registry to use. Registry names are defined in \fICargo config
files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used,
which is defined by the \fBregistry.default\fR config key which defaults to
\fBcrates\-io\fR\&.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Remove the default registry token:
.sp
.RS 4
.nf
cargo logout
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Remove the token for a specific registry:
.sp
.RS 4
.nf
cargo logout \-\-registry my\-registry
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-login\fR(1)

542
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-metadata.1 Normal file
View File

@ -0,0 +1,542 @@
'\" t
.TH "CARGO\-METADATA" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-metadata \[em] Machine\-readable metadata about the current package
.SH "SYNOPSIS"
\fBcargo metadata\fR [\fIoptions\fR]
.SH "DESCRIPTION"
Output JSON to stdout containing information about the workspace members and
resolved dependencies of the current package.
.sp
The format of the output is subject to change in futures versions of Cargo. It
is recommended to include the \fB\-\-format\-version\fR flag to future\-proof your code
to ensure the output is in the format you are expecting. For more on the
expectations, see \[lq]Compatibility\[rq]\&.
.sp
See the \fIcargo_metadata crate\fR <https://crates.io/crates/cargo_metadata>
for a Rust API for reading the metadata.
.SH "OUTPUT FORMAT"
.SS "Compatibility"
Within the same output format version, the compatibility is maintained, except
some scenarios. The following is a non\-exhaustive list of changes that are not
considersed as incompatible:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBAdding new fields\fR \[em] New fields will be added when needed. Reserving this
helps Cargo evolve without bumping the format version too often.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBAdding new values for enum\-like fields\fR \[em] Same as adding new fields. It
keeps metadata evolving without stagnation.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBChanging opaque representations\fR \[em] The inner representations of some
fields are implementation details. For example, fields related to
\[lq]Source ID\[rq] are treated as opaque identifiers to differentiate packages or
sources. Consumers shouldn\[cq]t rely on those representations unless specified.
.RE
.SS "JSON format"
The JSON output has the following format:
.sp
.RS 4
.nf
{
/* Array of all packages in the workspace.
It also includes all feature\-enabled dependencies unless \-\-no\-deps is used.
*/
"packages": [
{
/* The name of the package. */
"name": "my\-package",
/* The version of the package. */
"version": "0.1.0",
/* The Package ID for referring to the
package within the document and as the `\-\-package` argument to many commands
*/
"id": "file:///path/to/my\-package#0.1.0",
/* The license value from the manifest, or null. */
"license": "MIT/Apache\-2.0",
/* The license\-file value from the manifest, or null. */
"license_file": "LICENSE",
/* The description value from the manifest, or null. */
"description": "Package description.",
/* The source ID of the package, an "opaque" identifier representing
where a package is retrieved from. See "Compatibility" above for
the stability guarantee.
This is null for path dependencies and workspace members.
For other dependencies, it is a string with the format:
\- "registry+URL" for registry\-based dependencies.
Example: "registry+https://github.com/rust\-lang/crates.io\-index"
\- "git+URL" for git\-based dependencies.
Example: "git+https://github.com/rust\-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
\- "sparse+URL" for dependencies from a sparse registry
Example: "sparse+https://my\-sparse\-registry.org"
The value after the `+` is not explicitly defined, and may change
between versions of Cargo and may not directly correlate to other
things, such as registry definitions in a config file. New source
kinds may be added in the future which will have different `+`
prefixed identifiers.
*/
"source": null,
/* Array of dependencies declared in the package's manifest. */
"dependencies": [
{
/* The name of the dependency. */
"name": "bitflags",
/* The source ID of the dependency. May be null, see
description for the package source.
*/
"source": "registry+https://github.com/rust\-lang/crates.io\-index",
/* The version requirement for the dependency.
Dependencies without a version requirement have a value of "*".
*/
"req": "^1.0",
/* The dependency kind.
"dev", "build", or null for a normal dependency.
*/
"kind": null,
/* If the dependency is renamed, this is the new name for
the dependency as a string. null if it is not renamed.
*/
"rename": null,
/* Boolean of whether or not this is an optional dependency. */
"optional": false,
/* Boolean of whether or not default features are enabled. */
"uses_default_features": true,
/* Array of features enabled. */
"features": [],
/* The target platform for the dependency.
null if not a target dependency.
*/
"target": "cfg(windows)",
/* The file system path for a local path dependency.
not present if not a path dependency.
*/
"path": "/path/to/dep",
/* A string of the URL of the registry this dependency is from.
If not specified or null, the dependency is from the default
registry (crates.io).
*/
"registry": null
}
],
/* Array of Cargo targets. */
"targets": [
{
/* Array of target kinds.
\- lib targets list the `crate\-type` values from the
manifest such as "lib", "rlib", "dylib",
"proc\-macro", etc. (default ["lib"])
\- binary is ["bin"]
\- example is ["example"]
\- integration test is ["test"]
\- benchmark is ["bench"]
\- build script is ["custom\-build"]
*/
"kind": [
"bin"
],
/* Array of crate types.
\- lib and example libraries list the `crate\-type` values
from the manifest such as "lib", "rlib", "dylib",
"proc\-macro", etc. (default ["lib"])
\- all other target kinds are ["bin"]
*/
"crate_types": [
"bin"
],
/* The name of the target. */
"name": "my\-package",
/* Absolute path to the root source file of the target. */
"src_path": "/path/to/my\-package/src/main.rs",
/* The Rust edition of the target.
Defaults to the package edition.
*/
"edition": "2018",
/* Array of required features.
This property is not included if no required features are set.
*/
"required\-features": ["feat1"],
/* Whether the target should be documented by `cargo doc`. */
"doc": true,
/* Whether or not this target has doc tests enabled, and
the target is compatible with doc testing.
*/
"doctest": false,
/* Whether or not this target should be built and run with `\-\-test`
*/
"test": true
}
],
/* Set of features defined for the package.
Each feature maps to an array of features or dependencies it
enables.
*/
"features": {
"default": [
"feat1"
],
"feat1": [],
"feat2": []
},
/* Absolute path to this package's manifest. */
"manifest_path": "/path/to/my\-package/Cargo.toml",
/* Package metadata.
This is null if no metadata is specified.
*/
"metadata": {
"docs": {
"rs": {
"all\-features": true
}
}
},
/* List of registries to which this package may be published.
Publishing is unrestricted if null, and forbidden if an empty array. */
"publish": [
"crates\-io"
],
/* Array of authors from the manifest.
Empty array if no authors specified.
*/
"authors": [
"Jane Doe <user@example.com>"
],
/* Array of categories from the manifest. */
"categories": [
"command\-line\-utilities"
],
/* Optional string that is the default binary picked by cargo run. */
"default_run": null,
/* Optional string that is the minimum supported rust version */
"rust_version": "1.56",
/* Array of keywords from the manifest. */
"keywords": [
"cli"
],
/* The readme value from the manifest or null if not specified. */
"readme": "README.md",
/* The repository value from the manifest or null if not specified. */
"repository": "https://github.com/rust\-lang/cargo",
/* The homepage value from the manifest or null if not specified. */
"homepage": "https://rust\-lang.org",
/* The documentation value from the manifest or null if not specified. */
"documentation": "https://doc.rust\-lang.org/stable/std",
/* The default edition of the package.
Note that individual targets may have different editions.
*/
"edition": "2018",
/* Optional string that is the name of a native library the package
is linking to.
*/
"links": null,
}
],
/* Array of members of the workspace.
Each entry is the Package ID for the package.
*/
"workspace_members": [
"file:///path/to/my\-package#0.1.0",
],
/* Array of default members of the workspace.
Each entry is the Package ID for the package.
*/
"workspace_default_members": [
"file:///path/to/my\-package#0.1.0",
],
// The resolved dependency graph for the entire workspace. The enabled
// features are based on the enabled features for the "current" package.
// Inactivated optional dependencies are not listed.
//
// This is null if \-\-no\-deps is specified.
//
// By default, this includes all dependencies for all target platforms.
// The `\-\-filter\-platform` flag may be used to narrow to a specific
// target triple.
"resolve": {
/* Array of nodes within the dependency graph.
Each node is a package.
*/
"nodes": [
{
/* The Package ID of this node. */
"id": "file:///path/to/my\-package#0.1.0",
/* The dependencies of this package, an array of Package IDs. */
"dependencies": [
"https://github.com/rust\-lang/crates.io\-index#bitflags@1.0.4"
],
/* The dependencies of this package. This is an alternative to
"dependencies" which contains additional information. In
particular, this handles renamed dependencies.
*/
"deps": [
{
/* The name of the dependency's library target.
If this is a renamed dependency, this is the new
name.
*/
"name": "bitflags",
/* The Package ID of the dependency. */
"pkg": "https://github.com/rust\-lang/crates.io\-index#bitflags@1.0.4"
/* Array of dependency kinds. Added in Cargo 1.40. */
"dep_kinds": [
{
/* The dependency kind.
"dev", "build", or null for a normal dependency.
*/
"kind": null,
/* The target platform for the dependency.
null if not a target dependency.
*/
"target": "cfg(windows)"
}
]
}
],
/* Array of features enabled on this package. */
"features": [
"default"
]
}
],
/* The root package of the workspace.
This is null if this is a virtual workspace. Otherwise it is
the Package ID of the root package.
*/
"root": "file:///path/to/my\-package#0.1.0",
},
/* The absolute path to the build directory where Cargo places its output. */
"target_directory": "/path/to/my\-package/target",
/* The version of the schema for this metadata structure.
This will be changed if incompatible changes are ever made.
*/
"version": 1,
/* The absolute path to the root of the workspace. */
"workspace_root": "/path/to/my\-package"
/* Workspace metadata.
This is null if no metadata is specified. */
"metadata": {
"docs": {
"rs": {
"all\-features": true
}
}
}
}
.fi
.RE
.sp
Notes:
.sp
.RS 4
\h'-04'\(bu\h'+02'For \fB"id"\fR field syntax, see \fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html> in the reference.
.RE
.SH "OPTIONS"
.SS "Output Options"
.sp
\fB\-\-no\-deps\fR
.RS 4
Output information only about the workspace members and don\[cq]t fetch
dependencies.
.RE
.sp
\fB\-\-format\-version\fR \fIversion\fR
.RS 4
Specify the version of the output format to use. Currently \fB1\fR is the only
possible value.
.RE
.sp
\fB\-\-filter\-platform\fR \fItriple\fR
.RS 4
This filters the \fBresolve\fR output to only include dependencies for the
given \fItarget triple\fR <https://doc.rust\-lang.org/cargo/appendix/glossary.html#target>\&.
Without this flag, the resolve includes all targets.
.sp
Note that the dependencies listed in the \[lq]packages\[rq] array still includes all
dependencies. Each package definition is intended to be an unaltered
reproduction of the information within \fBCargo.toml\fR\&.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Output JSON about the current package:
.sp
.RS 4
.nf
cargo metadata \-\-format\-version=1
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-pkgid\fR(1), \fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html>, \fIJSON messages\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>

166
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-new.1 Normal file
View File

@ -0,0 +1,166 @@
'\" t
.TH "CARGO\-NEW" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-new \[em] Create a new Cargo package
.SH "SYNOPSIS"
\fBcargo new\fR [\fIoptions\fR] \fIpath\fR
.SH "DESCRIPTION"
This command will create a new Cargo package in the given directory. This
includes a simple template with a \fBCargo.toml\fR manifest, sample source file,
and a VCS ignore file. If the directory is not already in a VCS repository,
then a new repository is created (see \fB\-\-vcs\fR below).
.sp
See \fBcargo\-init\fR(1) for a similar command which will create a new manifest
in an existing directory.
.SH "OPTIONS"
.SS "New Options"
.sp
\fB\-\-bin\fR
.RS 4
Create a package with a binary target (\fBsrc/main.rs\fR).
This is the default behavior.
.RE
.sp
\fB\-\-lib\fR
.RS 4
Create a package with a library target (\fBsrc/lib.rs\fR).
.RE
.sp
\fB\-\-edition\fR \fIedition\fR
.RS 4
Specify the Rust edition to use. Default is 2021.
Possible values: 2015, 2018, 2021, 2024
.RE
.sp
\fB\-\-name\fR \fIname\fR
.RS 4
Set the package name. Defaults to the directory name.
.RE
.sp
\fB\-\-vcs\fR \fIvcs\fR
.RS 4
Initialize a new VCS repository for the given version control system (git,
hg, pijul, or fossil) or do not initialize any version control at all
(none). If not specified, defaults to \fBgit\fR or the configuration value
\fBcargo\-new.vcs\fR, or \fBnone\fR if already inside a VCS repository.
.RE
.sp
\fB\-\-registry\fR \fIregistry\fR
.RS 4
This sets the \fBpublish\fR field in \fBCargo.toml\fR to the given registry name
which will restrict publishing only to that registry.
.sp
Registry names are defined in \fICargo config files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
If not specified, the default registry defined by the \fBregistry.default\fR
config key is used. If the default registry is not set and \fB\-\-registry\fR is not
used, the \fBpublish\fR field will not be set which means that publishing will not
be restricted.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Create a binary Cargo package in the given directory:
.sp
.RS 4
.nf
cargo new foo
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-init\fR(1)

197
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-owner.1 Normal file
View File

@ -0,0 +1,197 @@
'\" t
.TH "CARGO\-OWNER" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-owner \[em] Manage the owners of a crate on the registry
.SH "SYNOPSIS"
\fBcargo owner\fR [\fIoptions\fR] \fB\-\-add\fR \fIlogin\fR [\fIcrate\fR]
.br
\fBcargo owner\fR [\fIoptions\fR] \fB\-\-remove\fR \fIlogin\fR [\fIcrate\fR]
.br
\fBcargo owner\fR [\fIoptions\fR] \fB\-\-list\fR [\fIcrate\fR]
.SH "DESCRIPTION"
This command will modify the owners for a crate on the registry. Owners of a
crate can upload new versions and yank old versions. Non\-team owners can also
modify the set of owners, so take care!
.sp
This command requires you to be authenticated with either the \fB\-\-token\fR option
or using \fBcargo\-login\fR(1).
.sp
If the crate name is not specified, it will use the package name from the
current directory.
.sp
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/publishing.html#cargo\-owner> for more
information about owners and publishing.
.SH "OPTIONS"
.SS "Owner Options"
.sp
\fB\-a\fR,
\fB\-\-add\fR \fIlogin\fR\[u2026]
.RS 4
Invite the given user or team as an owner.
.RE
.sp
\fB\-r\fR,
\fB\-\-remove\fR \fIlogin\fR\[u2026]
.RS 4
Remove the given user or team as an owner.
.RE
.sp
\fB\-l\fR,
\fB\-\-list\fR
.RS 4
List owners of a crate.
.RE
.sp
\fB\-\-token\fR \fItoken\fR
.RS 4
API token to use when authenticating. This overrides the token stored in
the credentials file (which is created by \fBcargo\-login\fR(1)).
.sp
\fICargo config\fR <https://doc.rust\-lang.org/cargo/reference/config.html> environment variables can be
used to override the tokens stored in the credentials file. The token for
crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fR environment
variable. Tokens for other registries may be specified with environment
variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name
of the registry in all capital letters.
.RE
.sp
\fB\-\-index\fR \fIindex\fR
.RS 4
The URL of the registry index to use.
.RE
.sp
\fB\-\-registry\fR \fIregistry\fR
.RS 4
Name of the registry to use. Registry names are defined in \fICargo config
files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used,
which is defined by the \fBregistry.default\fR config key which defaults to
\fBcrates\-io\fR\&.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'List owners of a package:
.sp
.RS 4
.nf
cargo owner \-\-list foo
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Invite an owner to a package:
.sp
.RS 4
.nf
cargo owner \-\-add username foo
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Remove an owner from a package:
.sp
.RS 4
.nf
cargo owner \-\-remove username foo
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-login\fR(1), \fBcargo\-publish\fR(1)

367
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-package.1 Normal file
View File

@ -0,0 +1,367 @@
'\" t
.TH "CARGO\-PACKAGE" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-package \[em] Assemble the local package into a distributable tarball
.SH "SYNOPSIS"
\fBcargo package\fR [\fIoptions\fR]
.SH "DESCRIPTION"
This command will create a distributable, compressed \fB\&.crate\fR file with the
source code of the package in the current directory. The resulting file will
be stored in the \fBtarget/package\fR directory. This performs the following
steps:
.sp
.RS 4
\h'-04' 1.\h'+01'Load and check the current workspace, performing some basic checks.
.sp
.RS 4
\h'-04'\(bu\h'+02'Path dependencies are not allowed unless they have a version key. Cargo
will ignore the path key for dependencies in published packages.
\fBdev\-dependencies\fR do not have this restriction.
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Create the compressed \fB\&.crate\fR file.
.sp
.RS 4
\h'-04'\(bu\h'+02'The original \fBCargo.toml\fR file is rewritten and normalized.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB[patch]\fR, \fB[replace]\fR, and \fB[workspace]\fR sections are removed from the
manifest.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBCargo.lock\fR is automatically included if the package contains an
executable binary or example target. \fBcargo\-install\fR(1) will use the
packaged lock file if the \fB\-\-locked\fR flag is used.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'A \fB\&.cargo_vcs_info.json\fR file is included that contains information
about the current VCS checkout hash if available (not included with
\fB\-\-allow\-dirty\fR).
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Extract the \fB\&.crate\fR file and build it to verify it can build.
.sp
.RS 4
\h'-04'\(bu\h'+02'This will rebuild your package from scratch to ensure that it can be
built from a pristine state. The \fB\-\-no\-verify\fR flag can be used to skip
this step.
.RE
.RE
.sp
.RS 4
\h'-04' 4.\h'+01'Check that build scripts did not modify any source files.
.RE
.sp
The list of files included can be controlled with the \fBinclude\fR and \fBexclude\fR
fields in the manifest.
.sp
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/publishing.html> for more details about
packaging and publishing.
.SS ".cargo_vcs_info.json format"
Will generate a \fB\&.cargo_vcs_info.json\fR in the following format
.sp
.RS 4
.nf
{
"git": {
"sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302"
},
"path_in_vcs": ""
}
.fi
.RE
.sp
\fBpath_in_vcs\fR will be set to a repo\-relative path for packages
in subdirectories of the version control repository.
.SH "OPTIONS"
.SS "Package Options"
.sp
\fB\-l\fR,
\fB\-\-list\fR
.RS 4
Print files included in a package without making one.
.RE
.sp
\fB\-\-no\-verify\fR
.RS 4
Don\[cq]t verify the contents by building them.
.RE
.sp
\fB\-\-no\-metadata\fR
.RS 4
Ignore warnings about a lack of human\-usable metadata (such as the description
or the license).
.RE
.sp
\fB\-\-allow\-dirty\fR
.RS 4
Allow working directories with uncommitted VCS changes to be packaged.
.RE
.SS "Package Selection"
By default, when no package selection options are given, the packages selected
depend on the selected manifest file (based on the current working directory if
\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then
the workspaces default members are selected, otherwise only the package defined
by the manifest will be selected.
.sp
The default members of a workspace can be set explicitly with the
\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a
virtual workspace will include all workspace members (equivalent to passing
\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself.
.sp
\fB\-p\fR \fIspec\fR\[u2026],
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Package only the specified packages. See \fBcargo\-pkgid\fR(1) for the
SPEC format. This flag may be specified multiple times and supports common Unix
glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally
expanding glob patterns before Cargo handles them, you must use single quotes or
double quotes around each pattern.
.RE
.sp
\fB\-\-workspace\fR
.RS 4
Package all members in the workspace.
.RE
.sp
\fB\-\-exclude\fR \fISPEC\fR\[u2026]
.RS 4
Exclude the specified packages. Must be used in conjunction with the
\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports
common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell
accidentally expanding glob patterns before Cargo handles them, you must use
single quotes or double quotes around each pattern.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Package for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Miscellaneous Options"
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
\fB\-\-keep\-going\fR
.RS 4
Build as many crates in the dependency graph as possible, rather than aborting
the build on the first one that fails to build.
.sp
For example if the current package depends on dependencies \fBfails\fR and \fBworks\fR,
one of which fails to build, \fBcargo package \-j1\fR may or may not build the
one that succeeds (depending on which one of the two builds Cargo picked to run
first), whereas \fBcargo package \-j1 \-\-keep\-going\fR would definitely run both
builds, even if the one run first fails.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Create a compressed \fB\&.crate\fR file of the current package:
.sp
.RS 4
.nf
cargo package
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-publish\fR(1)

258
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-pkgid.1 Normal file
View File

@ -0,0 +1,258 @@
'\" t
.TH "CARGO\-PKGID" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-pkgid \[em] Print a fully qualified package specification
.SH "SYNOPSIS"
\fBcargo pkgid\fR [\fIoptions\fR] [\fIspec\fR]
.SH "DESCRIPTION"
Given a \fIspec\fR argument, print out the fully qualified package ID specifier
for a package or dependency in the current workspace. This command will
generate an error if \fIspec\fR is ambiguous as to which package it refers to in
the dependency graph. If no \fIspec\fR is given, then the specifier for the local
package is printed.
.sp
This command requires that a lockfile is available and dependencies have been
fetched.
.sp
A package specifier consists of a name, version, and source URL. You are
allowed to use partial specifiers to succinctly match a specific package as
long as it matches only one package. This specifier is also used by other parts
in Cargo, such as \fBcargo\-metadata\fR(1) and \fIJSON messages\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> emitted by Cargo.
.sp
The format of a \fIspec\fR can be one of the following:
.TS
allbox tab(:);
lt lt.
T{
SPEC Structure
T}:T{
Example SPEC
T}
T{
\fIname\fR
T}:T{
\fBbitflags\fR
T}
T{
\fIname\fR\fB@\fR\fIversion\fR
T}:T{
\fBbitflags@1.0.4\fR
T}
T{
\fIurl\fR
T}:T{
\fBhttps://github.com/rust\-lang/cargo\fR
T}
T{
\fIurl\fR\fB#\fR\fIversion\fR
T}:T{
\fBhttps://github.com/rust\-lang/cargo#0.33.0\fR
T}
T{
\fIurl\fR\fB#\fR\fIname\fR
T}:T{
\fBhttps://github.com/rust\-lang/crates.io\-index#bitflags\fR
T}
T{
\fIurl\fR\fB#\fR\fIname\fR\fB@\fR\fIversion\fR
T}:T{
\fBhttps://github.com/rust\-lang/cargo#crates\-io@0.21.0\fR
T}
.TE
.sp
.sp
The specification grammar can be found in chapter \fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html>\&.
.SH "OPTIONS"
.SS "Package Selection"
.sp
\fB\-p\fR \fIspec\fR,
\fB\-\-package\fR \fIspec\fR
.RS 4
Get the package ID for the given package instead of the current package.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Retrieve package specification for \fBfoo\fR package:
.sp
.RS 4
.nf
cargo pkgid foo
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Retrieve package specification for version 1.0.0 of \fBfoo\fR:
.sp
.RS 4
.nf
cargo pkgid foo@1.0.0
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Retrieve package specification for \fBfoo\fR from crates.io:
.sp
.RS 4
.nf
cargo pkgid https://github.com/rust\-lang/crates.io\-index#foo
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 4.\h'+01'Retrieve package specification for \fBfoo\fR from a local package:
.sp
.RS 4
.nf
cargo pkgid file:///path/to/local/package#foo
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1), \fBcargo\-metadata\fR(1),
\fIPackage ID Specifications\fR <https://doc.rust\-lang.org/cargo/reference/pkgid\-spec.html>, \fIJSON messages\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>

323
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-publish.1 Normal file
View File

@ -0,0 +1,323 @@
'\" t
.TH "CARGO\-PUBLISH" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-publish \[em] Upload a package to the registry
.SH "SYNOPSIS"
\fBcargo publish\fR [\fIoptions\fR]
.SH "DESCRIPTION"
This command will create a distributable, compressed \fB\&.crate\fR file with the
source code of the package in the current directory and upload it to a
registry. The default registry is <https://crates.io>\&. This performs the
following steps:
.sp
.RS 4
\h'-04' 1.\h'+01'Performs a few checks, including:
.sp
.RS 4
\h'-04'\(bu\h'+02'Checks the \fBpackage.publish\fR key in the manifest for restrictions on
which registries you are allowed to publish to.
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Create a \fB\&.crate\fR file by following the steps in \fBcargo\-package\fR(1).
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Upload the crate to the registry. The server will perform additional
checks on the crate.
.RE
.sp
.RS 4
\h'-04' 4.\h'+01'The client will poll waiting for the package to appear in the index,
and may timeout. In that case, you will need to check for completion
manually. This timeout does not affect the upload.
.RE
.sp
This command requires you to be authenticated with either the \fB\-\-token\fR option
or using \fBcargo\-login\fR(1).
.sp
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/publishing.html> for more details about
packaging and publishing.
.SH "OPTIONS"
.SS "Publish Options"
.sp
\fB\-\-dry\-run\fR
.RS 4
Perform all checks without uploading.
.RE
.sp
\fB\-\-token\fR \fItoken\fR
.RS 4
API token to use when authenticating. This overrides the token stored in
the credentials file (which is created by \fBcargo\-login\fR(1)).
.sp
\fICargo config\fR <https://doc.rust\-lang.org/cargo/reference/config.html> environment variables can be
used to override the tokens stored in the credentials file. The token for
crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fR environment
variable. Tokens for other registries may be specified with environment
variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name
of the registry in all capital letters.
.RE
.sp
\fB\-\-no\-verify\fR
.RS 4
Don\[cq]t verify the contents by building them.
.RE
.sp
\fB\-\-allow\-dirty\fR
.RS 4
Allow working directories with uncommitted VCS changes to be packaged.
.RE
.sp
\fB\-\-index\fR \fIindex\fR
.RS 4
The URL of the registry index to use.
.RE
.sp
\fB\-\-registry\fR \fIregistry\fR
.RS 4
Name of the registry to publish to. Registry names are defined in \fICargo
config files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, and there is a
\fI\f(BIpackage.publish\fI\fR <https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-publish\-field> field in
\fBCargo.toml\fR with a single registry, then it will publish to that registry.
Otherwise it will use the default registry, which is defined by the
\fI\f(BIregistry.default\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#registrydefault> config key
which defaults to \fBcrates\-io\fR\&.
.RE
.SS "Package Selection"
By default, the package in the current working directory is selected. The \fB\-p\fR
flag can be used to choose a different package in a workspace.
.sp
\fB\-p\fR \fIspec\fR,
\fB\-\-package\fR \fIspec\fR
.RS 4
The package to publish. See \fBcargo\-pkgid\fR(1) for the SPEC
format.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Publish for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Miscellaneous Options"
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
\fB\-\-keep\-going\fR
.RS 4
Build as many crates in the dependency graph as possible, rather than aborting
the build on the first one that fails to build.
.sp
For example if the current package depends on dependencies \fBfails\fR and \fBworks\fR,
one of which fails to build, \fBcargo publish \-j1\fR may or may not build the
one that succeeds (depending on which one of the two builds Cargo picked to run
first), whereas \fBcargo publish \-j1 \-\-keep\-going\fR would definitely run both
builds, even if the one run first fails.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Publish the current package:
.sp
.RS 4
.nf
cargo publish
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-package\fR(1), \fBcargo\-login\fR(1)

214
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-remove.1 Normal file
View File

@ -0,0 +1,214 @@
'\" t
.TH "CARGO\-REMOVE" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-remove \[em] Remove dependencies from a Cargo.toml manifest file
.SH "SYNOPSIS"
\fBcargo remove\fR [\fIoptions\fR] \fIdependency\fR\[u2026]
.SH "DESCRIPTION"
Remove one or more dependencies from a \fBCargo.toml\fR manifest.
.SH "OPTIONS"
.SS "Section options"
.sp
\fB\-\-dev\fR
.RS 4
Remove as a \fIdevelopment dependency\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#development\-dependencies>\&.
.RE
.sp
\fB\-\-build\fR
.RS 4
Remove as a \fIbuild dependency\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#build\-dependencies>\&.
.RE
.sp
\fB\-\-target\fR \fItarget\fR
.RS 4
Remove as a dependency to the \fIgiven target platform\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#platform\-specific\-dependencies>\&.
.sp
To avoid unexpected shell expansions, you may use quotes around each target, e.g., \fB\-\-target 'cfg(unix)'\fR\&.
.RE
.SS "Miscellaneous Options"
.sp
\fB\-\-dry\-run\fR
.RS 4
Don\[cq]t actually write to the manifest.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Package Selection"
.sp
\fB\-p\fR \fIspec\fR\[u2026],
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Package to remove from.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Remove \fBregex\fR as a dependency
.sp
.RS 4
.nf
cargo remove regex
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Remove \fBtrybuild\fR as a dev\-dependency
.sp
.RS 4
.nf
cargo remove \-\-dev trybuild
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Remove \fBnom\fR from the \fBx86_64\-pc\-windows\-gnu\fR dependencies table
.sp
.RS 4
.nf
cargo remove \-\-target x86_64\-pc\-windows\-gnu nom
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-add\fR(1)

48
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-report.1 Normal file
View File

@ -0,0 +1,48 @@
'\" t
.TH "CARGO\-REPORT" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-report \[em] Generate and display various kinds of reports
.SH "SYNOPSIS"
\fBcargo report\fR \fItype\fR [\fIoptions\fR]
.SS "DESCRIPTION"
Displays a report of the given \fItype\fR \[em] currently, only \fBfuture\-incompat\fR is supported
.SH "OPTIONS"
.sp
\fB\-\-id\fR \fIid\fR
.RS 4
Show the report with the specified Cargo\-generated id
.RE
.sp
\fB\-p\fR \fIspec\fR\[u2026],
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Only display a report for the specified package
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Display the latest future\-incompat report:
.sp
.RS 4
.nf
cargo report future\-incompat
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Display the latest future\-incompat report for a specific package:
.sp
.RS 4
.nf
cargo report future\-incompat \-\-package my\-dep:0.0.1
.fi
.RE
.RE
.SH "SEE ALSO"
\fIFuture incompat report\fR <https://doc.rust\-lang.org/cargo/reference/future\-incompat\-report.html>
.sp
\fBcargo\fR(1)

359
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-run.1 Normal file
View File

@ -0,0 +1,359 @@
'\" t
.TH "CARGO\-RUN" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-run \[em] Run the current package
.SH "SYNOPSIS"
\fBcargo run\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR]
.SH "DESCRIPTION"
Run a binary or example of the local package.
.sp
All the arguments following the two dashes (\fB\-\-\fR) are passed to the binary to
run. If you\[cq]re passing arguments to both Cargo and the binary, the ones after
\fB\-\-\fR go to the binary, the ones before go to Cargo.
.sp
Unlike \fBcargo\-test\fR(1) and \fBcargo\-bench\fR(1), \fBcargo run\fR sets the
working directory of the binary executed to the current working directory, same
as if it was executed in the shell directly.
.SH "OPTIONS"
.SS "Package Selection"
By default, the package in the current working directory is selected. The \fB\-p\fR
flag can be used to choose a different package in a workspace.
.sp
\fB\-p\fR \fIspec\fR,
\fB\-\-package\fR \fIspec\fR
.RS 4
The package to run. See \fBcargo\-pkgid\fR(1) for the SPEC
format.
.RE
.SS "Target Selection"
When no target selection options are given, \fBcargo run\fR will run the binary
target. If there are multiple binary targets, you must pass a target flag to
choose one. Or, the \fBdefault\-run\fR field may be specified in the \fB[package]\fR
section of \fBCargo.toml\fR to choose the name of the binary to run by default.
.sp
\fB\-\-bin\fR \fIname\fR
.RS 4
Run the specified binary.
.RE
.sp
\fB\-\-example\fR \fIname\fR
.RS 4
Run the specified example.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Run for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-r\fR,
\fB\-\-release\fR
.RS 4
Run optimized artifacts with the \fBrelease\fR profile.
See also the \fB\-\-profile\fR option for choosing a specific profile by name.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
Run with the given profile.
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
.RE
.sp
\fB\-\-timings=\fR\fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&.
Specifying an output format (rather than the default) is unstable and requires
\fB\-Zunstable\-options\fR\&. Valid output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the
\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write
a report to the same directory with a timestamp in the filename if you want
to look at older runs. HTML output is suitable for human consumption only,
and does not provide machine\-readable timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
The output format for diagnostic messages. Can be specified multiple times
and consists of comma\-separated values. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with
\fBshort\fR and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR
and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See
\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains
the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages
contains embedded ANSI color codes for respecting rustc\[cq]s default color
scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics
in JSON messages printed, but instead Cargo itself should render the
JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others
coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SS "Miscellaneous Options"
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
\fB\-\-keep\-going\fR
.RS 4
Build as many crates in the dependency graph as possible, rather than aborting
the build on the first one that fails to build.
.sp
For example if the current package depends on dependencies \fBfails\fR and \fBworks\fR,
one of which fails to build, \fBcargo run \-j1\fR may or may not build the
one that succeeds (depending on which one of the two builds Cargo picked to run
first), whereas \fBcargo run \-j1 \-\-keep\-going\fR would definitely run both
builds, even if the one run first fails.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Build the local package and run its main target (assuming only one binary):
.sp
.RS 4
.nf
cargo run
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Run an example with extra arguments:
.sp
.RS 4
.nf
cargo run \-\-example exname \-\- \-\-exoption exarg1 exarg2
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-build\fR(1)

492
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-rustc.1 Normal file
View File

@ -0,0 +1,492 @@
'\" t
.TH "CARGO\-RUSTC" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-rustc \[em] Compile the current package, and pass extra options to the compiler
.SH "SYNOPSIS"
\fBcargo rustc\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR]
.SH "DESCRIPTION"
The specified target for the current package (or package specified by \fB\-p\fR if
provided) will be compiled along with all of its dependencies. The specified
\fIargs\fR will all be passed to the final compiler invocation, not any of the
dependencies. Note that the compiler will still unconditionally receive
arguments such as \fB\-L\fR, \fB\-\-extern\fR, and \fB\-\-crate\-type\fR, and the specified
\fIargs\fR will simply be added to the compiler invocation.
.sp
See <https://doc.rust\-lang.org/rustc/index.html> for documentation on rustc
flags.
.sp
This command requires that only one target is being compiled when additional
arguments are provided. If more than one target is available for the current
package the filters of \fB\-\-lib\fR, \fB\-\-bin\fR, etc, must be used to select which
target is compiled.
.sp
To pass flags to all compiler processes spawned by Cargo, use the \fBRUSTFLAGS\fR
\fIenvironment variable\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> or the
\fBbuild.rustflags\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.SH "OPTIONS"
.SS "Package Selection"
By default, the package in the current working directory is selected. The \fB\-p\fR
flag can be used to choose a different package in a workspace.
.sp
\fB\-p\fR \fIspec\fR,
\fB\-\-package\fR \fIspec\fR
.RS 4
The package to build. See \fBcargo\-pkgid\fR(1) for the SPEC
format.
.RE
.SS "Target Selection"
When no target selection options are given, \fBcargo rustc\fR will build all
binary and library targets of the selected package.
.sp
Binary targets are automatically built if there is an integration test or
benchmark being selected to build. This allows an integration
test to execute the binary to exercise and test its behavior.
The \fBCARGO_BIN_EXE_<name>\fR
\fIenvironment variable\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html#environment\-variables\-cargo\-sets\-for\-crates>
is set when the integration test is built so that it can use the
\fI\f(BIenv\fI macro\fR <https://doc.rust\-lang.org/std/macro.env.html> to locate the
executable.
.sp
Passing target selection flags will build only the specified
targets.
.sp
Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also
support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your
shell accidentally expanding glob patterns before Cargo handles them, you must
use single quotes or double quotes around each glob pattern.
.sp
\fB\-\-lib\fR
.RS 4
Build the package\[cq]s library.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
Build the specified binary. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-bins\fR
.RS 4
Build all binary targets.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
.RS 4
Build the specified example. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-examples\fR
.RS 4
Build all example targets.
.RE
.sp
\fB\-\-test\fR \fIname\fR\[u2026]
.RS 4
Build the specified integration test. This flag may be specified
multiple times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-tests\fR
.RS 4
Build all targets in test mode that have the \fBtest = true\fR manifest
flag set. By default this includes the library and binaries built as
unittests, and integration tests. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
unittest, and once as a dependency for binaries, integration tests, etc.).
Targets may be enabled or disabled by setting the \fBtest\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-bench\fR \fIname\fR\[u2026]
.RS 4
Build the specified benchmark. This flag may be specified multiple
times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-benches\fR
.RS 4
Build all targets in benchmark mode that have the \fBbench = true\fR
manifest flag set. By default this includes the library and binaries built
as benchmarks, and bench targets. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
benchmark, and once as a dependency for binaries, benchmarks, etc.).
Targets may be enabled or disabled by setting the \fBbench\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-all\-targets\fR
.RS 4
Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Build for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-r\fR,
\fB\-\-release\fR
.RS 4
Build optimized artifacts with the \fBrelease\fR profile.
See also the \fB\-\-profile\fR option for choosing a specific profile by name.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
Build with the given profile.
.sp
The \fBrustc\fR subcommand will treat the following named profiles with special behaviors:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBcheck\fR \[em] Builds in the same way as the \fBcargo\-check\fR(1) command with
the \fBdev\fR profile.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBtest\fR \[em] Builds in the same way as the \fBcargo\-test\fR(1) command,
enabling building in test mode which will enable tests and enable the \fBtest\fR
cfg option. See \fIrustc
tests\fR <https://doc.rust\-lang.org/rustc/tests/index.html> for more detail.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBbench\fR \[em] Builds in the same was as the \fBcargo\-bench\fR(1) command,
similar to the \fBtest\fR profile.
.RE
.sp
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
.RE
.sp
\fB\-\-timings=\fR\fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&.
Specifying an output format (rather than the default) is unstable and requires
\fB\-Zunstable\-options\fR\&. Valid output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the
\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write
a report to the same directory with a timestamp in the filename if you want
to look at older runs. HTML output is suitable for human consumption only,
and does not provide machine\-readable timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.sp
\fB\-\-crate\-type\fR \fIcrate\-type\fR
.RS 4
Build for the given crate type. This flag accepts a comma\-separated list of
1 or more crate types, of which the allowed values are the same as \fBcrate\-type\fR
field in the manifest for configuring a Cargo target. See
\fI\f(BIcrate\-type\fI field\fR <https://doc.rust\-lang.org/cargo/reference/cargo\-targets.html#the\-crate\-type\-field>
for possible values.
.sp
If the manifest contains a list, and \fB\-\-crate\-type\fR is provided,
the command\-line argument value will override what is in the manifest.
.sp
This flag only works when building a \fBlib\fR or \fBexample\fR library target.
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
The output format for diagnostic messages. Can be specified multiple times
and consists of comma\-separated values. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with
\fBshort\fR and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR
and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See
\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains
the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages
contains embedded ANSI color codes for respecting rustc\[cq]s default color
scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics
in JSON messages printed, but instead Cargo itself should render the
JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others
coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SS "Miscellaneous Options"
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
\fB\-\-keep\-going\fR
.RS 4
Build as many crates in the dependency graph as possible, rather than aborting
the build on the first one that fails to build.
.sp
For example if the current package depends on dependencies \fBfails\fR and \fBworks\fR,
one of which fails to build, \fBcargo rustc \-j1\fR may or may not build the
one that succeeds (depending on which one of the two builds Cargo picked to run
first), whereas \fBcargo rustc \-j1 \-\-keep\-going\fR would definitely run both
builds, even if the one run first fails.
.RE
.sp
\fB\-\-future\-incompat\-report\fR
.RS 4
Displays a future\-incompat report for any future\-incompatible warnings
produced during execution of this command
.sp
See \fBcargo\-report\fR(1)
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Check if your package (not including dependencies) uses unsafe code:
.sp
.RS 4
.nf
cargo rustc \-\-lib \-\- \-D unsafe\-code
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Try an experimental flag on the nightly compiler, such as this which prints
the size of every type:
.sp
.RS 4
.nf
cargo rustc \-\-lib \-\- \-Z print\-type\-sizes
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Override \fBcrate\-type\fR field in Cargo.toml with command\-line option:
.sp
.RS 4
.nf
cargo rustc \-\-lib \-\-crate\-type lib,cdylib
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-build\fR(1), \fBrustc\fR(1)

447
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-rustdoc.1 Normal file
View File

@ -0,0 +1,447 @@
'\" t
.TH "CARGO\-RUSTDOC" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-rustdoc \[em] Build a package\[cq]s documentation, using specified custom flags
.SH "SYNOPSIS"
\fBcargo rustdoc\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR]
.SH "DESCRIPTION"
The specified target for the current package (or package specified by \fB\-p\fR if
provided) will be documented with the specified \fIargs\fR being passed to the
final rustdoc invocation. Dependencies will not be documented as part of this
command. Note that rustdoc will still unconditionally receive arguments such
as \fB\-L\fR, \fB\-\-extern\fR, and \fB\-\-crate\-type\fR, and the specified \fIargs\fR will simply
be added to the rustdoc invocation.
.sp
See <https://doc.rust\-lang.org/rustdoc/index.html> for documentation on rustdoc
flags.
.sp
This command requires that only one target is being compiled when additional
arguments are provided. If more than one target is available for the current
package the filters of \fB\-\-lib\fR, \fB\-\-bin\fR, etc, must be used to select which
target is compiled.
.sp
To pass flags to all rustdoc processes spawned by Cargo, use the
\fBRUSTDOCFLAGS\fR \fIenvironment variable\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html>
or the \fBbuild.rustdocflags\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.SH "OPTIONS"
.SS "Documentation Options"
.sp
\fB\-\-open\fR
.RS 4
Open the docs in a browser after building them. This will use your default
browser unless you define another one in the \fBBROWSER\fR environment variable
or use the \fI\f(BIdoc.browser\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#docbrowser> configuration
option.
.RE
.SS "Package Selection"
By default, the package in the current working directory is selected. The \fB\-p\fR
flag can be used to choose a different package in a workspace.
.sp
\fB\-p\fR \fIspec\fR,
\fB\-\-package\fR \fIspec\fR
.RS 4
The package to document. See \fBcargo\-pkgid\fR(1) for the SPEC
format.
.RE
.SS "Target Selection"
When no target selection options are given, \fBcargo rustdoc\fR will document all
binary and library targets of the selected package. The binary will be skipped
if its name is the same as the lib target. Binaries are skipped if they have
\fBrequired\-features\fR that are missing.
.sp
Passing target selection flags will document only the specified
targets.
.sp
Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also
support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your
shell accidentally expanding glob patterns before Cargo handles them, you must
use single quotes or double quotes around each glob pattern.
.sp
\fB\-\-lib\fR
.RS 4
Document the package\[cq]s library.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
Document the specified binary. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-bins\fR
.RS 4
Document all binary targets.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
.RS 4
Document the specified example. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-examples\fR
.RS 4
Document all example targets.
.RE
.sp
\fB\-\-test\fR \fIname\fR\[u2026]
.RS 4
Document the specified integration test. This flag may be specified
multiple times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-tests\fR
.RS 4
Document all targets in test mode that have the \fBtest = true\fR manifest
flag set. By default this includes the library and binaries built as
unittests, and integration tests. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
unittest, and once as a dependency for binaries, integration tests, etc.).
Targets may be enabled or disabled by setting the \fBtest\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-bench\fR \fIname\fR\[u2026]
.RS 4
Document the specified benchmark. This flag may be specified multiple
times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-benches\fR
.RS 4
Document all targets in benchmark mode that have the \fBbench = true\fR
manifest flag set. By default this includes the library and binaries built
as benchmarks, and bench targets. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
benchmark, and once as a dependency for binaries, benchmarks, etc.).
Targets may be enabled or disabled by setting the \fBbench\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-all\-targets\fR
.RS 4
Document all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Document for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-r\fR,
\fB\-\-release\fR
.RS 4
Document optimized artifacts with the \fBrelease\fR profile.
See also the \fB\-\-profile\fR option for choosing a specific profile by name.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
Document with the given profile.
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
.RE
.sp
\fB\-\-timings=\fR\fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&.
Specifying an output format (rather than the default) is unstable and requires
\fB\-Zunstable\-options\fR\&. Valid output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the
\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write
a report to the same directory with a timestamp in the filename if you want
to look at older runs. HTML output is suitable for human consumption only,
and does not provide machine\-readable timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
The output format for diagnostic messages. Can be specified multiple times
and consists of comma\-separated values. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with
\fBshort\fR and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR
and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See
\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains
the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages
contains embedded ANSI color codes for respecting rustc\[cq]s default color
scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics
in JSON messages printed, but instead Cargo itself should render the
JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others
coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SS "Miscellaneous Options"
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
\fB\-\-keep\-going\fR
.RS 4
Build as many crates in the dependency graph as possible, rather than aborting
the build on the first one that fails to build.
.sp
For example if the current package depends on dependencies \fBfails\fR and \fBworks\fR,
one of which fails to build, \fBcargo rustdoc \-j1\fR may or may not build the
one that succeeds (depending on which one of the two builds Cargo picked to run
first), whereas \fBcargo rustdoc \-j1 \-\-keep\-going\fR would definitely run both
builds, even if the one run first fails.
.RE
.sp
\fB\-\-output\-format\fR
.RS 4
The output type for the documentation emitted. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR (default): Emit the documentation in HTML format.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR: Emit the documentation in the \fIexperimental JSON format\fR <https://doc.rust\-lang.org/nightly/nightly\-rustc/rustdoc_json_types>\&.
.RE
.sp
This option is only available on the \fInightly channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
and requires the \fB\-Z unstable\-options\fR flag to enable.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Build documentation with custom CSS included from a given file:
.sp
.RS 4
.nf
cargo rustdoc \-\-lib \-\- \-\-extend\-css extra.css
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-doc\fR(1), \fBrustdoc\fR(1)

138
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-search.1 Normal file
View File

@ -0,0 +1,138 @@
'\" t
.TH "CARGO\-SEARCH" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-search \[em] Search packages in the registry. Default registry is crates.io
.SH "SYNOPSIS"
\fBcargo search\fR [\fIoptions\fR] [\fIquery\fR\[u2026]]
.SH "DESCRIPTION"
This performs a textual search for crates on <https://crates.io>\&. The matching
crates will be displayed along with their description in TOML format suitable
for copying into a \fBCargo.toml\fR manifest.
.SH "OPTIONS"
.SS "Search Options"
.sp
\fB\-\-limit\fR \fIlimit\fR
.RS 4
Limit the number of results (default: 10, max: 100).
.RE
.sp
\fB\-\-index\fR \fIindex\fR
.RS 4
The URL of the registry index to use.
.RE
.sp
\fB\-\-registry\fR \fIregistry\fR
.RS 4
Name of the registry to use. Registry names are defined in \fICargo config
files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used,
which is defined by the \fBregistry.default\fR config key which defaults to
\fBcrates\-io\fR\&.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Search for a package from crates.io:
.sp
.RS 4
.nf
cargo search serde
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-install\fR(1), \fBcargo\-publish\fR(1)

610
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-test.1 Normal file
View File

@ -0,0 +1,610 @@
'\" t
.TH "CARGO\-TEST" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-test \[em] Execute unit and integration tests of a package
.SH "SYNOPSIS"
\fBcargo test\fR [\fIoptions\fR] [\fItestname\fR] [\fB\-\-\fR \fItest\-options\fR]
.SH "DESCRIPTION"
Compile and execute unit, integration, and documentation tests.
.sp
The test filtering argument \fBTESTNAME\fR and all the arguments following the two
dashes (\fB\-\-\fR) are passed to the test binaries and thus to \fIlibtest\fR (rustc\[cq]s
built in unit\-test and micro\-benchmarking framework). If you\[cq]re passing
arguments to both Cargo and the binary, the ones after \fB\-\-\fR go to the binary,
the ones before go to Cargo. For details about libtest\[cq]s arguments see the
output of \fBcargo test \-\- \-\-help\fR and check out the rustc book\[cq]s chapter on
how tests work at <https://doc.rust\-lang.org/rustc/tests/index.html>\&.
.sp
As an example, this will filter for tests with \fBfoo\fR in their name and run them
on 3 threads in parallel:
.sp
.RS 4
.nf
cargo test foo \-\- \-\-test\-threads 3
.fi
.RE
.sp
Tests are built with the \fB\-\-test\fR option to \fBrustc\fR which creates a special
executable by linking your code with libtest. The executable automatically
runs all functions annotated with the \fB#[test]\fR attribute in multiple threads.
\fB#[bench]\fR annotated functions will also be run with one iteration to verify
that they are functional.
.sp
If the package contains multiple test targets, each target compiles to a
special executable as aforementioned, and then is run serially.
.sp
The libtest harness may be disabled by setting \fBharness = false\fR in the target
manifest settings, in which case your code will need to provide its own \fBmain\fR
function to handle running tests.
.SS "Documentation tests"
Documentation tests are also run by default, which is handled by \fBrustdoc\fR\&. It
extracts code samples from documentation comments of the library target, and
then executes them.
.sp
Different from normal test targets, each code block compiles to a doctest
executable on the fly with \fBrustc\fR\&. These executables run in parallel in
separate processes. The compilation of a code block is in fact a part of test
function controlled by libtest, so some options such as \fB\-\-jobs\fR might not
take effect. Note that this execution model of doctests is not guaranteed
and may change in the future; beware of depending on it.
.sp
See the \fIrustdoc book\fR <https://doc.rust\-lang.org/rustdoc/> for more information
on writing doc tests.
.SS "Working directory of tests"
The working directory when running each unit and integration test is set to the
root directory of the package the test belongs to.
Setting the working directory of tests to the package\[cq]s root directory makes it
possible for tests to reliably access the package\[cq]s files using relative paths,
regardless from where \fBcargo test\fR was executed from.
.sp
For documentation tests, the working directory when invoking \fBrustdoc\fR is set to
the workspace root directory, and is also the directory \fBrustdoc\fR uses as the
compilation directory of each documentation test.
The working directory when running each documentation test is set to the root
directory of the package the test belongs to, and is controlled via \fBrustdoc\fR\[cq]s
\fB\-\-test\-run\-directory\fR option.
.SH "OPTIONS"
.SS "Test Options"
.sp
\fB\-\-no\-run\fR
.RS 4
Compile, but don\[cq]t run tests.
.RE
.sp
\fB\-\-no\-fail\-fast\fR
.RS 4
Run all tests regardless of failure. Without this flag, Cargo will exit
after the first executable fails. The Rust test harness will run all tests
within the executable to completion, this flag only applies to the executable
as a whole.
.RE
.SS "Package Selection"
By default, when no package selection options are given, the packages selected
depend on the selected manifest file (based on the current working directory if
\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then
the workspaces default members are selected, otherwise only the package defined
by the manifest will be selected.
.sp
The default members of a workspace can be set explicitly with the
\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a
virtual workspace will include all workspace members (equivalent to passing
\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself.
.sp
\fB\-p\fR \fIspec\fR\[u2026],
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Test only the specified packages. See \fBcargo\-pkgid\fR(1) for the
SPEC format. This flag may be specified multiple times and supports common Unix
glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally
expanding glob patterns before Cargo handles them, you must use single quotes or
double quotes around each pattern.
.RE
.sp
\fB\-\-workspace\fR
.RS 4
Test all members in the workspace.
.RE
.sp
\fB\-\-all\fR
.RS 4
Deprecated alias for \fB\-\-workspace\fR\&.
.RE
.sp
\fB\-\-exclude\fR \fISPEC\fR\[u2026]
.RS 4
Exclude the specified packages. Must be used in conjunction with the
\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports
common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell
accidentally expanding glob patterns before Cargo handles them, you must use
single quotes or double quotes around each pattern.
.RE
.SS "Target Selection"
When no target selection options are given, \fBcargo test\fR will build the
following targets of the selected packages:
.sp
.RS 4
\h'-04'\(bu\h'+02'lib \[em] used to link with binaries, examples, integration tests, and doc tests
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'bins (only if integration tests are built and required features are
available)
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'examples \[em] to ensure they compile
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'lib as a unit test
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'bins as unit tests
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'integration tests
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'doc tests for the lib target
.RE
.sp
The default behavior can be changed by setting the \fBtest\fR flag for the target
in the manifest settings. Setting examples to \fBtest = true\fR will build and run
the example as a test, replacing the example\[cq]s \fBmain\fR function with the
libtest harness. If you don\[cq]t want the \fBmain\fR function replaced, also include
\fBharness = false\fR, in which case the example will be built and executed as\-is.
.sp
Setting targets to \fBtest = false\fR will stop them from being tested by default.
Target selection options that take a target by name (such as \fB\-\-example foo\fR)
ignore the \fBtest\fR flag and will always test the given target.
.sp
Doc tests for libraries may be disabled by setting \fBdoctest = false\fR for the
library in the manifest.
.sp
See \fIConfiguring a target\fR <https://doc.rust\-lang.org/cargo/reference/cargo\-targets.html#configuring\-a\-target>
for more information on per\-target settings.
.sp
Binary targets are automatically built if there is an integration test or
benchmark being selected to test. This allows an integration
test to execute the binary to exercise and test its behavior.
The \fBCARGO_BIN_EXE_<name>\fR
\fIenvironment variable\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html#environment\-variables\-cargo\-sets\-for\-crates>
is set when the integration test is built so that it can use the
\fI\f(BIenv\fI macro\fR <https://doc.rust\-lang.org/std/macro.env.html> to locate the
executable.
.sp
Passing target selection flags will test only the specified
targets.
.sp
Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also
support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your
shell accidentally expanding glob patterns before Cargo handles them, you must
use single quotes or double quotes around each glob pattern.
.sp
\fB\-\-lib\fR
.RS 4
Test the package\[cq]s library.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
Test the specified binary. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-bins\fR
.RS 4
Test all binary targets.
.RE
.sp
\fB\-\-example\fR \fIname\fR\[u2026]
.RS 4
Test the specified example. This flag may be specified multiple times
and supports common Unix glob patterns.
.RE
.sp
\fB\-\-examples\fR
.RS 4
Test all example targets.
.RE
.sp
\fB\-\-test\fR \fIname\fR\[u2026]
.RS 4
Test the specified integration test. This flag may be specified
multiple times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-tests\fR
.RS 4
Test all targets in test mode that have the \fBtest = true\fR manifest
flag set. By default this includes the library and binaries built as
unittests, and integration tests. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
unittest, and once as a dependency for binaries, integration tests, etc.).
Targets may be enabled or disabled by setting the \fBtest\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-bench\fR \fIname\fR\[u2026]
.RS 4
Test the specified benchmark. This flag may be specified multiple
times and supports common Unix glob patterns.
.RE
.sp
\fB\-\-benches\fR
.RS 4
Test all targets in benchmark mode that have the \fBbench = true\fR
manifest flag set. By default this includes the library and binaries built
as benchmarks, and bench targets. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
benchmark, and once as a dependency for binaries, benchmarks, etc.).
Targets may be enabled or disabled by setting the \fBbench\fR flag in the
manifest settings for the target.
.RE
.sp
\fB\-\-all\-targets\fR
.RS 4
Test all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&.
.RE
.sp
\fB\-\-doc\fR
.RS 4
Test only the library\[cq]s documentation. This cannot be mixed with other
target options.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Compilation Options"
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Test for the given architecture. The default is the host architecture. The general format of the triple is
\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a
list of supported targets. This flag may be specified multiple times.
.sp
This may also be specified with the \fBbuild.target\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.sp
Note that specifying this flag makes Cargo run in a different mode where the
target artifacts are placed in a separate directory. See the
\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
.RE
.sp
\fB\-r\fR,
\fB\-\-release\fR
.RS 4
Test optimized artifacts with the \fBrelease\fR profile.
See also the \fB\-\-profile\fR option for choosing a specific profile by name.
.RE
.sp
\fB\-\-profile\fR \fIname\fR
.RS 4
Test with the given profile.
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
.RE
.sp
\fB\-\-timings=\fR\fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&.
Specifying an output format (rather than the default) is unstable and requires
\fB\-Zunstable\-options\fR\&. Valid output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the
\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write
a report to the same directory with a timestamp in the filename if you want
to look at older runs. HTML output is suitable for human consumption only,
and does not provide machine\-readable timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR
.RS 4
Directory for all generated artifacts and intermediate files. May also be
specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the
\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
Defaults to \fBtarget\fR in the root of the workspace.
.RE
.SS "Display Options"
By default the Rust test harness hides output from test execution to keep
results readable. Test output can be recovered (e.g., for debugging) by passing
\fB\-\-nocapture\fR to the test binaries:
.sp
.RS 4
.nf
cargo test \-\- \-\-nocapture
.fi
.RE
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-message\-format\fR \fIfmt\fR
.RS 4
The output format for diagnostic messages. Can be specified multiple times
and consists of comma\-separated values. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with
\fBshort\fR and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR
and \fBjson\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See
\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages>
for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains
the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages
contains embedded ANSI color codes for respecting rustc\[cq]s default color
scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics
in JSON messages printed, but instead Cargo itself should render the
JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others
coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&.
.RE
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SS "Miscellaneous Options"
The \fB\-\-jobs\fR argument affects the building of the test executable but does not
affect how many threads are used when running the tests. The Rust test harness
includes an option to control the number of threads used:
.sp
.RS 4
.nf
cargo test \-j 2 \-\- \-\-test\-threads=2
.fi
.RE
.sp
\fB\-j\fR \fIN\fR,
\fB\-\-jobs\fR \fIN\fR
.RS 4
Number of parallel jobs to run. May also be specified with the
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
the number of logical CPUs. If negative, it sets the maximum number of
parallel jobs to the number of logical CPUs plus provided value. If
a string \fBdefault\fR is provided, it sets the value back to defaults.
Should not be 0.
.RE
.sp
\fB\-\-future\-incompat\-report\fR
.RS 4
Displays a future\-incompat report for any future\-incompatible warnings
produced during execution of this command
.sp
See \fBcargo\-report\fR(1)
.RE
.sp
While \fBcargo test\fR involves compilation, it does not provide a \fB\-\-keep\-going\fR
flag. Use \fB\-\-no\-fail\-fast\fR to run as many tests as possible without stopping at
the first failure. To \[lq]compile\[rq] as many tests as possible, use \fB\-\-tests\fR to
build test binaries separately. For example:
.sp
.RS 4
.nf
cargo build \-\-tests \-\-keep\-going
cargo test \-\-tests \-\-no\-fail\-fast
.fi
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Execute all the unit and integration tests of the current package:
.sp
.RS 4
.nf
cargo test
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Run only tests whose names match against a filter string:
.sp
.RS 4
.nf
cargo test name_filter
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Run only a specific test within a specific integration test:
.sp
.RS 4
.nf
cargo test \-\-test int_test_name \-\- modname::test_name
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-bench\fR(1), \fItypes of tests\fR <https://doc.rust\-lang.org/cargo/reference/cargo\-targets.html#tests>, \fIhow to write tests\fR <https://doc.rust\-lang.org/rustc/tests/index.html>

517
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-tree.1 Normal file
View File

@ -0,0 +1,517 @@
'\" t
.TH "CARGO\-TREE" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-tree \[em] Display a tree visualization of a dependency graph
.SH "SYNOPSIS"
\fBcargo tree\fR [\fIoptions\fR]
.SH "DESCRIPTION"
This command will display a tree of dependencies to the terminal. An example
of a simple project that depends on the \[lq]rand\[rq] package:
.sp
.RS 4
.nf
myproject v0.1.0 (/myproject)
`\-\- rand v0.7.3
|\-\- getrandom v0.1.14
| |\-\- cfg\-if v0.1.10
| `\-\- libc v0.2.68
|\-\- libc v0.2.68 (*)
|\-\- rand_chacha v0.2.2
| |\-\- ppv\-lite86 v0.2.6
| `\-\- rand_core v0.5.1
| `\-\- getrandom v0.1.14 (*)
`\-\- rand_core v0.5.1 (*)
[build\-dependencies]
`\-\- cc v1.0.50
.fi
.RE
.sp
Packages marked with \fB(*)\fR have been \[lq]de\-duplicated\[rq]\&. The dependencies for the
package have already been shown elsewhere in the graph, and so are not
repeated. Use the \fB\-\-no\-dedupe\fR option to repeat the duplicates.
.sp
The \fB\-e\fR flag can be used to select the dependency kinds to display. The
\[lq]features\[rq] kind changes the output to display the features enabled by
each dependency. For example, \fBcargo tree \-e features\fR:
.sp
.RS 4
.nf
myproject v0.1.0 (/myproject)
`\-\- log feature "serde"
`\-\- log v0.4.8
|\-\- serde v1.0.106
`\-\- cfg\-if feature "default"
`\-\- cfg\-if v0.1.10
.fi
.RE
.sp
In this tree, \fBmyproject\fR depends on \fBlog\fR with the \fBserde\fR feature. \fBlog\fR in
turn depends on \fBcfg\-if\fR with \[lq]default\[rq] features. When using \fB\-e features\fR it
can be helpful to use \fB\-i\fR flag to show how the features flow into a package.
See the examples below for more detail.
.SS "Feature Unification"
This command shows a graph much closer to a feature\-unified graph Cargo will
build, rather than what you list in \fBCargo.toml\fR\&. For instance, if you specify
the same dependency in both \fB[dependencies]\fR and \fB[dev\-dependencies]\fR but with
different features on. This command may merge all features and show a \fB(*)\fR on
one of the dependency to indicate the duplicate.
.sp
As a result, for a mostly equivalent overview of what \fBcargo build\fR does,
\fBcargo tree \-e normal,build\fR is pretty close; for a mostly equivalent overview
of what \fBcargo test\fR does, \fBcargo tree\fR is pretty close. However, it doesn\[cq]t
guarantee the exact equivalence to what Cargo is going to build, since a
compilation is complex and depends on lots of different factors.
.sp
To learn more about feature unification, check out this
\fIdedicated section\fR <https://doc.rust\-lang.org/cargo/reference/features.html#feature\-unification>\&.
.SH "OPTIONS"
.SS "Tree Options"
.sp
\fB\-i\fR \fIspec\fR,
\fB\-\-invert\fR \fIspec\fR
.RS 4
Show the reverse dependencies for the given package. This flag will invert
the tree and display the packages that depend on the given package.
.sp
Note that in a workspace, by default it will only display the package\[cq]s
reverse dependencies inside the tree of the workspace member in the current
directory. The \fB\-\-workspace\fR flag can be used to extend it so that it will
show the package\[cq]s reverse dependencies across the entire workspace. The \fB\-p\fR
flag can be used to display the package\[cq]s reverse dependencies only with the
subtree of the package given to \fB\-p\fR\&.
.RE
.sp
\fB\-\-prune\fR \fIspec\fR
.RS 4
Prune the given package from the display of the dependency tree.
.RE
.sp
\fB\-\-depth\fR \fIdepth\fR
.RS 4
Maximum display depth of the dependency tree. A depth of 1 displays the direct
dependencies, for example.
.RE
.sp
\fB\-\-no\-dedupe\fR
.RS 4
Do not de\-duplicate repeated dependencies. Usually, when a package has already
displayed its dependencies, further occurrences will not re\-display its
dependencies, and will include a \fB(*)\fR to indicate it has already been shown.
This flag will cause those duplicates to be repeated.
.RE
.sp
\fB\-d\fR,
\fB\-\-duplicates\fR
.RS 4
Show only dependencies which come in multiple versions (implies \fB\-\-invert\fR).
When used with the \fB\-p\fR flag, only shows duplicates within the subtree of the
given package.
.sp
It can be beneficial for build times and executable sizes to avoid building
that same package multiple times. This flag can help identify the offending
packages. You can then investigate if the package that depends on the
duplicate with the older version can be updated to the newer version so that
only one instance is built.
.RE
.sp
\fB\-e\fR \fIkinds\fR,
\fB\-\-edges\fR \fIkinds\fR
.RS 4
The dependency kinds to display. Takes a comma separated list of values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBall\fR \[em] Show all edge kinds.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnormal\fR \[em] Show normal dependencies.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBbuild\fR \[em] Show build dependencies.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBdev\fR \[em] Show development dependencies.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBfeatures\fR \[em] Show features enabled by each dependency. If this is the only
kind given, then it will automatically include the other dependency kinds.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBno\-normal\fR \[em] Do not include normal dependencies.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBno\-build\fR \[em] Do not include build dependencies.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBno\-dev\fR \[em] Do not include development dependencies.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBno\-proc\-macro\fR \[em] Do not include procedural macro dependencies.
.RE
.sp
The \fBnormal\fR, \fBbuild\fR, \fBdev\fR, and \fBall\fR dependency kinds cannot be mixed with
\fBno\-normal\fR, \fBno\-build\fR, or \fBno\-dev\fR dependency kinds.
.sp
The default is \fBnormal,build,dev\fR\&.
.RE
.sp
\fB\-\-target\fR \fItriple\fR
.RS 4
Filter dependencies matching the given \fItarget triple\fR <https://doc.rust\-lang.org/cargo/appendix/glossary.html#target>\&.
The default is the host platform. Use the value \fBall\fR to include \fIall\fR targets.
.RE
.SS "Tree Formatting Options"
.sp
\fB\-\-charset\fR \fIcharset\fR
.RS 4
Chooses the character set to use for the tree. Valid values are \[lq]utf8\[rq] or
\[lq]ascii\[rq]\&. When unspecified, cargo will auto\-select a value.
.RE
.sp
\fB\-f\fR \fIformat\fR,
\fB\-\-format\fR \fIformat\fR
.RS 4
Set the format string for each package. The default is \[lq]{p}\[rq]\&.
.sp
This is an arbitrary string which will be used to display each package. The following
strings will be replaced with the corresponding value:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB{p}\fR \[em] The package name.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB{l}\fR \[em] The package license.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB{r}\fR \[em] The package repository URL.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB{f}\fR \[em] Comma\-separated list of package features that are enabled.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB{lib}\fR \[em] The name, as used in a \fBuse\fR statement, of the package\[cq]s library.
.RE
.RE
.sp
\fB\-\-prefix\fR \fIprefix\fR
.RS 4
Sets how each line is displayed. The \fIprefix\fR value can be one of:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBindent\fR (default) \[em] Shows each line indented as a tree.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBdepth\fR \[em] Show as a list, with the numeric depth printed before each entry.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnone\fR \[em] Show as a flat list.
.RE
.RE
.SS "Package Selection"
By default, when no package selection options are given, the packages selected
depend on the selected manifest file (based on the current working directory if
\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then
the workspaces default members are selected, otherwise only the package defined
by the manifest will be selected.
.sp
The default members of a workspace can be set explicitly with the
\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a
virtual workspace will include all workspace members (equivalent to passing
\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself.
.sp
\fB\-p\fR \fIspec\fR\[u2026],
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Display only the specified packages. See \fBcargo\-pkgid\fR(1) for the
SPEC format. This flag may be specified multiple times and supports common Unix
glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally
expanding glob patterns before Cargo handles them, you must use single quotes or
double quotes around each pattern.
.RE
.sp
\fB\-\-workspace\fR
.RS 4
Display all members in the workspace.
.RE
.sp
\fB\-\-exclude\fR \fISPEC\fR\[u2026]
.RS 4
Exclude the specified packages. Must be used in conjunction with the
\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports
common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell
accidentally expanding glob patterns before Cargo handles them, you must use
single quotes or double quotes around each pattern.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
selected package.
.sp
See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options>
for more details.
.sp
\fB\-F\fR \fIfeatures\fR,
\fB\-\-features\fR \fIfeatures\fR
.RS 4
Space or comma separated list of features to activate. Features of workspace
members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may
be specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fR
.RS 4
Activate all available features of all selected packages.
.RE
.sp
\fB\-\-no\-default\-features\fR
.RS 4
Do not activate the \fBdefault\fR feature of the selected packages.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Display the tree for the package in the current directory:
.sp
.RS 4
.nf
cargo tree
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Display all the packages that depend on the \fBsyn\fR package:
.sp
.RS 4
.nf
cargo tree \-i syn
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Show the features enabled on each package:
.sp
.RS 4
.nf
cargo tree \-\-format "{p} {f}"
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 4.\h'+01'Show all packages that are built multiple times. This can happen if multiple
semver\-incompatible versions appear in the tree (like 1.0.0 and 2.0.0).
.sp
.RS 4
.nf
cargo tree \-d
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 5.\h'+01'Explain why features are enabled for the \fBsyn\fR package:
.sp
.RS 4
.nf
cargo tree \-e features \-i syn
.fi
.RE
.sp
The \fB\-e features\fR flag is used to show features. The \fB\-i\fR flag is used to
invert the graph so that it displays the packages that depend on \fBsyn\fR\&. An
example of what this would display:
.sp
.RS 4
.nf
syn v1.0.17
|\-\- syn feature "clone\-impls"
| `\-\- syn feature "default"
| `\-\- rustversion v1.0.2
| `\-\- rustversion feature "default"
| `\-\- myproject v0.1.0 (/myproject)
| `\-\- myproject feature "default" (command\-line)
|\-\- syn feature "default" (*)
|\-\- syn feature "derive"
| `\-\- syn feature "default" (*)
|\-\- syn feature "full"
| `\-\- rustversion v1.0.2 (*)
|\-\- syn feature "parsing"
| `\-\- syn feature "default" (*)
|\-\- syn feature "printing"
| `\-\- syn feature "default" (*)
|\-\- syn feature "proc\-macro"
| `\-\- syn feature "default" (*)
`\-\- syn feature "quote"
|\-\- syn feature "printing" (*)
`\-\- syn feature "proc\-macro" (*)
.fi
.RE
.sp
To read this graph, you can follow the chain for each feature from the root
to see why it is included. For example, the \[lq]full\[rq] feature is added by the
\fBrustversion\fR crate which is included from \fBmyproject\fR (with the default
features), and \fBmyproject\fR is the package selected on the command\-line. All
of the other \fBsyn\fR features are added by the \[lq]default\[rq] feature (\[lq]quote\[rq] is
added by \[lq]printing\[rq] and \[lq]proc\-macro\[rq], both of which are default features).
.sp
If you\[cq]re having difficulty cross\-referencing the de\-duplicated \fB(*)\fR
entries, try with the \fB\-\-no\-dedupe\fR flag to get the full output.
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-metadata\fR(1)

161
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-uninstall.1 Normal file
View File

@ -0,0 +1,161 @@
'\" t
.TH "CARGO\-UNINSTALL" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-uninstall \[em] Remove a Rust binary
.SH "SYNOPSIS"
\fBcargo uninstall\fR [\fIoptions\fR] [\fIspec\fR\[u2026]]
.SH "DESCRIPTION"
This command removes a package installed with \fBcargo\-install\fR(1). The \fIspec\fR
argument is a package ID specification of the package to remove (see
\fBcargo\-pkgid\fR(1)).
.sp
By default all binaries are removed for a crate but the \fB\-\-bin\fR and
\fB\-\-example\fR flags can be used to only remove particular binaries.
.sp
The installation root is determined, in order of precedence:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB\-\-root\fR option
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBCARGO_INSTALL_ROOT\fR environment variable
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBinstall.root\fR Cargo \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBCARGO_HOME\fR environment variable
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB$HOME/.cargo\fR
.RE
.SH "OPTIONS"
.SS "Install Options"
.sp
\fB\-p\fR,
\fB\-\-package\fR \fIspec\fR\[u2026]
.RS 4
Package to uninstall.
.RE
.sp
\fB\-\-bin\fR \fIname\fR\[u2026]
.RS 4
Only uninstall the binary \fIname\fR\&.
.RE
.sp
\fB\-\-root\fR \fIdir\fR
.RS 4
Directory to uninstall packages from.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Uninstall a previously installed package.
.sp
.RS 4
.nf
cargo uninstall ripgrep
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-install\fR(1)

238
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-update.1 Normal file
View File

@ -0,0 +1,238 @@
'\" t
.TH "CARGO\-UPDATE" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-update \[em] Update dependencies as recorded in the local lock file
.SH "SYNOPSIS"
\fBcargo update\fR [\fIoptions\fR] \fIspec\fR
.SH "DESCRIPTION"
This command will update dependencies in the \fBCargo.lock\fR file to the latest
version. If the \fBCargo.lock\fR file does not exist, it will be created with the
latest available versions.
.SH "OPTIONS"
.SS "Update Options"
.sp
\fIspec\fR\[u2026]
.RS 4
Update only the specified packages. This flag may be specified
multiple times. See \fBcargo\-pkgid\fR(1) for the SPEC format.
.sp
If packages are specified with \fIspec\fR, then a conservative update of
the lockfile will be performed. This means that only the dependency specified
by SPEC will be updated. Its transitive dependencies will be updated only if
SPEC cannot be updated without updating dependencies. All other dependencies
will remain locked at their currently recorded versions.
.sp
If \fIspec\fR is not specified, all dependencies are updated.
.RE
.sp
\fB\-\-recursive\fR
.RS 4
When used with \fIspec\fR, dependencies of \fIspec\fR are forced to update as well.
Cannot be used with \fB\-\-precise\fR\&.
.RE
.sp
\fB\-\-precise\fR \fIprecise\fR
.RS 4
When used with \fIspec\fR, allows you to specify a specific version number to set
the package to. If the package comes from a git repository, this can be a git
revision (such as a SHA hash or tag).
.sp
While not recommended, you can specify a yanked version of a package (nightly only).
When possible, try other non\-yanked SemVer\-compatible versions or seek help
from the maintainers of the package.
.sp
A compatible \fBpre\-release\fR version can also be specified even when the version requirement in \fBCargo.toml\fR doesn\[cq]t contain any pre\-release identifier (nightly only).
.RE
.sp
\fB\-w\fR,
\fB\-\-workspace\fR
.RS 4
Attempt to update only packages defined in the workspace. Other packages
are updated only if they don\[cq]t already exist in the lockfile. This
option is useful for updating \fBCargo.lock\fR after you\[cq]ve changed version
numbers in \fBCargo.toml\fR\&.
.RE
.sp
\fB\-\-dry\-run\fR
.RS 4
Displays what would be updated, but doesn\[cq]t actually write the lockfile.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-ignore\-rust\-version\fR
.RS 4
Ignore \fBrust\-version\fR specification in packages.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Update all dependencies in the lockfile:
.sp
.RS 4
.nf
cargo update
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Update only specific dependencies:
.sp
.RS 4
.nf
cargo update foo bar
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Set a specific dependency to a specific version:
.sp
.RS 4
.nf
cargo update foo \-\-precise 1.2.3
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1)

237
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-vendor.1 Normal file
View File

@ -0,0 +1,237 @@
'\" t
.TH "CARGO\-VENDOR" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-vendor \[em] Vendor all dependencies locally
.SH "SYNOPSIS"
\fBcargo vendor\fR [\fIoptions\fR] [\fIpath\fR]
.SH "DESCRIPTION"
This cargo subcommand will vendor all crates.io and git dependencies for a
project into the specified directory at \fB<path>\fR\&. After this command completes
the vendor directory specified by \fB<path>\fR will contain all remote sources from
dependencies specified. Additional manifests beyond the default one can be
specified with the \fB\-s\fR option.
.sp
The configuration necessary to use the vendored sources would be printed to
stdout after \fBcargo vendor\fR completes the vendoring process.
You will need to add or redirect it to your Cargo configuration file,
which is usually \fB\&.cargo/config.toml\fR locally for the current package.
.sp
Cargo treats vendored sources as read\-only as it does to registry and git sources.
If you intend to modify a crate from a remote source,
use \fB[patch]\fR or a \fBpath\fR dependency pointing to a local copy of that crate.
Cargo will then correctly handle the crate on incremental rebuilds,
as it knowns that it is no longer a read\-only dependency.
.SH "OPTIONS"
.SS "Vendor Options"
.sp
\fB\-s\fR \fImanifest\fR,
\fB\-\-sync\fR \fImanifest\fR
.RS 4
Specify an extra \fBCargo.toml\fR manifest to workspaces which should also be
vendored and synced to the output. May be specified multiple times.
.RE
.sp
\fB\-\-no\-delete\fR
.RS 4
Don\[cq]t delete the \[lq]vendor\[rq] directory when vendoring, but rather keep all
existing contents of the vendor directory
.RE
.sp
\fB\-\-respect\-source\-config\fR
.RS 4
Instead of ignoring \fB[source]\fR configuration by default in \fB\&.cargo/config.toml\fR
read it and use it when downloading crates from crates.io, for example
.RE
.sp
\fB\-\-versioned\-dirs\fR
.RS 4
Normally versions are only added to disambiguate multiple versions of the
same package. This option causes all directories in the \[lq]vendor\[rq] directory
to be versioned, which makes it easier to track the history of vendored
packages over time, and can help with the performance of re\-vendoring when
only a subset of the packages have changed.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Vendor all dependencies into a local \[lq]vendor\[rq] folder
.sp
.RS 4
.nf
cargo vendor
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Vendor all dependencies into a local \[lq]third\-party/vendor\[rq] folder
.sp
.RS 4
.nf
cargo vendor third\-party/vendor
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Vendor the current workspace as well as another to \[lq]vendor\[rq]
.sp
.RS 4
.nf
cargo vendor \-s ../path/to/Cargo.toml
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 4.\h'+01'Vendor and redirect the necessary vendor configs to a config file.
.sp
.RS 4
.nf
cargo vendor > path/to/my/cargo/config.toml
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1)

178
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-verify-project.1 Normal file
View File

@ -0,0 +1,178 @@
'\" t
.TH "CARGO\-VERIFY\-PROJECT" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-verify\-project \[em] Check correctness of crate manifest
.SH "SYNOPSIS"
\fBcargo verify\-project\fR [\fIoptions\fR]
.SH "DESCRIPTION"
This command will parse the local manifest and check its validity. It emits a
JSON object with the result. A successful validation will display:
.sp
.RS 4
.nf
{"success":"true"}
.fi
.RE
.sp
An invalid workspace will display:
.sp
.RS 4
.nf
{"invalid":"human\-readable error message"}
.fi
.RE
.SH "OPTIONS"
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Manifest Options"
.sp
\fB\-\-manifest\-path\fR \fIpath\fR
.RS 4
Path to the \fBCargo.toml\fR file. By default, Cargo searches for the
\fBCargo.toml\fR file in the current directory or any parent directory.
.RE
.sp
\fB\-\-locked\fR
.RS 4
Asserts that the exact same dependencies and versions are used as when the
existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an
error when either of the following scenarios arises:
.sp
.RS 4
\h'-04'\(bu\h'+02'The lock file is missing.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution.
.RE
.sp
It may be used in environments where deterministic builds are desired,
such as in CI pipelines.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-frozen\fR
.RS 4
Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: The workspace is OK.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB1\fR: The workspace is invalid.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Check the current workspace for errors:
.sp
.RS 4
.nf
cargo verify\-project
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-package\fR(1)

52
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-version.1 Normal file
View File

@ -0,0 +1,52 @@
'\" t
.TH "CARGO\-VERSION" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-version \[em] Show version information
.SH "SYNOPSIS"
\fBcargo version\fR [\fIoptions\fR]
.SH "DESCRIPTION"
Displays the version of Cargo.
.SH "OPTIONS"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Display additional version information.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Display the version:
.sp
.RS 4
.nf
cargo version
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'The version is also available via flags:
.sp
.RS 4
.nf
cargo \-\-version
cargo \-V
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Display extra version information:
.sp
.RS 4
.nf
cargo \-Vv
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1)

248
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo-yank.1 Normal file
View File

@ -0,0 +1,248 @@
'\" t
.TH "CARGO\-YANK" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo\-yank \[em] Remove a pushed crate from the index
.SH "SYNOPSIS"
\fBcargo yank\fR [\fIoptions\fR] \fIcrate\fR@\fIversion\fR
.br
\fBcargo yank\fR [\fIoptions\fR] \fB\-\-version\fR \fIversion\fR [\fIcrate\fR]
.SH "DESCRIPTION"
The yank command removes a previously published crate\[cq]s version from the
server\[cq]s index. This command does not delete any data, and the crate will
still be available for download via the registry\[cq]s download link.
.sp
Cargo will not use a yanked version for any new project or checkout without a
pre\-existing lockfile, and will generate an error if there are no longer
any compatible versions for your crate.
.sp
This command requires you to be authenticated with either the \fB\-\-token\fR option
or using \fBcargo\-login\fR(1).
.sp
If the crate name is not specified, it will use the package name from the
current directory.
.SS "How yank works"
For example, the \fBfoo\fR crate published version \fB1.5.0\fR and another crate \fBbar\fR
declared a dependency on version \fBfoo = "1.5"\fR\&. Now \fBfoo\fR releases a new, but
not semver compatible, version \fB2.0.0\fR, and finds a critical issue with \fB1.5.0\fR\&.
If \fB1.5.0\fR is yanked, no new project or checkout without an existing lockfile
will be able to use crate \fBbar\fR as it relies on \fB1.5\fR\&.
.sp
In this case, the maintainers of \fBfoo\fR should first publish a semver compatible
version such as \fB1.5.1\fR prior to yanking \fB1.5.0\fR so that \fBbar\fR and all projects
that depend on \fBbar\fR will continue to work.
.sp
As another example, consider a crate \fBbar\fR with published versions \fB1.5.0\fR,
\fB1.5.1\fR, \fB1.5.2\fR, \fB2.0.0\fR and \fB3.0.0\fR\&. The following table identifies the
versions cargo could use in the absence of a lockfile for different SemVer
requirements, following a given release being yanked:
.TS
allbox tab(:);
lt lt lt lt.
T{
Yanked Version / SemVer requirement
T}:T{
\fBbar = "1.5.0"\fR
T}:T{
\fBbar = "=1.5.0"\fR
T}:T{
\fBbar = "2.0.0"\fR
T}
T{
\fB1.5.0\fR
T}:T{
Use either \fB1.5.1\fR or \fB1.5.2\fR
T}:T{
\fBReturn Error\fR
T}:T{
Use \fB2.0.0\fR
T}
T{
\fB1.5.1\fR
T}:T{
Use either \fB1.5.0\fR or \fB1.5.2\fR
T}:T{
Use \fB1.5.0\fR
T}:T{
Use \fB2.0.0\fR
T}
T{
\fB2.0.0\fR
T}:T{
Use either \fB1.5.0\fR, \fB1.5.1\fR or \fB1.5.2\fR
T}:T{
Use \fB1.5.0\fR
T}:T{
\fBReturn Error\fR
T}
.TE
.sp
.SS "When to yank"
Crates should only be yanked in exceptional circumstances, for example, an
accidental publish, an unintentional SemVer breakages, or a significantly
broken and unusable crate. In the case of security vulnerabilities, \fIRustSec\fR <https://rustsec.org/>
is typically a less disruptive mechanism to inform users and encourage them
to upgrade, and avoids the possibility of significant downstream disruption
irrespective of susceptibility to the vulnerability in question.
.sp
A common workflow is to yank a crate having already published a semver
compatible version, to reduce the probability of preventing dependent
crates from compiling.
.sp
When addressing copyright, licensing, or personal data issues with a published
crate, simply yanking it may not suffice. In such cases, contact the maintainers
of the registry you used. For crates.io, refer to their \fIpolicies\fR <https://crates.io/policies> and contact
them at <help@crates.io>\&.
.sp
If credentials have been leaked, the recommended course of action is to revoke
them immediately. Once a crate has been published, it is impossible to determine
if the leaked credentials have been copied. Yanking the crate only prevents new
users from downloading it, but cannot stop those who have already downloaded it
from keeping or even spreading the leaked credentials.
.SH "OPTIONS"
.SS "Yank Options"
.sp
\fB\-\-vers\fR \fIversion\fR,
\fB\-\-version\fR \fIversion\fR
.RS 4
The version to yank or un\-yank.
.RE
.sp
\fB\-\-undo\fR
.RS 4
Undo a yank, putting a version back into the index.
.RE
.sp
\fB\-\-token\fR \fItoken\fR
.RS 4
API token to use when authenticating. This overrides the token stored in
the credentials file (which is created by \fBcargo\-login\fR(1)).
.sp
\fICargo config\fR <https://doc.rust\-lang.org/cargo/reference/config.html> environment variables can be
used to override the tokens stored in the credentials file. The token for
crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fR environment
variable. Tokens for other registries may be specified with environment
variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name
of the registry in all capital letters.
.RE
.sp
\fB\-\-index\fR \fIindex\fR
.RS 4
The URL of the registry index to use.
.RE
.sp
\fB\-\-registry\fR \fIregistry\fR
.RS 4
Name of the registry to use. Registry names are defined in \fICargo config
files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used,
which is defined by the \fBregistry.default\fR config key which defaults to
\fBcrates\-io\fR\&.
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Yank a crate from the index:
.sp
.RS 4
.nf
cargo yank foo@1.0.7
.fi
.RE
.RE
.SH "SEE ALSO"
\fBcargo\fR(1), \fBcargo\-login\fR(1), \fBcargo\-publish\fR(1)

396
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/cargo.1 Normal file
View File

@ -0,0 +1,396 @@
'\" t
.TH "CARGO" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
cargo \[em] The Rust package manager
.SH "SYNOPSIS"
\fBcargo\fR [\fIoptions\fR] \fIcommand\fR [\fIargs\fR]
.br
\fBcargo\fR [\fIoptions\fR] \fB\-\-version\fR
.br
\fBcargo\fR [\fIoptions\fR] \fB\-\-list\fR
.br
\fBcargo\fR [\fIoptions\fR] \fB\-\-help\fR
.br
\fBcargo\fR [\fIoptions\fR] \fB\-\-explain\fR \fIcode\fR
.SH "DESCRIPTION"
This program is a package manager and build tool for the Rust language,
available at <https://rust\-lang.org>\&.
.SH "COMMANDS"
.SS "Build Commands"
\fBcargo\-bench\fR(1)
.br
\ \ \ \ Execute benchmarks of a package.
.sp
\fBcargo\-build\fR(1)
.br
\ \ \ \ Compile a package.
.sp
\fBcargo\-check\fR(1)
.br
\ \ \ \ Check a local package and all of its dependencies for errors.
.sp
\fBcargo\-clean\fR(1)
.br
\ \ \ \ Remove artifacts that Cargo has generated in the past.
.sp
\fBcargo\-doc\fR(1)
.br
\ \ \ \ Build a package\[cq]s documentation.
.sp
\fBcargo\-fetch\fR(1)
.br
\ \ \ \ Fetch dependencies of a package from the network.
.sp
\fBcargo\-fix\fR(1)
.br
\ \ \ \ Automatically fix lint warnings reported by rustc.
.sp
\fBcargo\-run\fR(1)
.br
\ \ \ \ Run a binary or example of the local package.
.sp
\fBcargo\-rustc\fR(1)
.br
\ \ \ \ Compile a package, and pass extra options to the compiler.
.sp
\fBcargo\-rustdoc\fR(1)
.br
\ \ \ \ Build a package\[cq]s documentation, using specified custom flags.
.sp
\fBcargo\-test\fR(1)
.br
\ \ \ \ Execute unit and integration tests of a package.
.SS "Manifest Commands"
\fBcargo\-generate\-lockfile\fR(1)
.br
\ \ \ \ Generate \fBCargo.lock\fR for a project.
.sp
\fBcargo\-locate\-project\fR(1)
.br
\ \ \ \ Print a JSON representation of a \fBCargo.toml\fR file\[cq]s location.
.sp
\fBcargo\-metadata\fR(1)
.br
\ \ \ \ Output the resolved dependencies of a package in machine\-readable format.
.sp
\fBcargo\-pkgid\fR(1)
.br
\ \ \ \ Print a fully qualified package specification.
.sp
\fBcargo\-tree\fR(1)
.br
\ \ \ \ Display a tree visualization of a dependency graph.
.sp
\fBcargo\-update\fR(1)
.br
\ \ \ \ Update dependencies as recorded in the local lock file.
.sp
\fBcargo\-vendor\fR(1)
.br
\ \ \ \ Vendor all dependencies locally.
.sp
\fBcargo\-verify\-project\fR(1)
.br
\ \ \ \ Check correctness of crate manifest.
.SS "Package Commands"
\fBcargo\-init\fR(1)
.br
\ \ \ \ Create a new Cargo package in an existing directory.
.sp
\fBcargo\-install\fR(1)
.br
\ \ \ \ Build and install a Rust binary.
.sp
\fBcargo\-new\fR(1)
.br
\ \ \ \ Create a new Cargo package.
.sp
\fBcargo\-search\fR(1)
.br
\ \ \ \ Search packages in crates.io.
.sp
\fBcargo\-uninstall\fR(1)
.br
\ \ \ \ Remove a Rust binary.
.SS "Publishing Commands"
\fBcargo\-login\fR(1)
.br
\ \ \ \ Save an API token from the registry locally.
.sp
\fBcargo\-logout\fR(1)
.br
\ \ \ \ Remove an API token from the registry locally.
.sp
\fBcargo\-owner\fR(1)
.br
\ \ \ \ Manage the owners of a crate on the registry.
.sp
\fBcargo\-package\fR(1)
.br
\ \ \ \ Assemble the local package into a distributable tarball.
.sp
\fBcargo\-publish\fR(1)
.br
\ \ \ \ Upload a package to the registry.
.sp
\fBcargo\-yank\fR(1)
.br
\ \ \ \ Remove a pushed crate from the index.
.SS "General Commands"
\fBcargo\-help\fR(1)
.br
\ \ \ \ Display help information about Cargo.
.sp
\fBcargo\-version\fR(1)
.br
\ \ \ \ Show version information.
.SH "OPTIONS"
.SS "Special Options"
.sp
\fB\-V\fR,
\fB\-\-version\fR
.RS 4
Print version info and exit. If used with \fB\-\-verbose\fR, prints extra
information.
.RE
.sp
\fB\-\-list\fR
.RS 4
List all installed Cargo subcommands. If used with \fB\-\-verbose\fR, prints extra
information.
.RE
.sp
\fB\-\-explain\fR \fIcode\fR
.RS 4
Run \fBrustc \-\-explain CODE\fR which will print out a detailed explanation of an
error message (for example, \fBE0004\fR).
.RE
.SS "Display Options"
.sp
\fB\-v\fR,
\fB\-\-verbose\fR
.RS 4
Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which
includes extra output such as dependency warnings and build script output.
May also be specified with the \fBterm.verbose\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-q\fR,
\fB\-\-quiet\fR
.RS 4
Do not print cargo log messages.
May also be specified with the \fBterm.quiet\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.sp
\fB\-\-color\fR \fIwhen\fR
.RS 4
Control when colored output is used. Valid values:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the
terminal.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors.
.RE
.sp
May also be specified with the \fBterm.color\fR
\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Manifest Options"
.sp
\fB\-\-frozen\fR,
\fB\-\-locked\fR
.RS 4
Either of these flags requires that the \fBCargo.lock\fR file is
up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will
exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from
attempting to access the network to determine if it is out\-of\-date.
.sp
These may be used in environments where you want to assert that the
\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network
access.
.RE
.sp
\fB\-\-offline\fR
.RS 4
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
.sp
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the \fBcargo\-fetch\fR(1) command to download dependencies before going
offline.
.sp
May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&.
.RE
.SS "Common Options"
.sp
\fB+\fR\fItoolchain\fR
.RS 4
If Cargo has been installed with rustup, and the first argument to \fBcargo\fR
begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such
as \fB+stable\fR or \fB+nightly\fR).
See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html>
for more information about how toolchain overrides work.
.RE
.sp
\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR
.RS 4
Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR,
or provided as a path to an extra configuration file. This flag may be specified multiple times.
See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information.
.RE
.sp
\fB\-C\fR \fIPATH\fR
.RS 4
Changes the current working directory before executing any specified operations. This affects
things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as
the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must
appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&.
.sp
This option is only available on the \fInightly
channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and
requires the \fB\-Z unstable\-options\fR flag to enable (see
\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>).
.RE
.sp
\fB\-h\fR,
\fB\-\-help\fR
.RS 4
Prints help information.
.RE
.sp
\fB\-Z\fR \fIflag\fR
.RS 4
Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
.RE
.SH "ENVIRONMENT"
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
details on environment variables that Cargo reads.
.SH "EXIT STATUS"
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete.
.RE
.SH "FILES"
\fB~/.cargo/\fR
.br
\ \ \ \ Default location for Cargo\[cq]s \[lq]home\[rq] directory where it
stores various files. The location can be changed with the \fBCARGO_HOME\fR
environment variable.
.sp
\fB$CARGO_HOME/bin/\fR
.br
\ \ \ \ Binaries installed by \fBcargo\-install\fR(1) will be located here. If using
\fIrustup\fR <https://rust\-lang.github.io/rustup/>, executables distributed with Rust are also located here.
.sp
\fB$CARGO_HOME/config.toml\fR
.br
\ \ \ \ The global configuration file. See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/config.html>
for more information about configuration files.
.sp
\fB\&.cargo/config.toml\fR
.br
\ \ \ \ Cargo automatically searches for a file named \fB\&.cargo/config.toml\fR in the
current directory, and all parent directories. These configuration files
will be merged with the global configuration file.
.sp
\fB$CARGO_HOME/credentials.toml\fR
.br
\ \ \ \ Private authentication information for logging in to a registry.
.sp
\fB$CARGO_HOME/registry/\fR
.br
\ \ \ \ This directory contains cached downloads of the registry index and any
downloaded dependencies.
.sp
\fB$CARGO_HOME/git/\fR
.br
\ \ \ \ This directory contains cached downloads of git dependencies.
.sp
Please note that the internal structure of the \fB$CARGO_HOME\fR directory is not
stable yet and may be subject to change.
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Build a local package and all of its dependencies:
.sp
.RS 4
.nf
cargo build
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 2.\h'+01'Build a package with optimizations:
.sp
.RS 4
.nf
cargo build \-\-release
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 3.\h'+01'Run tests for a cross\-compiled target:
.sp
.RS 4
.nf
cargo test \-\-target i686\-unknown\-linux\-gnu
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 4.\h'+01'Create a new package that builds an executable:
.sp
.RS 4
.nf
cargo new foobar
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 5.\h'+01'Create a package in the current directory:
.sp
.RS 4
.nf
mkdir foo && cd foo
cargo init .
.fi
.RE
.RE
.sp
.RS 4
\h'-04' 6.\h'+01'Learn about a command\[cq]s options and usage:
.sp
.RS 4
.nf
cargo help clean
.fi
.RE
.RE
.SH "BUGS"
See <https://github.com/rust\-lang/cargo/issues> for issues.
.SH "SEE ALSO"
\fBrustc\fR(1), \fBrustdoc\fR(1)

314
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/rustc.1 Normal file
View File

@ -0,0 +1,314 @@
.TH RUSTC "1" "April 2019" "rustc <INSERT VERSION HERE>" "User Commands"
.SH NAME
rustc \- The Rust compiler
.SH SYNOPSIS
.B rustc
[\fIOPTIONS\fR] \fIINPUT\fR
.SH DESCRIPTION
This program is a compiler for the Rust language, available at https://www.rust\-lang.org.
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
Display the help message.
.TP
\fB\-\-cfg\fR \fISPEC\fR
Configure the compilation environment.
.TP
\fB\-L\fR [\fIKIND\fR=]\fIPATH\fR
Add a directory to the library search path.
The optional \fIKIND\fR can be one of:
.RS
.TP
\fBdependency\fR
only lookup transitive dependencies here
.TP
.B crate
only lookup local `extern crate` directives here
.TP
.B native
only lookup native libraries here
.TP
.B framework
only look for OSX frameworks here
.TP
.B all
look for anything here (the default)
.RE
.TP
\fB\-l\fR [\fIKIND\fR=]\fINAME\fR
Link the generated crate(s) to the specified library \fINAME\fR.
The optional \fIKIND\fR can be one of \fIstatic\fR, \fIdylib\fR, or
\fIframework\fR.
If omitted, \fIdylib\fR is assumed.
.TP
\fB\-\-crate\-type\fR [bin|lib|rlib|dylib|cdylib|staticlib|proc\-macro]
Comma separated list of types of crates for the compiler to emit.
.TP
\fB\-\-crate\-name\fR \fINAME\fR
Specify the name of the crate being built.
.TP
\fB\-\-emit\fR [asm|llvm\-bc|llvm\-ir|obj|metadata|link|dep\-info|mir][=\fIPATH\fR]
Configure the output that \fBrustc\fR will produce. Each emission may also have
an optional explicit output \fIPATH\fR specified for that particular emission
kind. This path takes precedence over the \fB-o\fR option.
.TP
\fB\-\-print\fR [crate\-name|\:file\-names|\:sysroot|\:target\-libdir|\:cfg|\:target\-list|\:target\-cpus|\:target\-features|\:relocation\-models|\:code\-models|\:tls\-models|\:target\-spec\-json|\:native\-static\-libs|\:stack\-protector\-strategies|\:link\-args]
Comma separated list of compiler information to print on stdout.
.TP
\fB\-g\fR
Equivalent to \fI\-C\ debuginfo=2\fR.
.TP
\fB\-O\fR
Equivalent to \fI\-C\ opt\-level=2\fR.
.TP
\fB\-o\fR \fIFILENAME\fR
Write output to \fIFILENAME\fR. Ignored if multiple \fI\-\-emit\fR outputs are specified which
don't have an explicit path otherwise.
.TP
\fB\-\-out\-dir\fR \fIDIR\fR
Write output to compiler\[hy]chosen filename in \fIDIR\fR. Ignored if \fI\-o\fR is specified.
Defaults to the current directory.
.TP
\fB\-\-explain\fR \fIOPT\fR
Provide a detailed explanation of an error message.
.TP
\fB\-\-test\fR
Build a test harness.
.TP
\fB\-\-target\fR \fITARGET\fR
Target triple for which the code is compiled. This option defaults to the host’s target
triple. The target triple has the general format <arch><sub>\-<vendor>\-<sys>\-<abi>, where:
.RS
.TP
.B <arch>
x86, arm, thumb, mips, etc.
.TP
.B <sub>
for example on ARM: v5, v6m, v7a, v7m, etc.
.TP
.B <vendor>
pc, apple, nvidia, ibm, etc.
.TP
.B <sys>
none, linux, win32, darwin, cuda, etc.
.TP
.B <abi>
eabi, gnu, android, macho, elf, etc.
.RE
.TP
\fB\-W help\fR
Print 'lint' options and default settings.
.TP
\fB\-W\fR \fIOPT\fR, \fB\-\-warn\fR \fIOPT\fR
Set lint warnings.
.TP
\fB\-A\fR \fIOPT\fR, \fB\-\-allow\fR \fIOPT\fR
Set lint allowed.
.TP
\fB\-D\fR \fIOPT\fR, \fB\-\-deny\fR \fIOPT\fR
Set lint denied.
.TP
\fB\-F\fR \fIOPT\fR, \fB\-\-forbid\fR \fIOPT\fR
Set lint forbidden.
.TP
\fB\-C\fR \fIFLAG\fR[=\fIVAL\fR], \fB\-\-codegen\fR \fIFLAG\fR[=\fIVAL\fR]
Set a codegen\[hy]related flag to the value specified.
Use \fI\-C help\fR to print available flags.
See CODEGEN OPTIONS below.
.TP
\fB\-V\fR, \fB\-\-version\fR
Print version info and exit.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Use verbose output.
.TP
\fB\-\-remap\-path\-prefix\fR \fIfrom\fR=\fIto\fR
Remap source path prefixes in all output, including compiler diagnostics, debug information,
macro expansions, etc. The \fIfrom\fR=\fIto\fR parameter is scanned from right to left, so \fIfrom\fR
may contain '=', but \fIto\fR may not.
This is useful for normalizing build products, for example by removing the current directory out of
pathnames emitted into the object files. The replacement is purely textual, with no consideration of
the current system's pathname syntax. For example \fI\-\-remap\-path\-prefix foo=bar\fR will
match \fBfoo/lib.rs\fR but not \fB./foo/lib.rs\fR.
.TP
\fB\-\-extern\fR \fINAME\fR=\fIPATH\fR
Specify where an external rust library is located. These should match
\fIextern\fR declarations in the crate's source code.
.TP
\fB\-\-sysroot\fR \fIPATH\fR
Override the system root.
.TP
\fB\-Z\fR \fIFLAG\fR
Set unstable / perma-unstable options.
Use \fI\-Z help\fR to print available options.
.TP
\fB\-\-color\fR auto|always|never
Configure coloring of output:
.RS
.TP
.B auto
colorize, if output goes to a tty (default);
.TP
.B always
always colorize output;
.TP
.B never
never colorize output.
.RE
.SH CODEGEN OPTIONS
.TP
\fBlinker\fR=\fI/path/to/cc\fR
Path to the linker utility to use when linking libraries, executables, and
objects.
.TP
\fBlink\-args\fR='\fI\-flag1 \-flag2\fR'
A space\[hy]separated list of extra arguments to pass to the linker when the linker
is invoked.
.TP
\fBlto\fR
Perform LLVM link\[hy]time optimizations.
.TP
\fBtarget\-cpu\fR=\fIhelp\fR
Selects a target processor.
If the value is 'help', then a list of available CPUs is printed.
.TP
\fBtarget\-feature\fR='\fI+feature1\fR,\fI\-feature2\fR'
A comma\[hy]separated list of features to enable or disable for the target.
A preceding '+' enables a feature while a preceding '\-' disables it.
Available features can be discovered through \fIllc -mcpu=help\fR.
.TP
\fBpasses\fR=\fIval\fR
A space\[hy]separated list of extra LLVM passes to run.
A value of 'list' will cause \fBrustc\fR to print all known passes and
exit.
The passes specified are appended at the end of the normal pass manager.
.TP
\fBllvm\-args\fR='\fI\-arg1\fR \fI\-arg2\fR'
A space\[hy]separated list of arguments to pass through to LLVM.
.TP
\fBsave\-temps\fR
If specified, the compiler will save more files (.bc, .o, .no\-opt.bc) generated
throughout compilation in the output directory.
.TP
\fBrpath\fR
If specified, then the rpath value for dynamic libraries will be set in
either dynamic library or executable outputs.
.TP
\fBno\-prepopulate\-passes\fR
Suppresses pre\[hy]population of the LLVM pass manager that is run over the module.
.TP
\fBno\-vectorize\-loops\fR
Suppresses running the loop vectorization LLVM pass, regardless of optimization
level.
.TP
\fBno\-vectorize\-slp\fR
Suppresses running the LLVM SLP vectorization pass, regardless of optimization
level.
.TP
\fBsoft\-float\fR
Generates software floating point library calls instead of hardware
instructions.
.TP
\fBprefer\-dynamic\fR
Prefers dynamic linking to static linking.
.TP
\fBno\-integrated\-as\fR
Force usage of an external assembler rather than LLVM's integrated one.
.TP
\fBno\-redzone\fR
Disable the use of the redzone.
.TP
\fBrelocation\-model\fR=[pic,static,dynamic\-no\-pic]
The relocation model to use.
(Default: \fIpic\fR)
.TP
\fBcode\-model\fR=[small,kernel,medium,large]
Choose the code model to use.
.TP
\fBmetadata\fR=\fIval\fR
Metadata to mangle symbol names with.
.TP
\fBextra\-filename\fR=\fIval\fR
Extra data to put in each output filename.
.TP
\fBcodegen\-units\fR=\fIn\fR
Divide crate into \fIn\fR units to optimize in parallel.
.TP
\fBremark\fR=\fIval\fR
Print remarks for these optimization passes (space separated, or "all").
.TP
\fBno\-stack\-check\fR
Disable checks for stack exhaustion (a memory\[hy]safety hazard!).
.TP
\fBdebuginfo\fR=\fIval\fR
Debug info emission level:
.RS
.TP
.B 0
no debug info;
.TP
.B 1
line\[hy]tables only (for stacktraces and breakpoints);
.TP
.B 2
full debug info with variable and type information.
.RE
.TP
\fBopt\-level\fR=\fIVAL\fR
Optimize with possible levels 0\[en]3, s (optimize for size), or z (for minimal size)
.SH ENVIRONMENT
Some of these affect only test harness programs (generated via rustc --test);
others affect all programs which link to the Rust standard library.
.TP
\fBRUST_TEST_THREADS\fR
The test framework Rust provides executes tests in parallel. This variable sets
the maximum number of threads used for this purpose. This setting is overridden
by the --test-threads option.
.TP
\fBRUST_TEST_NOCAPTURE\fR
If set to a value other than "0", a synonym for the --nocapture flag.
.TP
\fBRUST_MIN_STACK\fR
Sets the minimum stack size for new threads.
.TP
\fBRUST_BACKTRACE\fR
If set to a value different than "0", produces a backtrace in the output of a program which panics.
.SH "EXAMPLES"
To build an executable from a source file with a main function:
$ rustc \-o hello hello.rs
To build a library from a source file:
$ rustc \-\-crate\-type=lib hello\-lib.rs
To build either with a crate (.rs) file:
$ rustc hello.rs
To build an executable with debug info:
$ rustc \-g \-o hello hello.rs
.SH "SEE ALSO"
.BR rustdoc (1)
.SH "BUGS"
See https://github.com/rust\-lang/rust/issues for issues.
.SH "AUTHOR"
See https://github.com/rust\-lang/rust/graphs/contributors or use `git log --all --format='%cN <%cE>' | sort -u` in the rust source distribution.
.SH "COPYRIGHT"
This work is dual\[hy]licensed under Apache\ 2.0 and MIT terms.
See \fICOPYRIGHT\fR file in the rust source distribution.

126
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/rustdoc.1 Normal file
View File

@ -0,0 +1,126 @@
.TH RUSTDOC "1" "July 2018" "rustdoc <INSERT VERSION HERE>" "User Commands"
.SH NAME
rustdoc \- generate documentation from Rust source code
.SH SYNOPSIS
.B rustdoc
[\fIOPTIONS\fR] \fIINPUT\fR
.SH DESCRIPTION
This tool generates API reference documentation by extracting comments from
source code written in the Rust language, available at
<\fBhttps://www.rust-lang.org\fR>. It accepts several input formats and
provides several output formats for the generated documentation.
.SH OPTIONS
.TP
\fB\-r\fR, \fB\-\-input\-format\fR \fIFORMAT\fR
rust
.TP
\fB\-w\fR, \fB\-\-output\-format\fR \fIFORMAT\fR
html
.TP
\fB\-o\fR, \fB\-\-output\fR \fIOUTPUT\fR,
where to place the output (default: \fIdoc/\fR for html)
.TP
\fB\-\-passes\fR \fILIST\fR
space\[hy]separated list of passes to run (default: '')
.TP
\fB\-\-no\-defaults\fR
don't run the default passes
.TP
\fB\-\-plugins\fR \fILIST\fR
space-separated list of plugins to run (default: '')
.TP
\fB\-\-plugin\-path\fR \fIDIR\fR
directory to load plugins from (default: \fI/tmp/rustdoc_ng/plugins\fR)
.TP
\fB\-\-target\fR \fITRIPLE\fR
target triple to document
.TP
\fB\-\-crate\-name\fR \fINAME\fR
specify the name of this crate
.TP
\fB\-L\fR, \fB\-\-library\-path\fR \fIDIR\fR
directory to add to crate search path
.TP
\fB\-\-cfg\fR \fISPEC\fR
pass a \fI\-\-cfg\fR to rustc
.TP
\fB\-\-extern\fR \fIVAL\fR
pass an \fI\-\-extern\fR to rustc
.TP
\fB\-\-test\fR
run code examples as tests
.TP
\fB\-\-test\-args\fR \fIARGS\fR
pass arguments to the test runner
.TP
\fB\-\-html\-in\-header\fR \fIFILE\fR
file to add to <head>
.TP
\fB\-\-html\-before\-content\fR \fIFILES\fR
files to include inline between <body> and the content of a rendered Markdown
file or generated documentation
.TP
\fB\-\-markdown\-before\-content\fR \fIFILES\fR
files to include inline between <body> and the content of a rendered
Markdown file or generated documentation
.TP
\fB\-\-html\-after\-content\fR \fIFILES\fR
files to include inline between the content and </body> of a rendered
Markdown file or generated documentation
.TP
\fB\-\-markdown\-after\-content\fR \fIFILES\fR
files to include inline between the content and </body> of a rendered
Markdown file or generated documentation
.TP
\fB\-\-markdown\-css\fR \fIFILES\fR
CSS files to include via <link> in a rendered Markdown file Markdown file or
generated documentation
.TP
\fB\-\-markdown\-playground\-url\fR \fIURL\fR
URL to send code snippets to
.TP
\fB\-\-markdown\-no\-toc\fR
don't include table of contents
.TP
\fB\-h\fR, \fB\-\-extend\-css\fR
to redefine some css rules with a given file to generate doc with your own theme
.TP
\fB\-V\fR, \fB\-\-version\fR
Print rustdoc's version
.SH "OUTPUT FORMATS"
The rustdoc tool can generate output in an HTML format.
If using an HTML format, then the specified output destination will be the root
directory of an HTML structure for all the documentation.
Pages will be placed into this directory, and source files will also
possibly be rendered into it as well.
.SH "EXAMPLES"
To generate documentation for the source in the current directory:
$ rustdoc hello.rs
List all available passes that rustdoc has, along with default passes:
$ rustdoc \-\-passes list
The generated HTML can be viewed with any standard web browser.
.SH "SEE ALSO"
.BR rustc (1)
.SH "BUGS"
See <\fBhttps://github.com/rust\-lang/rust/issues\fR>
for issues.
.SH "AUTHOR"
See the version control history or <\fBhttps://thanks.rust\-lang.org\fR>
.SH "COPYRIGHT"
This work is dual\[hy]licensed under Apache\ 2.0 and MIT terms.
See \fICOPYRIGHT\fR file in the rust source distribution.

353
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-addr2line.1 Normal file
View File

@ -0,0 +1,353 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ADDR2LINE 1"
.TH ADDR2LINE 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
addr2line \- convert addresses or symbol+offset into file names and line numbers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
addr2line [\fB\-a\fR|\fB\-\-addresses\fR]
[\fB\-b\fR \fIbfdname\fR|\fB\-\-target=\fR\fIbfdname\fR]
[\fB\-C\fR|\fB\-\-demangle\fR[=\fIstyle\fR]]
[\fB\-r\fR|\fB\-\-no\-recurse\-limit\fR]
[\fB\-R\fR|\fB\-\-recurse\-limit\fR]
[\fB\-e\fR \fIfilename\fR|\fB\-\-exe=\fR\fIfilename\fR]
[\fB\-f\fR|\fB\-\-functions\fR] [\fB\-s\fR|\fB\-\-basename\fR]
[\fB\-i\fR|\fB\-\-inlines\fR]
[\fB\-p\fR|\fB\-\-pretty\-print\fR]
[\fB\-j\fR|\fB\-\-section=\fR\fIname\fR]
[\fB\-H\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR]
[addr addr ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBaddr2line\fR translates addresses or symbol+offset into file names and line numbers.
Given an address or symbol+offset in an executable or an offset in a section of a relocatable
object, it uses the debugging information to figure out which file name and
line number are associated with it.
.PP
The executable or relocatable object to use is specified with the \fB\-e\fR
option. The default is the file \fIa.out\fR. The section in the relocatable
object to use is specified with the \fB\-j\fR option.
.PP
\&\fBaddr2line\fR has two modes of operation.
.PP
In the first, hexadecimal addresses or symbol+offset are specified on the command line,
and \fBaddr2line\fR displays the file name and line number for each
address.
.PP
In the second, \fBaddr2line\fR reads hexadecimal addresses or symbol+offset from
standard input, and prints the file name and line number for each
address on standard output. In this mode, \fBaddr2line\fR may be used
in a pipe to convert dynamically chosen addresses.
.PP
The format of the output is \fB\s-1FILENAME:LINENO\s0\fR. By default
each input address generates one line of output.
.PP
Two options can generate additional lines before each
\&\fB\s-1FILENAME:LINENO\s0\fR line (in that order).
.PP
If the \fB\-a\fR option is used then a line with the input address
is displayed.
.PP
If the \fB\-f\fR option is used, then a line with the
\&\fB\s-1FUNCTIONNAME\s0\fR is displayed. This is the name of the function
containing the address.
.PP
One option can generate additional lines after the
\&\fB\s-1FILENAME:LINENO\s0\fR line.
.PP
If the \fB\-i\fR option is used and the code at the given address is
present there because of inlining by the compiler then additional
lines are displayed afterwards. One or two extra lines (if the
\&\fB\-f\fR option is used) are displayed for each inlined function.
.PP
Alternatively if the \fB\-p\fR option is used then each input
address generates a single, long, output line containing the address,
the function name, the file name and the line number. If the
\&\fB\-i\fR option has also been used then any inlined functions will
be displayed in the same manner, but on separate lines, and prefixed
by the text \fB(inlined by)\fR.
.PP
If the file name or function name can not be determined,
\&\fBaddr2line\fR will print two question marks in their place. If the
line number can not be determined, \fBaddr2line\fR will print 0.
.PP
When symbol+offset is used, +offset is optional, except when the symbol
is ambigious with a hex number. The resolved symbols can be mangled
or unmangled, except unmangled symbols with + are not allowed.
.SH "OPTIONS"
.IX Header "OPTIONS"
The long and short forms of options, shown here as alternatives, are
equivalent.
.IP "\fB\-a\fR" 4
.IX Item "-a"
.PD 0
.IP "\fB\-\-addresses\fR" 4
.IX Item "--addresses"
.PD
Display the address before the function name, file and line number
information. The address is printed with a \fB0x\fR prefix to easily
identify it.
.IP "\fB\-b\fR \fIbfdname\fR" 4
.IX Item "-b bfdname"
.PD 0
.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
.IX Item "--target=bfdname"
.PD
Specify that the object-code format for the object files is
\&\fIbfdname\fR.
.IP "\fB\-C\fR" 4
.IX Item "-C"
.PD 0
.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
.IX Item "--demangle[=style]"
.PD
Decode (\fIdemangle\fR) low-level symbol names into user-level names.
Besides removing any initial underscore prepended by the system, this
makes \*(C+ function names readable. Different compilers have different
mangling styles. The optional demangling style argument can be used to
choose an appropriate demangling style for your compiler.
.IP "\fB\-e\fR \fIfilename\fR" 4
.IX Item "-e filename"
.PD 0
.IP "\fB\-\-exe=\fR\fIfilename\fR" 4
.IX Item "--exe=filename"
.PD
Specify the name of the executable for which addresses should be
translated. The default file is \fIa.out\fR.
.IP "\fB\-f\fR" 4
.IX Item "-f"
.PD 0
.IP "\fB\-\-functions\fR" 4
.IX Item "--functions"
.PD
Display function names as well as file and line number information.
.IP "\fB\-s\fR" 4
.IX Item "-s"
.PD 0
.IP "\fB\-\-basenames\fR" 4
.IX Item "--basenames"
.PD
Display only the base of each file name.
.IP "\fB\-i\fR" 4
.IX Item "-i"
.PD 0
.IP "\fB\-\-inlines\fR" 4
.IX Item "--inlines"
.PD
If the address belongs to a function that was inlined, the source
information for all enclosing scopes back to the first non-inlined
function will also be printed. For example, if \f(CW\*(C`main\*(C'\fR inlines
\&\f(CW\*(C`callee1\*(C'\fR which inlines \f(CW\*(C`callee2\*(C'\fR, and address is from
\&\f(CW\*(C`callee2\*(C'\fR, the source information for \f(CW\*(C`callee1\*(C'\fR and \f(CW\*(C`main\*(C'\fR
will also be printed.
.IP "\fB\-j\fR" 4
.IX Item "-j"
.PD 0
.IP "\fB\-\-section\fR" 4
.IX Item "--section"
.PD
Read offsets relative to the specified section instead of absolute addresses.
.IP "\fB\-p\fR" 4
.IX Item "-p"
.PD 0
.IP "\fB\-\-pretty\-print\fR" 4
.IX Item "--pretty-print"
.PD
Make the output more human friendly: each location are printed on one line.
If option \fB\-i\fR is specified, lines for all enclosing scopes are
prefixed with \fB(inlined by)\fR.
.IP "\fB\-r\fR" 4
.IX Item "-r"
.PD 0
.IP "\fB\-R\fR" 4
.IX Item "-R"
.IP "\fB\-\-recurse\-limit\fR" 4
.IX Item "--recurse-limit"
.IP "\fB\-\-no\-recurse\-limit\fR" 4
.IX Item "--no-recurse-limit"
.IP "\fB\-\-recursion\-limit\fR" 4
.IX Item "--recursion-limit"
.IP "\fB\-\-no\-recursion\-limit\fR" 4
.IX Item "--no-recursion-limit"
.PD
Enables or disables a limit on the amount of recursion performed
whilst demangling strings. Since the name mangling formats allow for
an infinite level of recursion it is possible to create strings whose
decoding will exhaust the amount of stack space available on the host
machine, triggering a memory fault. The limit tries to prevent this
from happening by restricting recursion to 2048 levels of nesting.
.Sp
The default is for this limit to be enabled, but disabling it may be
necessary in order to demangle truly complicated names. Note however
that if the recursion limit is disabled then stack exhaustion is
possible and any bug reports about such an event will be rejected.
.Sp
The \fB\-r\fR option is a synonym for the
\&\fB\-\-no\-recurse\-limit\fR option. The \fB\-R\fR option is a
synonym for the \fB\-\-recurse\-limit\fR option.
.Sp
Note this option is only effective if the \fB\-C\fR or
\&\fB\-\-demangle\fR option has been enabled.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

542
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-ar.1 Normal file
View File

@ -0,0 +1,542 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "AR 1"
.TH AR 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ar \- create, modify, and extract from archives
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
ar [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\fR] [\fB\-\-plugin\fR \fIname\fR] [\fB\-\-target\fR \fIbfdname\fR] [\fB\-\-output\fR \fIdirname\fR] [\fB\-\-record\-libdeps\fR \fIlibdeps\fR] [\fB\-\-thin\fR] [\fIrelpos\fR] [\fIcount\fR] \fIarchive\fR [\fImember\fR...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \s-1GNU\s0 \fBar\fR program creates, modifies, and extracts from
archives. An \fIarchive\fR is a single file holding a collection of
other files in a structure that makes it possible to retrieve
the original individual files (called \fImembers\fR of the archive).
.PP
The original files' contents, mode (permissions), timestamp, owner, and
group are preserved in the archive, and can be restored on
extraction.
.PP
\&\s-1GNU\s0 \fBar\fR can maintain archives whose members have names of any
length; however, depending on how \fBar\fR is configured on your
system, a limit on member-name length may be imposed for compatibility
with archive formats maintained with other tools. If it exists, the
limit is often 15 characters (typical of formats related to a.out) or 16
characters (typical of formats related to coff).
.PP
\&\fBar\fR is considered a binary utility because archives of this sort
are most often used as \fIlibraries\fR holding commonly needed
subroutines. Since libraries often will depend on other libraries,
\&\fBar\fR can also record the dependencies of a library when the
\&\fB\-\-record\-libdeps\fR option is specified.
.PP
\&\fBar\fR creates an index to the symbols defined in relocatable
object modules in the archive when you specify the modifier \fBs\fR.
Once created, this index is updated in the archive whenever \fBar\fR
makes a change to its contents (save for the \fBq\fR update operation).
An archive with such an index speeds up linking to the library, and
allows routines in the library to call each other without regard to
their placement in the archive.
.PP
You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index
table. If an archive lacks the table, another form of \fBar\fR called
\&\fBranlib\fR can be used to add just the table.
.PP
\&\s-1GNU\s0 \fBar\fR can optionally create a \fIthin\fR archive,
which contains a symbol index and references to the original copies
of the member files of the archive. This is useful for building
libraries for use within a local build tree, where the relocatable
objects are expected to remain available, and copying the contents of
each object would only waste time and space.
.PP
An archive can either be \fIthin\fR or it can be normal. It cannot
be both at the same time. Once an archive is created its format
cannot be changed without first deleting it and then creating a new
archive in its place.
.PP
Thin archives are also \fIflattened\fR, so that adding one thin
archive to another thin archive does not nest it, as would happen with
a normal archive. Instead the elements of the first archive are added
individually to the second archive.
.PP
The paths to the elements of the archive are stored relative to the
archive itself.
.PP
\&\s-1GNU\s0 \fBar\fR is designed to be compatible with two different
facilities. You can control its activity using command-line options,
like the different varieties of \fBar\fR on Unix systems; or, if you
specify the single command-line option \fB\-M\fR, you can control it
with a script supplied via standard input, like the \s-1MRI\s0 \*(L"librarian\*(R"
program.
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\s-1GNU\s0 \fBar\fR allows you to mix the operation code \fIp\fR and modifier
flags \fImod\fR in any order, within the first command-line argument.
.PP
If you wish, you may begin the first command-line argument with a
dash.
.PP
The \fIp\fR keyletter specifies what operation to execute; it may be
any of the following, but you must specify only one of them:
.IP "\fBd\fR" 4
.IX Item "d"
\&\fIDelete\fR modules from the archive. Specify the names of modules to
be deleted as \fImember\fR...; the archive is untouched if you
specify no files to delete.
.Sp
If you specify the \fBv\fR modifier, \fBar\fR lists each module
as it is deleted.
.IP "\fBm\fR" 4
.IX Item "m"
Use this operation to \fImove\fR members in an archive.
.Sp
The ordering of members in an archive can make a difference in how
programs are linked using the library, if a symbol is defined in more
than one member.
.Sp
If no modifiers are used with \f(CW\*(C`m\*(C'\fR, any members you name in the
\&\fImember\fR arguments are moved to the \fIend\fR of the archive;
you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a
specified place instead.
.IP "\fBp\fR" 4
.IX Item "p"
\&\fIPrint\fR the specified members of the archive, to the standard
output file. If the \fBv\fR modifier is specified, show the member
name before copying its contents to standard output.
.Sp
If you specify no \fImember\fR arguments, all the files in the archive are
printed.
.IP "\fBq\fR" 4
.IX Item "q"
\&\fIQuick append\fR; Historically, add the files \fImember\fR... to the end of
\&\fIarchive\fR, without checking for replacement.
.Sp
The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this
operation; new members are always placed at the end of the archive.
.Sp
The modifier \fBv\fR makes \fBar\fR list each file as it is appended.
.Sp
Since the point of this operation is speed, implementations of
\&\fBar\fR have the option of not updating the archive's symbol
table if one exists. Too many different systems however assume that
symbol tables are always up-to-date, so \s-1GNU\s0 \fBar\fR will
rebuild the table even with a quick append.
.Sp
Note \- \s-1GNU\s0 \fBar\fR treats the command \fBqs\fR as a
synonym for \fBr\fR \- replacing already existing files in the
archive and appending new ones at the end.
.IP "\fBr\fR" 4
.IX Item "r"
Insert the files \fImember\fR... into \fIarchive\fR (with
\&\fIreplacement\fR). This operation differs from \fBq\fR in that any
previously existing members are deleted if their names match those being
added.
.Sp
If one of the files named in \fImember\fR... does not exist, \fBar\fR
displays an error message, and leaves undisturbed any existing members
of the archive matching that name.
.Sp
By default, new members are added at the end of the file; but you may
use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request
placement relative to some existing member.
.Sp
The modifier \fBv\fR used with this operation elicits a line of
output for each file inserted, along with one of the letters \fBa\fR or
\&\fBr\fR to indicate whether the file was appended (no old member
deleted) or replaced.
.IP "\fBs\fR" 4
.IX Item "s"
Add an index to the archive, or update it if it already exists. Note
this command is an exception to the rule that there can only be one
command letter, as it is possible to use it as either a command or a
modifier. In either case it does the same thing.
.IP "\fBt\fR" 4
.IX Item "t"
Display a \fItable\fR listing the contents of \fIarchive\fR, or those
of the files listed in \fImember\fR... that are present in the
archive. Normally only the member name is shown, but if the modifier
\&\fBO\fR is specified, then the corresponding offset of the member is also
displayed. Finally, in order to see the modes (permissions), timestamp,
owner, group, and size the \fBv\fR modifier should be included.
.Sp
If you do not specify a \fImember\fR, all files in the archive
are listed.
.Sp
If there is more than one file with the same name (say, \fBfie\fR) in
an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the
first instance; to see them all, you must ask for a complete
listing\-\-\-in our example, \fBar t b.a\fR.
.IP "\fBx\fR" 4
.IX Item "x"
\&\fIExtract\fR members (named \fImember\fR) from the archive. You can
use the \fBv\fR modifier with this operation, to request that
\&\fBar\fR list each name as it extracts it.
.Sp
If you do not specify a \fImember\fR, all files in the archive
are extracted.
.Sp
Files cannot be extracted from a thin archive, and there are
restrictions on extracting from archives created with \fBP\fR: The
paths must not be absolute, may not contain \f(CW\*(C`..\*(C'\fR, and any
subdirectories in the paths must exist. If it is desired to avoid
these restrictions then used the \fB\-\-output\fR option to specify
an output directory.
.PP
A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR
keyletter, to specify variations on an operation's behavior:
.IP "\fBa\fR" 4
.IX Item "a"
Add new files \fIafter\fR an existing member of the
archive. If you use the modifier \fBa\fR, the name of an existing archive
member must be present as the \fIrelpos\fR argument, before the
\&\fIarchive\fR specification.
.IP "\fBb\fR" 4
.IX Item "b"
Add new files \fIbefore\fR an existing member of the
archive. If you use the modifier \fBb\fR, the name of an existing archive
member must be present as the \fIrelpos\fR argument, before the
\&\fIarchive\fR specification. (same as \fBi\fR).
.IP "\fBc\fR" 4
.IX Item "c"
\&\fICreate\fR the archive. The specified \fIarchive\fR is always
created if it did not exist, when you request an update. But a warning is
issued unless you specify in advance that you expect to create it, by
using this modifier.
.IP "\fBD\fR" 4
.IX Item "D"
Operate in \fIdeterministic\fR mode. When adding files and the archive
index use zero for UIDs, GIDs, timestamps, and use consistent file modes
for all files. When this option is used, if \fBar\fR is used with
identical options and identical input files, multiple runs will create
identical output files regardless of the input files' owners, groups,
file modes, or modification times.
.Sp
If \fIbinutils\fR was configured with
\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default.
It can be disabled with the \fBU\fR modifier, below.
.IP "\fBf\fR" 4
.IX Item "f"
Truncate names in the archive. \s-1GNU\s0 \fBar\fR will normally permit file
names of any length. This will cause it to create archives which are
not compatible with the native \fBar\fR program on some systems. If
this is a concern, the \fBf\fR modifier may be used to truncate file
names when putting them in the archive.
.IP "\fBi\fR" 4
.IX Item "i"
Insert new files \fIbefore\fR an existing member of the
archive. If you use the modifier \fBi\fR, the name of an existing archive
member must be present as the \fIrelpos\fR argument, before the
\&\fIarchive\fR specification. (same as \fBb\fR).
.IP "\fBl\fR" 4
.IX Item "l"
Specify dependencies of this library. The dependencies must immediately
follow this option character, must use the same syntax as the linker
command line, and must be specified within a single argument. I.e., if
multiple items are needed, they must be quoted to form a single command
line argument. For example \fBl \*(L"\-L/usr/local/lib \-lmydep1 \-lmydep2\*(R"\fR
.IP "\fBN\fR" 4
.IX Item "N"
Uses the \fIcount\fR parameter. This is used if there are multiple
entries in the archive with the same name. Extract or delete instance
\&\fIcount\fR of the given name from the archive.
.IP "\fBo\fR" 4
.IX Item "o"
Preserve the \fIoriginal\fR dates of members when extracting them. If
you do not specify this modifier, files extracted from the archive
are stamped with the time of extraction.
.IP "\fBO\fR" 4
.IX Item "O"
Display member offsets inside the archive. Use together with the \fBt\fR
option.
.IP "\fBP\fR" 4
.IX Item "P"
Use the full path name when matching or storing names in the archive.
Archives created with full path names are not \s-1POSIX\s0 compliant, and
thus may not work with tools other than up to date \s-1GNU\s0 tools.
Modifying such archives with \s-1GNU\s0 \fBar\fR without using
\&\fBP\fR will remove the full path names unless the archive is a
thin archive. Note that \fBP\fR may be useful when adding files to
a thin archive since \fBr\fR without \fBP\fR ignores the path
when choosing which element to replace. Thus
.Sp
.Vb 1
\& ar rcST archive.a subdir/file1 subdir/file2 file1
.Ve
.Sp
will result in the first \f(CW\*(C`subdir/file1\*(C'\fR being replaced with
\&\f(CW\*(C`file1\*(C'\fR from the current directory. Adding \fBP\fR will
prevent this replacement.
.IP "\fBs\fR" 4
.IX Item "s"
Write an object-file index into the archive, or update an existing one,
even if no other change is made to the archive. You may use this modifier
flag either with any operation, or alone. Running \fBar s\fR on an
archive is equivalent to running \fBranlib\fR on it.
.IP "\fBS\fR" 4
.IX Item "S"
Do not generate an archive symbol table. This can speed up building a
large library in several steps. The resulting archive can not be used
with the linker. In order to build a symbol table, you must omit the
\&\fBS\fR modifier on the last execution of \fBar\fR, or you must run
\&\fBranlib\fR on the archive.
.IP "\fBT\fR" 4
.IX Item "T"
Deprecated alias for \fB\-\-thin\fR. \fBT\fR is not recommended because in
many ar implementations \fBT\fR has a different meaning, as specified by
X/Open System Interface.
.IP "\fBu\fR" 4
.IX Item "u"
Normally, \fBar r\fR... inserts all files
listed into the archive. If you would like to insert \fIonly\fR those
of the files you list that are newer than existing members of the same
names, use this modifier. The \fBu\fR modifier is allowed only for the
operation \fBr\fR (replace). In particular, the combination \fBqu\fR is
not allowed, since checking the timestamps would lose any speed
advantage from the operation \fBq\fR.
.Sp
Note \- if an archive has been created in a deterministic manner, eg
via the use of the \fBD\fR modifier, then replacement will always
happen and the \fBu\fR modifier will be ineffective.
.IP "\fBU\fR" 4
.IX Item "U"
Do \fInot\fR operate in \fIdeterministic\fR mode. This is the inverse
of the \fBD\fR modifier, above: added files and the archive index will
get their actual \s-1UID, GID,\s0 timestamp, and file mode values.
.Sp
This is the default unless \fIbinutils\fR was configured with
\&\fB\-\-enable\-deterministic\-archives\fR.
.IP "\fBv\fR" 4
.IX Item "v"
This modifier requests the \fIverbose\fR version of an operation. Many
operations display additional information, such as filenames processed,
when the modifier \fBv\fR is appended.
.IP "\fBV\fR" 4
.IX Item "V"
This modifier shows the version number of \fBar\fR.
.PP
The \fBar\fR program also supports some command-line options which
are neither modifiers nor actions, but which do change its behaviour
in specific ways:
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Displays the list of command-line options supported by \fBar\fR
and then exits.
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
Displays the version information of \fBar\fR and then exits.
.IP "\fB\-X32_64\fR" 4
.IX Item "-X32_64"
\&\fBar\fR ignores an initial option spelled \fB\-X32_64\fR, for
compatibility with \s-1AIX.\s0 The behaviour produced by this option is the
default for \s-1GNU\s0 \fBar\fR. \fBar\fR does not support any
of the other \fB\-X\fR options; in particular, it does not support
\&\fB\-X32\fR which is the default for \s-1AIX\s0 \fBar\fR.
.IP "\fB\-\-plugin\fR \fIname\fR" 4
.IX Item "--plugin name"
The optional command-line switch \fB\-\-plugin\fR \fIname\fR causes
\&\fBar\fR to load the plugin called \fIname\fR which adds support
for more file formats, including object files with link-time
optimization information.
.Sp
This option is only available if the toolchain has been built with
plugin support enabled.
.Sp
If \fB\-\-plugin\fR is not provided, but plugin support has been
enabled then \fBar\fR iterates over the files in
\&\fI${libdir}/bfd\-plugins\fR in alphabetic order and the first
plugin that claims the object in question is used.
.Sp
Please note that this plugin search directory is \fInot\fR the one
used by \fBld\fR's \fB\-plugin\fR option. In order to make
\&\fBar\fR use the linker plugin it must be copied into the
\&\fI${libdir}/bfd\-plugins\fR directory. For \s-1GCC\s0 based compilations
the linker plugin is called \fIliblto_plugin.so.0.0.0\fR. For Clang
based compilations it is called \fILLVMgold.so\fR. The \s-1GCC\s0 plugin
is always backwards compatible with earlier versions, so it is
sufficient to just copy the newest one.
.IP "\fB\-\-target\fR \fItarget\fR" 4
.IX Item "--target target"
The optional command-line switch \fB\-\-target\fR \fIbfdname\fR
specifies that the archive members are in an object code format
different from your system's default format. See
.IP "\fB\-\-output\fR \fIdirname\fR" 4
.IX Item "--output dirname"
The \fB\-\-output\fR option can be used to specify a path to a
directory into which archive members should be extracted. If this
option is not specified then the current directory will be used.
.Sp
Note \- although the presence of this option does imply a \fBx\fR
extraction operation that option must still be included on the command
line.
.IP "\fB\-\-record\-libdeps\fR \fIlibdeps\fR" 4
.IX Item "--record-libdeps libdeps"
The \fB\-\-record\-libdeps\fR option is identical to the \fBl\fR modifier,
just handled in long form.
.IP "\fB\-\-thin\fR" 4
.IX Item "--thin"
Make the specified \fIarchive\fR a \fIthin\fR archive. If it already
exists and is a regular archive, the existing members must be present
in the same directory as \fIarchive\fR.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnm\fR\|(1), \fBranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

3146
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-as.1 Normal file
View File

File diff suppressed because it is too large Load Diff

376
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-c++filt.1 Normal file
View File

@ -0,0 +1,376 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "C++FILT 1"
.TH C++FILT 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
c++filt \- demangle C++ and Java symbols
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
c++filt [\fB\-_\fR|\fB\-\-strip\-underscore\fR]
[\fB\-n\fR|\fB\-\-no\-strip\-underscore\fR]
[\fB\-p\fR|\fB\-\-no\-params\fR]
[\fB\-t\fR|\fB\-\-types\fR]
[\fB\-i\fR|\fB\-\-no\-verbose\fR]
[\fB\-r\fR|\fB\-\-no\-recurse\-limit\fR]
[\fB\-R\fR|\fB\-\-recurse\-limit\fR]
[\fB\-s\fR \fIformat\fR|\fB\-\-format=\fR\fIformat\fR]
[\fB\-\-help\fR] [\fB\-\-version\fR] [\fIsymbol\fR...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \*(C+ and Java languages provide function overloading, which means
that you can write many functions with the same name, providing that
each function takes parameters of different types. In order to be
able to distinguish these similarly named functions \*(C+ and Java
encode them into a low-level assembler name which uniquely identifies
each different version. This process is known as \fImangling\fR. The
\&\fBc++filt\fR
[1]
program does the inverse mapping: it decodes (\fIdemangles\fR) low-level
names into user-level names so that they can be read.
.PP
Every alphanumeric word (consisting of letters, digits, underscores,
dollars, or periods) seen in the input is a potential mangled name.
If the name decodes into a \*(C+ name, the \*(C+ name replaces the
low-level name in the output, otherwise the original word is output.
In this way you can pass an entire assembler source file, containing
mangled names, through \fBc++filt\fR and see the same source file
containing demangled names.
.PP
You can also use \fBc++filt\fR to decipher individual symbols by
passing them on the command line:
.PP
.Vb 1
\& c++filt <symbol>
.Ve
.PP
If no \fIsymbol\fR arguments are given, \fBc++filt\fR reads symbol
names from the standard input instead. All the results are printed on
the standard output. The difference between reading names from the
command line versus reading names from the standard input is that
command-line arguments are expected to be just mangled names and no
checking is performed to separate them from surrounding text. Thus
for example:
.PP
.Vb 1
\& c++filt \-n _Z1fv
.Ve
.PP
will work and demangle the name to \*(L"f()\*(R" whereas:
.PP
.Vb 1
\& c++filt \-n _Z1fv,
.Ve
.PP
will not work. (Note the extra comma at the end of the mangled
name which makes it invalid). This command however will work:
.PP
.Vb 1
\& echo _Z1fv, | c++filt \-n
.Ve
.PP
and will display \*(L"f(),\*(R", i.e., the demangled name followed by a
trailing comma. This behaviour is because when the names are read
from the standard input it is expected that they might be part of an
assembler source file where there might be extra, extraneous
characters trailing after a mangled name. For example:
.PP
.Vb 1
\& .type _Z1fv, @function
.Ve
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-_\fR" 4
.IX Item "-_"
.PD 0
.IP "\fB\-\-strip\-underscore\fR" 4
.IX Item "--strip-underscore"
.PD
On some systems, both the C and \*(C+ compilers put an underscore in front
of every name. For example, the C name \f(CW\*(C`foo\*(C'\fR gets the low-level
name \f(CW\*(C`_foo\*(C'\fR. This option removes the initial underscore. Whether
\&\fBc++filt\fR removes the underscore by default is target dependent.
.IP "\fB\-n\fR" 4
.IX Item "-n"
.PD 0
.IP "\fB\-\-no\-strip\-underscore\fR" 4
.IX Item "--no-strip-underscore"
.PD
Do not remove the initial underscore.
.IP "\fB\-p\fR" 4
.IX Item "-p"
.PD 0
.IP "\fB\-\-no\-params\fR" 4
.IX Item "--no-params"
.PD
When demangling the name of a function, do not display the types of
the function's parameters.
.IP "\fB\-t\fR" 4
.IX Item "-t"
.PD 0
.IP "\fB\-\-types\fR" 4
.IX Item "--types"
.PD
Attempt to demangle types as well as function names. This is disabled
by default since mangled types are normally only used internally in
the compiler, and they can be confused with non-mangled names. For example,
a function called \*(L"a\*(R" treated as a mangled type name would be
demangled to \*(L"signed char\*(R".
.IP "\fB\-i\fR" 4
.IX Item "-i"
.PD 0
.IP "\fB\-\-no\-verbose\fR" 4
.IX Item "--no-verbose"
.PD
Do not include implementation details (if any) in the demangled
output.
.IP "\fB\-r\fR" 4
.IX Item "-r"
.PD 0
.IP "\fB\-R\fR" 4
.IX Item "-R"
.IP "\fB\-\-recurse\-limit\fR" 4
.IX Item "--recurse-limit"
.IP "\fB\-\-no\-recurse\-limit\fR" 4
.IX Item "--no-recurse-limit"
.IP "\fB\-\-recursion\-limit\fR" 4
.IX Item "--recursion-limit"
.IP "\fB\-\-no\-recursion\-limit\fR" 4
.IX Item "--no-recursion-limit"
.PD
Enables or disables a limit on the amount of recursion performed
whilst demangling strings. Since the name mangling formats allow for
an infinite level of recursion it is possible to create strings whose
decoding will exhaust the amount of stack space available on the host
machine, triggering a memory fault. The limit tries to prevent this
from happening by restricting recursion to 2048 levels of nesting.
.Sp
The default is for this limit to be enabled, but disabling it may be
necessary in order to demangle truly complicated names. Note however
that if the recursion limit is disabled then stack exhaustion is
possible and any bug reports about such an event will be rejected.
.Sp
The \fB\-r\fR option is a synonym for the
\&\fB\-\-no\-recurse\-limit\fR option. The \fB\-R\fR option is a
synonym for the \fB\-\-recurse\-limit\fR option.
.IP "\fB\-s\fR \fIformat\fR" 4
.IX Item "-s format"
.PD 0
.IP "\fB\-\-format=\fR\fIformat\fR" 4
.IX Item "--format=format"
.PD
\&\fBc++filt\fR can decode various methods of mangling, used by
different compilers. The argument to this option selects which
method it uses:
.RS 4
.ie n .IP """auto""" 4
.el .IP "\f(CWauto\fR" 4
.IX Item "auto"
Automatic selection based on executable (the default method)
.ie n .IP """gnu""" 4
.el .IP "\f(CWgnu\fR" 4
.IX Item "gnu"
the one used by the \s-1GNU \*(C+\s0 compiler (g++)
.ie n .IP """lucid""" 4
.el .IP "\f(CWlucid\fR" 4
.IX Item "lucid"
the one used by the Lucid compiler (lcc)
.ie n .IP """arm""" 4
.el .IP "\f(CWarm\fR" 4
.IX Item "arm"
the one specified by the \*(C+ Annotated Reference Manual
.ie n .IP """hp""" 4
.el .IP "\f(CWhp\fR" 4
.IX Item "hp"
the one used by the \s-1HP\s0 compiler (aCC)
.ie n .IP """edg""" 4
.el .IP "\f(CWedg\fR" 4
.IX Item "edg"
the one used by the \s-1EDG\s0 compiler
.ie n .IP """gnu\-v3""" 4
.el .IP "\f(CWgnu\-v3\fR" 4
.IX Item "gnu-v3"
the one used by the \s-1GNU \*(C+\s0 compiler (g++) with the V3 \s-1ABI.\s0
.ie n .IP """java""" 4
.el .IP "\f(CWjava\fR" 4
.IX Item "java"
the one used by the \s-1GNU\s0 Java compiler (gcj)
.ie n .IP """gnat""" 4
.el .IP "\f(CWgnat\fR" 4
.IX Item "gnat"
the one used by the \s-1GNU\s0 Ada compiler (\s-1GNAT\s0).
.RE
.RS 4
.RE
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Print a summary of the options to \fBc++filt\fR and exit.
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
Print the version number of \fBc++filt\fR and exit.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "FOOTNOTES"
.IX Header "FOOTNOTES"
.IP "1." 4
MS-DOS does not allow \f(CW\*(C`+\*(C'\fR characters in file names, so on
MS-DOS this program is named \fB\s-1CXXFILT\s0\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
the Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

953
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-cpp.1 Normal file
View File

@ -0,0 +1,953 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CPP 1"
.TH CPP 1 "2023-07-27" "gcc-13.2.0" "GNU"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
cpp \- The C Preprocessor
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
cpp [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR]
[\fB\-I\fR\fIdir\fR...] [\fB\-iquote\fR\fIdir\fR...]
[\fB\-M\fR|\fB\-MM\fR] [\fB\-MG\fR] [\fB\-MF\fR \fIfilename\fR]
[\fB\-MP\fR] [\fB\-MQ\fR \fItarget\fR...]
[\fB\-MT\fR \fItarget\fR...]
\fIinfile\fR [[\fB\-o\fR] \fIoutfile\fR]
.PP
Only the most useful options are given above; see below for a more
complete list of preprocessor-specific options.
In addition, \fBcpp\fR accepts most \fBgcc\fR driver options, which
are not listed here. Refer to the \s-1GCC\s0 documentation for details.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The C preprocessor, often known as \fIcpp\fR, is a \fImacro processor\fR
that is used automatically by the C compiler to transform your program
before compilation. It is called a macro processor because it allows
you to define \fImacros\fR, which are brief abbreviations for longer
constructs.
.PP
The C preprocessor is intended to be used only with C, \*(C+, and
Objective-C source code. In the past, it has been abused as a general
text processor. It will choke on input which does not obey C's lexical
rules. For example, apostrophes will be interpreted as the beginning of
character constants, and cause errors. Also, you cannot rely on it
preserving characteristics of the input which are not significant to
C\-family languages. If a Makefile is preprocessed, all the hard tabs
will be removed, and the Makefile will not work.
.PP
Having said that, you can often get away with using cpp on things which
are not C. Other Algol-ish programming languages are often safe
(Ada, etc.) So is assembly, with caution. \fB\-traditional\-cpp\fR
mode preserves more white space, and is otherwise more permissive. Many
of the problems can be avoided by writing C or \*(C+ style comments
instead of native language comments, and keeping macros simple.
.PP
Wherever possible, you should use a preprocessor geared to the language
you are writing in. Modern versions of the \s-1GNU\s0 assembler have macro
facilities. Most high level programming languages have their own
conditional compilation and inclusion mechanism. If all else fails,
try a true general text processor, such as \s-1GNU M4.\s0
.PP
C preprocessors vary in some details. This manual discusses the \s-1GNU C\s0
preprocessor, which provides a small superset of the features of \s-1ISO\s0
Standard C. In its default mode, the \s-1GNU C\s0 preprocessor does not do a
few things required by the standard. These are features which are
rarely, if ever, used, and may cause surprising changes to the meaning
of a program which does not expect them. To get strict \s-1ISO\s0 Standard C,
you should use the \fB\-std=c90\fR, \fB\-std=c99\fR,
\&\fB\-std=c11\fR or \fB\-std=c17\fR options, depending
on which version of the standard you want. To get all the mandatory
diagnostics, you must also use \fB\-pedantic\fR.
.PP
This manual describes the behavior of the \s-1ISO\s0 preprocessor. To
minimize gratuitous differences, where the \s-1ISO\s0 preprocessor's
behavior does not conflict with traditional semantics, the
traditional preprocessor should behave the same way. The various
differences that do exist are detailed in the section \fBTraditional
Mode\fR.
.PP
For clarity, unless noted otherwise, references to \fB\s-1CPP\s0\fR in this
manual refer to \s-1GNU CPP.\s0
.SH "OPTIONS"
.IX Header "OPTIONS"
The \fBcpp\fR command expects two file names as arguments, \fIinfile\fR and
\&\fIoutfile\fR. The preprocessor reads \fIinfile\fR together with any
other files it specifies with \fB#include\fR. All the output generated
by the combined input files is written in \fIoutfile\fR.
.PP
Either \fIinfile\fR or \fIoutfile\fR may be \fB\-\fR, which as
\&\fIinfile\fR means to read from standard input and as \fIoutfile\fR
means to write to standard output. If either file is omitted, it
means the same as if \fB\-\fR had been specified for that file.
You can also use the \fB\-o\fR \fIoutfile\fR option to specify the
output file.
.PP
Unless otherwise noted, or the option ends in \fB=\fR, all options
which take an argument may have that argument appear either immediately
after the option, or with a space between option and argument:
\&\fB\-Ifoo\fR and \fB\-I foo\fR have the same effect.
.PP
Many options have multi-letter names; therefore multiple single-letter
options may \fInot\fR be grouped: \fB\-dM\fR is very different from
\&\fB\-d\ \-M\fR.
.IP "\fB\-D\fR \fIname\fR" 4
.IX Item "-D name"
Predefine \fIname\fR as a macro, with definition \f(CW1\fR.
.IP "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4
.IX Item "-D name=definition"
The contents of \fIdefinition\fR are tokenized and processed as if
they appeared during translation phase three in a \fB#define\fR
directive. In particular, the definition is truncated by
embedded newline characters.
.Sp
If you are invoking the preprocessor from a shell or shell-like
program you may need to use the shell's quoting syntax to protect
characters such as spaces that have a meaning in the shell syntax.
.Sp
If you wish to define a function-like macro on the command line, write
its argument list with surrounding parentheses before the equals sign
(if any). Parentheses are meaningful to most shells, so you should
quote the option. With \fBsh\fR and \fBcsh\fR,
\&\fB\-D'\fR\fIname\fR\fB(\fR\fIargs...\fR\fB)=\fR\fIdefinition\fR\fB'\fR works.
.Sp
\&\fB\-D\fR and \fB\-U\fR options are processed in the order they
are given on the command line. All \fB\-imacros\fR \fIfile\fR and
\&\fB\-include\fR \fIfile\fR options are processed after all
\&\fB\-D\fR and \fB\-U\fR options.
.IP "\fB\-U\fR \fIname\fR" 4
.IX Item "-U name"
Cancel any previous definition of \fIname\fR, either built in or
provided with a \fB\-D\fR option.
.IP "\fB\-include\fR \fIfile\fR" 4
.IX Item "-include file"
Process \fIfile\fR as if \f(CW\*(C`#include "file"\*(C'\fR appeared as the first
line of the primary source file. However, the first directory searched
for \fIfile\fR is the preprocessor's working directory \fIinstead of\fR
the directory containing the main source file. If not found there, it
is searched for in the remainder of the \f(CW\*(C`#include "..."\*(C'\fR search
chain as normal.
.Sp
If multiple \fB\-include\fR options are given, the files are included
in the order they appear on the command line.
.IP "\fB\-imacros\fR \fIfile\fR" 4
.IX Item "-imacros file"
Exactly like \fB\-include\fR, except that any output produced by
scanning \fIfile\fR is thrown away. Macros it defines remain defined.
This allows you to acquire all the macros from a header without also
processing its declarations.
.Sp
All files specified by \fB\-imacros\fR are processed before all files
specified by \fB\-include\fR.
.IP "\fB\-undef\fR" 4
.IX Item "-undef"
Do not predefine any system-specific or GCC-specific macros. The
standard predefined macros remain defined.
.IP "\fB\-pthread\fR" 4
.IX Item "-pthread"
Define additional macros required for using the \s-1POSIX\s0 threads library.
You should use this option consistently for both compilation and linking.
This option is supported on GNU/Linux targets, most other Unix derivatives,
and also on x86 Cygwin and MinGW targets.
.IP "\fB\-M\fR" 4
.IX Item "-M"
Instead of outputting the result of preprocessing, output a rule
suitable for \fBmake\fR describing the dependencies of the main
source file. The preprocessor outputs one \fBmake\fR rule containing
the object file name for that source file, a colon, and the names of all
the included files, including those coming from \fB\-include\fR or
\&\fB\-imacros\fR command-line options.
.Sp
Unless specified explicitly (with \fB\-MT\fR or \fB\-MQ\fR), the
object file name consists of the name of the source file with any
suffix replaced with object file suffix and with any leading directory
parts removed. If there are many included files then the rule is
split into several lines using \fB\e\fR\-newline. The rule has no
commands.
.Sp
This option does not suppress the preprocessor's debug output, such as
\&\fB\-dM\fR. To avoid mixing such debug output with the dependency
rules you should explicitly specify the dependency output file with
\&\fB\-MF\fR, or use an environment variable like
\&\fB\s-1DEPENDENCIES_OUTPUT\s0\fR. Debug output
is still sent to the regular output stream as normal.
.Sp
Passing \fB\-M\fR to the driver implies \fB\-E\fR, and suppresses
warnings with an implicit \fB\-w\fR.
.IP "\fB\-MM\fR" 4
.IX Item "-MM"
Like \fB\-M\fR but do not mention header files that are found in
system header directories, nor header files that are included,
directly or indirectly, from such a header.
.Sp
This implies that the choice of angle brackets or double quotes in an
\&\fB#include\fR directive does not in itself determine whether that
header appears in \fB\-MM\fR dependency output.
.IP "\fB\-MF\fR \fIfile\fR" 4
.IX Item "-MF file"
When used with \fB\-M\fR or \fB\-MM\fR, specifies a
file to write the dependencies to. If no \fB\-MF\fR switch is given
the preprocessor sends the rules to the same place it would send
preprocessed output.
.Sp
When used with the driver options \fB\-MD\fR or \fB\-MMD\fR,
\&\fB\-MF\fR overrides the default dependency output file.
.Sp
If \fIfile\fR is \fI\-\fR, then the dependencies are written to \fIstdout\fR.
.IP "\fB\-MG\fR" 4
.IX Item "-MG"
In conjunction with an option such as \fB\-M\fR requesting
dependency generation, \fB\-MG\fR assumes missing header files are
generated files and adds them to the dependency list without raising
an error. The dependency filename is taken directly from the
\&\f(CW\*(C`#include\*(C'\fR directive without prepending any path. \fB\-MG\fR
also suppresses preprocessed output, as a missing header file renders
this useless.
.Sp
This feature is used in automatic updating of makefiles.
.IP "\fB\-Mno\-modules\fR" 4
.IX Item "-Mno-modules"
Disable dependency generation for compiled module interfaces.
.IP "\fB\-MP\fR" 4
.IX Item "-MP"
This option instructs \s-1CPP\s0 to add a phony target for each dependency
other than the main file, causing each to depend on nothing. These
dummy rules work around errors \fBmake\fR gives if you remove header
files without updating the \fIMakefile\fR to match.
.Sp
This is typical output:
.Sp
.Vb 1
\& test.o: test.c test.h
\&
\& test.h:
.Ve
.IP "\fB\-MT\fR \fItarget\fR" 4
.IX Item "-MT target"
Change the target of the rule emitted by dependency generation. By
default \s-1CPP\s0 takes the name of the main input file, deletes any
directory components and any file suffix such as \fB.c\fR, and
appends the platform's usual object suffix. The result is the target.
.Sp
An \fB\-MT\fR option sets the target to be exactly the string you
specify. If you want multiple targets, you can specify them as a single
argument to \fB\-MT\fR, or use multiple \fB\-MT\fR options.
.Sp
For example, \fB\-MT\ '$(objpfx)foo.o'\fR might give
.Sp
.Vb 1
\& $(objpfx)foo.o: foo.c
.Ve
.IP "\fB\-MQ\fR \fItarget\fR" 4
.IX Item "-MQ target"
Same as \fB\-MT\fR, but it quotes any characters which are special to
Make. \fB\-MQ\ '$(objpfx)foo.o'\fR gives
.Sp
.Vb 1
\& $$(objpfx)foo.o: foo.c
.Ve
.Sp
The default target is automatically quoted, as if it were given with
\&\fB\-MQ\fR.
.IP "\fB\-MD\fR" 4
.IX Item "-MD"
\&\fB\-MD\fR is equivalent to \fB\-M \-MF\fR \fIfile\fR, except that
\&\fB\-E\fR is not implied. The driver determines \fIfile\fR based on
whether an \fB\-o\fR option is given. If it is, the driver uses its
argument but with a suffix of \fI.d\fR, otherwise it takes the name
of the input file, removes any directory components and suffix, and
applies a \fI.d\fR suffix.
.Sp
If \fB\-MD\fR is used in conjunction with \fB\-E\fR, any
\&\fB\-o\fR switch is understood to specify the dependency output file, but if used without \fB\-E\fR, each \fB\-o\fR
is understood to specify a target object file.
.Sp
Since \fB\-E\fR is not implied, \fB\-MD\fR can be used to generate
a dependency output file as a side effect of the compilation process.
.IP "\fB\-MMD\fR" 4
.IX Item "-MMD"
Like \fB\-MD\fR except mention only user header files, not system
header files.
.IP "\fB\-fpreprocessed\fR" 4
.IX Item "-fpreprocessed"
Indicate to the preprocessor that the input file has already been
preprocessed. This suppresses things like macro expansion, trigraph
conversion, escaped newline splicing, and processing of most directives.
The preprocessor still recognizes and removes comments, so that you can
pass a file preprocessed with \fB\-C\fR to the compiler without
problems. In this mode the integrated preprocessor is little more than
a tokenizer for the front ends.
.Sp
\&\fB\-fpreprocessed\fR is implicit if the input file has one of the
extensions \fB.i\fR, \fB.ii\fR or \fB.mi\fR. These are the
extensions that \s-1GCC\s0 uses for preprocessed files created by
\&\fB\-save\-temps\fR.
.IP "\fB\-fdirectives\-only\fR" 4
.IX Item "-fdirectives-only"
When preprocessing, handle directives, but do not expand macros.
.Sp
The option's behavior depends on the \fB\-E\fR and \fB\-fpreprocessed\fR
options.
.Sp
With \fB\-E\fR, preprocessing is limited to the handling of directives
such as \f(CW\*(C`#define\*(C'\fR, \f(CW\*(C`#ifdef\*(C'\fR, and \f(CW\*(C`#error\*(C'\fR. Other
preprocessor operations, such as macro expansion and trigraph
conversion are not performed. In addition, the \fB\-dD\fR option is
implicitly enabled.
.Sp
With \fB\-fpreprocessed\fR, predefinition of command line and most
builtin macros is disabled. Macros such as \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, which are
contextually dependent, are handled normally. This enables compilation of
files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR.
.Sp
With both \fB\-E\fR and \fB\-fpreprocessed\fR, the rules for
\&\fB\-fpreprocessed\fR take precedence. This enables full preprocessing of
files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR.
.IP "\fB\-fdollars\-in\-identifiers\fR" 4
.IX Item "-fdollars-in-identifiers"
Accept \fB$\fR in identifiers.
.IP "\fB\-fextended\-identifiers\fR" 4
.IX Item "-fextended-identifiers"
Accept universal character names and extended characters in
identifiers. This option is enabled by default for C99 (and later C
standard versions) and \*(C+.
.IP "\fB\-fno\-canonical\-system\-headers\fR" 4
.IX Item "-fno-canonical-system-headers"
When preprocessing, do not shorten system header paths with canonicalization.
.IP "\fB\-fmax\-include\-depth=\fR\fIdepth\fR" 4
.IX Item "-fmax-include-depth=depth"
Set the maximum depth of the nested #include. The default is 200.
.IP "\fB\-ftabstop=\fR\fIwidth\fR" 4
.IX Item "-ftabstop=width"
Set the distance between tab stops. This helps the preprocessor report
correct column numbers in warnings or errors, even if tabs appear on the
line. If the value is less than 1 or greater than 100, the option is
ignored. The default is 8.
.IP "\fB\-ftrack\-macro\-expansion\fR[\fB=\fR\fIlevel\fR]" 4
.IX Item "-ftrack-macro-expansion[=level]"
Track locations of tokens across macro expansions. This allows the
compiler to emit diagnostic about the current macro expansion stack
when a compilation error occurs in a macro expansion. Using this
option makes the preprocessor and the compiler consume more
memory. The \fIlevel\fR parameter can be used to choose the level of
precision of token location tracking thus decreasing the memory
consumption if necessary. Value \fB0\fR of \fIlevel\fR de-activates
this option. Value \fB1\fR tracks tokens locations in a
degraded mode for the sake of minimal memory overhead. In this mode
all tokens resulting from the expansion of an argument of a
function-like macro have the same location. Value \fB2\fR tracks
tokens locations completely. This value is the most memory hungry.
When this option is given no argument, the default parameter value is
\&\fB2\fR.
.Sp
Note that \f(CW\*(C`\-ftrack\-macro\-expansion=2\*(C'\fR is activated by default.
.IP "\fB\-fmacro\-prefix\-map=\fR\fIold\fR\fB=\fR\fInew\fR" 4
.IX Item "-fmacro-prefix-map=old=new"
When preprocessing files residing in directory \fI\fIold\fI\fR,
expand the \f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_BASE_FILE_\|_\*(C'\fR macros as if the
files resided in directory \fI\fInew\fI\fR instead. This can be used
to change an absolute path to a relative path by using \fI.\fR for
\&\fInew\fR which can result in more reproducible builds that are
location independent. This option also affects
\&\f(CW\*(C`_\|_builtin_FILE()\*(C'\fR during compilation. See also
\&\fB\-ffile\-prefix\-map\fR and \fB\-fcanon\-prefix\-map\fR.
.IP "\fB\-fexec\-charset=\fR\fIcharset\fR" 4
.IX Item "-fexec-charset=charset"
Set the execution character set, used for string and character
constants. The default is \s-1UTF\-8.\s0 \fIcharset\fR can be any encoding
supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine.
.IP "\fB\-fwide\-exec\-charset=\fR\fIcharset\fR" 4
.IX Item "-fwide-exec-charset=charset"
Set the wide execution character set, used for wide string and
character constants. The default is one of \s-1UTF\-32BE, UTF\-32LE, UTF\-16BE,\s0
or \s-1UTF\-16LE,\s0 whichever corresponds to the width of \f(CW\*(C`wchar_t\*(C'\fR and the
big-endian or little-endian byte order being used for code generation. As
with \fB\-fexec\-charset\fR, \fIcharset\fR can be any encoding supported
by the system's \f(CW\*(C`iconv\*(C'\fR library routine; however, you will have
problems with encodings that do not fit exactly in \f(CW\*(C`wchar_t\*(C'\fR.
.IP "\fB\-finput\-charset=\fR\fIcharset\fR" 4
.IX Item "-finput-charset=charset"
Set the input character set, used for translation from the character
set of the input file to the source character set used by \s-1GCC.\s0 If the
locale does not specify, or \s-1GCC\s0 cannot get this information from the
locale, the default is \s-1UTF\-8.\s0 This can be overridden by either the locale
or this command-line option. Currently the command-line option takes
precedence if there's a conflict. \fIcharset\fR can be any encoding
supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine.
.IP "\fB\-fworking\-directory\fR" 4
.IX Item "-fworking-directory"
Enable generation of linemarkers in the preprocessor output that
let the compiler know the current working directory at the time of
preprocessing. When this option is enabled, the preprocessor
emits, after the initial linemarker, a second linemarker with the
current working directory followed by two slashes. \s-1GCC\s0 uses this
directory, when it's present in the preprocessed input, as the
directory emitted as the current working directory in some debugging
information formats. This option is implicitly enabled if debugging
information is enabled, but this can be inhibited with the negated
form \fB\-fno\-working\-directory\fR. If the \fB\-P\fR flag is
present in the command line, this option has no effect, since no
\&\f(CW\*(C`#line\*(C'\fR directives are emitted whatsoever.
.IP "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4
.IX Item "-A predicate=answer"
Make an assertion with the predicate \fIpredicate\fR and answer
\&\fIanswer\fR. This form is preferred to the older form \fB\-A\fR
\&\fIpredicate\fR\fB(\fR\fIanswer\fR\fB)\fR, which is still supported, because
it does not use shell special characters.
.IP "\fB\-A \-\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4
.IX Item "-A -predicate=answer"
Cancel an assertion with the predicate \fIpredicate\fR and answer
\&\fIanswer\fR.
.IP "\fB\-C\fR" 4
.IX Item "-C"
Do not discard comments. All comments are passed through to the output
file, except for comments in processed directives, which are deleted
along with the directive.
.Sp
You should be prepared for side effects when using \fB\-C\fR; it
causes the preprocessor to treat comments as tokens in their own right.
For example, comments appearing at the start of what would be a
directive line have the effect of turning that line into an ordinary
source line, since the first token on the line is no longer a \fB#\fR.
.IP "\fB\-CC\fR" 4
.IX Item "-CC"
Do not discard comments, including during macro expansion. This is
like \fB\-C\fR, except that comments contained within macros are
also passed through to the output file where the macro is expanded.
.Sp
In addition to the side effects of the \fB\-C\fR option, the
\&\fB\-CC\fR option causes all \*(C+\-style comments inside a macro
to be converted to C\-style comments. This is to prevent later use
of that macro from inadvertently commenting out the remainder of
the source line.
.Sp
The \fB\-CC\fR option is generally used to support lint comments.
.IP "\fB\-P\fR" 4
.IX Item "-P"
Inhibit generation of linemarkers in the output from the preprocessor.
This might be useful when running the preprocessor on something that is
not C code, and will be sent to a program which might be confused by the
linemarkers.
.IP "\fB\-traditional\fR" 4
.IX Item "-traditional"
.PD 0
.IP "\fB\-traditional\-cpp\fR" 4
.IX Item "-traditional-cpp"
.PD
Try to imitate the behavior of pre-standard C preprocessors, as
opposed to \s-1ISO C\s0 preprocessors.
.Sp
Note that \s-1GCC\s0 does not otherwise attempt to emulate a pre-standard
C compiler, and these options are only supported with the \fB\-E\fR
switch, or when invoking \s-1CPP\s0 explicitly.
.IP "\fB\-trigraphs\fR" 4
.IX Item "-trigraphs"
Support \s-1ISO C\s0 trigraphs.
These are three-character sequences, all starting with \fB??\fR, that
are defined by \s-1ISO C\s0 to stand for single characters. For example,
\&\fB??/\fR stands for \fB\e\fR, so \fB'??/n'\fR is a character
constant for a newline.
.Sp
By default, \s-1GCC\s0 ignores trigraphs, but in
standard-conforming modes it converts them. See the \fB\-std\fR and
\&\fB\-ansi\fR options.
.IP "\fB\-remap\fR" 4
.IX Item "-remap"
Enable special code to work around file systems which only permit very
short file names, such as MS-DOS.
.IP "\fB\-H\fR" 4
.IX Item "-H"
Print the name of each header file used, in addition to other normal
activities. Each name is indented to show how deep in the
\&\fB#include\fR stack it is. Precompiled header files are also
printed, even if they are found to be invalid; an invalid precompiled
header file is printed with \fB...x\fR and a valid one with \fB...!\fR .
.IP "\fB\-d\fR\fIletters\fR" 4
.IX Item "-dletters"
Says to make debugging dumps during compilation as specified by
\&\fIletters\fR. The flags documented here are those relevant to the
preprocessor. Other \fIletters\fR are interpreted
by the compiler proper, or reserved for future versions of \s-1GCC,\s0 and so
are silently ignored. If you specify \fIletters\fR whose behavior
conflicts, the result is undefined.
.RS 4
.IP "\fB\-dM\fR" 4
.IX Item "-dM"
Instead of the normal output, generate a list of \fB#define\fR
directives for all the macros defined during the execution of the
preprocessor, including predefined macros. This gives you a way of
finding out what is predefined in your version of the preprocessor.
Assuming you have no file \fIfoo.h\fR, the command
.Sp
.Vb 1
\& touch foo.h; cpp \-dM foo.h
.Ve
.Sp
shows all the predefined macros.
.IP "\fB\-dD\fR" 4
.IX Item "-dD"
Like \fB\-dM\fR except in two respects: it does \fInot\fR include the
predefined macros, and it outputs \fIboth\fR the \fB#define\fR
directives and the result of preprocessing. Both kinds of output go to
the standard output file.
.IP "\fB\-dN\fR" 4
.IX Item "-dN"
Like \fB\-dD\fR, but emit only the macro names, not their expansions.
.IP "\fB\-dI\fR" 4
.IX Item "-dI"
Output \fB#include\fR directives in addition to the result of
preprocessing.
.IP "\fB\-dU\fR" 4
.IX Item "-dU"
Like \fB\-dD\fR except that only macros that are expanded, or whose
definedness is tested in preprocessor directives, are output; the
output is delayed until the use or test of the macro; and
\&\fB#undef\fR directives are also output for macros tested but
undefined at the time.
.RE
.RS 4
.RE
.IP "\fB\-fdebug\-cpp\fR" 4
.IX Item "-fdebug-cpp"
This option is only useful for debugging \s-1GCC.\s0 When used from \s-1CPP\s0 or with
\&\fB\-E\fR, it dumps debugging information about location maps. Every
token in the output is preceded by the dump of the map its location
belongs to.
.Sp
When used from \s-1GCC\s0 without \fB\-E\fR, this option has no effect.
.IP "\fB\-I\fR \fIdir\fR" 4
.IX Item "-I dir"
.PD 0
.IP "\fB\-iquote\fR \fIdir\fR" 4
.IX Item "-iquote dir"
.IP "\fB\-isystem\fR \fIdir\fR" 4
.IX Item "-isystem dir"
.IP "\fB\-idirafter\fR \fIdir\fR" 4
.IX Item "-idirafter dir"
.PD
Add the directory \fIdir\fR to the list of directories to be searched
for header files during preprocessing.
.Sp
If \fIdir\fR begins with \fB=\fR or \f(CW$SYSROOT\fR, then the \fB=\fR
or \f(CW$SYSROOT\fR is replaced by the sysroot prefix; see
\&\fB\-\-sysroot\fR and \fB\-isysroot\fR.
.Sp
Directories specified with \fB\-iquote\fR apply only to the quote
form of the directive, \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR.
Directories specified with \fB\-I\fR, \fB\-isystem\fR,
or \fB\-idirafter\fR apply to lookup for both the
\&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR and
\&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR directives.
.Sp
You can specify any number or combination of these options on the
command line to search for header files in several directories.
The lookup order is as follows:
.RS 4
.IP "1." 4
.IX Item "1."
For the quote form of the include directive, the directory of the current
file is searched first.
.IP "2." 4
.IX Item "2."
For the quote form of the include directive, the directories specified
by \fB\-iquote\fR options are searched in left-to-right order,
as they appear on the command line.
.IP "3." 4
.IX Item "3."
Directories specified with \fB\-I\fR options are scanned in
left-to-right order.
.IP "4." 4
.IX Item "4."
Directories specified with \fB\-isystem\fR options are scanned in
left-to-right order.
.IP "5." 4
.IX Item "5."
Standard system directories are scanned.
.IP "6." 4
.IX Item "6."
Directories specified with \fB\-idirafter\fR options are scanned in
left-to-right order.
.RE
.RS 4
.Sp
You can use \fB\-I\fR to override a system header
file, substituting your own version, since these directories are
searched before the standard system header file directories.
However, you should
not use this option to add directories that contain vendor-supplied
system header files; use \fB\-isystem\fR for that.
.Sp
The \fB\-isystem\fR and \fB\-idirafter\fR options also mark the directory
as a system directory, so that it gets the same special treatment that
is applied to the standard system directories.
.Sp
If a standard system include directory, or a directory specified with
\&\fB\-isystem\fR, is also specified with \fB\-I\fR, the \fB\-I\fR
option is ignored. The directory is still searched but as a
system directory at its normal position in the system include chain.
This is to ensure that \s-1GCC\s0's procedure to fix buggy system headers and
the ordering for the \f(CW\*(C`#include_next\*(C'\fR directive are not inadvertently
changed.
If you really need to change the search order for system directories,
use the \fB\-nostdinc\fR and/or \fB\-isystem\fR options.
.RE
.IP "\fB\-I\-\fR" 4
.IX Item "-I-"
Split the include path.
This option has been deprecated. Please use \fB\-iquote\fR instead for
\&\fB\-I\fR directories before the \fB\-I\-\fR and remove the \fB\-I\-\fR
option.
.Sp
Any directories specified with \fB\-I\fR
options before \fB\-I\-\fR are searched only for headers requested with
\&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for
\&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR. If additional directories are
specified with \fB\-I\fR options after the \fB\-I\-\fR, those
directories are searched for all \fB#include\fR directives.
.Sp
In addition, \fB\-I\-\fR inhibits the use of the directory of the current
file directory as the first search directory for \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR. There is no way to override this effect of \fB\-I\-\fR.
.IP "\fB\-iprefix\fR \fIprefix\fR" 4
.IX Item "-iprefix prefix"
Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR
options. If the prefix represents a directory, you should include the
final \fB/\fR.
.IP "\fB\-iwithprefix\fR \fIdir\fR" 4
.IX Item "-iwithprefix dir"
.PD 0
.IP "\fB\-iwithprefixbefore\fR \fIdir\fR" 4
.IX Item "-iwithprefixbefore dir"
.PD
Append \fIdir\fR to the prefix specified previously with
\&\fB\-iprefix\fR, and add the resulting directory to the include search
path. \fB\-iwithprefixbefore\fR puts it in the same place \fB\-I\fR
would; \fB\-iwithprefix\fR puts it where \fB\-idirafter\fR would.
.IP "\fB\-isysroot\fR \fIdir\fR" 4
.IX Item "-isysroot dir"
This option is like the \fB\-\-sysroot\fR option, but applies only to
header files (except for Darwin targets, where it applies to both header
files and libraries). See the \fB\-\-sysroot\fR option for more
information.
.IP "\fB\-imultilib\fR \fIdir\fR" 4
.IX Item "-imultilib dir"
Use \fIdir\fR as a subdirectory of the directory containing
target-specific \*(C+ headers.
.IP "\fB\-nostdinc\fR" 4
.IX Item "-nostdinc"
Do not search the standard system directories for header files.
Only the directories explicitly specified with \fB\-I\fR,
\&\fB\-iquote\fR, \fB\-isystem\fR, and/or \fB\-idirafter\fR
options (and the directory of the current file, if appropriate)
are searched.
.IP "\fB\-nostdinc++\fR" 4
.IX Item "-nostdinc++"
Do not search for header files in the \*(C+\-specific standard directories,
but do still search the other standard directories. (This option is
used when building the \*(C+ library.)
.IP "\fB\-Wcomment\fR" 4
.IX Item "-Wcomment"
.PD 0
.IP "\fB\-Wcomments\fR" 4
.IX Item "-Wcomments"
.PD
Warn whenever a comment-start sequence \fB/*\fR appears in a \fB/*\fR
comment, or whenever a backslash-newline appears in a \fB//\fR comment.
This warning is enabled by \fB\-Wall\fR.
.IP "\fB\-Wtrigraphs\fR" 4
.IX Item "-Wtrigraphs"
Warn if any trigraphs are encountered that might change the meaning of
the program. Trigraphs within comments are not warned about,
except those that would form escaped newlines.
.Sp
This option is implied by \fB\-Wall\fR. If \fB\-Wall\fR is not
given, this option is still enabled unless trigraphs are enabled. To
get trigraph conversion without warnings, but get the other
\&\fB\-Wall\fR warnings, use \fB\-trigraphs \-Wall \-Wno\-trigraphs\fR.
.IP "\fB\-Wundef\fR" 4
.IX Item "-Wundef"
Warn if an undefined identifier is evaluated in an \f(CW\*(C`#if\*(C'\fR directive.
Such identifiers are replaced with zero.
.IP "\fB\-Wexpansion\-to\-defined\fR" 4
.IX Item "-Wexpansion-to-defined"
Warn whenever \fBdefined\fR is encountered in the expansion of a macro
(including the case where the macro is expanded by an \fB#if\fR directive).
Such usage is not portable.
This warning is also enabled by \fB\-Wpedantic\fR and \fB\-Wextra\fR.
.IP "\fB\-Wunused\-macros\fR" 4
.IX Item "-Wunused-macros"
Warn about macros defined in the main file that are unused. A macro
is \fIused\fR if it is expanded or tested for existence at least once.
The preprocessor also warns if the macro has not been used at the
time it is redefined or undefined.
.Sp
Built-in macros, macros defined on the command line, and macros
defined in include files are not warned about.
.Sp
\&\fINote:\fR If a macro is actually used, but only used in skipped
conditional blocks, then the preprocessor reports it as unused. To avoid the
warning in such a case, you might improve the scope of the macro's
definition by, for example, moving it into the first skipped block.
Alternatively, you could provide a dummy use with something like:
.Sp
.Vb 2
\& #if defined the_macro_causing_the_warning
\& #endif
.Ve
.IP "\fB\-Wno\-endif\-labels\fR" 4
.IX Item "-Wno-endif-labels"
Do not warn whenever an \f(CW\*(C`#else\*(C'\fR or an \f(CW\*(C`#endif\*(C'\fR are followed by text.
This sometimes happens in older programs with code of the form
.Sp
.Vb 5
\& #if FOO
\& ...
\& #else FOO
\& ...
\& #endif FOO
.Ve
.Sp
The second and third \f(CW\*(C`FOO\*(C'\fR should be in comments.
This warning is on by default.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
This section describes the environment variables that affect how \s-1CPP\s0
operates. You can use them to specify directories or prefixes to use
when searching for include files, or to control dependency output.
.PP
Note that you can also specify places to search using options such as
\&\fB\-I\fR, and control dependency output with options like
\&\fB\-M\fR. These take precedence over
environment variables, which in turn take precedence over the
configuration of \s-1GCC.\s0
.IP "\fB\s-1CPATH\s0\fR" 4
.IX Item "CPATH"
.PD 0
.IP "\fBC_INCLUDE_PATH\fR" 4
.IX Item "C_INCLUDE_PATH"
.IP "\fB\s-1CPLUS_INCLUDE_PATH\s0\fR" 4
.IX Item "CPLUS_INCLUDE_PATH"
.IP "\fB\s-1OBJC_INCLUDE_PATH\s0\fR" 4
.IX Item "OBJC_INCLUDE_PATH"
.PD
Each variable's value is a list of directories separated by a special
character, much like \fB\s-1PATH\s0\fR, in which to look for header files.
The special character, \f(CW\*(C`PATH_SEPARATOR\*(C'\fR, is target-dependent and
determined at \s-1GCC\s0 build time. For Microsoft Windows-based targets it is a
semicolon, and for almost all other targets it is a colon.
.Sp
\&\fB\s-1CPATH\s0\fR specifies a list of directories to be searched as if
specified with \fB\-I\fR, but after any paths given with \fB\-I\fR
options on the command line. This environment variable is used
regardless of which language is being preprocessed.
.Sp
The remaining environment variables apply only when preprocessing the
particular language indicated. Each specifies a list of directories
to be searched as if specified with \fB\-isystem\fR, but after any
paths given with \fB\-isystem\fR options on the command line.
.Sp
In all these variables, an empty element instructs the compiler to
search its current working directory. Empty elements can appear at the
beginning or end of a path. For instance, if the value of
\&\fB\s-1CPATH\s0\fR is \f(CW\*(C`:/special/include\*(C'\fR, that has the same
effect as \fB\-I.\ \-I/special/include\fR.
.IP "\fB\s-1DEPENDENCIES_OUTPUT\s0\fR" 4
.IX Item "DEPENDENCIES_OUTPUT"
If this variable is set, its value specifies how to output
dependencies for Make based on the non-system header files processed
by the compiler. System header files are ignored in the dependency
output.
.Sp
The value of \fB\s-1DEPENDENCIES_OUTPUT\s0\fR can be just a file name, in
which case the Make rules are written to that file, guessing the target
name from the source file name. Or the value can have the form
\&\fIfile\fR\fB \fR\fItarget\fR, in which case the rules are written to
file \fIfile\fR using \fItarget\fR as the target name.
.Sp
In other words, this environment variable is equivalent to combining
the options \fB\-MM\fR and \fB\-MF\fR,
with an optional \fB\-MT\fR switch too.
.IP "\fB\s-1SUNPRO_DEPENDENCIES\s0\fR" 4
.IX Item "SUNPRO_DEPENDENCIES"
This variable is the same as \fB\s-1DEPENDENCIES_OUTPUT\s0\fR (see above),
except that system header files are not ignored, so it implies
\&\fB\-M\fR rather than \fB\-MM\fR. However, the dependence on the
main input file is omitted.
.IP "\fB\s-1SOURCE_DATE_EPOCH\s0\fR" 4
.IX Item "SOURCE_DATE_EPOCH"
If this variable is set, its value specifies a \s-1UNIX\s0 timestamp to be
used in replacement of the current date and time in the \f(CW\*(C`_\|_DATE_\|_\*(C'\fR
and \f(CW\*(C`_\|_TIME_\|_\*(C'\fR macros, so that the embedded timestamps become
reproducible.
.Sp
The value of \fB\s-1SOURCE_DATE_EPOCH\s0\fR must be a \s-1UNIX\s0 timestamp,
defined as the number of seconds (excluding leap seconds) since
01 Jan 1970 00:00:00 represented in \s-1ASCII\s0; identical to the output of
\&\f(CW\*(C`date +%s\*(C'\fR on GNU/Linux and other systems that support the
\&\f(CW%s\fR extension in the \f(CW\*(C`date\*(C'\fR command.
.Sp
The value should be a known timestamp such as the last modification
time of the source or package and it should be set by the build
process.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBgpl\fR\|(7), \fBgfdl\fR\|(7), \fBfsf\-funding\fR\|(7),
\&\fBgcc\fR\|(1), and the Info entries for \fIcpp\fR and \fIgcc\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1987\-2023 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation. A copy of
the license is included in the
man page \fBgfdl\fR\|(7).
This manual contains no Invariant Sections. The Front-Cover Texts are
(a) (see below), and the Back-Cover Texts are (b) (see below).
.PP
(a) The \s-1FSF\s0's Front-Cover Text is:
.PP
.Vb 1
\& A GNU Manual
.Ve
.PP
(b) The \s-1FSF\s0's Back-Cover Text is:
.PP
.Vb 3
\& You have freedom to copy and modify this GNU Manual, like GNU
\& software. Copies published by the Free Software Foundation raise
\& funds for GNU development.
.Ve

554
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-dlltool.1 Normal file
View File

@ -0,0 +1,554 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DLLTOOL 1"
.TH DLLTOOL 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dlltool \- create files needed to build and use DLLs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
dlltool [\fB\-d\fR|\fB\-\-input\-def\fR \fIdef-file-name\fR]
[\fB\-b\fR|\fB\-\-base\-file\fR \fIbase-file-name\fR]
[\fB\-e\fR|\fB\-\-output\-exp\fR \fIexports-file-name\fR]
[\fB\-z\fR|\fB\-\-output\-def\fR \fIdef-file-name\fR]
[\fB\-l\fR|\fB\-\-output\-lib\fR \fIlibrary-file-name\fR]
[\fB\-y\fR|\fB\-\-output\-delaylib\fR \fIlibrary-file-name\fR]
[\fB\-\-export\-all\-symbols\fR] [\fB\-\-no\-export\-all\-symbols\fR]
[\fB\-\-exclude\-symbols\fR \fIlist\fR]
[\fB\-\-no\-default\-excludes\fR]
[\fB\-S\fR|\fB\-\-as\fR \fIpath-to-assembler\fR] [\fB\-f\fR|\fB\-\-as\-flags\fR \fIoptions\fR]
[\fB\-D\fR|\fB\-\-dllname\fR \fIname\fR] [\fB\-m\fR|\fB\-\-machine\fR \fImachine\fR]
[\fB\-a\fR|\fB\-\-add\-indirect\fR]
[\fB\-U\fR|\fB\-\-add\-underscore\fR] [\fB\-\-add\-stdcall\-underscore\fR]
[\fB\-k\fR|\fB\-\-kill\-at\fR] [\fB\-A\fR|\fB\-\-add\-stdcall\-alias\fR]
[\fB\-p\fR|\fB\-\-ext\-prefix\-alias\fR \fIprefix\fR]
[\fB\-x\fR|\fB\-\-no\-idata4\fR] [\fB\-c\fR|\fB\-\-no\-idata5\fR]
[\fB\-\-use\-nul\-prefixed\-import\-tables\fR]
[\fB\-I\fR|\fB\-\-identify\fR \fIlibrary-file-name\fR] [\fB\-\-identify\-strict\fR]
[\fB\-i\fR|\fB\-\-interwork\fR]
[\fB\-n\fR|\fB\-\-nodelete\fR] [\fB\-t\fR|\fB\-\-temp\-prefix\fR \fIprefix\fR]
[\fB\-v\fR|\fB\-\-verbose\fR]
[\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR]
[\fB\-\-no\-leading\-underscore\fR] [\fB\-\-leading\-underscore\fR]
[\fB\-\-deterministic\-libraries\fR] [\fB\-\-non\-deterministic\-libraries\fR]
[object\-file ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdlltool\fR reads its inputs, which can come from the \fB\-d\fR and
\&\fB\-b\fR options as well as object files specified on the command
line. It then processes these inputs and if the \fB\-e\fR option has
been specified it creates a exports file. If the \fB\-l\fR option
has been specified it creates a library file and if the \fB\-z\fR option
has been specified it creates a def file. Any or all of the \fB\-e\fR,
\&\fB\-l\fR and \fB\-z\fR options can be present in one invocation of
dlltool.
.PP
When creating a \s-1DLL,\s0 along with the source for the \s-1DLL,\s0 it is necessary
to have three other files. \fBdlltool\fR can help with the creation of
these files.
.PP
The first file is a \fI.def\fR file which specifies which functions are
exported from the \s-1DLL,\s0 which functions the \s-1DLL\s0 imports, and so on. This
is a text file and can be created by hand, or \fBdlltool\fR can be used
to create it using the \fB\-z\fR option. In this case \fBdlltool\fR
will scan the object files specified on its command line looking for
those functions which have been specially marked as being exported and
put entries for them in the \fI.def\fR file it creates.
.PP
In order to mark a function as being exported from a \s-1DLL,\s0 it needs to
have an \fB\-export:<name_of_function>\fR entry in the \fB.drectve\fR
section of the object file. This can be done in C by using the
\&\fBasm()\fR operator:
.PP
.Vb 2
\& asm (".section .drectve");
\& asm (".ascii \e"\-export:my_func\e"");
\&
\& int my_func (void) { ... }
.Ve
.PP
The second file needed for \s-1DLL\s0 creation is an exports file. This file
is linked with the object files that make up the body of the \s-1DLL\s0 and it
handles the interface between the \s-1DLL\s0 and the outside world. This is a
binary file and it can be created by giving the \fB\-e\fR option to
\&\fBdlltool\fR when it is creating or reading in a \fI.def\fR file.
.PP
The third file needed for \s-1DLL\s0 creation is the library file that programs
will link with in order to access the functions in the \s-1DLL\s0 (an `import
library'). This file can be created by giving the \fB\-l\fR option to
dlltool when it is creating or reading in a \fI.def\fR file.
.PP
If the \fB\-y\fR option is specified, dlltool generates a delay-import
library that can be used instead of the normal import library to allow
a program to link to the dll only as soon as an imported function is
called for the first time. The resulting executable will need to be
linked to the static delayimp library containing _\|\fB_delayLoadHelper2()\fR,
which in turn will import LoadLibraryA and GetProcAddress from kernel32.
.PP
\&\fBdlltool\fR builds the library file by hand, but it builds the
exports file by creating temporary files containing assembler statements
and then assembling these. The \fB\-S\fR command-line option can be
used to specify the path to the assembler that dlltool will use,
and the \fB\-f\fR option can be used to pass specific flags to that
assembler. The \fB\-n\fR can be used to prevent dlltool from deleting
these temporary assembler files when it is done, and if \fB\-n\fR is
specified twice then this will prevent dlltool from deleting the
temporary object files it used to build the library.
.PP
Here is an example of creating a \s-1DLL\s0 from a source file \fBdll.c\fR and
also creating a program (from an object file called \fBprogram.o\fR)
that uses that \s-1DLL:\s0
.PP
.Vb 4
\& gcc \-c dll.c
\& dlltool \-e exports.o \-l dll.lib dll.o
\& gcc dll.o exports.o \-o dll.dll
\& gcc program.o dll.lib \-o program
.Ve
.PP
\&\fBdlltool\fR may also be used to query an existing import library
to determine the name of the \s-1DLL\s0 to which it is associated. See the
description of the \fB\-I\fR or \fB\-\-identify\fR option.
.SH "OPTIONS"
.IX Header "OPTIONS"
The command-line options have the following meanings:
.IP "\fB\-d\fR \fIfilename\fR" 4
.IX Item "-d filename"
.PD 0
.IP "\fB\-\-input\-def\fR \fIfilename\fR" 4
.IX Item "--input-def filename"
.PD
Specifies the name of a \fI.def\fR file to be read in and processed.
.IP "\fB\-b\fR \fIfilename\fR" 4
.IX Item "-b filename"
.PD 0
.IP "\fB\-\-base\-file\fR \fIfilename\fR" 4
.IX Item "--base-file filename"
.PD
Specifies the name of a base file to be read in and processed. The
contents of this file will be added to the relocation section in the
exports file generated by dlltool.
.IP "\fB\-e\fR \fIfilename\fR" 4
.IX Item "-e filename"
.PD 0
.IP "\fB\-\-output\-exp\fR \fIfilename\fR" 4
.IX Item "--output-exp filename"
.PD
Specifies the name of the export file to be created by dlltool.
.IP "\fB\-z\fR \fIfilename\fR" 4
.IX Item "-z filename"
.PD 0
.IP "\fB\-\-output\-def\fR \fIfilename\fR" 4
.IX Item "--output-def filename"
.PD
Specifies the name of the \fI.def\fR file to be created by dlltool.
.IP "\fB\-l\fR \fIfilename\fR" 4
.IX Item "-l filename"
.PD 0
.IP "\fB\-\-output\-lib\fR \fIfilename\fR" 4
.IX Item "--output-lib filename"
.PD
Specifies the name of the library file to be created by dlltool.
.IP "\fB\-y\fR \fIfilename\fR" 4
.IX Item "-y filename"
.PD 0
.IP "\fB\-\-output\-delaylib\fR \fIfilename\fR" 4
.IX Item "--output-delaylib filename"
.PD
Specifies the name of the delay-import library file to be created by dlltool.
.IP "\fB\-\-deterministic\-libraries\fR" 4
.IX Item "--deterministic-libraries"
.PD 0
.IP "\fB\-\-non\-deterministic\-libraries\fR" 4
.IX Item "--non-deterministic-libraries"
.PD
When creating output libraries in response to either the
\&\fB\-\-output\-lib\fR or \fB\-\-output\-delaylib\fR options either use
the value of zero for any timestamps, user ids and group ids created
(\fB\-\-deterministic\-libraries\fR) or the actual timestamps, user
ids and group ids (\fB\-\-non\-deterministic\-libraries\fR).
.IP "\fB\-\-export\-all\-symbols\fR" 4
.IX Item "--export-all-symbols"
Treat all global and weak defined symbols found in the input object
files as symbols to be exported. There is a small list of symbols which
are not exported by default; see the \fB\-\-no\-default\-excludes\fR
option. You may add to the list of symbols to not export by using the
\&\fB\-\-exclude\-symbols\fR option.
.IP "\fB\-\-no\-export\-all\-symbols\fR" 4
.IX Item "--no-export-all-symbols"
Only export symbols explicitly listed in an input \fI.def\fR file or in
\&\fB.drectve\fR sections in the input object files. This is the default
behaviour. The \fB.drectve\fR sections are created by \fBdllexport\fR
attributes in the source code.
.IP "\fB\-\-exclude\-symbols\fR \fIlist\fR" 4
.IX Item "--exclude-symbols list"
Do not export the symbols in \fIlist\fR. This is a list of symbol names
separated by comma or colon characters. The symbol names should not
contain a leading underscore. This is only meaningful when
\&\fB\-\-export\-all\-symbols\fR is used.
.IP "\fB\-\-no\-default\-excludes\fR" 4
.IX Item "--no-default-excludes"
When \fB\-\-export\-all\-symbols\fR is used, it will by default avoid
exporting certain special symbols. The current list of symbols to avoid
exporting is \fBDllMain@12\fR, \fBDllEntryPoint@0\fR,
\&\fBimpure_ptr\fR. You may use the \fB\-\-no\-default\-excludes\fR option
to go ahead and export these special symbols. This is only meaningful
when \fB\-\-export\-all\-symbols\fR is used.
.IP "\fB\-S\fR \fIpath\fR" 4
.IX Item "-S path"
.PD 0
.IP "\fB\-\-as\fR \fIpath\fR" 4
.IX Item "--as path"
.PD
Specifies the path, including the filename, of the assembler to be used
to create the exports file.
.IP "\fB\-f\fR \fIoptions\fR" 4
.IX Item "-f options"
.PD 0
.IP "\fB\-\-as\-flags\fR \fIoptions\fR" 4
.IX Item "--as-flags options"
.PD
Specifies any specific command-line options to be passed to the
assembler when building the exports file. This option will work even if
the \fB\-S\fR option is not used. This option only takes one argument,
and if it occurs more than once on the command line, then later
occurrences will override earlier occurrences. So if it is necessary to
pass multiple options to the assembler they should be enclosed in
double quotes.
.IP "\fB\-D\fR \fIname\fR" 4
.IX Item "-D name"
.PD 0
.IP "\fB\-\-dll\-name\fR \fIname\fR" 4
.IX Item "--dll-name name"
.PD
Specifies the name to be stored in the \fI.def\fR file as the name of
the \s-1DLL\s0 when the \fB\-e\fR option is used. If this option is not
present, then the filename given to the \fB\-e\fR option will be
used as the name of the \s-1DLL.\s0
.IP "\fB\-m\fR \fImachine\fR" 4
.IX Item "-m machine"
.PD 0
.IP "\fB\-machine\fR \fImachine\fR" 4
.IX Item "-machine machine"
.PD
Specifies the type of machine for which the library file should be
built. \fBdlltool\fR has a built in default type, depending upon how
it was created, but this option can be used to override that. This is
normally only useful when creating DLLs for an \s-1ARM\s0 processor, when the
contents of the \s-1DLL\s0 are actually encode using Thumb instructions.
.IP "\fB\-a\fR" 4
.IX Item "-a"
.PD 0
.IP "\fB\-\-add\-indirect\fR" 4
.IX Item "--add-indirect"
.PD
Specifies that when \fBdlltool\fR is creating the exports file it
should add a section which allows the exported functions to be
referenced without using the import library. Whatever the hell that
means!
.IP "\fB\-U\fR" 4
.IX Item "-U"
.PD 0
.IP "\fB\-\-add\-underscore\fR" 4
.IX Item "--add-underscore"
.PD
Specifies that when \fBdlltool\fR is creating the exports file it
should prepend an underscore to the names of \fIall\fR exported symbols.
.IP "\fB\-\-no\-leading\-underscore\fR" 4
.IX Item "--no-leading-underscore"
.PD 0
.IP "\fB\-\-leading\-underscore\fR" 4
.IX Item "--leading-underscore"
.PD
Specifies whether standard symbol should be forced to be prefixed, or
not.
.IP "\fB\-\-add\-stdcall\-underscore\fR" 4
.IX Item "--add-stdcall-underscore"
Specifies that when \fBdlltool\fR is creating the exports file it
should prepend an underscore to the names of exported \fIstdcall\fR
functions. Variable names and non-stdcall function names are not modified.
This option is useful when creating GNU-compatible import libs for third
party DLLs that were built with MS-Windows tools.
.IP "\fB\-k\fR" 4
.IX Item "-k"
.PD 0
.IP "\fB\-\-kill\-at\fR" 4
.IX Item "--kill-at"
.PD
Specifies that \fB@<number>\fR suffixes should be omitted from the names
of stdcall functions that will be imported from the \s-1DLL.\s0 This is
useful when creating an import library for a \s-1DLL\s0 which exports stdcall
functions but without the usual \fB@<number>\fR symbol name suffix.
.Sp
This does not change the naming of symbols provided by the import library
to programs linked against it, but only the entries in the import table
(ie the .idata section).
.IP "\fB\-A\fR" 4
.IX Item "-A"
.PD 0
.IP "\fB\-\-add\-stdcall\-alias\fR" 4
.IX Item "--add-stdcall-alias"
.PD
Specifies that when \fBdlltool\fR is creating the exports file it
should add aliases for stdcall symbols without \fB@ <number>\fR
in addition to the symbols with \fB@ <number>\fR.
.IP "\fB\-p\fR" 4
.IX Item "-p"
.PD 0
.IP "\fB\-\-ext\-prefix\-alias\fR \fIprefix\fR" 4
.IX Item "--ext-prefix-alias prefix"
.PD
Causes \fBdlltool\fR to create external aliases for all \s-1DLL\s0
imports with the specified prefix. The aliases are created for both
external and import symbols with no leading underscore.
.IP "\fB\-x\fR" 4
.IX Item "-x"
.PD 0
.IP "\fB\-\-no\-idata4\fR" 4
.IX Item "--no-idata4"
.PD
Specifies that when \fBdlltool\fR is creating the exports and library
files it should omit the \f(CW\*(C`.idata4\*(C'\fR section. This is for compatibility
with certain operating systems.
.IP "\fB\-\-use\-nul\-prefixed\-import\-tables\fR" 4
.IX Item "--use-nul-prefixed-import-tables"
Specifies that when \fBdlltool\fR is creating the exports and library
files it should prefix the \f(CW\*(C`.idata4\*(C'\fR and \f(CW\*(C`.idata5\*(C'\fR by zero an
element. This emulates old gnu import library generation of
\&\f(CW\*(C`dlltool\*(C'\fR. By default this option is turned off.
.IP "\fB\-c\fR" 4
.IX Item "-c"
.PD 0
.IP "\fB\-\-no\-idata5\fR" 4
.IX Item "--no-idata5"
.PD
Specifies that when \fBdlltool\fR is creating the exports and library
files it should omit the \f(CW\*(C`.idata5\*(C'\fR section. This is for compatibility
with certain operating systems.
.IP "\fB\-I\fR \fIfilename\fR" 4
.IX Item "-I filename"
.PD 0
.IP "\fB\-\-identify\fR \fIfilename\fR" 4
.IX Item "--identify filename"
.PD
Specifies that \fBdlltool\fR should inspect the import library
indicated by \fIfilename\fR and report, on \f(CW\*(C`stdout\*(C'\fR, the name(s)
of the associated \s-1DLL\s0(s). This can be performed in addition to any
other operations indicated by the other options and arguments.
\&\fBdlltool\fR fails if the import library does not exist or is not
actually an import library. See also \fB\-\-identify\-strict\fR.
.IP "\fB\-\-identify\-strict\fR" 4
.IX Item "--identify-strict"
Modifies the behavior of the \fB\-\-identify\fR option, such
that an error is reported if \fIfilename\fR is associated with
more than one \s-1DLL.\s0
.IP "\fB\-i\fR" 4
.IX Item "-i"
.PD 0
.IP "\fB\-\-interwork\fR" 4
.IX Item "--interwork"
.PD
Specifies that \fBdlltool\fR should mark the objects in the library
file and exports file that it produces as supporting interworking
between \s-1ARM\s0 and Thumb code.
.IP "\fB\-n\fR" 4
.IX Item "-n"
.PD 0
.IP "\fB\-\-nodelete\fR" 4
.IX Item "--nodelete"
.PD
Makes \fBdlltool\fR preserve the temporary assembler files it used to
create the exports file. If this option is repeated then dlltool will
also preserve the temporary object files it uses to create the library
file.
.IP "\fB\-t\fR \fIprefix\fR" 4
.IX Item "-t prefix"
.PD 0
.IP "\fB\-\-temp\-prefix\fR \fIprefix\fR" 4
.IX Item "--temp-prefix prefix"
.PD
Makes \fBdlltool\fR use \fIprefix\fR when constructing the names of
temporary assembler and object files. By default, the temp file prefix
is generated from the pid.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Make dlltool describe what it is doing.
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Displays a list of command-line options and then exits.
.IP "\fB\-V\fR" 4
.IX Item "-V"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Displays dlltool's version number and then exits.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The Info pages for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

273
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-elfedit.1 Normal file
View File

@ -0,0 +1,273 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ELFEDIT 1"
.TH ELFEDIT 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
elfedit \- update ELF header and program property of ELF files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
elfedit [\fB\-\-input\-mach=\fR\fImachine\fR]
[\fB\-\-input\-type=\fR\fItype\fR]
[\fB\-\-input\-osabi=\fR\fIosabi\fR]
[\fB\-\-input\-abiversion=\fR\fIversion\fR]
\fB\-\-output\-mach=\fR\fImachine\fR
\fB\-\-output\-type=\fR\fItype\fR
\fB\-\-output\-osabi=\fR\fIosabi\fR
\fB\-\-output\-abiversion=\fR\fIversion\fR
\fB\-\-enable\-x86\-feature=\fR\fIfeature\fR
\fB\-\-disable\-x86\-feature=\fR\fIfeature\fR
[\fB\-v\fR|\fB\-\-version\fR]
[\fB\-h\fR|\fB\-\-help\fR]
\fIelffile\fR...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBelfedit\fR updates the \s-1ELF\s0 header and program property of \s-1ELF\s0
files which have the matching \s-1ELF\s0 machine and file types. The options
control how and which fields in the \s-1ELF\s0 header and program property
should be updated.
.PP
\&\fIelffile\fR... are the \s-1ELF\s0 files to be updated. 32\-bit and
64\-bit \s-1ELF\s0 files are supported, as are archives containing \s-1ELF\s0 files.
.SH "OPTIONS"
.IX Header "OPTIONS"
The long and short forms of options, shown here as alternatives, are
equivalent. At least one of the \fB\-\-output\-mach\fR,
\&\fB\-\-output\-type\fR, \fB\-\-output\-osabi\fR,
\&\fB\-\-output\-abiversion\fR,
\&\fB\-\-enable\-x86\-feature\fR and \fB\-\-disable\-x86\-feature\fR
options must be given.
.IP "\fB\-\-input\-mach=\fR\fImachine\fR" 4
.IX Item "--input-mach=machine"
Set the matching input \s-1ELF\s0 machine type to \fImachine\fR. If
\&\fB\-\-input\-mach\fR isn't specified, it will match any \s-1ELF\s0
machine types.
.Sp
The supported \s-1ELF\s0 machine types are, \fIi386\fR, \fI\s-1IAMCU\s0\fR, \fIL1OM\fR,
\&\fIK1OM\fR and \fIx86\-64\fR.
.IP "\fB\-\-output\-mach=\fR\fImachine\fR" 4
.IX Item "--output-mach=machine"
Change the \s-1ELF\s0 machine type in the \s-1ELF\s0 header to \fImachine\fR. The
supported \s-1ELF\s0 machine types are the same as \fB\-\-input\-mach\fR.
.IP "\fB\-\-input\-type=\fR\fItype\fR" 4
.IX Item "--input-type=type"
Set the matching input \s-1ELF\s0 file type to \fItype\fR. If
\&\fB\-\-input\-type\fR isn't specified, it will match any \s-1ELF\s0 file types.
.Sp
The supported \s-1ELF\s0 file types are, \fIrel\fR, \fIexec\fR and \fIdyn\fR.
.IP "\fB\-\-output\-type=\fR\fItype\fR" 4
.IX Item "--output-type=type"
Change the \s-1ELF\s0 file type in the \s-1ELF\s0 header to \fItype\fR. The
supported \s-1ELF\s0 types are the same as \fB\-\-input\-type\fR.
.IP "\fB\-\-input\-osabi=\fR\fIosabi\fR" 4
.IX Item "--input-osabi=osabi"
Set the matching input \s-1ELF\s0 file \s-1OSABI\s0 to \fIosabi\fR. If
\&\fB\-\-input\-osabi\fR isn't specified, it will match any \s-1ELF\s0 OSABIs.
.Sp
The supported \s-1ELF\s0 OSABIs are, \fInone\fR, \fI\s-1HPUX\s0\fR, \fINetBSD\fR,
\&\fI\s-1GNU\s0\fR, \fILinux\fR (alias for \fI\s-1GNU\s0\fR),
\&\fISolaris\fR, \fI\s-1AIX\s0\fR, \fIIrix\fR,
\&\fIFreeBSD\fR, \fI\s-1TRU64\s0\fR, \fIModesto\fR, \fIOpenBSD\fR, \fIOpenVMS\fR,
\&\fI\s-1NSK\s0\fR, \fI\s-1AROS\s0\fR and \fIFenixOS\fR.
.IP "\fB\-\-output\-osabi=\fR\fIosabi\fR" 4
.IX Item "--output-osabi=osabi"
Change the \s-1ELF OSABI\s0 in the \s-1ELF\s0 header to \fIosabi\fR. The
supported \s-1ELF OSABI\s0 are the same as \fB\-\-input\-osabi\fR.
.IP "\fB\-\-input\-abiversion=\fR\fIversion\fR" 4
.IX Item "--input-abiversion=version"
Set the matching input \s-1ELF\s0 file \s-1ABIVERSION\s0 to \fIversion\fR.
\&\fIversion\fR must be between 0 and 255. If \fB\-\-input\-abiversion\fR
isn't specified, it will match any \s-1ELF\s0 ABIVERSIONs.
.IP "\fB\-\-output\-abiversion=\fR\fIversion\fR" 4
.IX Item "--output-abiversion=version"
Change the \s-1ELF ABIVERSION\s0 in the \s-1ELF\s0 header to \fIversion\fR.
\&\fIversion\fR must be between 0 and 255.
.IP "\fB\-\-enable\-x86\-feature=\fR\fIfeature\fR" 4
.IX Item "--enable-x86-feature=feature"
Set the \fIfeature\fR bit in program property in \fIexec\fR or \fIdyn\fR
\&\s-1ELF\s0 files with machine types of \fIi386\fR or \fIx86\-64\fR. The
supported features are, \fIibt\fR, \fIshstk\fR, \fIlam_u48\fR and
\&\fIlam_u57\fR.
.IP "\fB\-\-disable\-x86\-feature=\fR\fIfeature\fR" 4
.IX Item "--disable-x86-feature=feature"
Clear the \fIfeature\fR bit in program property in \fIexec\fR or
\&\fIdyn\fR \s-1ELF\s0 files with machine types of \fIi386\fR or \fIx86\-64\fR.
The supported features are the same as \fB\-\-enable\-x86\-feature\fR.
.Sp
Note: \fB\-\-enable\-x86\-feature\fR and \fB\-\-disable\-x86\-feature\fR
are available only on hosts with \fBmmap\fR support.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Display the version number of \fBelfedit\fR.
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Display the command-line options understood by \fBelfedit\fR.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBreadelf\fR\|(1), and the Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

33598
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-g++.1 Normal file
View File

File diff suppressed because it is too large Load Diff

33598
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-gcc.1 Normal file
View File

File diff suppressed because it is too large Load Diff

226
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-gcov-dump.1 Normal file
View File

@ -0,0 +1,226 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GCOV-DUMP 1"
.TH GCOV-DUMP 1 "2023-07-27" "gcc-13.2.0" "GNU"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
gcov\-dump \- offline gcda and gcno profile dump tool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
gcov-dump [\fB\-v\fR|\fB\-\-version\fR]
[\fB\-h\fR|\fB\-\-help\fR]
[\fB\-l\fR|\fB\-\-long\fR]
[\fB\-p\fR|\fB\-\-positions\fR]
[\fB\-r\fR|\fB\-\-raw\fR]
[\fB\-s\fR|\fB\-\-stable\fR]
\fIgcovfiles\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBgcov-dump\fR is a tool you can use in conjunction with \s-1GCC\s0 to
dump content of gcda and gcno profile files offline.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Display help about using \fBgcov-dump\fR (on the standard output), and
exit without doing any further processing.
.IP "\fB\-l\fR" 4
.IX Item "-l"
.PD 0
.IP "\fB\-\-long\fR" 4
.IX Item "--long"
.PD
Dump content of records.
.IP "\fB\-p\fR" 4
.IX Item "-p"
.PD 0
.IP "\fB\-\-positions\fR" 4
.IX Item "--positions"
.PD
Dump positions of records.
.IP "\fB\-r\fR" 4
.IX Item "-r"
.PD 0
.IP "\fB\-\-raw\fR" 4
.IX Item "--raw"
.PD
Print content records in raw format.
.IP "\fB\-s\fR" 4
.IX Item "-s"
.PD 0
.IP "\fB\-\-stable\fR" 4
.IX Item "--stable"
.PD
Print content in stable format usable for comparison.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Display the \fBgcov-dump\fR version number (on the standard output),
and exit without doing any further processing.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2017\-2023 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being \*(L"\s-1GNU\s0 General Public License\*(R" and \*(L"Funding
Free Software\*(R", the Front-Cover texts being (a) (see below), and with
the Back-Cover Texts being (b) (see below). A copy of the license is
included in the \fBgfdl\fR\|(7) man page.
.PP
(a) The \s-1FSF\s0's Front-Cover Text is:
.PP
.Vb 1
\& A GNU Manual
.Ve
.PP
(b) The \s-1FSF\s0's Back-Cover Text is:
.PP
.Vb 3
\& You have freedom to copy and modify this GNU Manual, like GNU
\& software. Copies published by the Free Software Foundation raise
\& funds for GNU development.
.Ve

415
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-gcov-tool.1 Normal file
View File

@ -0,0 +1,415 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GCOV-TOOL 1"
.TH GCOV-TOOL 1 "2023-07-27" "gcc-13.2.0" "GNU"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
gcov\-tool \- offline gcda profile processing tool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
gcov-tool [\fB\-v\fR|\fB\-\-version\fR] [\fB\-h\fR|\fB\-\-help\fR]
.PP
gcov-tool merge [merge\-options] \fIdirectory1\fR \fIdirectory2\fR
[\fB\-o\fR|\fB\-\-output\fR \fIdirectory\fR]
[\fB\-v\fR|\fB\-\-verbose\fR]
[\fB\-w\fR|\fB\-\-weight\fR \fIw1,w2\fR]
.PP
gcov-tool merge-stream [merge\-stream\-options] [\fIfile\fR]
[\fB\-v\fR|\fB\-\-verbose\fR]
[\fB\-w\fR|\fB\-\-weight\fR \fIw1,w2\fR]
.PP
gcov-tool rewrite [rewrite\-options] \fIdirectory\fR
[\fB\-n\fR|\fB\-\-normalize\fR \fIlong_long_value\fR]
[\fB\-o\fR|\fB\-\-output\fR \fIdirectory\fR]
[\fB\-s\fR|\fB\-\-scale\fR \fIfloat_or_simple\-frac_value\fR]
[\fB\-v\fR|\fB\-\-verbose\fR]
.PP
gcov-tool overlap [overlap\-options] \fIdirectory1\fR \fIdirectory2\fR
[\fB\-f\fR|\fB\-\-function\fR]
[\fB\-F\fR|\fB\-\-fullname\fR]
[\fB\-h\fR|\fB\-\-hotonly\fR]
[\fB\-o\fR|\fB\-\-object\fR]
[\fB\-t\fR|\fB\-\-hot_threshold\fR] \fIfloat\fR
[\fB\-v\fR|\fB\-\-verbose\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBgcov-tool\fR is an offline tool to process gcc's gcda profile files.
.PP
Current gcov-tool supports the following functionalities:
.IP "*" 4
merge two sets of profiles with weights.
.IP "*" 4
read a stream of profiles with associated filenames and merge it with a set of
profiles with weights.
.IP "*" 4
read one set of profile and rewrite profile contents. One can scale or
normalize the count values.
.PP
Examples of the use cases for this tool are:
.IP "*" 4
Collect the profiles for different set of inputs, and use this tool to merge
them. One can specify the weight to factor in the relative importance of
each input.
.IP "*" 4
Collect profiles from target systems without a filesystem (freestanding
environments). Merge the collected profiles with associated profiles
present on the host system. One can specify the weight to factor in the
relative importance of each input.
.IP "*" 4
Rewrite the profile after removing a subset of the gcda files, while maintaining
the consistency of the summary and the histogram.
.IP "*" 4
It can also be used to debug or libgcov code as the tools shares the majority
code as the runtime library.
.PP
Note that for the merging operation, this profile generated offline may
contain slight different values from the online merged profile. Here are
a list of typical differences:
.IP "*" 4
histogram difference: This offline tool recomputes the histogram after merging
the counters. The resulting histogram, therefore, is precise. The online
merging does not have this capability \*(-- the histogram is merged from two
histograms and the result is an approximation.
.IP "*" 4
summary checksum difference: Summary checksum uses a \s-1CRC32\s0 operation. The value
depends on the link list order of gcov-info objects. This order is different in
gcov-tool from that in the online merge. It's expected to have different
summary checksums. It does not really matter as the compiler does not use this
checksum anywhere.
.IP "*" 4
value profile counter values difference: Some counter values for value profile
are runtime dependent, like heap addresses. It's normal to see some difference
in these kind of counters.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Display help about using \fBgcov-tool\fR (on the standard output), and
exit without doing any further processing.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Display the \fBgcov-tool\fR version number (on the standard output),
and exit without doing any further processing.
.IP "\fBmerge\fR" 4
.IX Item "merge"
Merge two profile directories.
.RS 4
.IP "\fB\-o\fR \fIdirectory\fR" 4
.IX Item "-o directory"
.PD 0
.IP "\fB\-\-output\fR \fIdirectory\fR" 4
.IX Item "--output directory"
.PD
Set the output profile directory. Default output directory name is
\&\fImerged_profile\fR.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Set the verbose mode.
.IP "\fB\-w\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "-w w1,w2"
.PD 0
.IP "\fB\-\-weight\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "--weight w1,w2"
.PD
Set the merge weights of the \fIdirectory1\fR and \fIdirectory2\fR,
respectively. The default weights are 1 for both.
.RE
.RS 4
.RE
.IP "\fBmerge-stream\fR" 4
.IX Item "merge-stream"
Collect profiles with associated filenames from a \fIgcfn\fR and \fIgcda\fR
data stream. Read the stream from the file specified by \fIfile\fR or from
\&\fIstdin\fR. Merge the profiles with associated profiles in the host
filesystem. Apply the optional weights while merging profiles.
.Sp
For the generation of a \fIgcfn\fR and \fIgcda\fR data stream on the target
system, please have a look at the \f(CW\*(C`_\|_gcov_filename_to_gcfn()\*(C'\fR and
\&\f(CW\*(C`_\|_gcov_info_to_gcda()\*(C'\fR functions declared in \f(CW\*(C`#include <gcov.h>\*(C'\fR.
.RS 4
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Set the verbose mode.
.IP "\fB\-w\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "-w w1,w2"
.PD 0
.IP "\fB\-\-weight\fR \fIw1\fR\fB,\fR\fIw2\fR" 4
.IX Item "--weight w1,w2"
.PD
Set the merge weights of the profiles from the \fIgcfn\fR and \fIgcda\fR data
stream and the associated profiles in the host filesystem, respectively. The
default weights are 1 for both.
.RE
.RS 4
.RE
.IP "\fBrewrite\fR" 4
.IX Item "rewrite"
Read the specified profile directory and rewrite to a new directory.
.RS 4
.IP "\fB\-n\fR \fIlong_long_value\fR" 4
.IX Item "-n long_long_value"
.PD 0
.IP "\fB\-\-normalize <long_long_value>\fR" 4
.IX Item "--normalize <long_long_value>"
.PD
Normalize the profile. The specified value is the max counter value
in the new profile.
.IP "\fB\-o\fR \fIdirectory\fR" 4
.IX Item "-o directory"
.PD 0
.IP "\fB\-\-output\fR \fIdirectory\fR" 4
.IX Item "--output directory"
.PD
Set the output profile directory. Default output name is \fIrewrite_profile\fR.
.IP "\fB\-s\fR \fIfloat_or_simple\-frac_value\fR" 4
.IX Item "-s float_or_simple-frac_value"
.PD 0
.IP "\fB\-\-scale\fR \fIfloat_or_simple\-frac_value\fR" 4
.IX Item "--scale float_or_simple-frac_value"
.PD
Scale the profile counters. The specified value can be in floating point value,
or simple fraction value form, such 1, 2, 2/3, and 5/3.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Set the verbose mode.
.RE
.RS 4
.RE
.IP "\fBoverlap\fR" 4
.IX Item "overlap"
Compute the overlap score between the two specified profile directories.
The overlap score is computed based on the arc profiles. It is defined as
the sum of min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all),
for all arc counter i, where p1_counter[i] and p2_counter[i] are two
matched counters and p1_sum_all and p2_sum_all are the sum of counter
values in profile 1 and profile 2, respectively.
.RS 4
.IP "\fB\-f\fR" 4
.IX Item "-f"
.PD 0
.IP "\fB\-\-function\fR" 4
.IX Item "--function"
.PD
Print function level overlap score.
.IP "\fB\-F\fR" 4
.IX Item "-F"
.PD 0
.IP "\fB\-\-fullname\fR" 4
.IX Item "--fullname"
.PD
Print full gcda filename.
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-hotonly\fR" 4
.IX Item "--hotonly"
.PD
Only print info for hot objects/functions.
.IP "\fB\-o\fR" 4
.IX Item "-o"
.PD 0
.IP "\fB\-\-object\fR" 4
.IX Item "--object"
.PD
Print object level overlap score.
.IP "\fB\-t\fR \fIfloat\fR" 4
.IX Item "-t float"
.PD 0
.IP "\fB\-\-hot_threshold <float>\fR" 4
.IX Item "--hot_threshold <float>"
.PD
Set the threshold for hot counter value.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Set the verbose mode.
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBgpl\fR\|(7), \fBgfdl\fR\|(7), \fBfsf\-funding\fR\|(7), \fBgcc\fR\|(1), \fBgcov\fR\|(1) and the Info entry for
\&\fIgcc\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2014\-2023 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being \*(L"\s-1GNU\s0 General Public License\*(R" and \*(L"Funding
Free Software\*(R", the Front-Cover texts being (a) (see below), and with
the Back-Cover Texts being (b) (see below). A copy of the license is
included in the \fBgfdl\fR\|(7) man page.
.PP
(a) The \s-1FSF\s0's Front-Cover Text is:
.PP
.Vb 1
\& A GNU Manual
.Ve
.PP
(b) The \s-1FSF\s0's Back-Cover Text is:
.PP
.Vb 3
\& You have freedom to copy and modify this GNU Manual, like GNU
\& software. Copies published by the Free Software Foundation raise
\& funds for GNU development.
.Ve

1045
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-gcov.1 Normal file
View File

File diff suppressed because it is too large Load Diff

197
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-gdb-add-index.1 Normal file
View File

@ -0,0 +1,197 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GDB-ADD-INDEX 1"
.TH GDB-ADD-INDEX 1 "2024-10-18" "gdb-16.0.50.20240817-git" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
gdb\-add\-index \- Add index files to speed up GDB
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
gdb-add-index \fIfilename\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
When \s-1GDB\s0 finds a symbol file, it scans the symbols in the
file in order to construct an internal symbol table. This lets most
\&\s-1GDB\s0 operations work quickly\*(--at the cost of a delay early on.
For large programs, this delay can be quite lengthy, so \s-1GDB\s0
provides a way to build an index, which speeds up startup.
.PP
To determine whether a file contains such an index, use the command
\&\f(CW\*(C`readelf \-S filename\*(C'\fR: the index is stored in a section named
\&\f(CW\*(C`.gdb_index\*(C'\fR. The index file can only be produced on systems
which use \s-1ELF\s0 binaries and \s-1DWARF\s0 debug information (i.e., sections
named \f(CW\*(C`.debug_*\*(C'\fR).
.PP
\&\fBgdb-add-index\fR uses \s-1GDB\s0 and \fBobjdump\fR found
in the \fB\s-1PATH\s0\fR environment variable. If you want to use different
versions of these programs, you can specify them through the
\&\fB\s-1GDB\s0\fR and \fB\s-1OBJDUMP\s0\fR environment variables.
.PP
See more in
the \s-1GDB\s0 manual in node \f(CW\*(C`Index Files\*(C'\fR
\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n "Index Files"\*(C'\fR.
.SH "OPTIONS"
.IX Header "OPTIONS"
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual.
If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo
documentation are properly installed at your site, the command
.PP
.Vb 1
\& info gdb
.Ve
.PP
should give you access to the complete manual.
.PP
\&\fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR,
Richard M. Stallman and Roland H. Pesch, July 1991.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1988\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs
Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R"
and with the Back-Cover Texts as in (a) below.
.PP
(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify
this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in
developing \s-1GNU\s0 and promoting software freedom.\*(R"

506
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-gdb.1 Normal file
View File

@ -0,0 +1,506 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GDB 1"
.TH GDB 1 "2024-10-18" "gdb-16.0.50.20240817-git" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
gdb \- The GNU Debugger
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
gdb [\s-1OPTIONS\s0] [\fIprog\fR|\fIprog\fR \fIprocID\fR|\fIprog\fR \fIcore\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The purpose of a debugger such as \s-1GDB\s0 is to allow you to see what is
going on \*(L"inside\*(R" another program while it executes \*(-- or what another
program was doing at the moment it crashed.
.PP
\&\s-1GDB\s0 can do four main kinds of things (plus other things in support of
these) to help you catch bugs in the act:
.IP "\(bu" 4
Start your program, specifying anything that might affect its behavior.
.IP "\(bu" 4
Make your program stop on specified conditions.
.IP "\(bu" 4
Examine what has happened, when your program has stopped.
.IP "\(bu" 4
Change things in your program, so you can experiment with correcting the
effects of one bug and go on to learn about another.
.PP
You can use \s-1GDB\s0 to debug programs written in C, \*(C+, Fortran and
Modula\-2.
.PP
\&\s-1GDB\s0 is invoked with the shell command \f(CW\*(C`gdb\*(C'\fR. Once started, it reads
commands from the terminal until you tell it to exit with the \s-1GDB\s0
command \f(CW\*(C`quit\*(C'\fR or \f(CW\*(C`exit\*(C'\fR. You can get online help from \s-1GDB\s0 itself
by using the command \f(CW\*(C`help\*(C'\fR.
.PP
You can run \f(CW\*(C`gdb\*(C'\fR with no arguments or options; but the most
usual way to start \s-1GDB\s0 is with one argument or two, specifying an
executable program as the argument:
.PP
.Vb 1
\& gdb program
.Ve
.PP
You can also start with both an executable program and a core file specified:
.PP
.Vb 1
\& gdb program core
.Ve
.PP
You can, instead, specify a process \s-1ID\s0 as a second argument or use option
\&\f(CW\*(C`\-p\*(C'\fR, if you want to debug a running process:
.PP
.Vb 2
\& gdb program 1234
\& gdb \-p 1234
.Ve
.PP
would attach \s-1GDB\s0 to process \f(CW1234\fR. With option \fB\-p\fR you
can omit the \fIprogram\fR filename.
.PP
Here are some of the most frequently needed \s-1GDB\s0 commands:
.IP "\fBbreak [\fR\fIfile\fR\fB:][\fR\fIfunction\fR\fB|\fR\fIline\fR\fB]\fR" 4
.IX Item "break [file:][function|line]"
Set a breakpoint at \fIfunction\fR or \fIline\fR (in \fIfile\fR).
.IP "\fBrun [\fR\fIarglist\fR\fB]\fR" 4
.IX Item "run [arglist]"
Start your program (with \fIarglist\fR, if specified).
.IP "\fBbt\fR" 4
.IX Item "bt"
Backtrace: display the program stack.
.IP "\fBprint\fR \fIexpr\fR" 4
.IX Item "print expr"
Display the value of an expression.
.IP "\fBc\fR" 4
.IX Item "c"
Continue running your program (after stopping, e.g. at a breakpoint).
.IP "\fBnext\fR" 4
.IX Item "next"
Execute next program line (after stopping); step \fIover\fR any
function calls in the line.
.IP "\fBedit [\fR\fIfile\fR\fB:]\fR\fIfunction\fR" 4
.IX Item "edit [file:]function"
look at the program line where it is presently stopped.
.IP "\fBlist [\fR\fIfile\fR\fB:]\fR\fIfunction\fR" 4
.IX Item "list [file:]function"
type the text of the program in the vicinity of where it is presently stopped.
.IP "\fBstep\fR" 4
.IX Item "step"
Execute next program line (after stopping); step \fIinto\fR any
function calls in the line.
.IP "\fBhelp [\fR\fIname\fR\fB]\fR" 4
.IX Item "help [name]"
Show information about \s-1GDB\s0 command \fIname\fR, or general information
about using \s-1GDB.\s0
.IP "\fBquit\fR" 4
.IX Item "quit"
.PD 0
.IP "\fBexit\fR" 4
.IX Item "exit"
.PD
Exit from \s-1GDB.\s0
.PP
For full details on \s-1GDB,\s0
see \fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR,
by Richard M. Stallman and Roland H. Pesch. The same text is available online
as the \f(CW\*(C`gdb\*(C'\fR entry in the \f(CW\*(C`info\*(C'\fR program.
.SH "OPTIONS"
.IX Header "OPTIONS"
Any arguments other than options specify an executable
file and core file (or process \s-1ID\s0); that is, the first argument
encountered with no
associated option flag is equivalent to a \fB\-\-se\fR option, and the second,
if any, is equivalent to a \fB\-c\fR option if it's the name of a file.
Many options have
both long and abbreviated forms; both are shown here. The long forms are also
recognized if you truncate them, so long as enough of the option is
present to be unambiguous.
.PP
The abbreviated forms are shown here with \fB\-\fR and long forms are shown
with \fB\-\-\fR to reflect how they are shown in \fB\-\-help\fR. However,
\&\s-1GDB\s0 recognizes all of the following conventions for most options:
.ie n .IP """\-\-option=\fIvalue\fP""" 4
.el .IP "\f(CW\-\-option=\f(CIvalue\f(CW\fR" 4
.IX Item "--option=value"
.PD 0
.ie n .IP """\-\-option \fIvalue\fP""" 4
.el .IP "\f(CW\-\-option \f(CIvalue\f(CW\fR" 4
.IX Item "--option value"
.ie n .IP """\-option=\fIvalue\fP""" 4
.el .IP "\f(CW\-option=\f(CIvalue\f(CW\fR" 4
.IX Item "-option=value"
.ie n .IP """\-option \fIvalue\fP""" 4
.el .IP "\f(CW\-option \f(CIvalue\f(CW\fR" 4
.IX Item "-option value"
.ie n .IP """\-\-o=\fIvalue\fP""" 4
.el .IP "\f(CW\-\-o=\f(CIvalue\f(CW\fR" 4
.IX Item "--o=value"
.ie n .IP """\-\-o \fIvalue\fP""" 4
.el .IP "\f(CW\-\-o \f(CIvalue\f(CW\fR" 4
.IX Item "--o value"
.ie n .IP """\-o=\fIvalue\fP""" 4
.el .IP "\f(CW\-o=\f(CIvalue\f(CW\fR" 4
.IX Item "-o=value"
.ie n .IP """\-o \fIvalue\fP""" 4
.el .IP "\f(CW\-o \f(CIvalue\f(CW\fR" 4
.IX Item "-o value"
.PD
.PP
All the options and command line arguments you give are processed
in sequential order. The order makes a difference when the \fB\-x\fR
option is used.
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD 0
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD
List all options, with brief explanations.
.IP "\fB\-\-symbols=\fR\fIfile\fR" 4
.IX Item "--symbols=file"
.PD 0
.IP "\fB\-s\fR \fIfile\fR" 4
.IX Item "-s file"
.PD
Read symbol table from \fIfile\fR.
.IP "\fB\-\-write\fR" 4
.IX Item "--write"
Enable writing into executable and core files.
.IP "\fB\-\-exec=\fR\fIfile\fR" 4
.IX Item "--exec=file"
.PD 0
.IP "\fB\-e\fR \fIfile\fR" 4
.IX Item "-e file"
.PD
Use \fIfile\fR as the executable file to execute when
appropriate, and for examining pure data in conjunction with a core
dump.
.IP "\fB\-\-se=\fR\fIfile\fR" 4
.IX Item "--se=file"
Read symbol table from \fIfile\fR and use it as the executable
file.
.IP "\fB\-\-core=\fR\fIfile\fR" 4
.IX Item "--core=file"
.PD 0
.IP "\fB\-c\fR \fIfile\fR" 4
.IX Item "-c file"
.PD
Use \fIfile\fR as a core dump to examine.
.IP "\fB\-\-command=\fR\fIfile\fR" 4
.IX Item "--command=file"
.PD 0
.IP "\fB\-x\fR \fIfile\fR" 4
.IX Item "-x file"
.PD
Execute \s-1GDB\s0 commands from \fIfile\fR.
.IP "\fB\-\-eval\-command=\fR\fIcommand\fR" 4
.IX Item "--eval-command=command"
.PD 0
.IP "\fB\-ex\fR \fIcommand\fR" 4
.IX Item "-ex command"
.PD
Execute given \s-1GDB\s0 \fIcommand\fR.
.IP "\fB\-\-init\-eval\-command=\fR\fIcommand\fR" 4
.IX Item "--init-eval-command=command"
.PD 0
.IP "\fB\-iex\fR" 4
.IX Item "-iex"
.PD
Execute \s-1GDB\s0 \fIcommand\fR before loading the inferior.
.IP "\fB\-\-directory=\fR\fIdirectory\fR" 4
.IX Item "--directory=directory"
.PD 0
.IP "\fB\-d\fR \fIdirectory\fR" 4
.IX Item "-d directory"
.PD
Add \fIdirectory\fR to the path to search for source files.
.IP "\fB\-\-nh\fR" 4
.IX Item "--nh"
Do not execute commands from \fI~/.config/gdb/gdbinit\fR,
\&\fI~/.gdbinit\fR, \fI~/.config/gdb/gdbearlyinit\fR, or
\&\fI~/.gdbearlyinit\fR
.IP "\fB\-\-nx\fR" 4
.IX Item "--nx"
.PD 0
.IP "\fB\-n\fR" 4
.IX Item "-n"
.PD
Do not execute commands from any \fI.gdbinit\fR or
\&\fI.gdbearlyinit\fR initialization files.
.IP "\fB\-\-quiet\fR" 4
.IX Item "--quiet"
.PD 0
.IP "\fB\-\-silent\fR" 4
.IX Item "--silent"
.IP "\fB\-q\fR" 4
.IX Item "-q"
.PD
\&\*(L"Quiet\*(R". Do not print the introductory and copyright messages. These
messages are also suppressed in batch mode.
.IP "\fB\-\-batch\fR" 4
.IX Item "--batch"
Run in batch mode. Exit with status \f(CW0\fR after processing all the command
files specified with \fB\-x\fR (and \fI.gdbinit\fR, if not inhibited).
Exit with nonzero status if an error occurs in executing the \s-1GDB\s0
commands in the command files.
.Sp
Batch mode may be useful for running \s-1GDB\s0 as a filter, for example to
download and run a program on another computer; in order to make this
more useful, the message
.Sp
.Vb 1
\& Program exited normally.
.Ve
.Sp
(which is ordinarily issued whenever a program running under \s-1GDB\s0 control
terminates) is not issued when running in batch mode.
.IP "\fB\-\-batch\-silent\fR" 4
.IX Item "--batch-silent"
Run in batch mode, just like \fB\-\-batch\fR, but totally silent. All \s-1GDB\s0
output is suppressed (stderr is unaffected). This is much quieter than
\&\fB\-\-silent\fR and would be useless for an interactive session.
.Sp
This is particularly useful when using targets that give \fBLoading section\fR
messages, for example.
.Sp
Note that targets that give their output via \s-1GDB,\s0 as opposed to writing
directly to \f(CW\*(C`stdout\*(C'\fR, will also be made silent.
.IP "\fB\-\-args\fR \fIprog\fR \fB[\fR\fIarglist\fR\fB]\fR" 4
.IX Item "--args prog [arglist]"
Change interpretation of command line so that arguments following this
option are passed as arguments to the inferior. As an example, take
the following command:
.Sp
.Vb 1
\& gdb ./a.out \-q
.Ve
.Sp
It would start \s-1GDB\s0 with \fB\-q\fR, not printing the introductory message. On
the other hand, using:
.Sp
.Vb 1
\& gdb \-\-args ./a.out \-q
.Ve
.Sp
starts \s-1GDB\s0 with the introductory message, and passes the option to the inferior.
.IP "\fB\-\-pid=\fR\fIpid\fR" 4
.IX Item "--pid=pid"
Attach \s-1GDB\s0 to an already running program, with the \s-1PID\s0 \fIpid\fR.
.IP "\fB\-\-tui\fR" 4
.IX Item "--tui"
Open the terminal user interface.
.IP "\fB\-\-readnow\fR" 4
.IX Item "--readnow"
Read all symbols from the given symfile on the first access.
.IP "\fB\-\-readnever\fR" 4
.IX Item "--readnever"
Do not read symbol files.
.IP "\fB\-\-return\-child\-result\fR" 4
.IX Item "--return-child-result"
\&\s-1GDB\s0's exit code will be the same as the child's exit code.
.IP "\fB\-\-configuration\fR" 4
.IX Item "--configuration"
Print details about \s-1GDB\s0 configuration and then exit.
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
Print version information and then exit.
.IP "\fB\-\-cd=\fR\fIdirectory\fR" 4
.IX Item "--cd=directory"
Run \s-1GDB\s0 using \fIdirectory\fR as its working directory,
instead of the current directory.
.IP "\fB\-\-data\-directory=\fR\fIdirectory\fR" 4
.IX Item "--data-directory=directory"
.PD 0
.IP "\fB\-D\fR" 4
.IX Item "-D"
.PD
Run \s-1GDB\s0 using \fIdirectory\fR as its data directory. The data
directory is where \s-1GDB\s0 searches for its auxiliary files.
.IP "\fB\-\-fullname\fR" 4
.IX Item "--fullname"
.PD 0
.IP "\fB\-f\fR" 4
.IX Item "-f"
.PD
Emacs sets this option when it runs \s-1GDB\s0 as a subprocess. It tells
\&\s-1GDB\s0 to output the full file name and line number in a standard,
recognizable fashion each time a stack frame is displayed (which
includes each time the program stops). This recognizable format looks
like two \fB\e032\fR characters, followed by the file name, line number
and character position separated by colons, and a newline. The
Emacs-to-GDB interface program uses the two \fB\e032\fR
characters as a signal to display the source code for the frame.
.IP "\fB\-b\fR \fIbaudrate\fR" 4
.IX Item "-b baudrate"
Set the line speed (baud rate or bits per second) of any serial
interface used by \s-1GDB\s0 for remote debugging.
.IP "\fB\-l\fR \fItimeout\fR" 4
.IX Item "-l timeout"
Set timeout, in seconds, for remote debugging.
.IP "\fB\-\-tty=\fR\fIdevice\fR" 4
.IX Item "--tty=device"
Run using \fIdevice\fR for your program's standard input and output.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual.
If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo
documentation are properly installed at your site, the command
.PP
.Vb 1
\& info gdb
.Ve
.PP
should give you access to the complete manual.
.PP
\&\fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR,
Richard M. Stallman and Roland H. Pesch, July 1991.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1988\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs
Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R"
and with the Back-Cover Texts as in (a) below.
.PP
(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify
this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in
developing \s-1GNU\s0 and promoting software freedom.\*(R"

392
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-gdbserver.1 Normal file
View File

@ -0,0 +1,392 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GDBSERVER 1"
.TH GDBSERVER 1 "2024-10-18" "gdb-16.0.50.20240817-git" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
gdbserver \- Remote Server for the GNU Debugger
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
gdbserver \fIcomm\fR \fIprog\fR [\fIargs\fR...]
.PP
gdbserver \-\-attach \fIcomm\fR \fIpid\fR
.PP
gdbserver \-\-multi \fIcomm\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBgdbserver\fR is a program that allows you to run \s-1GDB\s0 on a different machine
than the one which is running the program being debugged.
.PP
Usage (server (target) side):
.PP
First, you need to have a copy of the program you want to debug put onto
the target system. The program can be stripped to save space if needed, as
\&\fBgdbserver\fR doesn't care about symbols. All symbol handling is taken care of by
the \s-1GDB\s0 running on the host system.
.PP
To use the server, you log on to the target system, and run the \fBgdbserver\fR
program. You must tell it (a) how to communicate with \s-1GDB,\s0 (b) the name of
your program, and (c) its arguments. The general syntax is:
.PP
.Vb 1
\& target> gdbserver <comm> <program> [<args> ...]
.Ve
.PP
For example, using a serial port, you might say:
.PP
.Vb 1
\& target> gdbserver /dev/com1 emacs foo.txt
.Ve
.PP
This tells \fBgdbserver\fR to debug emacs with an argument of foo.txt, and
to communicate with \s-1GDB\s0 via \fI/dev/com1\fR. \fBgdbserver\fR now
waits patiently for the host \s-1GDB\s0 to communicate with it.
.PP
To use a \s-1TCP\s0 connection, you could say:
.PP
.Vb 1
\& target> gdbserver host:2345 emacs foo.txt
.Ve
.PP
This says pretty much the same thing as the last example, except that we are
going to communicate with the \f(CW\*(C`host\*(C'\fR \s-1GDB\s0 via \s-1TCP.\s0 The \f(CW\*(C`host:2345\*(C'\fR argument means
that we are expecting to see a \s-1TCP\s0 connection from \f(CW\*(C`host\*(C'\fR to local \s-1TCP\s0 port
2345. (Currently, the \f(CW\*(C`host\*(C'\fR part is ignored.) You can choose any number you
want for the port number as long as it does not conflict with any existing \s-1TCP\s0
ports on the target system. This same port number must be used in the host
GDBs \f(CW\*(C`target remote\*(C'\fR command, which will be described shortly. Note that if
you chose a port number that conflicts with another service, \fBgdbserver\fR will
print an error message and exit.
.PP
\&\fBgdbserver\fR can also attach to running programs.
This is accomplished via the \fB\-\-attach\fR argument. The syntax is:
.PP
.Vb 1
\& target> gdbserver \-\-attach <comm> <pid>
.Ve
.PP
\&\fIpid\fR is the process \s-1ID\s0 of a currently running process. It isn't
necessary to point \fBgdbserver\fR at a binary for the running process.
.PP
To start \f(CW\*(C`gdbserver\*(C'\fR without supplying an initial command to run
or process \s-1ID\s0 to attach, use the \fB\-\-multi\fR command line option.
In such case you should connect using \f(CW\*(C`target extended\-remote\*(C'\fR to start
the program you want to debug.
.PP
.Vb 1
\& target> gdbserver \-\-multi <comm>
.Ve
.PP
Usage (host side):
.PP
You need an unstripped copy of the target program on your host system, since
\&\s-1GDB\s0 needs to examine its symbol tables and such. Start up \s-1GDB\s0 as you normally
would, with the target program as the first argument. (You may need to use the
\&\fB\-\-baud\fR option if the serial line is running at anything except 9600 baud.)
That is \f(CW\*(C`gdb TARGET\-PROG\*(C'\fR, or \f(CW\*(C`gdb \-\-baud BAUD TARGET\-PROG\*(C'\fR. After that, the only
new command you need to know about is \f(CW\*(C`target remote\*(C'\fR
(or \f(CW\*(C`target extended\-remote\*(C'\fR). Its argument is either
a device name (usually a serial device, like \fI/dev/ttyb\fR), or a \f(CW\*(C`HOST:PORT\*(C'\fR
descriptor. For example:
.PP
.Vb 1
\& (gdb) target remote /dev/ttyb
.Ve
.PP
communicates with the server via serial line \fI/dev/ttyb\fR, and:
.PP
.Vb 1
\& (gdb) target remote the\-target:2345
.Ve
.PP
communicates via a \s-1TCP\s0 connection to port 2345 on host `the\-target', where
you previously started up \fBgdbserver\fR with the same port number. Note that for
\&\s-1TCP\s0 connections, you must start up \fBgdbserver\fR prior to using the `target remote'
command, otherwise you may get an error that looks something like
`Connection refused'.
.PP
\&\fBgdbserver\fR can also debug multiple inferiors at once,
described in
the \s-1GDB\s0 manual in node \f(CW\*(C`Inferiors Connections and Programs\*(C'\fR
\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n \*(AqInferiors Connections and Programs\*(Aq\*(C'\fR.
In such case use the \f(CW\*(C`extended\-remote\*(C'\fR \s-1GDB\s0 command variant:
.PP
.Vb 1
\& (gdb) target extended\-remote the\-target:2345
.Ve
.PP
The \fBgdbserver\fR option \fB\-\-multi\fR may or may not be used in such
case.
.SH "OPTIONS"
.IX Header "OPTIONS"
There are three different modes for invoking \fBgdbserver\fR:
.IP "\(bu" 4
Debug a specific program specified by its program name:
.Sp
.Vb 1
\& gdbserver <comm> <prog> [<args>...]
.Ve
.Sp
The \fIcomm\fR parameter specifies how should the server communicate
with \s-1GDB\s0; it is either a device name (to use a serial line),
a \s-1TCP\s0 port number (\f(CW\*(C`:1234\*(C'\fR), or \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`stdio\*(C'\fR to use
stdin/stdout of \f(CW\*(C`gdbserver\*(C'\fR. Specify the name of the program to
debug in \fIprog\fR. Any remaining arguments will be passed to the
program verbatim. When the program exits, \s-1GDB\s0 will close the
connection, and \f(CW\*(C`gdbserver\*(C'\fR will exit.
.IP "\(bu" 4
Debug a specific program by specifying the process \s-1ID\s0 of a running
program:
.Sp
.Vb 1
\& gdbserver \-\-attach <comm> <pid>
.Ve
.Sp
The \fIcomm\fR parameter is as described above. Supply the process \s-1ID\s0
of a running program in \fIpid\fR; \s-1GDB\s0 will do everything
else. Like with the previous mode, when the process \fIpid\fR exits,
\&\s-1GDB\s0 will close the connection, and \f(CW\*(C`gdbserver\*(C'\fR will exit.
.IP "\(bu" 4
Multi-process mode \*(-- debug more than one program/process:
.Sp
.Vb 1
\& gdbserver \-\-multi <comm>
.Ve
.Sp
In this mode, \s-1GDB\s0 can instruct \fBgdbserver\fR which
command(s) to run. Unlike the other 2 modes, \s-1GDB\s0 will not
close the connection when a process being debugged exits, so you can
debug several processes in the same session.
.PP
In each of the modes you may specify these options:
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
List all options, with brief explanations.
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
This option causes \fBgdbserver\fR to print its version number and exit.
.IP "\fB\-\-attach\fR" 4
.IX Item "--attach"
\&\fBgdbserver\fR will attach to a running program. The syntax is:
.Sp
.Vb 1
\& target> gdbserver \-\-attach <comm> <pid>
.Ve
.Sp
\&\fIpid\fR is the process \s-1ID\s0 of a currently running process. It isn't
necessary to point \fBgdbserver\fR at a binary for the running process.
.IP "\fB\-\-multi\fR" 4
.IX Item "--multi"
To start \f(CW\*(C`gdbserver\*(C'\fR without supplying an initial command to run
or process \s-1ID\s0 to attach, use this command line option.
Then you can connect using \f(CW\*(C`target extended\-remote\*(C'\fR and start
the program you want to debug. The syntax is:
.Sp
.Vb 1
\& target> gdbserver \-\-multi <comm>
.Ve
.IP "\fB\-\-debug\fR[\fB=option1,option2,...\fR]" 4
.IX Item "--debug[=option1,option2,...]"
Instruct \f(CW\*(C`gdbserver\*(C'\fR to display extra status information about
the debugging process. This option is intended for \f(CW\*(C`gdbserver\*(C'\fR
development and for bug reports to the developers.
.Sp
Each \fIoption\fR is the name of a component for which debugging
should be enabled. The list of possible options is \fBall\fR,
\&\fBthreads\fR, \fBevent-loop\fR, \fBremote\fR. The special
option \fBall\fR enables all components. The option list is
processed left to right, and an option can be prefixed with the
\&\f(CW\*(C`\-\*(C'\fR character to disable output for that component, so you could write:
.Sp
.Vb 1
\& target> gdbserver \-\-debug=all,\-event\-loop
.Ve
.Sp
to turn on debug output for all components except \fBevent-loop\fR.
If no options are passed to \fB\-\-debug\fR then this is treated as
equivalent to \fB\-\-debug=threads\fR. This could change in future
releases of \f(CW\*(C`gdbserver\*(C'\fR.
.IP "\fB\-\-debug\-file=\fR\fIfilename\fR" 4
.IX Item "--debug-file=filename"
Instruct \f(CW\*(C`gdbserver\*(C'\fR to send any debug output to the given \fIfilename\fR.
This option is intended for \f(CW\*(C`gdbserver\*(C'\fR development and for bug reports to
the developers.
.IP "\fB\-\-debug\-format=option1\fR[\fB,option2,...\fR]" 4
.IX Item "--debug-format=option1[,option2,...]"
Instruct \f(CW\*(C`gdbserver\*(C'\fR to include extra information in each line
of debugging output.
.IP "\fB\-\-wrapper\fR" 4
.IX Item "--wrapper"
Specify a wrapper to launch programs
for debugging. The option should be followed by the name of the
wrapper, then any command-line arguments to pass to the wrapper, then
\&\f(CW\*(C`\-\-\*(C'\fR indicating the end of the wrapper arguments.
.IP "\fB\-\-once\fR" 4
.IX Item "--once"
By default, \fBgdbserver\fR keeps the listening \s-1TCP\s0 port open, so that
additional connections are possible. However, if you start \f(CW\*(C`gdbserver\*(C'\fR
with the \fB\-\-once\fR option, it will stop listening for any further
connection attempts after connecting to the first \s-1GDB\s0 session.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual.
If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo
documentation are properly installed at your site, the command
.PP
.Vb 1
\& info gdb
.Ve
.PP
should give you access to the complete manual.
.PP
\&\fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR,
Richard M. Stallman and Roland H. Pesch, July 1991.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1988\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs
Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R"
and with the Back-Cover Texts as in (a) below.
.PP
(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify
this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in
developing \s-1GNU\s0 and promoting software freedom.\*(R"

776
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-gprof.1 Normal file
View File

@ -0,0 +1,776 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GPROF 1"
.TH GPROF 1 "2024-10-18" "binutils-2.43.1" "GNU"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
gprof \- display call graph profile data
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
gprof [ \-[abcDhilLrsTvwxyz] ] [ \-[ABCeEfFJnNOpPqQRStZ][\fIname\fR] ]
[ \-I \fIdirs\fR ] [ \-d[\fInum\fR] ] [ \-k \fIfrom/to\fR ]
[ \-m \fImin-count\fR ] [ \-R \fImap_file\fR ] [ \-t \fItable-length\fR ]
[ \-\-[no\-]annotated\-source[=\fIname\fR] ]
[ \-\-[no\-]exec\-counts[=\fIname\fR] ]
[ \-\-[no\-]flat\-profile[=\fIname\fR] ] [ \-\-[no\-]graph[=\fIname\fR] ]
[ \-\-[no\-]time=\fIname\fR] [ \-\-all\-lines ] [ \-\-brief ]
[ \-\-debug[=\fIlevel\fR] ] [ \-\-function\-ordering ]
[ \-\-file\-ordering \fImap_file\fR ] [ \-\-directory\-path=\fIdirs\fR ]
[ \-\-display\-unused\-functions ] [ \-\-file\-format=\fIname\fR ]
[ \-\-file\-info ] [ \-\-help ] [ \-\-line ] [ \-\-inline\-file\-names ]
[ \-\-min\-count=\fIn\fR ] [ \-\-no\-static ] [ \-\-print\-path ]
[ \-\-separate\-files ] [ \-\-static\-call\-graph ] [ \-\-sum ]
[ \-\-table\-length=\fIlen\fR ] [ \-\-traditional ] [ \-\-version ]
[ \-\-width=\fIn\fR ] [ \-\-ignore\-non\-functions ]
[ \-\-demangle[=\fI\s-1STYLE\s0\fR] ] [ \-\-no\-demangle ]
[\-\-external\-symbol\-table=name]
[ \fIimage-file\fR ] [ \fIprofile-file\fR ... ]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`gprof\*(C'\fR produces an execution profile of C, Pascal, or Fortran77
programs. The effect of called routines is incorporated in the profile
of each caller. The profile data is taken from the call graph profile file
(\fIgmon.out\fR default) which is created by programs
that are compiled with the \fB\-pg\fR option of
\&\f(CW\*(C`cc\*(C'\fR, \f(CW\*(C`pc\*(C'\fR, and \f(CW\*(C`f77\*(C'\fR.
The \fB\-pg\fR option also links in versions of the library routines
that are compiled for profiling. \f(CW\*(C`Gprof\*(C'\fR reads the given object
file (the default is \f(CW\*(C`a.out\*(C'\fR) and establishes the relation between
its symbol table and the call graph profile from \fIgmon.out\fR.
If more than one profile file is specified, the \f(CW\*(C`gprof\*(C'\fR
output shows the sum of the profile information in the given profile files.
.PP
\&\f(CW\*(C`Gprof\*(C'\fR calculates the amount of time spent in each routine.
Next, these times are propagated along the edges of the call graph.
Cycles are discovered, and calls into a cycle are made to share the time
of the cycle.
.PP
Several forms of output are available from the analysis.
.PP
The \fIflat profile\fR shows how much time your program spent in each function,
and how many times that function was called. If you simply want to know
which functions burn most of the cycles, it is stated concisely here.
.PP
The \fIcall graph\fR shows, for each function, which functions called it, which
other functions it called, and how many times. There is also an estimate
of how much time was spent in the subroutines of each function. This can
suggest places where you might try to eliminate function calls that use a
lot of time.
.PP
The \fIannotated source\fR listing is a copy of the program's
source code, labeled with the number of times each line of the
program was executed.
.SH "OPTIONS"
.IX Header "OPTIONS"
These options specify which of several output formats
\&\f(CW\*(C`gprof\*(C'\fR should produce.
.PP
Many of these options take an optional \fIsymspec\fR to specify
functions to be included or excluded. These options can be
specified multiple times, with different symspecs, to include
or exclude sets of symbols.
.PP
Specifying any of these options overrides the default (\fB\-p \-q\fR),
which prints a flat profile and call graph analysis
for all functions.
.ie n .IP """\-A[\fIsymspec\fP]""" 4
.el .IP "\f(CW\-A[\f(CIsymspec\f(CW]\fR" 4
.IX Item "-A[symspec]"
.PD 0
.ie n .IP """\-\-annotated\-source[=\fIsymspec\fP]""" 4
.el .IP "\f(CW\-\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4
.IX Item "--annotated-source[=symspec]"
.PD
The \fB\-A\fR option causes \f(CW\*(C`gprof\*(C'\fR to print annotated source code.
If \fIsymspec\fR is specified, print output only for matching symbols.
.ie n .IP """\-b""" 4
.el .IP "\f(CW\-b\fR" 4
.IX Item "-b"
.PD 0
.ie n .IP """\-\-brief""" 4
.el .IP "\f(CW\-\-brief\fR" 4
.IX Item "--brief"
.PD
If the \fB\-b\fR option is given, \f(CW\*(C`gprof\*(C'\fR doesn't print the
verbose blurbs that try to explain the meaning of all of the fields in
the tables. This is useful if you intend to print out the output, or
are tired of seeing the blurbs.
.ie n .IP """\-B""" 4
.el .IP "\f(CW\-B\fR" 4
.IX Item "-B"
The \fB\-B\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis.
.ie n .IP """\-C[\fIsymspec\fP]""" 4
.el .IP "\f(CW\-C[\f(CIsymspec\f(CW]\fR" 4
.IX Item "-C[symspec]"
.PD 0
.ie n .IP """\-\-exec\-counts[=\fIsymspec\fP]""" 4
.el .IP "\f(CW\-\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4
.IX Item "--exec-counts[=symspec]"
.PD
The \fB\-C\fR option causes \f(CW\*(C`gprof\*(C'\fR to
print a tally of functions and the number of times each was called.
If \fIsymspec\fR is specified, print tally only for matching symbols.
.Sp
If the profile data file contains basic-block count records, specifying
the \fB\-l\fR option, along with \fB\-C\fR, will cause basic-block
execution counts to be tallied and displayed.
.ie n .IP """\-i""" 4
.el .IP "\f(CW\-i\fR" 4
.IX Item "-i"
.PD 0
.ie n .IP """\-\-file\-info""" 4
.el .IP "\f(CW\-\-file\-info\fR" 4
.IX Item "--file-info"
.PD
The \fB\-i\fR option causes \f(CW\*(C`gprof\*(C'\fR to display summary information
about the profile data file(s) and then exit. The number of histogram,
call graph, and basic-block count records is displayed.
.ie n .IP """\-I \fIdirs\fP""" 4
.el .IP "\f(CW\-I \f(CIdirs\f(CW\fR" 4
.IX Item "-I dirs"
.PD 0
.ie n .IP """\-\-directory\-path=\fIdirs\fP""" 4
.el .IP "\f(CW\-\-directory\-path=\f(CIdirs\f(CW\fR" 4
.IX Item "--directory-path=dirs"
.PD
The \fB\-I\fR option specifies a list of search directories in
which to find source files. Environment variable \fI\s-1GPROF_PATH\s0\fR
can also be used to convey this information.
Used mostly for annotated source output.
.ie n .IP """\-J[\fIsymspec\fP]""" 4
.el .IP "\f(CW\-J[\f(CIsymspec\f(CW]\fR" 4
.IX Item "-J[symspec]"
.PD 0
.ie n .IP """\-\-no\-annotated\-source[=\fIsymspec\fP]""" 4
.el .IP "\f(CW\-\-no\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4
.IX Item "--no-annotated-source[=symspec]"
.PD
The \fB\-J\fR option causes \f(CW\*(C`gprof\*(C'\fR not to
print annotated source code.
If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints annotated source,
but excludes matching symbols.
.ie n .IP """\-L""" 4
.el .IP "\f(CW\-L\fR" 4
.IX Item "-L"
.PD 0
.ie n .IP """\-\-print\-path""" 4
.el .IP "\f(CW\-\-print\-path\fR" 4
.IX Item "--print-path"
.PD
Normally, source filenames are printed with the path
component suppressed. The \fB\-L\fR option causes \f(CW\*(C`gprof\*(C'\fR
to print the full pathname of
source filenames, which is determined
from symbolic debugging information in the image file
and is relative to the directory in which the compiler
was invoked.
.ie n .IP """\-p[\fIsymspec\fP]""" 4
.el .IP "\f(CW\-p[\f(CIsymspec\f(CW]\fR" 4
.IX Item "-p[symspec]"
.PD 0
.ie n .IP """\-\-flat\-profile[=\fIsymspec\fP]""" 4
.el .IP "\f(CW\-\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4
.IX Item "--flat-profile[=symspec]"
.PD
The \fB\-p\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a flat profile.
If \fIsymspec\fR is specified, print flat profile only for matching symbols.
.ie n .IP """\-P[\fIsymspec\fP]""" 4
.el .IP "\f(CW\-P[\f(CIsymspec\f(CW]\fR" 4
.IX Item "-P[symspec]"
.PD 0
.ie n .IP """\-\-no\-flat\-profile[=\fIsymspec\fP]""" 4
.el .IP "\f(CW\-\-no\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4
.IX Item "--no-flat-profile[=symspec]"
.PD
The \fB\-P\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing a flat profile.
If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a flat profile,
but excludes matching symbols.
.ie n .IP """\-q[\fIsymspec\fP]""" 4
.el .IP "\f(CW\-q[\f(CIsymspec\f(CW]\fR" 4
.IX Item "-q[symspec]"
.PD 0
.ie n .IP """\-\-graph[=\fIsymspec\fP]""" 4
.el .IP "\f(CW\-\-graph[=\f(CIsymspec\f(CW]\fR" 4
.IX Item "--graph[=symspec]"
.PD
The \fB\-q\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis.
If \fIsymspec\fR is specified, print call graph only for matching symbols
and their children.
.ie n .IP """\-Q[\fIsymspec\fP]""" 4
.el .IP "\f(CW\-Q[\f(CIsymspec\f(CW]\fR" 4
.IX Item "-Q[symspec]"
.PD 0
.ie n .IP """\-\-no\-graph[=\fIsymspec\fP]""" 4
.el .IP "\f(CW\-\-no\-graph[=\f(CIsymspec\f(CW]\fR" 4
.IX Item "--no-graph[=symspec]"
.PD
The \fB\-Q\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing the
call graph.
If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a call graph,
but excludes matching symbols.
.ie n .IP """\-t""" 4
.el .IP "\f(CW\-t\fR" 4
.IX Item "-t"
.PD 0
.ie n .IP """\-\-table\-length=\fInum\fP""" 4
.el .IP "\f(CW\-\-table\-length=\f(CInum\f(CW\fR" 4
.IX Item "--table-length=num"
.PD
The \fB\-t\fR option causes the \fInum\fR most active source lines in
each source file to be listed when source annotation is enabled. The
default is 10.
.ie n .IP """\-y""" 4
.el .IP "\f(CW\-y\fR" 4
.IX Item "-y"
.PD 0
.ie n .IP """\-\-separate\-files""" 4
.el .IP "\f(CW\-\-separate\-files\fR" 4
.IX Item "--separate-files"
.PD
This option affects annotated source output only.
Normally, \f(CW\*(C`gprof\*(C'\fR prints annotated source files
to standard-output. If this option is specified,
annotated source for a file named \fIpath/\fIfilename\fI\fR
is generated in the file \fI\fIfilename\fI\-ann\fR. If the underlying
file system would truncate \fI\fIfilename\fI\-ann\fR so that it
overwrites the original \fI\fIfilename\fI\fR, \f(CW\*(C`gprof\*(C'\fR generates
annotated source in the file \fI\fIfilename\fI.ann\fR instead (if the
original file name has an extension, that extension is \fIreplaced\fR
with \fI.ann\fR).
.ie n .IP """\-Z[\fIsymspec\fP]""" 4
.el .IP "\f(CW\-Z[\f(CIsymspec\f(CW]\fR" 4
.IX Item "-Z[symspec]"
.PD 0
.ie n .IP """\-\-no\-exec\-counts[=\fIsymspec\fP]""" 4
.el .IP "\f(CW\-\-no\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4
.IX Item "--no-exec-counts[=symspec]"
.PD
The \fB\-Z\fR option causes \f(CW\*(C`gprof\*(C'\fR not to
print a tally of functions and the number of times each was called.
If \fIsymspec\fR is specified, print tally, but exclude matching symbols.
.ie n .IP """\-r""" 4
.el .IP "\f(CW\-r\fR" 4
.IX Item "-r"
.PD 0
.ie n .IP """\-\-function\-ordering""" 4
.el .IP "\f(CW\-\-function\-ordering\fR" 4
.IX Item "--function-ordering"
.PD
The \fB\-\-function\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a
suggested function ordering for the program based on profiling data.
This option suggests an ordering which may improve paging, tlb and
cache behavior for the program on systems which support arbitrary
ordering of functions in an executable.
.Sp
The exact details of how to force the linker to place functions
in a particular order is system dependent and out of the scope of this
manual.
.ie n .IP """\-R \fImap_file\fP""" 4
.el .IP "\f(CW\-R \f(CImap_file\f(CW\fR" 4
.IX Item "-R map_file"
.PD 0
.ie n .IP """\-\-file\-ordering \fImap_file\fP""" 4
.el .IP "\f(CW\-\-file\-ordering \f(CImap_file\f(CW\fR" 4
.IX Item "--file-ordering map_file"
.PD
The \fB\-\-file\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a
suggested .o link line ordering for the program based on profiling data.
This option suggests an ordering which may improve paging, tlb and
cache behavior for the program on systems which do not support arbitrary
ordering of functions in an executable.
.Sp
Use of the \fB\-a\fR argument is highly recommended with this option.
.Sp
The \fImap_file\fR argument is a pathname to a file which provides
function name to object file mappings. The format of the file is similar to
the output of the program \f(CW\*(C`nm\*(C'\fR.
.Sp
.Vb 8
\& c\-parse.o:00000000 T yyparse
\& c\-parse.o:00000004 C yyerrflag
\& c\-lang.o:00000000 T maybe_objc_method_name
\& c\-lang.o:00000000 T print_lang_statistics
\& c\-lang.o:00000000 T recognize_objc_keyword
\& c\-decl.o:00000000 T print_lang_identifier
\& c\-decl.o:00000000 T print_lang_type
\& ...
.Ve
.Sp
To create a \fImap_file\fR with \s-1GNU\s0 \f(CW\*(C`nm\*(C'\fR, type a command like
\&\f(CW\*(C`nm \-\-extern\-only \-\-defined\-only \-v \-\-print\-file\-name program\-name\*(C'\fR.
.ie n .IP """\-T""" 4
.el .IP "\f(CW\-T\fR" 4
.IX Item "-T"
.PD 0
.ie n .IP """\-\-traditional""" 4
.el .IP "\f(CW\-\-traditional\fR" 4
.IX Item "--traditional"
.PD
The \fB\-T\fR option causes \f(CW\*(C`gprof\*(C'\fR to print its output in
\&\*(L"traditional\*(R" \s-1BSD\s0 style.
.ie n .IP """\-w \fIwidth\fP""" 4
.el .IP "\f(CW\-w \f(CIwidth\f(CW\fR" 4
.IX Item "-w width"
.PD 0
.ie n .IP """\-\-width=\fIwidth\fP""" 4
.el .IP "\f(CW\-\-width=\f(CIwidth\f(CW\fR" 4
.IX Item "--width=width"
.PD
Sets width of output lines to \fIwidth\fR.
Currently only used when printing the function index at the bottom
of the call graph.
.ie n .IP """\-x""" 4
.el .IP "\f(CW\-x\fR" 4
.IX Item "-x"
.PD 0
.ie n .IP """\-\-all\-lines""" 4
.el .IP "\f(CW\-\-all\-lines\fR" 4
.IX Item "--all-lines"
.PD
This option affects annotated source output only.
By default, only the lines at the beginning of a basic-block
are annotated. If this option is specified, every line in
a basic-block is annotated by repeating the annotation for the
first line. This behavior is similar to \f(CW\*(C`tcov\*(C'\fR's \fB\-a\fR.
.ie n .IP """\-\-demangle[=\fIstyle\fP]""" 4
.el .IP "\f(CW\-\-demangle[=\f(CIstyle\f(CW]\fR" 4
.IX Item "--demangle[=style]"
.PD 0
.ie n .IP """\-\-no\-demangle""" 4
.el .IP "\f(CW\-\-no\-demangle\fR" 4
.IX Item "--no-demangle"
.PD
These options control whether \*(C+ symbol names should be demangled when
printing output. The default is to demangle symbols. The
\&\f(CW\*(C`\-\-no\-demangle\*(C'\fR option may be used to turn off demangling. Different
compilers have different mangling styles. The optional demangling style
argument can be used to choose an appropriate demangling style for your
compiler.
.SS "Analysis Options"
.IX Subsection "Analysis Options"
.ie n .IP """\-a""" 4
.el .IP "\f(CW\-a\fR" 4
.IX Item "-a"
.PD 0
.ie n .IP """\-\-no\-static""" 4
.el .IP "\f(CW\-\-no\-static\fR" 4
.IX Item "--no-static"
.PD
The \fB\-a\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress the printing of
statically declared (private) functions. (These are functions whose
names are not listed as global, and which are not visible outside the
file/function/block where they were defined.) Time spent in these
functions, calls to/from them, etc., will all be attributed to the
function that was loaded directly before it in the executable file.
This option affects both the flat profile and the call graph.
.ie n .IP """\-c""" 4
.el .IP "\f(CW\-c\fR" 4
.IX Item "-c"
.PD 0
.ie n .IP """\-\-static\-call\-graph""" 4
.el .IP "\f(CW\-\-static\-call\-graph\fR" 4
.IX Item "--static-call-graph"
.PD
The \fB\-c\fR option causes the call graph of the program to be
augmented by a heuristic which examines the text space of the object
file and identifies function calls in the binary machine code.
Since normal call graph records are only generated when functions are
entered, this option identifies children that could have been called,
but never were. Calls to functions that were not compiled with
profiling enabled are also identified, but only if symbol table
entries are present for them.
Calls to dynamic library routines are typically \fInot\fR found
by this option.
Parents or children identified via this heuristic
are indicated in the call graph with call counts of \fB0\fR.
.ie n .IP """\-D""" 4
.el .IP "\f(CW\-D\fR" 4
.IX Item "-D"
.PD 0
.ie n .IP """\-\-ignore\-non\-functions""" 4
.el .IP "\f(CW\-\-ignore\-non\-functions\fR" 4
.IX Item "--ignore-non-functions"
.PD
The \fB\-D\fR option causes \f(CW\*(C`gprof\*(C'\fR to ignore symbols which
are not known to be functions. This option will give more accurate
profile data on systems where it is supported (Solaris and \s-1HPUX\s0 for
example).
.ie n .IP """\-k \fIfrom\fP/\fIto\fP""" 4
.el .IP "\f(CW\-k \f(CIfrom\f(CW/\f(CIto\f(CW\fR" 4
.IX Item "-k from/to"
The \fB\-k\fR option allows you to delete from the call graph any arcs from
symbols matching symspec \fIfrom\fR to those matching symspec \fIto\fR.
.ie n .IP """\-l""" 4
.el .IP "\f(CW\-l\fR" 4
.IX Item "-l"
.PD 0
.ie n .IP """\-\-line""" 4
.el .IP "\f(CW\-\-line\fR" 4
.IX Item "--line"
.PD
The \fB\-l\fR option enables line-by-line profiling, which causes
histogram hits to be charged to individual source code lines,
instead of functions. This feature only works with programs compiled
by older versions of the \f(CW\*(C`gcc\*(C'\fR compiler. Newer versions of
\&\f(CW\*(C`gcc\*(C'\fR are designed to work with the \f(CW\*(C`gcov\*(C'\fR tool instead.
.Sp
If the program was compiled with basic-block counting enabled,
this option will also identify how many times each line of
code was executed.
While line-by-line profiling can help isolate where in a large function
a program is spending its time, it also significantly increases
the running time of \f(CW\*(C`gprof\*(C'\fR, and magnifies statistical
inaccuracies.
.ie n .IP """\-\-inline\-file\-names""" 4
.el .IP "\f(CW\-\-inline\-file\-names\fR" 4
.IX Item "--inline-file-names"
This option causes \f(CW\*(C`gprof\*(C'\fR to print the source file after each
symbol in both the flat profile and the call graph. The full path to the
file is printed if used with the \fB\-L\fR option.
.ie n .IP """\-m \fInum\fP""" 4
.el .IP "\f(CW\-m \f(CInum\f(CW\fR" 4
.IX Item "-m num"
.PD 0
.ie n .IP """\-\-min\-count=\fInum\fP""" 4
.el .IP "\f(CW\-\-min\-count=\f(CInum\f(CW\fR" 4
.IX Item "--min-count=num"
.PD
This option affects execution count output only.
Symbols that are executed less than \fInum\fR times are suppressed.
.ie n .IP """\-n\fIsymspec\fP""" 4
.el .IP "\f(CW\-n\f(CIsymspec\f(CW\fR" 4
.IX Item "-nsymspec"
.PD 0
.ie n .IP """\-\-time=\fIsymspec\fP""" 4
.el .IP "\f(CW\-\-time=\f(CIsymspec\f(CW\fR" 4
.IX Item "--time=symspec"
.PD
The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis,
to only propagate times for symbols matching \fIsymspec\fR.
.ie n .IP """\-N\fIsymspec\fP""" 4
.el .IP "\f(CW\-N\f(CIsymspec\f(CW\fR" 4
.IX Item "-Nsymspec"
.PD 0
.ie n .IP """\-\-no\-time=\fIsymspec\fP""" 4
.el .IP "\f(CW\-\-no\-time=\f(CIsymspec\f(CW\fR" 4
.IX Item "--no-time=symspec"
.PD
The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis,
not to propagate times for symbols matching \fIsymspec\fR.
.ie n .IP """\-S\fIfilename\fP""" 4
.el .IP "\f(CW\-S\f(CIfilename\f(CW\fR" 4
.IX Item "-Sfilename"
.PD 0
.ie n .IP """\-\-external\-symbol\-table=\fIfilename\fP""" 4
.el .IP "\f(CW\-\-external\-symbol\-table=\f(CIfilename\f(CW\fR" 4
.IX Item "--external-symbol-table=filename"
.PD
The \fB\-S\fR option causes \f(CW\*(C`gprof\*(C'\fR to read an external symbol table
file, such as \fI/proc/kallsyms\fR, rather than read the symbol table
from the given object file (the default is \f(CW\*(C`a.out\*(C'\fR). This is useful
for profiling kernel modules.
.ie n .IP """\-z""" 4
.el .IP "\f(CW\-z\fR" 4
.IX Item "-z"
.PD 0
.ie n .IP """\-\-display\-unused\-functions""" 4
.el .IP "\f(CW\-\-display\-unused\-functions\fR" 4
.IX Item "--display-unused-functions"
.PD
If you give the \fB\-z\fR option, \f(CW\*(C`gprof\*(C'\fR will mention all
functions in the flat profile, even those that were never called, and
that had no time spent in them. This is useful in conjunction with the
\&\fB\-c\fR option for discovering which routines were never called.
.SS "Miscellaneous Options"
.IX Subsection "Miscellaneous Options"
.ie n .IP """\-d[\fInum\fP]""" 4
.el .IP "\f(CW\-d[\f(CInum\f(CW]\fR" 4
.IX Item "-d[num]"
.PD 0
.ie n .IP """\-\-debug[=\fInum\fP]""" 4
.el .IP "\f(CW\-\-debug[=\f(CInum\f(CW]\fR" 4
.IX Item "--debug[=num]"
.PD
The \fB\-d\fR \fInum\fR option specifies debugging options.
If \fInum\fR is not specified, enable all debugging.
.ie n .IP """\-h""" 4
.el .IP "\f(CW\-h\fR" 4
.IX Item "-h"
.PD 0
.ie n .IP """\-\-help""" 4
.el .IP "\f(CW\-\-help\fR" 4
.IX Item "--help"
.PD
The \fB\-h\fR option prints command line usage.
.ie n .IP """\-O\fIname\fP""" 4
.el .IP "\f(CW\-O\f(CIname\f(CW\fR" 4
.IX Item "-Oname"
.PD 0
.ie n .IP """\-\-file\-format=\fIname\fP""" 4
.el .IP "\f(CW\-\-file\-format=\f(CIname\f(CW\fR" 4
.IX Item "--file-format=name"
.PD
Selects the format of the profile data files. Recognized formats are
\&\fBauto\fR (the default), \fBbsd\fR, \fB4.4bsd\fR, \fBmagic\fR, and
\&\fBprof\fR (not yet supported).
.ie n .IP """\-s""" 4
.el .IP "\f(CW\-s\fR" 4
.IX Item "-s"
.PD 0
.ie n .IP """\-\-sum""" 4
.el .IP "\f(CW\-\-sum\fR" 4
.IX Item "--sum"
.PD
The \fB\-s\fR option causes \f(CW\*(C`gprof\*(C'\fR to summarize the information
in the profile data files it read in, and write out a profile data
file called \fIgmon.sum\fR, which contains all the information from
the profile data files that \f(CW\*(C`gprof\*(C'\fR read in. The file \fIgmon.sum\fR
may be one of the specified input files; the effect of this is to
merge the data in the other input files into \fIgmon.sum\fR.
.Sp
Eventually you can run \f(CW\*(C`gprof\*(C'\fR again without \fB\-s\fR to analyze the
cumulative data in the file \fIgmon.sum\fR.
.ie n .IP """\-v""" 4
.el .IP "\f(CW\-v\fR" 4
.IX Item "-v"
.PD 0
.ie n .IP """\-\-version""" 4
.el .IP "\f(CW\-\-version\fR" 4
.IX Item "--version"
.PD
The \fB\-v\fR flag causes \f(CW\*(C`gprof\*(C'\fR to print the current version
number, and then exit.
.SS "Deprecated Options"
.IX Subsection "Deprecated Options"
These options have been replaced with newer versions that use symspecs.
.ie n .IP """\-e \fIfunction_name\fP""" 4
.el .IP "\f(CW\-e \f(CIfunction_name\f(CW\fR" 4
.IX Item "-e function_name"
The \fB\-e\fR \fIfunction\fR option tells \f(CW\*(C`gprof\*(C'\fR to not print
information about the function \fIfunction_name\fR (and its
children...) in the call graph. The function will still be listed
as a child of any functions that call it, but its index number will be
shown as \fB[not printed]\fR. More than one \fB\-e\fR option may be
given; only one \fIfunction_name\fR may be indicated with each \fB\-e\fR
option.
.ie n .IP """\-E \fIfunction_name\fP""" 4
.el .IP "\f(CW\-E \f(CIfunction_name\f(CW\fR" 4
.IX Item "-E function_name"
The \f(CW\*(C`\-E \f(CIfunction\f(CW\*(C'\fR option works like the \f(CW\*(C`\-e\*(C'\fR option, but
time spent in the function (and children who were not called from
anywhere else), will not be used to compute the percentages-of-time for
the call graph. More than one \fB\-E\fR option may be given; only one
\&\fIfunction_name\fR may be indicated with each \fB\-E\fR option.
.ie n .IP """\-f \fIfunction_name\fP""" 4
.el .IP "\f(CW\-f \f(CIfunction_name\f(CW\fR" 4
.IX Item "-f function_name"
The \fB\-f\fR \fIfunction\fR option causes \f(CW\*(C`gprof\*(C'\fR to limit the
call graph to the function \fIfunction_name\fR and its children (and
their children...). More than one \fB\-f\fR option may be given;
only one \fIfunction_name\fR may be indicated with each \fB\-f\fR
option.
.ie n .IP """\-F \fIfunction_name\fP""" 4
.el .IP "\f(CW\-F \f(CIfunction_name\f(CW\fR" 4
.IX Item "-F function_name"
The \fB\-F\fR \fIfunction\fR option works like the \f(CW\*(C`\-f\*(C'\fR option, but
only time spent in the function and its children (and their
children...) will be used to determine total-time and
percentages-of-time for the call graph. More than one \fB\-F\fR option
may be given; only one \fIfunction_name\fR may be indicated with each
\&\fB\-F\fR option. The \fB\-F\fR option overrides the \fB\-E\fR option.
.SH "FILES"
.IX Header "FILES"
.ie n .IP """\fIa.out\fP""" 4
.el .IP "\f(CW\f(CIa.out\f(CW\fR" 4
.IX Item "a.out"
the namelist and text space.
.ie n .IP """\fIgmon.out\fP""" 4
.el .IP "\f(CW\f(CIgmon.out\f(CW\fR" 4
.IX Item "gmon.out"
dynamic call graph and profile.
.ie n .IP """\fIgmon.sum\fP""" 4
.el .IP "\f(CW\f(CIgmon.sum\f(CW\fR" 4
.IX Item "gmon.sum"
summarized dynamic call graph and profile.
.SH "BUGS"
.IX Header "BUGS"
The granularity of the sampling is shown, but remains
statistical at best.
We assume that the time for each execution of a function
can be expressed by the total time for the function divided
by the number of times the function is called.
Thus the time propagated along the call graph arcs to the function's
parents is directly proportional to the number of times that
arc is traversed.
.PP
Parents that are not themselves profiled will have the time of
their profiled children propagated to them, but they will appear
to be spontaneously invoked in the call graph listing, and will
not have their time propagated further.
Similarly, signal catchers, even though profiled, will appear
to be spontaneous (although for more obscure reasons).
Any profiled children of signal catchers should have their times
propagated properly, unless the signal catcher was invoked during
the execution of the profiling routine, in which case all is lost.
.PP
The profiled program must call \f(CW\*(C`exit\*(C'\fR(2)
or return normally for the profiling information to be saved
in the \fIgmon.out\fR file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBmonitor\fR\|(3), \fBprofil\fR\|(2), \fBcc\fR\|(1), \fBprof\fR\|(1), and the Info entry for \fIgprof\fR.
.PP
\&\*(L"An Execution Profiler for Modular Programs\*(R",
by S. Graham, P. Kessler, M. McKusick;
Software \- Practice and Experience,
Vol. 13, pp. 671\-685, 1983.
.PP
\&\*(L"gprof: A Call Graph Execution Profiler\*(R",
by S. Graham, P. Kessler, M. McKusick;
Proceedings of the \s-1SIGPLAN\s0 '82 Symposium on Compiler Construction,
\&\s-1SIGPLAN\s0 Notices, Vol. 17, No 6, pp. 120\-126, June 1982.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1988\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

3763
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-ld.1 Normal file
View File

File diff suppressed because it is too large Load Diff

239
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-lto-dump.1 Normal file
View File

@ -0,0 +1,239 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "LTO-DUMP 1"
.TH LTO-DUMP 1 "2023-07-27" "gcc-13.2.0" "GNU"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
lto\-dump \- Tool for dumping LTO object files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
lto-dump [\fB\-list\fR]
[\fB\-demangle\fR]
[\fB\-defined\-only\fR]
[\fB\-print\-value\fR]
[\fB\-name\-sort\fR]
[\fB\-size\-sort\fR]
[\fB\-reverse\-sort\fR]
[\fB\-no\-sort\fR]
[\fB\-symbol=\fR]
[\fB\-objects\fR]
[\fB\-type\-stats\fR]
[\fB\-tree\-stats\fR]
[\fB\-gimple\-stats\fR]
[\fB\-dump\-level=\fR]
[\fB\-dump\-body=\fR]
[\fB\-help\fR] \fIlto-dump\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBlto-dump\fR is a tool you can use in conjunction with \s-1GCC\s0 to
dump link time optimization object files.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-list\fR" 4
.IX Item "-list"
Dumps list of details of functions and variables.
.IP "\fB\-demangle\fR" 4
.IX Item "-demangle"
Dump the demangled output.
.IP "\fB\-defined\-only\fR" 4
.IX Item "-defined-only"
Dump only the defined symbols.
.IP "\fB\-print\-value\fR" 4
.IX Item "-print-value"
Dump initial values of the variables.
.IP "\fB\-name\-sort\fR" 4
.IX Item "-name-sort"
Sort the symbols alphabetically.
.IP "\fB\-size\-sort\fR" 4
.IX Item "-size-sort"
Sort the symbols according to size.
.IP "\fB\-reverse\-sort\fR" 4
.IX Item "-reverse-sort"
Dump the symbols in reverse order.
.IP "\fB\-no\-sort\fR" 4
.IX Item "-no-sort"
Dump the symbols in order of occurrence.
.IP "\fB\-symbol=\fR" 4
.IX Item "-symbol="
Dump the details of specific symbol.
.IP "\fB\-objects\fR" 4
.IX Item "-objects"
Dump the details of \s-1LTO\s0 objects.
.IP "\fB\-type\-stats\fR" 4
.IX Item "-type-stats"
Dump the statistics of tree types.
.IP "\fB\-tree\-stats\fR" 4
.IX Item "-tree-stats"
Dump the statistics of trees.
.IP "\fB\-gimple\-stats\fR" 4
.IX Item "-gimple-stats"
Dump the statistics of gimple statements.
.IP "\fB\-dump\-level=\fR" 4
.IX Item "-dump-level="
For deciding the optimization level of body.
.IP "\fB\-dump\-body=\fR" 4
.IX Item "-dump-body="
Dump the specific gimple body.
.IP "\fB\-help\fR" 4
.IX Item "-help"
Display the dump tool help.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2017\-2023 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being \*(L"\s-1GNU\s0 General Public License\*(R" and \*(L"Funding
Free Software\*(R", the Front-Cover texts being (a) (see below), and with
the Back-Cover Texts being (b) (see below). A copy of the license is
included in the \fBgfdl\fR\|(7) man page.
.PP
(a) The \s-1FSF\s0's Front-Cover Text is:
.PP
.Vb 1
\& A GNU Manual
.Ve
.PP
(b) The \s-1FSF\s0's Back-Cover Text is:
.PP
.Vb 3
\& You have freedom to copy and modify this GNU Manual, like GNU
\& software. Copies published by the Free Software Foundation raise
\& funds for GNU development.
.Ve

689
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-nm.1 Normal file
View File

@ -0,0 +1,689 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "NM 1"
.TH NM 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nm \- list symbols from object files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
nm [\fB\-A\fR|\fB\-o\fR|\fB\-\-print\-file\-name\fR]
[\fB\-a\fR|\fB\-\-debug\-syms\fR]
[\fB\-B\fR|\fB\-\-format=bsd\fR]
[\fB\-C\fR|\fB\-\-demangle\fR[=\fIstyle\fR]]
[\fB\-D\fR|\fB\-\-dynamic\fR]
[\fB\-f\fR\fIformat\fR|\fB\-\-format=\fR\fIformat\fR]
[\fB\-g\fR|\fB\-\-extern\-only\fR]
[\fB\-h\fR|\fB\-\-help\fR]
[\fB\-\-ifunc\-chars=\fR\fI\s-1CHARS\s0\fR]
[\fB\-j\fR|\fB\-\-format=just\-symbols\fR]
[\fB\-l\fR|\fB\-\-line\-numbers\fR] [\fB\-\-inlines\fR]
[\fB\-n\fR|\fB\-v\fR|\fB\-\-numeric\-sort\fR]
[\fB\-P\fR|\fB\-\-portability\fR]
[\fB\-p\fR|\fB\-\-no\-sort\fR]
[\fB\-r\fR|\fB\-\-reverse\-sort\fR]
[\fB\-S\fR|\fB\-\-print\-size\fR]
[\fB\-s\fR|\fB\-\-print\-armap\fR]
[\fB\-t\fR \fIradix\fR|\fB\-\-radix=\fR\fIradix\fR]
[\fB\-u\fR|\fB\-\-undefined\-only\fR]
[\fB\-U\fR|\fB\-\-defined\-only\fR]
[\fB\-V\fR|\fB\-\-version\fR]
[\fB\-W\fR|\fB\-\-no\-weak\fR]
[\fB\-X 32_64\fR]
[\fB\-\-no\-demangle\fR]
[\fB\-\-no\-recurse\-limit\fR|\fB\-\-recurse\-limit\fR]]
[\fB\-\-plugin\fR \fIname\fR]
[\fB\-\-size\-sort\fR]
[\fB\-\-special\-syms\fR]
[\fB\-\-synthetic\fR]
[\fB\-\-target=\fR\fIbfdname\fR]
[\fB\-\-unicode=\fR\fImethod\fR]
[\fB\-\-with\-symbol\-versions\fR]
[\fB\-\-without\-symbol\-versions\fR]
[\fIobjfile\fR...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1GNU\s0 \fBnm\fR lists the symbols from object files \fIobjfile\fR....
If no object files are listed as arguments, \fBnm\fR assumes the file
\&\fIa.out\fR.
.PP
For each symbol, \fBnm\fR shows:
.IP "\(bu" 4
The symbol value, in the radix selected by options (see below), or
hexadecimal by default.
.IP "\(bu" 4
The symbol type. At least the following types are used; others are, as
well, depending on the object file format. If lowercase, the symbol is
usually local; if uppercase, the symbol is global (external). There
are however a few lowercase symbols that are shown for special global
symbols (\f(CW\*(C`u\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`w\*(C'\fR).
.RS 4
.ie n .IP """A""" 4
.el .IP "\f(CWA\fR" 4
.IX Item "A"
The symbol's value is absolute, and will not be changed by further
linking.
.ie n .IP """B""" 4
.el .IP "\f(CWB\fR" 4
.IX Item "B"
.PD 0
.ie n .IP """b""" 4
.el .IP "\f(CWb\fR" 4
.IX Item "b"
.PD
The symbol is in the \s-1BSS\s0 data section. This section typically
contains zero-initialized or uninitialized data, although the exact
behavior is system dependent.
.ie n .IP """C""" 4
.el .IP "\f(CWC\fR" 4
.IX Item "C"
.PD 0
.ie n .IP """c""" 4
.el .IP "\f(CWc\fR" 4
.IX Item "c"
.PD
The symbol is common. Common symbols are uninitialized data. When
linking, multiple common symbols may appear with the same name. If the
symbol is defined anywhere, the common symbols are treated as undefined
references.
The lower case \fIc\fR character is used when the symbol is in a
special section for small commons.
.ie n .IP """D""" 4
.el .IP "\f(CWD\fR" 4
.IX Item "D"
.PD 0
.ie n .IP """d""" 4
.el .IP "\f(CWd\fR" 4
.IX Item "d"
.PD
The symbol is in the initialized data section.
.ie n .IP """G""" 4
.el .IP "\f(CWG\fR" 4
.IX Item "G"
.PD 0
.ie n .IP """g""" 4
.el .IP "\f(CWg\fR" 4
.IX Item "g"
.PD
The symbol is in an initialized data section for small objects. Some
object file formats permit more efficient access to small data objects,
such as a global int variable as opposed to a large global array.
.ie n .IP """i""" 4
.el .IP "\f(CWi\fR" 4
.IX Item "i"
For \s-1PE\s0 format files this indicates that the symbol is in a section
specific to the implementation of DLLs.
.Sp
For \s-1ELF\s0 format files this indicates that the symbol is an indirect
function. This is a \s-1GNU\s0 extension to the standard set of \s-1ELF\s0 symbol
types. It indicates a symbol which if referenced by a relocation does
not evaluate to its address, but instead must be invoked at runtime.
The runtime execution will then return the value to be used in the
relocation.
.Sp
Note \- the actual symbols display for \s-1GNU\s0 indirect symbols is
controlled by the \fB\-\-ifunc\-chars\fR command line option. If this
option has been provided then the first character in the string will
be used for global indirect function symbols. If the string contains
a second character then that will be used for local indirect function
symbols.
.ie n .IP """I""" 4
.el .IP "\f(CWI\fR" 4
.IX Item "I"
The symbol is an indirect reference to another symbol.
.ie n .IP """N""" 4
.el .IP "\f(CWN\fR" 4
.IX Item "N"
The symbol is a debugging symbol.
.ie n .IP """n""" 4
.el .IP "\f(CWn\fR" 4
.IX Item "n"
The symbol is in a non-data, non-code, non-debug read-only section.
.ie n .IP """p""" 4
.el .IP "\f(CWp\fR" 4
.IX Item "p"
The symbol is in a stack unwind section.
.ie n .IP """R""" 4
.el .IP "\f(CWR\fR" 4
.IX Item "R"
.PD 0
.ie n .IP """r""" 4
.el .IP "\f(CWr\fR" 4
.IX Item "r"
.PD
The symbol is in a read only data section.
.ie n .IP """S""" 4
.el .IP "\f(CWS\fR" 4
.IX Item "S"
.PD 0
.ie n .IP """s""" 4
.el .IP "\f(CWs\fR" 4
.IX Item "s"
.PD
The symbol is in an uninitialized or zero-initialized data section
for small objects.
.ie n .IP """T""" 4
.el .IP "\f(CWT\fR" 4
.IX Item "T"
.PD 0
.ie n .IP """t""" 4
.el .IP "\f(CWt\fR" 4
.IX Item "t"
.PD
The symbol is in the text (code) section.
.ie n .IP """U""" 4
.el .IP "\f(CWU\fR" 4
.IX Item "U"
The symbol is undefined.
.ie n .IP """u""" 4
.el .IP "\f(CWu\fR" 4
.IX Item "u"
The symbol is a unique global symbol. This is a \s-1GNU\s0 extension to the
standard set of \s-1ELF\s0 symbol bindings. For such a symbol the dynamic linker
will make sure that in the entire process there is just one symbol with
this name and type in use.
.ie n .IP """V""" 4
.el .IP "\f(CWV\fR" 4
.IX Item "V"
.PD 0
.ie n .IP """v""" 4
.el .IP "\f(CWv\fR" 4
.IX Item "v"
.PD
The symbol is a weak object. When a weak defined symbol is linked with
a normal defined symbol, the normal defined symbol is used with no error.
When a weak undefined symbol is linked and the symbol is not defined,
the value of the weak symbol becomes zero with no error. On some
systems, uppercase indicates that a default value has been specified.
.ie n .IP """W""" 4
.el .IP "\f(CWW\fR" 4
.IX Item "W"
.PD 0
.ie n .IP """w""" 4
.el .IP "\f(CWw\fR" 4
.IX Item "w"
.PD
The symbol is a weak symbol that has not been specifically tagged as a
weak object symbol. When a weak defined symbol is linked with a normal
defined symbol, the normal defined symbol is used with no error.
When a weak undefined symbol is linked and the symbol is not defined,
the value of the symbol is determined in a system-specific manner without
error. On some systems, uppercase indicates that a default value has been
specified.
.ie n .IP """\-""" 4
.el .IP "\f(CW\-\fR" 4
.IX Item "-"
The symbol is a stabs symbol in an a.out object file. In this case, the
next values printed are the stabs other field, the stabs desc field, and
the stab type. Stabs symbols are used to hold debugging information.
.ie n .IP """?""" 4
.el .IP "\f(CW?\fR" 4
.IX Item "?"
The symbol type is unknown, or object file format specific.
.RE
.RS 4
.RE
.IP "\(bu" 4
The symbol name. If a symbol has version information associated with it,
then the version information is displayed as well. If the versioned
symbol is undefined or hidden from linker, the version string is displayed
as a suffix to the symbol name, preceded by an @ character. For example
\&\fBfoo@VER_1\fR. If the version is the default version to be used when
resolving unversioned references to the symbol, then it is displayed as a
suffix preceded by two @ characters. For example \fBfoo@@VER_2\fR.
.SH "OPTIONS"
.IX Header "OPTIONS"
The long and short forms of options, shown here as alternatives, are
equivalent.
.IP "\fB\-A\fR" 4
.IX Item "-A"
.PD 0
.IP "\fB\-o\fR" 4
.IX Item "-o"
.IP "\fB\-\-print\-file\-name\fR" 4
.IX Item "--print-file-name"
.PD
Precede each symbol by the name of the input file (or archive member)
in which it was found, rather than identifying the input file once only,
before all of its symbols.
.IP "\fB\-a\fR" 4
.IX Item "-a"
.PD 0
.IP "\fB\-\-debug\-syms\fR" 4
.IX Item "--debug-syms"
.PD
Display all symbols, even debugger-only symbols; normally these are not
listed.
.IP "\fB\-B\fR" 4
.IX Item "-B"
The same as \fB\-\-format=bsd\fR (for compatibility with the \s-1MIPS\s0 \fBnm\fR).
.IP "\fB\-C\fR" 4
.IX Item "-C"
.PD 0
.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
.IX Item "--demangle[=style]"
.PD
Decode (\fIdemangle\fR) low-level symbol names into user-level names.
Besides removing any initial underscore prepended by the system, this
makes \*(C+ function names readable. Different compilers have different
mangling styles. The optional demangling style argument can be used to
choose an appropriate demangling style for your compiler.
.IP "\fB\-\-no\-demangle\fR" 4
.IX Item "--no-demangle"
Do not demangle low-level symbol names. This is the default.
.IP "\fB\-\-recurse\-limit\fR" 4
.IX Item "--recurse-limit"
.PD 0
.IP "\fB\-\-no\-recurse\-limit\fR" 4
.IX Item "--no-recurse-limit"
.IP "\fB\-\-recursion\-limit\fR" 4
.IX Item "--recursion-limit"
.IP "\fB\-\-no\-recursion\-limit\fR" 4
.IX Item "--no-recursion-limit"
.PD
Enables or disables a limit on the amount of recursion performed
whilst demangling strings. Since the name mangling formats allow for
an infinite level of recursion it is possible to create strings whose
decoding will exhaust the amount of stack space available on the host
machine, triggering a memory fault. The limit tries to prevent this
from happening by restricting recursion to 2048 levels of nesting.
.Sp
The default is for this limit to be enabled, but disabling it may be
necessary in order to demangle truly complicated names. Note however
that if the recursion limit is disabled then stack exhaustion is
possible and any bug reports about such an event will be rejected.
.IP "\fB\-D\fR" 4
.IX Item "-D"
.PD 0
.IP "\fB\-\-dynamic\fR" 4
.IX Item "--dynamic"
.PD
Display the dynamic symbols rather than the normal symbols. This is
only meaningful for dynamic objects, such as certain types of shared
libraries.
.IP "\fB\-f\fR \fIformat\fR" 4
.IX Item "-f format"
.PD 0
.IP "\fB\-\-format=\fR\fIformat\fR" 4
.IX Item "--format=format"
.PD
Use the output format \fIformat\fR, which can be \f(CW\*(C`bsd\*(C'\fR,
\&\f(CW\*(C`sysv\*(C'\fR, \f(CW\*(C`posix\*(C'\fR or \f(CW\*(C`just\-symbols\*(C'\fR. The default is \f(CW\*(C`bsd\*(C'\fR.
Only the first character of \fIformat\fR is significant; it can be
either upper or lower case.
.IP "\fB\-g\fR" 4
.IX Item "-g"
.PD 0
.IP "\fB\-\-extern\-only\fR" 4
.IX Item "--extern-only"
.PD
Display only external symbols.
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Show a summary of the options to \fBnm\fR and exit.
.IP "\fB\-\-ifunc\-chars=\fR\fI\s-1CHARS\s0\fR" 4
.IX Item "--ifunc-chars=CHARS"
When display \s-1GNU\s0 indirect function symbols \fBnm\fR will default
to using the \f(CW\*(C`i\*(C'\fR character for both local indirect functions and
global indirect functions. The \fB\-\-ifunc\-chars\fR option allows
the user to specify a string containing one or two characters. The
first character will be used for global indirect function symbols and
the second character, if present, will be used for local indirect
function symbols.
.IP "\fBj\fR" 4
.IX Item "j"
The same as \fB\-\-format=just\-symbols\fR.
.IP "\fB\-l\fR" 4
.IX Item "-l"
.PD 0
.IP "\fB\-\-line\-numbers\fR" 4
.IX Item "--line-numbers"
.PD
For each symbol, use debugging information to try to find a filename and
line number. For a defined symbol, look for the line number of the
address of the symbol. For an undefined symbol, look for the line
number of a relocation entry which refers to the symbol. If line number
information can be found, print it after the other symbol information.
.IP "\fB\-\-inlines\fR" 4
.IX Item "--inlines"
When option \fB\-l\fR is active, if the address belongs to a
function that was inlined, then this option causes the source
information for all enclosing scopes back to the first non-inlined
function to be printed as well. For example, if \f(CW\*(C`main\*(C'\fR inlines
\&\f(CW\*(C`callee1\*(C'\fR which inlines \f(CW\*(C`callee2\*(C'\fR, and address is from
\&\f(CW\*(C`callee2\*(C'\fR, the source information for \f(CW\*(C`callee1\*(C'\fR and \f(CW\*(C`main\*(C'\fR
will also be printed.
.IP "\fB\-n\fR" 4
.IX Item "-n"
.PD 0
.IP "\fB\-v\fR" 4
.IX Item "-v"
.IP "\fB\-\-numeric\-sort\fR" 4
.IX Item "--numeric-sort"
.PD
Sort symbols numerically by their addresses, rather than alphabetically
by their names.
.IP "\fB\-p\fR" 4
.IX Item "-p"
.PD 0
.IP "\fB\-\-no\-sort\fR" 4
.IX Item "--no-sort"
.PD
Do not bother to sort the symbols in any order; print them in the order
encountered.
.IP "\fB\-P\fR" 4
.IX Item "-P"
.PD 0
.IP "\fB\-\-portability\fR" 4
.IX Item "--portability"
.PD
Use the \s-1POSIX.2\s0 standard output format instead of the default format.
Equivalent to \fB\-f posix\fR.
.IP "\fB\-r\fR" 4
.IX Item "-r"
.PD 0
.IP "\fB\-\-reverse\-sort\fR" 4
.IX Item "--reverse-sort"
.PD
Reverse the order of the sort (whether numeric or alphabetic); let the
last come first.
.IP "\fB\-S\fR" 4
.IX Item "-S"
.PD 0
.IP "\fB\-\-print\-size\fR" 4
.IX Item "--print-size"
.PD
Print both value and size of defined symbols for the \f(CW\*(C`bsd\*(C'\fR output style.
This option has no effect for object formats that do not record symbol
sizes, unless \fB\-\-size\-sort\fR is also used in which case a
calculated size is displayed.
.IP "\fB\-s\fR" 4
.IX Item "-s"
.PD 0
.IP "\fB\-\-print\-armap\fR" 4
.IX Item "--print-armap"
.PD
When listing symbols from archive members, include the index: a mapping
(stored in the archive by \fBar\fR or \fBranlib\fR) of which modules
contain definitions for which names.
.IP "\fB\-t\fR \fIradix\fR" 4
.IX Item "-t radix"
.PD 0
.IP "\fB\-\-radix=\fR\fIradix\fR" 4
.IX Item "--radix=radix"
.PD
Use \fIradix\fR as the radix for printing the symbol values. It must be
\&\fBd\fR for decimal, \fBo\fR for octal, or \fBx\fR for hexadecimal.
.IP "\fB\-u\fR" 4
.IX Item "-u"
.PD 0
.IP "\fB\-\-undefined\-only\fR" 4
.IX Item "--undefined-only"
.PD
Display only undefined symbols (those external to each object file).
By default both defined and undefined symbols are displayed.
.IP "\fB\-U\fR" 4
.IX Item "-U"
.PD 0
.IP "\fB\-\-defined\-only\fR" 4
.IX Item "--defined-only"
.PD
Display only defined symbols for each object file.
By default both defined and undefined symbols are displayed.
.IP "\fB\-V\fR" 4
.IX Item "-V"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Show the version number of \fBnm\fR and exit.
.IP "\fB\-X\fR" 4
.IX Item "-X"
This option is ignored for compatibility with the \s-1AIX\s0 version of
\&\fBnm\fR. It takes one parameter which must be the string
\&\fB32_64\fR. The default mode of \s-1AIX\s0 \fBnm\fR corresponds
to \fB\-X 32\fR, which is not supported by \s-1GNU\s0 \fBnm\fR.
.IP "\fB\-\-plugin\fR \fIname\fR" 4
.IX Item "--plugin name"
Load the plugin called \fIname\fR to add support for extra target
types. This option is only available if the toolchain has been built
with plugin support enabled.
.Sp
If \fB\-\-plugin\fR is not provided, but plugin support has been
enabled then \fBnm\fR iterates over the files in
\&\fI${libdir}/bfd\-plugins\fR in alphabetic order and the first
plugin that claims the object in question is used.
.Sp
Please note that this plugin search directory is \fInot\fR the one
used by \fBld\fR's \fB\-plugin\fR option. In order to make
\&\fBnm\fR use the linker plugin it must be copied into the
\&\fI${libdir}/bfd\-plugins\fR directory. For \s-1GCC\s0 based compilations
the linker plugin is called \fIliblto_plugin.so.0.0.0\fR. For Clang
based compilations it is called \fILLVMgold.so\fR. The \s-1GCC\s0 plugin
is always backwards compatible with earlier versions, so it is
sufficient to just copy the newest one.
.IP "\fB\-\-size\-sort\fR" 4
.IX Item "--size-sort"
Sort symbols by size. For \s-1ELF\s0 objects symbol sizes are read from the
\&\s-1ELF,\s0 for other object types the symbol sizes are computed as the
difference between the value of the symbol and the value of the symbol
with the next higher value. If the \f(CW\*(C`bsd\*(C'\fR output format is used
the size of the symbol is printed, rather than the value, and
\&\fB\-S\fR must be used in order both size and value to be printed.
.Sp
Note \- this option does not work if \fB\-\-undefined\-only\fR has been
enabled as undefined symbols have no size.
.IP "\fB\-\-special\-syms\fR" 4
.IX Item "--special-syms"
Display symbols which have a target-specific special meaning. These
symbols are usually used by the target for some special processing and
are not normally helpful when included in the normal symbol lists.
For example for \s-1ARM\s0 targets this option would skip the mapping symbols
used to mark transitions between \s-1ARM\s0 code, \s-1THUMB\s0 code and data.
.IP "\fB\-\-synthetic\fR" 4
.IX Item "--synthetic"
Include synthetic symbols in the output. These are special symbols
created by the linker for various purposes. They are not shown by
default since they are not part of the binary's original source code.
.IP "\fB\-\-unicode=\fR\fI[default|invalid|locale|escape|hex|highlight]\fR" 4
.IX Item "--unicode=[default|invalid|locale|escape|hex|highlight]"
Controls the display of \s-1UTF\-8\s0 encoded multibyte characters in strings.
The default (\fB\-\-unicode=default\fR) is to give them no special
treatment. The \fB\-\-unicode=locale\fR option displays the sequence
in the current locale, which may or may not support them. The options
\&\fB\-\-unicode=hex\fR and \fB\-\-unicode=invalid\fR display them as
hex byte sequences enclosed by either angle brackets or curly braces.
.Sp
The \fB\-\-unicode=escape\fR option displays them as escape sequences
(\fI\euxxxx\fR) and the \fB\-\-unicode=highlight\fR option displays
them as escape sequences highlighted in red (if supported by the
output device). The colouring is intended to draw attention to the
presence of unicode sequences where they might not be expected.
.IP "\fB\-W\fR" 4
.IX Item "-W"
.PD 0
.IP "\fB\-\-no\-weak\fR" 4
.IX Item "--no-weak"
.PD
Do not display weak symbols.
.IP "\fB\-\-with\-symbol\-versions\fR" 4
.IX Item "--with-symbol-versions"
.PD 0
.IP "\fB\-\-without\-symbol\-versions\fR" 4
.IX Item "--without-symbol-versions"
.PD
Enables or disables the display of symbol version information. The
version string is displayed as a suffix to the symbol name, preceded
by an @ character. For example \fBfoo@VER_1\fR. If the version is
the default version to be used when resolving unversioned references
to the symbol then it is displayed as a suffix preceded by two @
characters. For example \fBfoo@@VER_2\fR. By default, symbol
version information is displayed.
.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
.IX Item "--target=bfdname"
Specify an object code format other than your system's default format.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBar\fR\|(1), \fBobjdump\fR\|(1), \fBranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

1282
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-objcopy.1 Normal file
View File

File diff suppressed because it is too large Load Diff

1496
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-objdump.1 Normal file
View File

File diff suppressed because it is too large Load Diff

227
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-ranlib.1 Normal file
View File

@ -0,0 +1,227 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "RANLIB 1"
.TH RANLIB 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ranlib \- generate an index to an archive
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
ranlib [\fB\-\-plugin\fR \fIname\fR] [\fB\-DhHvVt\fR] \fIarchive\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBranlib\fR generates an index to the contents of an archive and
stores it in the archive. The index lists each symbol defined by a
member of an archive that is a relocatable object file.
.PP
You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index.
.PP
An archive with such an index speeds up linking to the library and
allows routines in the library to call each other without regard to
their placement in the archive.
.PP
The \s-1GNU\s0 \fBranlib\fR program is another form of \s-1GNU\s0 \fBar\fR; running
\&\fBranlib\fR is completely equivalent to executing \fBar \-s\fR.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-H\fR" 4
.IX Item "-H"
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Show usage information for \fBranlib\fR.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-V\fR" 4
.IX Item "-V"
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Show the version number of \fBranlib\fR.
.IP "\fB\-D\fR" 4
.IX Item "-D"
Operate in \fIdeterministic\fR mode. The symbol map archive member's
header will show zero for the \s-1UID, GID,\s0 and timestamp. When this
option is used, multiple runs will produce identical output files.
.Sp
If \fIbinutils\fR was configured with
\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by
default. It can be disabled with the \fB\-U\fR option, described
below.
.IP "\fB\-t\fR" 4
.IX Item "-t"
Update the timestamp of the symbol map of an archive.
.IP "\fB\-U\fR" 4
.IX Item "-U"
Do \fInot\fR operate in \fIdeterministic\fR mode. This is the
inverse of the \fB\-D\fR option, above: the archive index will get
actual \s-1UID, GID,\s0 timestamp, and file mode values.
.Sp
If \fIbinutils\fR was configured \fIwithout\fR
\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by
default.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBar\fR\|(1), \fBnm\fR\|(1), and the Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

958
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-readelf.1 Normal file
View File

@ -0,0 +1,958 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "READELF 1"
.TH READELF 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
readelf \- display information about ELF files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
readelf [\fB\-a\fR|\fB\-\-all\fR]
[\fB\-h\fR|\fB\-\-file\-header\fR]
[\fB\-l\fR|\fB\-\-program\-headers\fR|\fB\-\-segments\fR]
[\fB\-S\fR|\fB\-\-section\-headers\fR|\fB\-\-sections\fR]
[\fB\-g\fR|\fB\-\-section\-groups\fR]
[\fB\-t\fR|\fB\-\-section\-details\fR]
[\fB\-e\fR|\fB\-\-headers\fR]
[\fB\-s\fR|\fB\-\-syms\fR|\fB\-\-symbols\fR]
[\fB\-\-dyn\-syms\fR|\fB\-\-lto\-syms\fR]
[\fB\-\-sym\-base=[0|8|10|16]\fR]
[\fB\-\-demangle\fR\fI=style\fR|\fB\-\-no\-demangle\fR]
[\fB\-\-quiet\fR]
[\fB\-\-recurse\-limit\fR|\fB\-\-no\-recurse\-limit\fR]
[\fB\-U\fR \fImethod\fR|\fB\-\-unicode=\fR\fImethod\fR]
[\fB\-X\fR|\fB\-\-extra\-sym\-info\fR|\fB\-\-no\-extra\-sym\-info\fR]
[\fB\-n\fR|\fB\-\-notes\fR]
[\fB\-r\fR|\fB\-\-relocs\fR]
[\fB\-u\fR|\fB\-\-unwind\fR]
[\fB\-d\fR|\fB\-\-dynamic\fR]
[\fB\-V\fR|\fB\-\-version\-info\fR]
[\fB\-A\fR|\fB\-\-arch\-specific\fR]
[\fB\-D\fR|\fB\-\-use\-dynamic\fR]
[\fB\-L\fR|\fB\-\-lint\fR|\fB\-\-enable\-checks\fR]
[\fB\-x\fR <number or name>|\fB\-\-hex\-dump=\fR<number or name>]
[\fB\-p\fR <number or name>|\fB\-\-string\-dump=\fR<number or name>]
[\fB\-R\fR <number or name>|\fB\-\-relocated\-dump=\fR<number or name>]
[\fB\-j\fR <number or name>|\fB\-\-display\-section=\fR<number or name>]
[\fB\-z\fR|\fB\-\-decompress\fR]
[\fB\-c\fR|\fB\-\-archive\-index\fR]
[\fB\-w[lLiaprmfFsoORtUuTgAck]\fR|
\fB\-\-debug\-dump\fR[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=str\-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links]]
[\fB\-wK\fR|\fB\-\-debug\-dump=follow\-links\fR]
[\fB\-wN\fR|\fB\-\-debug\-dump=no\-follow\-links\fR]
[\fB\-wD\fR|\fB\-\-debug\-dump=use\-debuginfod\fR]
[\fB\-wE\fR|\fB\-\-debug\-dump=do\-not\-use\-debuginfod\fR]
[\fB\-P\fR|\fB\-\-process\-links\fR]
[\fB\-\-dwarf\-depth=\fR\fIn\fR]
[\fB\-\-dwarf\-start=\fR\fIn\fR]
[\fB\-\-ctf=\fR\fIsection\fR]
[\fB\-\-ctf\-parent=\fR\fIsection\fR]
[\fB\-\-ctf\-symbols=\fR\fIsection\fR]
[\fB\-\-ctf\-strings=\fR\fIsection\fR]
[\fB\-\-sframe=\fR\fIsection\fR]
[\fB\-I\fR|\fB\-\-histogram\fR]
[\fB\-v\fR|\fB\-\-version\fR]
[\fB\-W\fR|\fB\-\-wide\fR]
[\fB\-T\fR|\fB\-\-silent\-truncation\fR]
[\fB\-H\fR|\fB\-\-help\fR]
\fIelffile\fR...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBreadelf\fR displays information about one or more \s-1ELF\s0 format object
files. The options control what particular information to display.
.PP
\&\fIelffile\fR... are the object files to be examined. 32\-bit and
64\-bit \s-1ELF\s0 files are supported, as are archives containing \s-1ELF\s0 files.
.PP
This program performs a similar function to \fBobjdump\fR but it
goes into more detail and it exists independently of the \s-1BFD\s0
library, so if there is a bug in \s-1BFD\s0 then readelf will not be
affected.
.SH "OPTIONS"
.IX Header "OPTIONS"
The long and short forms of options, shown here as alternatives, are
equivalent. At least one option besides \fB\-v\fR or \fB\-H\fR must be
given.
.IP "\fB\-a\fR" 4
.IX Item "-a"
.PD 0
.IP "\fB\-\-all\fR" 4
.IX Item "--all"
.PD
Equivalent to specifying \fB\-\-file\-header\fR,
\&\fB\-\-program\-headers\fR, \fB\-\-sections\fR, \fB\-\-symbols\fR,
\&\fB\-\-relocs\fR, \fB\-\-dynamic\fR, \fB\-\-notes\fR,
\&\fB\-\-version\-info\fR, \fB\-\-arch\-specific\fR, \fB\-\-unwind\fR,
\&\fB\-\-section\-groups\fR and \fB\-\-histogram\fR.
.Sp
Note \- this option does not enable \fB\-\-use\-dynamic\fR itself, so
if that option is not present on the command line then dynamic symbols
and dynamic relocs will not be displayed.
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-file\-header\fR" 4
.IX Item "--file-header"
.PD
Displays the information contained in the \s-1ELF\s0 header at the start of the
file.
.IP "\fB\-l\fR" 4
.IX Item "-l"
.PD 0
.IP "\fB\-\-program\-headers\fR" 4
.IX Item "--program-headers"
.IP "\fB\-\-segments\fR" 4
.IX Item "--segments"
.PD
Displays the information contained in the file's segment headers, if it
has any.
.IP "\fB\-\-quiet\fR" 4
.IX Item "--quiet"
Suppress \*(L"no symbols\*(R" diagnostic.
.IP "\fB\-S\fR" 4
.IX Item "-S"
.PD 0
.IP "\fB\-\-sections\fR" 4
.IX Item "--sections"
.IP "\fB\-\-section\-headers\fR" 4
.IX Item "--section-headers"
.PD
Displays the information contained in the file's section headers, if it
has any.
.IP "\fB\-g\fR" 4
.IX Item "-g"
.PD 0
.IP "\fB\-\-section\-groups\fR" 4
.IX Item "--section-groups"
.PD
Displays the information contained in the file's section groups, if it
has any.
.IP "\fB\-t\fR" 4
.IX Item "-t"
.PD 0
.IP "\fB\-\-section\-details\fR" 4
.IX Item "--section-details"
.PD
Displays the detailed section information. Implies \fB\-S\fR.
.IP "\fB\-s\fR" 4
.IX Item "-s"
.PD 0
.IP "\fB\-\-symbols\fR" 4
.IX Item "--symbols"
.IP "\fB\-\-syms\fR" 4
.IX Item "--syms"
.PD
Displays the entries in symbol table section of the file, if it has one.
If a symbol has version information associated with it then this is
displayed as well. The version string is displayed as a suffix to the
symbol name, preceded by an @ character. For example
\&\fBfoo@VER_1\fR. If the version is the default version to be used
when resolving unversioned references to the symbol then it is
displayed as a suffix preceded by two @ characters. For example
\&\fBfoo@@VER_2\fR.
.IP "\fB\-\-dyn\-syms\fR" 4
.IX Item "--dyn-syms"
Displays the entries in dynamic symbol table section of the file, if it
has one. The output format is the same as the format used by the
\&\fB\-\-syms\fR option.
.IP "\fB\-\-lto\-syms\fR" 4
.IX Item "--lto-syms"
Displays the contents of any \s-1LTO\s0 symbol tables in the file.
.IP "\fB\-\-sym\-base=[0|8|10|16]\fR" 4
.IX Item "--sym-base=[0|8|10|16]"
Forces the size field of the symbol table to use the given base. Any
unrecognized options will be treated as \fB0\fR. \fB\-\-sym\-base=0\fR
represents the default and legacy behaviour. This will output sizes as decimal
for numbers less than 100000. For sizes 100000 and greater hexadecimal notation
will be used with a 0x prefix.
\&\fB\-\-sym\-base=8\fR will give the symbol sizes in octal.
\&\fB\-\-sym\-base=10\fR will always give the symbol sizes in decimal.
\&\fB\-\-sym\-base=16\fR will always give the symbol sizes in hexadecimal with a
0x prefix.
.IP "\fB\-C\fR" 4
.IX Item "-C"
.PD 0
.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
.IX Item "--demangle[=style]"
.PD
Decode (\fIdemangle\fR) low-level symbol names into user-level names.
This makes \*(C+ function names readable. Different compilers have
different mangling styles. The optional demangling style argument can
be used to choose an appropriate demangling style for your
compiler.
.IP "\fB\-\-no\-demangle\fR" 4
.IX Item "--no-demangle"
Do not demangle low-level symbol names. This is the default.
.IP "\fB\-\-recurse\-limit\fR" 4
.IX Item "--recurse-limit"
.PD 0
.IP "\fB\-\-no\-recurse\-limit\fR" 4
.IX Item "--no-recurse-limit"
.IP "\fB\-\-recursion\-limit\fR" 4
.IX Item "--recursion-limit"
.IP "\fB\-\-no\-recursion\-limit\fR" 4
.IX Item "--no-recursion-limit"
.PD
Enables or disables a limit on the amount of recursion performed
whilst demangling strings. Since the name mangling formats allow for
an infinite level of recursion it is possible to create strings whose
decoding will exhaust the amount of stack space available on the host
machine, triggering a memory fault. The limit tries to prevent this
from happening by restricting recursion to 2048 levels of nesting.
.Sp
The default is for this limit to be enabled, but disabling it may be
necessary in order to demangle truly complicated names. Note however
that if the recursion limit is disabled then stack exhaustion is
possible and any bug reports about such an event will be rejected.
.IP "\fB\-U\fR \fI[d|i|l|e|x|h]\fR" 4
.IX Item "-U [d|i|l|e|x|h]"
.PD 0
.IP "\fB\-\-unicode=[default|invalid|locale|escape|hex|highlight]\fR" 4
.IX Item "--unicode=[default|invalid|locale|escape|hex|highlight]"
.PD
Controls the display of non-ASCII characters in identifier names.
The default (\fB\-\-unicode=locale\fR or \fB\-\-unicode=default\fR) is
to treat them as multibyte characters and display them in the current
locale. All other versions of this option treat the bytes as \s-1UTF\-8\s0
encoded values and attempt to interpret them. If they cannot be
interpreted or if the \fB\-\-unicode=invalid\fR option is used then
they are displayed as a sequence of hex bytes, encloses in curly
parethesis characters.
.Sp
Using the \fB\-\-unicode=escape\fR option will display the characters
as as unicode escape sequences (\fI\euxxxx\fR). Using the
\&\fB\-\-unicode=hex\fR will display the characters as hex byte
sequences enclosed between angle brackets.
.Sp
Using the \fB\-\-unicode=highlight\fR will display the characters as
unicode escape sequences but it will also highlighted them in red,
assuming that colouring is supported by the output device. The
colouring is intended to draw attention to the presence of unicode
sequences when they might not be expected.
.IP "\fB\-X\fR" 4
.IX Item "-X"
.PD 0
.IP "\fB\-\-extra\-sym\-info\fR" 4
.IX Item "--extra-sym-info"
.PD
When displaying details of symbols, include extra information not
normally presented. Currently this just adds the name of the section
referenced by the symbol's index field, if there is one. In the
future more information may be displayed when this option is enabled.
.Sp
Enabling this option effectively enables the \fB\-\-wide\fR option as
well, at least when displaying symbol information.
.IP "\fB\-\-no\-extra\-sym\-info\fR" 4
.IX Item "--no-extra-sym-info"
Disables the effect of the \fB\-\-extra\-sym\-info\fR option. This
is the default.
.IP "\fB\-e\fR" 4
.IX Item "-e"
.PD 0
.IP "\fB\-\-headers\fR" 4
.IX Item "--headers"
.PD
Display all the headers in the file. Equivalent to \fB\-h \-l \-S\fR.
.IP "\fB\-n\fR" 4
.IX Item "-n"
.PD 0
.IP "\fB\-\-notes\fR" 4
.IX Item "--notes"
.PD
Displays the contents of the \s-1NOTE\s0 segments and/or sections, if any.
.IP "\fB\-r\fR" 4
.IX Item "-r"
.PD 0
.IP "\fB\-\-relocs\fR" 4
.IX Item "--relocs"
.PD
Displays the contents of the file's relocation section, if it has one.
.IP "\fB\-u\fR" 4
.IX Item "-u"
.PD 0
.IP "\fB\-\-unwind\fR" 4
.IX Item "--unwind"
.PD
Displays the contents of the file's unwind section, if it has one. Only
the unwind sections for \s-1IA64 ELF\s0 files, as well as \s-1ARM\s0 unwind tables
(\f(CW\*(C`.ARM.exidx\*(C'\fR / \f(CW\*(C`.ARM.extab\*(C'\fR) are currently supported. If
support is not yet implemented for your architecture you could try
dumping the contents of the \fI.eh_frames\fR section using the
\&\fB\-\-debug\-dump=frames\fR or \fB\-\-debug\-dump=frames\-interp\fR
options.
.IP "\fB\-d\fR" 4
.IX Item "-d"
.PD 0
.IP "\fB\-\-dynamic\fR" 4
.IX Item "--dynamic"
.PD
Displays the contents of the file's dynamic section, if it has one.
.IP "\fB\-V\fR" 4
.IX Item "-V"
.PD 0
.IP "\fB\-\-version\-info\fR" 4
.IX Item "--version-info"
.PD
Displays the contents of the version sections in the file, it they
exist.
.IP "\fB\-A\fR" 4
.IX Item "-A"
.PD 0
.IP "\fB\-\-arch\-specific\fR" 4
.IX Item "--arch-specific"
.PD
Displays architecture-specific information in the file, if there
is any.
.IP "\fB\-D\fR" 4
.IX Item "-D"
.PD 0
.IP "\fB\-\-use\-dynamic\fR" 4
.IX Item "--use-dynamic"
.PD
When displaying symbols, this option makes \fBreadelf\fR use the
symbol hash tables in the file's dynamic section, rather than the
symbol table sections.
.Sp
When displaying relocations, this option makes \fBreadelf\fR
display the dynamic relocations rather than the static relocations.
.IP "\fB\-L\fR" 4
.IX Item "-L"
.PD 0
.IP "\fB\-\-lint\fR" 4
.IX Item "--lint"
.IP "\fB\-\-enable\-checks\fR" 4
.IX Item "--enable-checks"
.PD
Displays warning messages about possible problems with the file(s)
being examined. If used on its own then all of the contents of the
file(s) will be examined. If used with one of the dumping options
then the warning messages will only be produced for the things being
displayed.
.IP "\fB\-x <number or name>\fR" 4
.IX Item "-x <number or name>"
.PD 0
.IP "\fB\-\-hex\-dump=<number or name>\fR" 4
.IX Item "--hex-dump=<number or name>"
.PD
Displays the contents of the indicated section as a hexadecimal bytes.
A number identifies a particular section by index in the section table;
any other string identifies all sections with that name in the object file.
This option can be repeated multiple times on the command line in
order to request multiple hex dumps.
.IP "\fB\-R <number or name>\fR" 4
.IX Item "-R <number or name>"
.PD 0
.IP "\fB\-\-relocated\-dump=<number or name>\fR" 4
.IX Item "--relocated-dump=<number or name>"
.PD
Displays the contents of the indicated section as a hexadecimal
bytes. A number identifies a particular section by index in the
section table; any other string identifies all sections with that name
in the object file. The contents of the section will be relocated
before they are displayed.
This option can be repeated multiple times on the command line in
order to request multiple relocated dumps.
.IP "\fB\-p <number or name>\fR" 4
.IX Item "-p <number or name>"
.PD 0
.IP "\fB\-\-string\-dump=<number or name>\fR" 4
.IX Item "--string-dump=<number or name>"
.PD
Displays the contents of the indicated section as printable strings.
A number identifies a particular section by index in the section table;
any other string identifies all sections with that name in the object file.
This option can be repeated multiple times on the command line in
order to request multiple string dumps.
.IP "\fB\-j <number or name>\fR" 4
.IX Item "-j <number or name>"
.PD 0
.IP "\fB\-\-display\-section\fR" 4
.IX Item "--display-section"
.PD
Displays the contents of the indicated section according to its
section header type. Sections containing relocations will be
displayed as if the \fB\-\-relocations\fR option had been used,
sections contains symbols will be displayed as if the \fB\-\-syms\fR
option had been used and so on.
.Sp
A number identifies a particular section by index in the section
table; any other string identifies all sections with that name in the
input file(s).
.Sp
This option can be repeated multiple times on the command line in
order to request multiple section dumps.
.IP "\fB\-z\fR" 4
.IX Item "-z"
.PD 0
.IP "\fB\-\-decompress\fR" 4
.IX Item "--decompress"
.PD
Requests that the section(s) being dumped by \fBx\fR, \fBR\fR or
\&\fBp\fR options are decompressed before being displayed. If the
section(s) are not compressed then they are displayed as is.
.IP "\fB\-c\fR" 4
.IX Item "-c"
.PD 0
.IP "\fB\-\-archive\-index\fR" 4
.IX Item "--archive-index"
.PD
Displays the file symbol index information contained in the header part
of binary archives. Performs the same function as the \fBt\fR
command to \fBar\fR, but without using the \s-1BFD\s0 library.
.IP "\fB\-w[lLiaprmfFsOoRtUuTgAckK]\fR" 4
.IX Item "-w[lLiaprmfFsOoRtUuTgAckK]"
.PD 0
.IP "\fB\-\-debug\-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=str\-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow\-links]\fR" 4
.IX Item "--debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]"
.PD
Displays the contents of the \s-1DWARF\s0 debug sections in the file, if any
are present. Compressed debug sections are automatically decompressed
(temporarily) before they are displayed. If one or more of the
optional letters or words follows the switch then only those type(s)
of data will be dumped. The letters and words refer to the following
information:
.RS 4
.ie n .IP """a""" 4
.el .IP "\f(CWa\fR" 4
.IX Item "a"
.PD 0
.ie n .IP """=abbrev""" 4
.el .IP "\f(CW=abbrev\fR" 4
.IX Item "=abbrev"
.PD
Displays the contents of the \fB.debug_abbrev\fR section.
.ie n .IP """A""" 4
.el .IP "\f(CWA\fR" 4
.IX Item "A"
.PD 0
.ie n .IP """=addr""" 4
.el .IP "\f(CW=addr\fR" 4
.IX Item "=addr"
.PD
Displays the contents of the \fB.debug_addr\fR section.
.ie n .IP """c""" 4
.el .IP "\f(CWc\fR" 4
.IX Item "c"
.PD 0
.ie n .IP """=cu_index""" 4
.el .IP "\f(CW=cu_index\fR" 4
.IX Item "=cu_index"
.PD
Displays the contents of the \fB.debug_cu_index\fR and/or
\&\fB.debug_tu_index\fR sections.
.ie n .IP """f""" 4
.el .IP "\f(CWf\fR" 4
.IX Item "f"
.PD 0
.ie n .IP """=frames""" 4
.el .IP "\f(CW=frames\fR" 4
.IX Item "=frames"
.PD
Display the raw contents of a \fB.debug_frame\fR section.
.ie n .IP """F""" 4
.el .IP "\f(CWF\fR" 4
.IX Item "F"
.PD 0
.ie n .IP """=frames\-interp""" 4
.el .IP "\f(CW=frames\-interp\fR" 4
.IX Item "=frames-interp"
.PD
Display the interpreted contents of a \fB.debug_frame\fR section.
.ie n .IP """g""" 4
.el .IP "\f(CWg\fR" 4
.IX Item "g"
.PD 0
.ie n .IP """=gdb_index""" 4
.el .IP "\f(CW=gdb_index\fR" 4
.IX Item "=gdb_index"
.PD
Displays the contents of the \fB.gdb_index\fR and/or
\&\fB.debug_names\fR sections.
.ie n .IP """i""" 4
.el .IP "\f(CWi\fR" 4
.IX Item "i"
.PD 0
.ie n .IP """=info""" 4
.el .IP "\f(CW=info\fR" 4
.IX Item "=info"
.PD
Displays the contents of the \fB.debug_info\fR section. Note: the
output from this option can also be restricted by the use of the
\&\fB\-\-dwarf\-depth\fR and \fB\-\-dwarf\-start\fR options.
.ie n .IP """k""" 4
.el .IP "\f(CWk\fR" 4
.IX Item "k"
.PD 0
.ie n .IP """=links""" 4
.el .IP "\f(CW=links\fR" 4
.IX Item "=links"
.PD
Displays the contents of the \fB.gnu_debuglink\fR,
\&\fB.gnu_debugaltlink\fR and \fB.debug_sup\fR sections, if any of
them are present. Also displays any links to separate dwarf object
files (dwo), if they are specified by the DW_AT_GNU_dwo_name or
DW_AT_dwo_name attributes in the \fB.debug_info\fR section.
.ie n .IP """K""" 4
.el .IP "\f(CWK\fR" 4
.IX Item "K"
.PD 0
.ie n .IP """=follow\-links""" 4
.el .IP "\f(CW=follow\-links\fR" 4
.IX Item "=follow-links"
.PD
Display the contents of any selected debug sections that are found in
linked, separate debug info file(s). This can result in multiple
versions of the same debug section being displayed if it exists in
more than one file.
.Sp
In addition, when displaying \s-1DWARF\s0 attributes, if a form is found that
references the separate debug info file, then the referenced contents
will also be displayed.
.Sp
Note \- in some distributions this option is enabled by default. It
can be disabled via the \fBN\fR debug option. The default can be
chosen when configuring the binutils via the
\&\fB\-\-enable\-follow\-debug\-links=yes\fR or
\&\fB\-\-enable\-follow\-debug\-links=no\fR options. If these are not
used then the default is to enable the following of debug links.
.Sp
Note \- if support for the debuginfod protocol was enabled when the
binutils were built then this option will also include an attempt to
contact any debuginfod servers mentioned in the \fI\s-1DEBUGINFOD_URLS\s0\fR
environment variable. This could take some time to resolve. This
behaviour can be disabled via the \fB=do\-not\-use\-debuginfod\fR debug
option.
.ie n .IP """N""" 4
.el .IP "\f(CWN\fR" 4
.IX Item "N"
.PD 0
.ie n .IP """=no\-follow\-links""" 4
.el .IP "\f(CW=no\-follow\-links\fR" 4
.IX Item "=no-follow-links"
.PD
Disables the following of links to separate debug info files.
.ie n .IP """D""" 4
.el .IP "\f(CWD\fR" 4
.IX Item "D"
.PD 0
.ie n .IP """=use\-debuginfod""" 4
.el .IP "\f(CW=use\-debuginfod\fR" 4
.IX Item "=use-debuginfod"
.PD
Enables contacting debuginfod servers if there is a need to follow
debug links. This is the default behaviour.
.ie n .IP """E""" 4
.el .IP "\f(CWE\fR" 4
.IX Item "E"
.PD 0
.ie n .IP """=do\-not\-use\-debuginfod""" 4
.el .IP "\f(CW=do\-not\-use\-debuginfod\fR" 4
.IX Item "=do-not-use-debuginfod"
.PD
Disables contacting debuginfod servers when there is a need to follow
debug links.
.ie n .IP """l""" 4
.el .IP "\f(CWl\fR" 4
.IX Item "l"
.PD 0
.ie n .IP """=rawline""" 4
.el .IP "\f(CW=rawline\fR" 4
.IX Item "=rawline"
.PD
Displays the contents of the \fB.debug_line\fR section in a raw
format.
.ie n .IP """L""" 4
.el .IP "\f(CWL\fR" 4
.IX Item "L"
.PD 0
.ie n .IP """=decodedline""" 4
.el .IP "\f(CW=decodedline\fR" 4
.IX Item "=decodedline"
.PD
Displays the interpreted contents of the \fB.debug_line\fR section.
.ie n .IP """m""" 4
.el .IP "\f(CWm\fR" 4
.IX Item "m"
.PD 0
.ie n .IP """=macro""" 4
.el .IP "\f(CW=macro\fR" 4
.IX Item "=macro"
.PD
Displays the contents of the \fB.debug_macro\fR and/or
\&\fB.debug_macinfo\fR sections.
.ie n .IP """o""" 4
.el .IP "\f(CWo\fR" 4
.IX Item "o"
.PD 0
.ie n .IP """=loc""" 4
.el .IP "\f(CW=loc\fR" 4
.IX Item "=loc"
.PD
Displays the contents of the \fB.debug_loc\fR and/or
\&\fB.debug_loclists\fR sections.
.ie n .IP """O""" 4
.el .IP "\f(CWO\fR" 4
.IX Item "O"
.PD 0
.ie n .IP """=str\-offsets""" 4
.el .IP "\f(CW=str\-offsets\fR" 4
.IX Item "=str-offsets"
.PD
Displays the contents of the \fB.debug_str_offsets\fR section.
.ie n .IP """p""" 4
.el .IP "\f(CWp\fR" 4
.IX Item "p"
.PD 0
.ie n .IP """=pubnames""" 4
.el .IP "\f(CW=pubnames\fR" 4
.IX Item "=pubnames"
.PD
Displays the contents of the \fB.debug_pubnames\fR and/or
\&\fB.debug_gnu_pubnames\fR sections.
.ie n .IP """r""" 4
.el .IP "\f(CWr\fR" 4
.IX Item "r"
.PD 0
.ie n .IP """=aranges""" 4
.el .IP "\f(CW=aranges\fR" 4
.IX Item "=aranges"
.PD
Displays the contents of the \fB.debug_aranges\fR section.
.ie n .IP """R""" 4
.el .IP "\f(CWR\fR" 4
.IX Item "R"
.PD 0
.ie n .IP """=Ranges""" 4
.el .IP "\f(CW=Ranges\fR" 4
.IX Item "=Ranges"
.PD
Displays the contents of the \fB.debug_ranges\fR and/or
\&\fB.debug_rnglists\fR sections.
.ie n .IP """s""" 4
.el .IP "\f(CWs\fR" 4
.IX Item "s"
.PD 0
.ie n .IP """=str""" 4
.el .IP "\f(CW=str\fR" 4
.IX Item "=str"
.PD
Displays the contents of the \fB.debug_str\fR, \fB.debug_line_str\fR
and/or \fB.debug_str_offsets\fR sections.
.ie n .IP """t""" 4
.el .IP "\f(CWt\fR" 4
.IX Item "t"
.PD 0
.ie n .IP """=pubtype""" 4
.el .IP "\f(CW=pubtype\fR" 4
.IX Item "=pubtype"
.PD
Displays the contents of the \fB.debug_pubtypes\fR and/or
\&\fB.debug_gnu_pubtypes\fR sections.
.ie n .IP """T""" 4
.el .IP "\f(CWT\fR" 4
.IX Item "T"
.PD 0
.ie n .IP """=trace_aranges""" 4
.el .IP "\f(CW=trace_aranges\fR" 4
.IX Item "=trace_aranges"
.PD
Displays the contents of the \fB.trace_aranges\fR section.
.ie n .IP """u""" 4
.el .IP "\f(CWu\fR" 4
.IX Item "u"
.PD 0
.ie n .IP """=trace_abbrev""" 4
.el .IP "\f(CW=trace_abbrev\fR" 4
.IX Item "=trace_abbrev"
.PD
Displays the contents of the \fB.trace_abbrev\fR section.
.ie n .IP """U""" 4
.el .IP "\f(CWU\fR" 4
.IX Item "U"
.PD 0
.ie n .IP """=trace_info""" 4
.el .IP "\f(CW=trace_info\fR" 4
.IX Item "=trace_info"
.PD
Displays the contents of the \fB.trace_info\fR section.
.RE
.RS 4
.Sp
Note: displaying the contents of \fB.debug_static_funcs\fR,
\&\fB.debug_static_vars\fR and \fBdebug_weaknames\fR sections is not
currently supported.
.RE
.IP "\fB\-\-dwarf\-depth=\fR\fIn\fR" 4
.IX Item "--dwarf-depth=n"
Limit the dump of the \f(CW\*(C`.debug_info\*(C'\fR section to \fIn\fR children.
This is only useful with \fB\-\-debug\-dump=info\fR. The default is
to print all DIEs; the special value 0 for \fIn\fR will also have this
effect.
.Sp
With a non-zero value for \fIn\fR, DIEs at or deeper than \fIn\fR
levels will not be printed. The range for \fIn\fR is zero-based.
.IP "\fB\-\-dwarf\-start=\fR\fIn\fR" 4
.IX Item "--dwarf-start=n"
Print only DIEs beginning with the \s-1DIE\s0 numbered \fIn\fR. This is only
useful with \fB\-\-debug\-dump=info\fR.
.Sp
If specified, this option will suppress printing of any header
information and all DIEs before the \s-1DIE\s0 numbered \fIn\fR. Only
siblings and children of the specified \s-1DIE\s0 will be printed.
.Sp
This can be used in conjunction with \fB\-\-dwarf\-depth\fR.
.IP "\fB\-P\fR" 4
.IX Item "-P"
.PD 0
.IP "\fB\-\-process\-links\fR" 4
.IX Item "--process-links"
.PD
Display the contents of non-debug sections found in separate debuginfo
files that are linked to the main file. This option automatically
implies the \fB\-wK\fR option, and only sections requested by other
command line options will be displayed.
.IP "\fB\-\-ctf[=\fR\fIsection\fR\fB]\fR" 4
.IX Item "--ctf[=section]"
Display the contents of the specified \s-1CTF\s0 section. \s-1CTF\s0 sections themselves
contain many subsections, all of which are displayed in order.
.Sp
By default, display the name of the section named \fI.ctf\fR, which is the
name emitted by \fBld\fR.
.IP "\fB\-\-ctf\-parent=\fR\fImember\fR" 4
.IX Item "--ctf-parent=member"
If the \s-1CTF\s0 section contains ambiguously-defined types, it will consist
of an archive of many \s-1CTF\s0 dictionaries, all inheriting from one
dictionary containing unambiguous types. This member is by default
named \fI.ctf\fR, like the section containing it, but it is possible to
change this name using the \f(CW\*(C`ctf_link_set_memb_name_changer\*(C'\fR
function at link time. When looking at \s-1CTF\s0 archives that have been
created by a linker that uses the name changer to rename the parent
archive member, \fB\-\-ctf\-parent\fR can be used to specify the name
used for the parent.
.IP "\fB\-\-ctf\-parent\-section=\fR\fIsection\fR" 4
.IX Item "--ctf-parent-section=section"
This option lets you pick a completely different section for the \s-1CTF\s0
parent dictionary containing unambiguous types than for the child
dictionaries that contain the ambiguous remainder. The linker does
not emit \s-1ELF\s0 objects structured like this, but some third-party linkers
may. It's also convenient to inspect \s-1CTF\s0 written out as multiple raw
files to compose them with objcopy, which can put them in different
\&\s-1ELF\s0 sections but not in different members of a single \s-1CTF\s0 dict.
.IP "\fB\-\-ctf\-symbols=\fR\fIsection\fR" 4
.IX Item "--ctf-symbols=section"
.PD 0
.IP "\fB\-\-ctf\-strings=\fR\fIsection\fR" 4
.IX Item "--ctf-strings=section"
.PD
Specify the name of another section from which the \s-1CTF\s0 file can inherit
strings and symbols. By default, the \f(CW\*(C`.symtab\*(C'\fR and its linked
string table are used.
.Sp
If either of \fB\-\-ctf\-symbols\fR or \fB\-\-ctf\-strings\fR is specified, the
other must be specified as well.
.IP "\fB\-I\fR" 4
.IX Item "-I"
.PD 0
.IP "\fB\-\-histogram\fR" 4
.IX Item "--histogram"
.PD
Display a histogram of bucket list lengths when displaying the contents
of the symbol tables.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Display the version number of readelf.
.IP "\fB\-W\fR" 4
.IX Item "-W"
.PD 0
.IP "\fB\-\-wide\fR" 4
.IX Item "--wide"
.PD
Don't break output lines to fit into 80 columns. By default
\&\fBreadelf\fR breaks section header and segment listing lines for
64\-bit \s-1ELF\s0 files, so that they fit into 80 columns. This option causes
\&\fBreadelf\fR to print each section header resp. each segment one a
single line, which is far more readable on terminals wider than 80 columns.
.IP "\fB\-T\fR" 4
.IX Item "-T"
.PD 0
.IP "\fB\-\-silent\-truncation\fR" 4
.IX Item "--silent-truncation"
.PD
Normally when readelf is displaying a symbol name, and it has to
truncate the name to fit into an 80 column display, it will add a
suffix of \f(CW\*(C`[...]\*(C'\fR to the name. This command line option
disables this behaviour, allowing 5 more characters of the name to be
displayed and restoring the old behaviour of readelf (prior to release
2.35).
.IP "\fB\-H\fR" 4
.IX Item "-H"
.PD 0
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Display the command-line options understood by \fBreadelf\fR.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBobjdump\fR\|(1), and the Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

312
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-size.1 Normal file
View File

@ -0,0 +1,312 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SIZE 1"
.TH SIZE 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
size \- list section sizes and total size of binary files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
size [\fB\-A\fR|\fB\-B\fR|\fB\-G\fR|\fB\-\-format=\fR\fIcompatibility\fR]
[\fB\-\-help\fR]
[\fB\-d\fR|\fB\-o\fR|\fB\-x\fR|\fB\-\-radix=\fR\fInumber\fR]
[\fB\-\-common\fR]
[\fB\-t\fR|\fB\-\-totals\fR]
[\fB\-\-target=\fR\fIbfdname\fR] [\fB\-V\fR|\fB\-\-version\fR]
[\fB\-f\fR]
[\fIobjfile\fR...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \s-1GNU\s0 \fBsize\fR utility lists the section sizes and the total
size for each of the binary files \fIobjfile\fR on its argument list.
By default, one line of output is generated for each file or each
module if the file is an archive.
.PP
\&\fIobjfile\fR... are the files to be examined. If none are
specified, the file \f(CW\*(C`a.out\*(C'\fR will be used instead.
.SH "OPTIONS"
.IX Header "OPTIONS"
The command-line options have the following meanings:
.IP "\fB\-A\fR" 4
.IX Item "-A"
.PD 0
.IP "\fB\-B\fR" 4
.IX Item "-B"
.IP "\fB\-G\fR" 4
.IX Item "-G"
.IP "\fB\-\-format=\fR\fIcompatibility\fR" 4
.IX Item "--format=compatibility"
.PD
Using one of these options, you can choose whether the output from \s-1GNU\s0
\&\fBsize\fR resembles output from System V \fBsize\fR (using \fB\-A\fR,
or \fB\-\-format=sysv\fR), or Berkeley \fBsize\fR (using \fB\-B\fR, or
\&\fB\-\-format=berkeley\fR). The default is the one-line format similar to
Berkeley's. Alternatively, you can choose the \s-1GNU\s0 format output
(using \fB\-G\fR, or \fB\-\-format=gnu\fR), this is similar to
Berkeley's output format, but sizes are counted differently.
.Sp
Here is an example of the Berkeley (default) format of output from
\&\fBsize\fR:
.Sp
.Vb 4
\& $ size \-\-format=Berkeley ranlib size
\& text data bss dec hex filename
\& 294880 81920 11592 388392 5ed28 ranlib
\& 294880 81920 11888 388688 5ee50 size
.Ve
.Sp
The Berkeley style output counts read only data in the \f(CW\*(C`text\*(C'\fR
column, not in the \f(CW\*(C`data\*(C'\fR column, the \f(CW\*(C`dec\*(C'\fR and \f(CW\*(C`hex\*(C'\fR
columns both display the sum of the \f(CW\*(C`text\*(C'\fR, \f(CW\*(C`data\*(C'\fR, and
\&\f(CW\*(C`bss\*(C'\fR columns in decimal and hexadecimal respectively.
.Sp
The \s-1GNU\s0 format counts read only data in the \f(CW\*(C`data\*(C'\fR column, not
the \f(CW\*(C`text\*(C'\fR column, and only displays the sum of the \f(CW\*(C`text\*(C'\fR,
\&\f(CW\*(C`data\*(C'\fR, and \f(CW\*(C`bss\*(C'\fR columns once, in the \f(CW\*(C`total\*(C'\fR column.
The \fB\-\-radix\fR option can be used to change the number base for
all columns. Here is the same data displayed with \s-1GNU\s0 conventions:
.Sp
.Vb 4
\& $ size \-\-format=GNU ranlib size
\& text data bss total filename
\& 279880 96920 11592 388392 ranlib
\& 279880 96920 11888 388688 size
.Ve
.Sp
This is the same data, but displayed closer to System V conventions:
.Sp
.Vb 7
\& $ size \-\-format=SysV ranlib size
\& ranlib :
\& section size addr
\& .text 294880 8192
\& .data 81920 303104
\& .bss 11592 385024
\& Total 388392
\&
\&
\& size :
\& section size addr
\& .text 294880 8192
\& .data 81920 303104
\& .bss 11888 385024
\& Total 388688
.Ve
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD 0
.IP "\fB\-h\fR" 4
.IX Item "-h"
.IP "\fB\-H\fR" 4
.IX Item "-H"
.IP "\fB\-?\fR" 4
.IX Item "-?"
.PD
Show a summary of acceptable arguments and options.
.IP "\fB\-d\fR" 4
.IX Item "-d"
.PD 0
.IP "\fB\-o\fR" 4
.IX Item "-o"
.IP "\fB\-x\fR" 4
.IX Item "-x"
.IP "\fB\-\-radix=\fR\fInumber\fR" 4
.IX Item "--radix=number"
.PD
Using one of these options, you can control whether the size of each
section is given in decimal (\fB\-d\fR, or \fB\-\-radix=10\fR); octal
(\fB\-o\fR, or \fB\-\-radix=8\fR); or hexadecimal (\fB\-x\fR, or
\&\fB\-\-radix=16\fR). In \fB\-\-radix=\fR\fInumber\fR, only the three
values (8, 10, 16) are supported. The total size is always given in two
radices; decimal and hexadecimal for \fB\-d\fR or \fB\-x\fR output, or
octal and hexadecimal if you're using \fB\-o\fR.
.IP "\fB\-\-common\fR" 4
.IX Item "--common"
Print total size of common symbols in each file. When using Berkeley
or \s-1GNU\s0 format these are included in the bss size.
.IP "\fB\-t\fR" 4
.IX Item "-t"
.PD 0
.IP "\fB\-\-totals\fR" 4
.IX Item "--totals"
.PD
Show totals of all objects listed (Berkeley or \s-1GNU\s0 format mode only).
.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
.IX Item "--target=bfdname"
Specify that the object-code format for \fIobjfile\fR is
\&\fIbfdname\fR. This option may not be necessary; \fBsize\fR can
automatically recognize many formats.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-V\fR" 4
.IX Item "-V"
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Display the version number of \fBsize\fR.
.IP "\fB\-f\fR" 4
.IX Item "-f"
Ignored. This option is used by other versions of the \fBsize\fR
program, but it is not supported by the \s-1GNU\s0 Binutils version.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBar\fR\|(1), \fBobjdump\fR\|(1), \fBreadelf\fR\|(1), and the Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

346
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-strings.1 Normal file
View File

@ -0,0 +1,346 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "STRINGS 1"
.TH STRINGS 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
strings \- print the sequences of printable characters in files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
strings [\fB\-afovV\fR] [\fB\-\fR\fImin-len\fR]
[\fB\-n\fR \fImin-len\fR] [\fB\-\-bytes=\fR\fImin-len\fR]
[\fB\-t\fR \fIradix\fR] [\fB\-\-radix=\fR\fIradix\fR]
[\fB\-e\fR \fIencoding\fR] [\fB\-\-encoding=\fR\fIencoding\fR]
[\fB\-U\fR \fImethod\fR] [\fB\-\-unicode=\fR\fImethod\fR]
[\fB\-\fR] [\fB\-\-all\fR] [\fB\-\-print\-file\-name\fR]
[\fB\-T\fR \fIbfdname\fR] [\fB\-\-target=\fR\fIbfdname\fR]
[\fB\-w\fR] [\fB\-\-include\-all\-whitespace\fR]
[\fB\-s\fR] [\fB\-\-output\-separator\fR \fIsep_string\fR]
[\fB\-\-help\fR] [\fB\-\-version\fR] \fIfile\fR...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
For each \fIfile\fR given, \s-1GNU\s0 \fBstrings\fR prints the
printable character sequences that are at least 4 characters long (or
the number given with the options below) and are followed by an
unprintable character.
.PP
Depending upon how the strings program was configured it will default
to either displaying all the printable sequences that it can find in
each file, or only those sequences that are in loadable, initialized
data sections. If the file type is unrecognizable, or if strings is
reading from stdin then it will always display all of the printable
sequences that it can find.
.PP
For backwards compatibility any file that occurs after a command-line
option of just \fB\-\fR will also be scanned in full, regardless of
the presence of any \fB\-d\fR option.
.PP
\&\fBstrings\fR is mainly useful for determining the contents of
non-text files.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-a\fR" 4
.IX Item "-a"
.PD 0
.IP "\fB\-\-all\fR" 4
.IX Item "--all"
.IP "\fB\-\fR" 4
.IX Item "-"
.PD
Scan the whole file, regardless of what sections it contains or
whether those sections are loaded or initialized. Normally this is
the default behaviour, but strings can be configured so that the
\&\fB\-d\fR is the default instead.
.Sp
The \fB\-\fR option is position dependent and forces strings to
perform full scans of any file that is mentioned after the \fB\-\fR
on the command line, even if the \fB\-d\fR option has been
specified.
.IP "\fB\-d\fR" 4
.IX Item "-d"
.PD 0
.IP "\fB\-\-data\fR" 4
.IX Item "--data"
.PD
Only print strings from initialized, loaded data sections in the
file. This may reduce the amount of garbage in the output, but it
also exposes the strings program to any security flaws that may be
present in the \s-1BFD\s0 library used to scan and load sections. Strings
can be configured so that this option is the default behaviour. In
such cases the \fB\-a\fR option can be used to avoid using the \s-1BFD\s0
library and instead just print all of the strings found in the file.
.IP "\fB\-f\fR" 4
.IX Item "-f"
.PD 0
.IP "\fB\-\-print\-file\-name\fR" 4
.IX Item "--print-file-name"
.PD
Print the name of the file before each string.
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Print a summary of the program usage on the standard output and exit.
.IP "\fB\-\fR\fImin-len\fR" 4
.IX Item "-min-len"
.PD 0
.IP "\fB\-n\fR \fImin-len\fR" 4
.IX Item "-n min-len"
.IP "\fB\-\-bytes=\fR\fImin-len\fR" 4
.IX Item "--bytes=min-len"
.PD
Print sequences of displayable characters that are at least
\&\fImin-len\fR characters long. If not specified a default minimum
length of 4 is used. The distinction between displayable and
non-displayable characters depends upon the setting of the
\&\fB\-e\fR and \fB\-U\fR options. Sequences are always terminated
at control characters such as new-line and carriage-return, but not
the tab character.
.IP "\fB\-o\fR" 4
.IX Item "-o"
Like \fB\-t o\fR. Some other versions of \fBstrings\fR have \fB\-o\fR
act like \fB\-t d\fR instead. Since we can not be compatible with both
ways, we simply chose one.
.IP "\fB\-t\fR \fIradix\fR" 4
.IX Item "-t radix"
.PD 0
.IP "\fB\-\-radix=\fR\fIradix\fR" 4
.IX Item "--radix=radix"
.PD
Print the offset within the file before each string. The single
character argument specifies the radix of the offset\-\-\-\fBo\fR for
octal, \fBx\fR for hexadecimal, or \fBd\fR for decimal.
.IP "\fB\-e\fR \fIencoding\fR" 4
.IX Item "-e encoding"
.PD 0
.IP "\fB\-\-encoding=\fR\fIencoding\fR" 4
.IX Item "--encoding=encoding"
.PD
Select the character encoding of the strings that are to be found.
Possible values for \fIencoding\fR are: \fBs\fR = single\-7\-bit\-byte
characters (default), \fBS\fR =
single\-8\-bit\-byte characters, \fBb\fR = 16\-bit bigendian, \fBl\fR =
16\-bit littleendian, \fBB\fR = 32\-bit bigendian, \fBL\fR = 32\-bit
littleendian. Useful for finding wide character strings. (\fBl\fR
and \fBb\fR apply to, for example, Unicode \s-1UTF\-16/UCS\-2\s0 encodings).
.IP "\fB\-U\fR \fI[d|i|l|e|x|h]\fR" 4
.IX Item "-U [d|i|l|e|x|h]"
.PD 0
.IP "\fB\-\-unicode=\fR\fI[default|invalid|locale|escape|hex|highlight]\fR" 4
.IX Item "--unicode=[default|invalid|locale|escape|hex|highlight]"
.PD
Controls the display of \s-1UTF\-8\s0 encoded multibyte characters in strings.
The default (\fB\-\-unicode=default\fR) is to give them no special
treatment, and instead rely upon the setting of the
\&\fB\-\-encoding\fR option. The other values for this option
automatically enable \fB\-\-encoding=S\fR.
.Sp
The \fB\-\-unicode=invalid\fR option treats them as non-graphic
characters and hence not part of a valid string. All the remaining
options treat them as valid string characters.
.Sp
The \fB\-\-unicode=locale\fR option displays them in the current
locale, which may or may not support \s-1UTF\-8\s0 encoding. The
\&\fB\-\-unicode=hex\fR option displays them as hex byte sequences
enclosed between \fI<>\fR characters. The \fB\-\-unicode=escape\fR
option displays them as escape sequences (\fI\euxxxx\fR) and the
\&\fB\-\-unicode=highlight\fR option displays them as escape sequences
highlighted in red (if supported by the output device). The colouring
is intended to draw attention to the presence of unicode sequences
where they might not be expected.
.IP "\fB\-T\fR \fIbfdname\fR" 4
.IX Item "-T bfdname"
.PD 0
.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
.IX Item "--target=bfdname"
.PD
Specify an object code format other than your system's default format.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-V\fR" 4
.IX Item "-V"
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Print the program version number on the standard output and exit.
.IP "\fB\-w\fR" 4
.IX Item "-w"
.PD 0
.IP "\fB\-\-include\-all\-whitespace\fR" 4
.IX Item "--include-all-whitespace"
.PD
By default tab and space characters are included in the strings that
are displayed, but other whitespace characters, such a newlines and
carriage returns, are not. The \fB\-w\fR option changes this so
that all whitespace characters are considered to be part of a string.
.IP "\fB\-s\fR" 4
.IX Item "-s"
.PD 0
.IP "\fB\-\-output\-separator\fR" 4
.IX Item "--output-separator"
.PD
By default, output strings are delimited by a new-line. This option
allows you to supply any string to be used as the output record
separator. Useful with \-\-include\-all\-whitespace where strings
may contain new-lines internally.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBar\fR\|(1), \fBnm\fR\|(1), \fBobjdump\fR\|(1), \fBranlib\fR\|(1), \fBreadelf\fR\|(1)
and the Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

515
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-strip.1 Normal file
View File

@ -0,0 +1,515 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "STRIP 1"
.TH STRIP 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
strip \- discard symbols and other data from object files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
strip [\fB\-F\fR \fIbfdname\fR |\fB\-\-target=\fR\fIbfdname\fR]
[\fB\-I\fR \fIbfdname\fR |\fB\-\-input\-target=\fR\fIbfdname\fR]
[\fB\-O\fR \fIbfdname\fR |\fB\-\-output\-target=\fR\fIbfdname\fR]
[\fB\-s\fR|\fB\-\-strip\-all\fR]
[\fB\-S\fR|\fB\-g\fR|\fB\-d\fR|\fB\-\-strip\-debug\fR]
[\fB\-\-strip\-dwo\fR]
[\fB\-K\fR \fIsymbolname\fR|\fB\-\-keep\-symbol=\fR\fIsymbolname\fR]
[\fB\-M\fR|\fB\-\-merge\-notes\fR][\fB\-\-no\-merge\-notes\fR]
[\fB\-N\fR \fIsymbolname\fR |\fB\-\-strip\-symbol=\fR\fIsymbolname\fR]
[\fB\-w\fR|\fB\-\-wildcard\fR]
[\fB\-x\fR|\fB\-\-discard\-all\fR] [\fB\-X\fR |\fB\-\-discard\-locals\fR]
[\fB\-R\fR \fIsectionname\fR |\fB\-\-remove\-section=\fR\fIsectionname\fR]
[\fB\-\-keep\-section=\fR\fIsectionpattern\fR]
[\fB\-\-remove\-relocations=\fR\fIsectionpattern\fR]
[\fB\-\-strip\-section\-headers\fR]
[\fB\-o\fR \fIfile\fR] [\fB\-p\fR|\fB\-\-preserve\-dates\fR]
[\fB\-D\fR|\fB\-\-enable\-deterministic\-archives\fR]
[\fB\-U\fR|\fB\-\-disable\-deterministic\-archives\fR]
[\fB\-\-keep\-section\-symbols\fR]
[\fB\-\-keep\-file\-symbols\fR]
[\fB\-\-only\-keep\-debug\fR]
[\fB\-v\fR |\fB\-\-verbose\fR] [\fB\-V\fR|\fB\-\-version\fR]
[\fB\-\-help\fR] [\fB\-\-info\fR]
\fIobjfile\fR...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1GNU\s0 \fBstrip\fR discards all symbols from object files
\&\fIobjfile\fR. The list of object files may include archives.
At least one object file must be given.
.PP
\&\fBstrip\fR modifies the files named in its argument,
rather than writing modified copies under different names.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-F\fR \fIbfdname\fR" 4
.IX Item "-F bfdname"
.PD 0
.IP "\fB\-\-target=\fR\fIbfdname\fR" 4
.IX Item "--target=bfdname"
.PD
Treat the original \fIobjfile\fR as a file with the object
code format \fIbfdname\fR, and rewrite it in the same format.
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Show a summary of the options to \fBstrip\fR and exit.
.IP "\fB\-\-info\fR" 4
.IX Item "--info"
Display a list showing all architectures and object formats available.
.IP "\fB\-I\fR \fIbfdname\fR" 4
.IX Item "-I bfdname"
.PD 0
.IP "\fB\-\-input\-target=\fR\fIbfdname\fR" 4
.IX Item "--input-target=bfdname"
.PD
Treat the original \fIobjfile\fR as a file with the object
code format \fIbfdname\fR.
.IP "\fB\-O\fR \fIbfdname\fR" 4
.IX Item "-O bfdname"
.PD 0
.IP "\fB\-\-output\-target=\fR\fIbfdname\fR" 4
.IX Item "--output-target=bfdname"
.PD
Replace \fIobjfile\fR with a file in the output format \fIbfdname\fR.
.IP "\fB\-R\fR \fIsectionname\fR" 4
.IX Item "-R sectionname"
.PD 0
.IP "\fB\-\-remove\-section=\fR\fIsectionname\fR" 4
.IX Item "--remove-section=sectionname"
.PD
Remove any section named \fIsectionname\fR from the output file, in
addition to whatever sections would otherwise be removed. This
option may be given more than once. Note that using this option
inappropriately may make the output file unusable. The wildcard
character \fB*\fR may be given at the end of \fIsectionname\fR. If
so, then any section starting with \fIsectionname\fR will be removed.
.Sp
If the first character of \fIsectionpattern\fR is the exclamation
point (!) then matching sections will not be removed even if an
earlier use of \fB\-\-remove\-section\fR on the same command line
would otherwise remove it. For example:
.Sp
.Vb 1
\& \-\-remove\-section=.text.* \-\-remove\-section=!.text.foo
.Ve
.Sp
will remove all sections matching the pattern '.text.*', but will not
remove the section '.text.foo'.
.IP "\fB\-\-keep\-section=\fR\fIsectionpattern\fR" 4
.IX Item "--keep-section=sectionpattern"
When removing sections from the output file, keep sections that match
\&\fIsectionpattern\fR.
.IP "\fB\-\-remove\-relocations=\fR\fIsectionpattern\fR" 4
.IX Item "--remove-relocations=sectionpattern"
Remove relocations from the output file for any section matching
\&\fIsectionpattern\fR. This option may be given more than once. Note
that using this option inappropriately may make the output file
unusable. Wildcard characters are accepted in \fIsectionpattern\fR.
For example:
.Sp
.Vb 1
\& \-\-remove\-relocations=.text.*
.Ve
.Sp
will remove the relocations for all sections matching the patter
\&'.text.*'.
.Sp
If the first character of \fIsectionpattern\fR is the exclamation
point (!) then matching sections will not have their relocation
removed even if an earlier use of \fB\-\-remove\-relocations\fR on the
same command line would otherwise cause the relocations to be removed.
For example:
.Sp
.Vb 1
\& \-\-remove\-relocations=.text.* \-\-remove\-relocations=!.text.foo
.Ve
.Sp
will remove all relocations for sections matching the pattern
\&'.text.*', but will not remove relocations for the section
\&'.text.foo'.
.IP "\fB\-\-strip\-section\-headers\fR" 4
.IX Item "--strip-section-headers"
Strip section headers. This option is specific to \s-1ELF\s0 files. Implies
\&\fB\-\-strip\-all\fR and \fB\-\-merge\-notes\fR.
.IP "\fB\-s\fR" 4
.IX Item "-s"
.PD 0
.IP "\fB\-\-strip\-all\fR" 4
.IX Item "--strip-all"
.PD
Remove all symbols.
.IP "\fB\-g\fR" 4
.IX Item "-g"
.PD 0
.IP "\fB\-S\fR" 4
.IX Item "-S"
.IP "\fB\-d\fR" 4
.IX Item "-d"
.IP "\fB\-\-strip\-debug\fR" 4
.IX Item "--strip-debug"
.PD
Remove debugging symbols only.
.IP "\fB\-\-strip\-dwo\fR" 4
.IX Item "--strip-dwo"
Remove the contents of all \s-1DWARF\s0 .dwo sections, leaving the
remaining debugging sections and all symbols intact.
See the description of this option in the \fBobjcopy\fR section
for more information.
.IP "\fB\-\-strip\-unneeded\fR" 4
.IX Item "--strip-unneeded"
Remove all symbols that are not needed for relocation processing in
addition to debugging symbols and sections stripped by
\&\fB\-\-strip\-debug\fR.
.IP "\fB\-K\fR \fIsymbolname\fR" 4
.IX Item "-K symbolname"
.PD 0
.IP "\fB\-\-keep\-symbol=\fR\fIsymbolname\fR" 4
.IX Item "--keep-symbol=symbolname"
.PD
When stripping symbols, keep symbol \fIsymbolname\fR even if it would
normally be stripped. This option may be given more than once.
.IP "\fB\-M\fR" 4
.IX Item "-M"
.PD 0
.IP "\fB\-\-merge\-notes\fR" 4
.IX Item "--merge-notes"
.IP "\fB\-\-no\-merge\-notes\fR" 4
.IX Item "--no-merge-notes"
.PD
For \s-1ELF\s0 files, attempt (or do not attempt) to reduce the size of any
\&\s-1SHT_NOTE\s0 type sections by removing duplicate notes. The default is to
attempt this reduction unless stripping debug or \s-1DWO\s0 information.
.IP "\fB\-N\fR \fIsymbolname\fR" 4
.IX Item "-N symbolname"
.PD 0
.IP "\fB\-\-strip\-symbol=\fR\fIsymbolname\fR" 4
.IX Item "--strip-symbol=symbolname"
.PD
Remove symbol \fIsymbolname\fR from the source file. This option may be
given more than once, and may be combined with strip options other than
\&\fB\-K\fR.
.IP "\fB\-o\fR \fIfile\fR" 4
.IX Item "-o file"
Put the stripped output in \fIfile\fR, rather than replacing the
existing file. When this argument is used, only one \fIobjfile\fR
argument may be specified.
.IP "\fB\-p\fR" 4
.IX Item "-p"
.PD 0
.IP "\fB\-\-preserve\-dates\fR" 4
.IX Item "--preserve-dates"
.PD
Preserve the access and modification dates of the file.
.IP "\fB\-D\fR" 4
.IX Item "-D"
.PD 0
.IP "\fB\-\-enable\-deterministic\-archives\fR" 4
.IX Item "--enable-deterministic-archives"
.PD
Operate in \fIdeterministic\fR mode. When copying archive members
and writing the archive index, use zero for UIDs, GIDs, timestamps,
and use consistent file modes for all files.
.Sp
If \fIbinutils\fR was configured with
\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default.
It can be disabled with the \fB\-U\fR option, below.
.IP "\fB\-U\fR" 4
.IX Item "-U"
.PD 0
.IP "\fB\-\-disable\-deterministic\-archives\fR" 4
.IX Item "--disable-deterministic-archives"
.PD
Do \fInot\fR operate in \fIdeterministic\fR mode. This is the
inverse of the \fB\-D\fR option, above: when copying archive members
and writing the archive index, use their actual \s-1UID, GID,\s0 timestamp,
and file mode values.
.Sp
This is the default unless \fIbinutils\fR was configured with
\&\fB\-\-enable\-deterministic\-archives\fR.
.IP "\fB\-w\fR" 4
.IX Item "-w"
.PD 0
.IP "\fB\-\-wildcard\fR" 4
.IX Item "--wildcard"
.PD
Permit regular expressions in \fIsymbolname\fRs used in other command
line options. The question mark (?), asterisk (*), backslash (\e) and
square brackets ([]) operators can be used anywhere in the symbol
name. If the first character of the symbol name is the exclamation
point (!) then the sense of the switch is reversed for that symbol.
For example:
.Sp
.Vb 1
\& \-w \-K !foo \-K fo*
.Ve
.Sp
would cause strip to only keep symbols that start with the letters
\&\*(L"fo\*(R", but to discard the symbol \*(L"foo\*(R".
.IP "\fB\-x\fR" 4
.IX Item "-x"
.PD 0
.IP "\fB\-\-discard\-all\fR" 4
.IX Item "--discard-all"
.PD
Remove non-global symbols.
.IP "\fB\-X\fR" 4
.IX Item "-X"
.PD 0
.IP "\fB\-\-discard\-locals\fR" 4
.IX Item "--discard-locals"
.PD
Remove compiler-generated local symbols.
(These usually start with \fBL\fR or \fB.\fR.)
.IP "\fB\-\-keep\-section\-symbols\fR" 4
.IX Item "--keep-section-symbols"
When stripping a file, perhaps with \fB\-\-strip\-debug\fR or
\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying section names,
which would otherwise get stripped.
.IP "\fB\-\-keep\-file\-symbols\fR" 4
.IX Item "--keep-file-symbols"
When stripping a file, perhaps with \fB\-\-strip\-debug\fR or
\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying source file names,
which would otherwise get stripped.
.IP "\fB\-\-only\-keep\-debug\fR" 4
.IX Item "--only-keep-debug"
Strip a file, emptying the contents of any sections that would not be
stripped by \fB\-\-strip\-debug\fR and leaving the debugging sections
intact. In \s-1ELF\s0 files, this preserves all the note sections in the
output as well.
.Sp
Note \- the section headers of the stripped sections are preserved,
including their sizes, but the contents of the section are discarded.
The section headers are preserved so that other tools can match up the
debuginfo file with the real executable, even if that executable has
been relocated to a different address space.
.Sp
The intention is that this option will be used in conjunction with
\&\fB\-\-add\-gnu\-debuglink\fR to create a two part executable. One a
stripped binary which will occupy less space in \s-1RAM\s0 and in a
distribution and the second a debugging information file which is only
needed if debugging abilities are required. The suggested procedure
to create these files is as follows:
.RS 4
.IP "1.<Link the executable as normal. Assuming that it is called>" 4
.IX Item "1.<Link the executable as normal. Assuming that it is called>"
\&\f(CW\*(C`foo\*(C'\fR then...
.ie n .IP "1.<Run ""objcopy \-\-only\-keep\-debug foo foo.dbg"" to>" 4
.el .IP "1.<Run \f(CWobjcopy \-\-only\-keep\-debug foo foo.dbg\fR to>" 4
.IX Item "1.<Run objcopy --only-keep-debug foo foo.dbg to>"
create a file containing the debugging info.
.ie n .IP "1.<Run ""objcopy \-\-strip\-debug foo"" to create a>" 4
.el .IP "1.<Run \f(CWobjcopy \-\-strip\-debug foo\fR to create a>" 4
.IX Item "1.<Run objcopy --strip-debug foo to create a>"
stripped executable.
.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.dbg foo"">" 4
.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.dbg foo\fR>" 4
.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.dbg foo>"
to add a link to the debugging info into the stripped executable.
.RE
.RS 4
.Sp
Note\-\-\-the choice of \f(CW\*(C`.dbg\*(C'\fR as an extension for the debug info
file is arbitrary. Also the \f(CW\*(C`\-\-only\-keep\-debug\*(C'\fR step is
optional. You could instead do this:
.IP "1.<Link the executable as normal.>" 4
.IX Item "1.<Link the executable as normal.>"
.PD 0
.ie n .IP "1.<Copy ""foo"" to ""foo.full"">" 4
.el .IP "1.<Copy \f(CWfoo\fR to \f(CWfoo.full\fR>" 4
.IX Item "1.<Copy foo to foo.full>"
.ie n .IP "1.<Run ""strip \-\-strip\-debug foo"">" 4
.el .IP "1.<Run \f(CWstrip \-\-strip\-debug foo\fR>" 4
.IX Item "1.<Run strip --strip-debug foo>"
.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.full foo"">" 4
.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.full foo\fR>" 4
.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.full foo>"
.RE
.RS 4
.PD
.Sp
i.e., the file pointed to by the \fB\-\-add\-gnu\-debuglink\fR can be the
full executable. It does not have to be a file created by the
\&\fB\-\-only\-keep\-debug\fR switch.
.Sp
Note\-\-\-this switch is only intended for use on fully linked files. It
does not make sense to use it on object files where the debugging
information may be incomplete. Besides the gnu_debuglink feature
currently only supports the presence of one filename containing
debugging information, not multiple filenames on a one-per-object-file
basis.
.RE
.IP "\fB\-V\fR" 4
.IX Item "-V"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Show the version number for \fBstrip\fR.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Verbose output: list all object files modified. In the case of
archives, \fBstrip \-v\fR lists all members of the archive.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
the Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

360
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-windmc.1 Normal file
View File

@ -0,0 +1,360 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "WINDMC 1"
.TH WINDMC 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
windmc \- generates Windows message resources
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
windmc [options] input-file
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBwindmc\fR reads message definitions from an input file (.mc) and
translate them into a set of output files. The output files may be of
four kinds:
.ie n .IP """h""" 4
.el .IP "\f(CWh\fR" 4
.IX Item "h"
A C header file containing the message definitions.
.ie n .IP """rc""" 4
.el .IP "\f(CWrc\fR" 4
.IX Item "rc"
A resource file compilable by the \fBwindres\fR tool.
.ie n .IP """bin""" 4
.el .IP "\f(CWbin\fR" 4
.IX Item "bin"
One or more binary files containing the resource data for a specific
message language.
.ie n .IP """dbg""" 4
.el .IP "\f(CWdbg\fR" 4
.IX Item "dbg"
A C include file that maps message id's to their symbolic name.
.PP
The exact description of these different formats is available in
documentation from Microsoft.
.PP
When \fBwindmc\fR converts from the \f(CW\*(C`mc\*(C'\fR format to the \f(CW\*(C`bin\*(C'\fR
format, \f(CW\*(C`rc\*(C'\fR, \f(CW\*(C`h\*(C'\fR, and optional \f(CW\*(C`dbg\*(C'\fR it is acting like the
Windows Message Compiler.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-a\fR" 4
.IX Item "-a"
.PD 0
.IP "\fB\-\-ascii_in\fR" 4
.IX Item "--ascii_in"
.PD
Specifies that the input file specified is \s-1ASCII.\s0 This is the default
behaviour.
.IP "\fB\-A\fR" 4
.IX Item "-A"
.PD 0
.IP "\fB\-\-ascii_out\fR" 4
.IX Item "--ascii_out"
.PD
Specifies that messages in the output \f(CW\*(C`bin\*(C'\fR files should be in \s-1ASCII\s0
format.
.IP "\fB\-b\fR" 4
.IX Item "-b"
.PD 0
.IP "\fB\-\-binprefix\fR" 4
.IX Item "--binprefix"
.PD
Specifies that \f(CW\*(C`bin\*(C'\fR filenames should have to be prefixed by the
basename of the source file.
.IP "\fB\-c\fR" 4
.IX Item "-c"
.PD 0
.IP "\fB\-\-customflag\fR" 4
.IX Item "--customflag"
.PD
Sets the customer bit in all message id's.
.IP "\fB\-C\fR \fIcodepage\fR" 4
.IX Item "-C codepage"
.PD 0
.IP "\fB\-\-codepage_in\fR \fIcodepage\fR" 4
.IX Item "--codepage_in codepage"
.PD
Sets the default codepage to be used to convert input file to \s-1UTF16.\s0 The
default is ocdepage 1252.
.IP "\fB\-d\fR" 4
.IX Item "-d"
.PD 0
.IP "\fB\-\-decimal_values\fR" 4
.IX Item "--decimal_values"
.PD
Outputs the constants in the header file in decimal. Default is using
hexadecimal output.
.IP "\fB\-e\fR \fIext\fR" 4
.IX Item "-e ext"
.PD 0
.IP "\fB\-\-extension\fR \fIext\fR" 4
.IX Item "--extension ext"
.PD
The extension for the header file. The default is .h extension.
.IP "\fB\-F\fR \fItarget\fR" 4
.IX Item "-F target"
.PD 0
.IP "\fB\-\-target\fR \fItarget\fR" 4
.IX Item "--target target"
.PD
Specify the \s-1BFD\s0 format to use for a bin file as output. This
is a \s-1BFD\s0 target name; you can use the \fB\-\-help\fR option to see a list
of supported targets. Normally \fBwindmc\fR will use the default
format, which is the first one listed by the \fB\-\-help\fR option.
.IP "\fB\-h\fR \fIpath\fR" 4
.IX Item "-h path"
.PD 0
.IP "\fB\-\-headerdir\fR \fIpath\fR" 4
.IX Item "--headerdir path"
.PD
The target directory of the generated header file. The default is the
current directory.
.IP "\fB\-H\fR" 4
.IX Item "-H"
.PD 0
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Displays a list of command-line options and then exits.
.IP "\fB\-m\fR \fIcharacters\fR" 4
.IX Item "-m characters"
.PD 0
.IP "\fB\-\-maxlength\fR \fIcharacters\fR" 4
.IX Item "--maxlength characters"
.PD
Instructs \fBwindmc\fR to generate a warning if the length
of any message exceeds the number specified.
.IP "\fB\-n\fR" 4
.IX Item "-n"
.PD 0
.IP "\fB\-\-nullterminate\fR" 4
.IX Item "--nullterminate"
.PD
Terminate message text in \f(CW\*(C`bin\*(C'\fR files by zero. By default they are
terminated by \s-1CR/LF.\s0
.IP "\fB\-o\fR" 4
.IX Item "-o"
.PD 0
.IP "\fB\-\-hresult_use\fR" 4
.IX Item "--hresult_use"
.PD
Not yet implemented. Instructs \f(CW\*(C`windmc\*(C'\fR to generate an \s-1OLE2\s0 header
file, using \s-1HRESULT\s0 definitions. Status codes are used if the flag is not
specified.
.IP "\fB\-O\fR \fIcodepage\fR" 4
.IX Item "-O codepage"
.PD 0
.IP "\fB\-\-codepage_out\fR \fIcodepage\fR" 4
.IX Item "--codepage_out codepage"
.PD
Sets the default codepage to be used to output text files. The default
is ocdepage 1252.
.IP "\fB\-r\fR \fIpath\fR" 4
.IX Item "-r path"
.PD 0
.IP "\fB\-\-rcdir\fR \fIpath\fR" 4
.IX Item "--rcdir path"
.PD
The target directory for the generated \f(CW\*(C`rc\*(C'\fR script and the generated
\&\f(CW\*(C`bin\*(C'\fR files that the resource compiler script includes. The default
is the current directory.
.IP "\fB\-u\fR" 4
.IX Item "-u"
.PD 0
.IP "\fB\-\-unicode_in\fR" 4
.IX Item "--unicode_in"
.PD
Specifies that the input file is \s-1UTF16.\s0
.IP "\fB\-U\fR" 4
.IX Item "-U"
.PD 0
.IP "\fB\-\-unicode_out\fR" 4
.IX Item "--unicode_out"
.PD
Specifies that messages in the output \f(CW\*(C`bin\*(C'\fR file should be in \s-1UTF16\s0
format. This is the default behaviour.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Enable verbose mode.
.IP "\fB\-V\fR" 4
.IX Item "-V"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Prints the version number for \fBwindmc\fR.
.IP "\fB\-x\fR \fIpath\fR" 4
.IX Item "-x path"
.PD 0
.IP "\fB\-\-xdgb\fR \fIpath\fR" 4
.IX Item "--xdgb path"
.PD
The path of the \f(CW\*(C`dbg\*(C'\fR C include file that maps message id's to the
symbolic name. No such file is generated without specifying the switch.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
the Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

372
tools/bin/x86_64-unknown-redox/toolchain/share/man/man1/x86_64-unknown-redox-windres.1 Normal file
View File

@ -0,0 +1,372 @@
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "WINDRES 1"
.TH WINDRES 1 "2024-10-18" "binutils-2.43.1" "GNU Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
windres \- manipulate Windows resources
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
windres [options] [input\-file] [output\-file]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBwindres\fR reads resources from an input file and copies them into
an output file. Either file may be in one of three formats:
.ie n .IP """rc""" 4
.el .IP "\f(CWrc\fR" 4
.IX Item "rc"
A text format read by the Resource Compiler.
.ie n .IP """res""" 4
.el .IP "\f(CWres\fR" 4
.IX Item "res"
A binary format generated by the Resource Compiler.
.ie n .IP """coff""" 4
.el .IP "\f(CWcoff\fR" 4
.IX Item "coff"
A \s-1COFF\s0 object or executable.
.PP
The exact description of these different formats is available in
documentation from Microsoft.
.PP
When \fBwindres\fR converts from the \f(CW\*(C`rc\*(C'\fR format to the \f(CW\*(C`res\*(C'\fR
format, it is acting like the Windows Resource Compiler. When
\&\fBwindres\fR converts from the \f(CW\*(C`res\*(C'\fR format to the \f(CW\*(C`coff\*(C'\fR
format, it is acting like the Windows \f(CW\*(C`CVTRES\*(C'\fR program.
.PP
When \fBwindres\fR generates an \f(CW\*(C`rc\*(C'\fR file, the output is similar
but not identical to the format expected for the input. When an input
\&\f(CW\*(C`rc\*(C'\fR file refers to an external filename, an output \f(CW\*(C`rc\*(C'\fR file
will instead include the file contents.
.PP
If the input or output format is not specified, \fBwindres\fR will
guess based on the file name, or, for the input file, the file contents.
A file with an extension of \fI.rc\fR will be treated as an \f(CW\*(C`rc\*(C'\fR
file, a file with an extension of \fI.res\fR will be treated as a
\&\f(CW\*(C`res\*(C'\fR file, and a file with an extension of \fI.o\fR or
\&\fI.exe\fR will be treated as a \f(CW\*(C`coff\*(C'\fR file.
.PP
If no output file is specified, \fBwindres\fR will print the resources
in \f(CW\*(C`rc\*(C'\fR format to standard output.
.PP
The normal use is for you to write an \f(CW\*(C`rc\*(C'\fR file, use \fBwindres\fR
to convert it to a \s-1COFF\s0 object file, and then link the \s-1COFF\s0 file into
your application. This will make the resources described in the
\&\f(CW\*(C`rc\*(C'\fR file available to Windows.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-i\fR \fIfilename\fR" 4
.IX Item "-i filename"
.PD 0
.IP "\fB\-\-input\fR \fIfilename\fR" 4
.IX Item "--input filename"
.PD
The name of the input file. If this option is not used, then
\&\fBwindres\fR will use the first non-option argument as the input file
name. If there are no non-option arguments, then \fBwindres\fR will
read from standard input. \fBwindres\fR can not read a \s-1COFF\s0 file from
standard input.
.IP "\fB\-o\fR \fIfilename\fR" 4
.IX Item "-o filename"
.PD 0
.IP "\fB\-\-output\fR \fIfilename\fR" 4
.IX Item "--output filename"
.PD
The name of the output file. If this option is not used, then
\&\fBwindres\fR will use the first non-option argument, after any used
for the input file name, as the output file name. If there is no
non-option argument, then \fBwindres\fR will write to standard output.
\&\fBwindres\fR can not write a \s-1COFF\s0 file to standard output. Note,
for compatibility with \fBrc\fR the option \fB\-fo\fR is also
accepted, but its use is not recommended.
.IP "\fB\-J\fR \fIformat\fR" 4
.IX Item "-J format"
.PD 0
.IP "\fB\-\-input\-format\fR \fIformat\fR" 4
.IX Item "--input-format format"
.PD
The input format to read. \fIformat\fR may be \fBres\fR, \fBrc\fR, or
\&\fBcoff\fR. If no input format is specified, \fBwindres\fR will
guess, as described above.
.IP "\fB\-O\fR \fIformat\fR" 4
.IX Item "-O format"
.PD 0
.IP "\fB\-\-output\-format\fR \fIformat\fR" 4
.IX Item "--output-format format"
.PD
The output format to generate. \fIformat\fR may be \fBres\fR,
\&\fBrc\fR, or \fBcoff\fR. If no output format is specified,
\&\fBwindres\fR will guess, as described above.
.IP "\fB\-F\fR \fItarget\fR" 4
.IX Item "-F target"
.PD 0
.IP "\fB\-\-target\fR \fItarget\fR" 4
.IX Item "--target target"
.PD
Specify the \s-1BFD\s0 format to use for a \s-1COFF\s0 file as input or output. This
is a \s-1BFD\s0 target name; you can use the \fB\-\-help\fR option to see a list
of supported targets. Normally \fBwindres\fR will use the default
format, which is the first one listed by the \fB\-\-help\fR option.
.IP "\fB\-\-preprocessor\fR \fIprogram\fR" 4
.IX Item "--preprocessor program"
When \fBwindres\fR reads an \f(CW\*(C`rc\*(C'\fR file, it runs it through the C
preprocessor first. This option may be used to specify the preprocessor
to use. The default preprocessor is \f(CW\*(C`gcc\*(C'\fR.
.IP "\fB\-\-preprocessor\-arg\fR \fIoption\fR" 4
.IX Item "--preprocessor-arg option"
When \fBwindres\fR reads an \f(CW\*(C`rc\*(C'\fR file, it runs it through
the C preprocessor first. This option may be used to specify additional
text to be passed to preprocessor on its command line.
This option can be used multiple times to add multiple options to the
preprocessor command line.
If the \fB\-\-preprocessor\fR option has not been specified then a
default set of preprocessor arguments will be used, with any
\&\fB\-\-preprocessor\-arg\fR options being placed after them on the
command line. These default arguments are \f(CW\*(C`\-E\*(C'\fR,
\&\f(CW\*(C`\-xc\-header\*(C'\fR and \f(CW\*(C`\-DRC_INVOKED\*(C'\fR.
.IP "\fB\-I\fR \fIdirectory\fR" 4
.IX Item "-I directory"
.PD 0
.IP "\fB\-\-include\-dir\fR \fIdirectory\fR" 4
.IX Item "--include-dir directory"
.PD
Specify an include directory to use when reading an \f(CW\*(C`rc\*(C'\fR file.
\&\fBwindres\fR will pass this to the preprocessor as an \fB\-I\fR
option. \fBwindres\fR will also search this directory when looking for
files named in the \f(CW\*(C`rc\*(C'\fR file. If the argument passed to this command
matches any of the supported \fIformats\fR (as described in the \fB\-J\fR
option), it will issue a deprecation warning, and behave just like the
\&\fB\-J\fR option. New programs should not use this behaviour. If a
directory happens to match a \fIformat\fR, simple prefix it with \fB./\fR
to disable the backward compatibility.
.IP "\fB\-D\fR \fItarget\fR" 4
.IX Item "-D target"
.PD 0
.IP "\fB\-\-define\fR \fIsym\fR\fB[=\fR\fIval\fR\fB]\fR" 4
.IX Item "--define sym[=val]"
.PD
Specify a \fB\-D\fR option to pass to the preprocessor when reading an
\&\f(CW\*(C`rc\*(C'\fR file.
.IP "\fB\-U\fR \fItarget\fR" 4
.IX Item "-U target"
.PD 0
.IP "\fB\-\-undefine\fR \fIsym\fR" 4
.IX Item "--undefine sym"
.PD
Specify a \fB\-U\fR option to pass to the preprocessor when reading an
\&\f(CW\*(C`rc\*(C'\fR file.
.IP "\fB\-r\fR" 4
.IX Item "-r"
Ignored for compatibility with rc.
.IP "\fB\-v\fR" 4
.IX Item "-v"
Enable verbose mode. This tells you what the preprocessor is if you
didn't specify one.
.IP "\fB\-c\fR \fIval\fR" 4
.IX Item "-c val"
.PD 0
.IP "\fB\-\-codepage\fR \fIval\fR" 4
.IX Item "--codepage val"
.PD
Specify the default codepage to use when reading an \f(CW\*(C`rc\*(C'\fR file.
\&\fIval\fR should be a hexadecimal prefixed by \fB0x\fR or decimal
codepage code. The valid range is from zero up to 0xffff, but the
validity of the codepage is host and configuration dependent.
.IP "\fB\-l\fR \fIval\fR" 4
.IX Item "-l val"
.PD 0
.IP "\fB\-\-language\fR \fIval\fR" 4
.IX Item "--language val"
.PD
Specify the default language to use when reading an \f(CW\*(C`rc\*(C'\fR file.
\&\fIval\fR should be a hexadecimal language code. The low eight bits are
the language, and the high eight bits are the sublanguage.
.IP "\fB\-\-use\-temp\-file\fR" 4
.IX Item "--use-temp-file"
Use a temporary file to instead of using popen to read the output of
the preprocessor. Use this option if the popen implementation is buggy
on the host (eg., certain non-English language versions of Windows 95 and
Windows 98 are known to have buggy popen where the output will instead
go the console).
.IP "\fB\-\-no\-use\-temp\-file\fR" 4
.IX Item "--no-use-temp-file"
Use popen, not a temporary file, to read the output of the preprocessor.
This is the default behaviour.
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Prints a usage summary.
.IP "\fB\-V\fR" 4
.IX Item "-V"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Prints the version number for \fBwindres\fR.
.IP "\fB\-\-yydebug\fR" 4
.IX Item "--yydebug"
If \fBwindres\fR is compiled with \f(CW\*(C`YYDEBUG\*(C'\fR defined as \f(CW1\fR,
this will turn on parser debugging.
.IP "\fB@\fR\fIfile\fR" 4
.IX Item "@file"
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
the Info entries for \fIbinutils\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".