Skip to content

Commit 2c8d2f6

Browse files
matthewhughes934ytmimi
authored andcommitted
Contrib docs: note how to run a binary directly
Because it took me a moment to figure this out when I was wanting to run `rustfmt` through a debugger. For references of the variable to set to modify behaviour see Windows[1], glibc[2], MacOS[3] Note the examples use Bash parameter expansion, specifically the form `${parameter:+word}`[4], to avoid potentially adding an empty element to `LD_LIBRARY_PATH` that could be a security issue (see[5]) Some history: there used to be a note in `README.md` about setting this variable, but that was removed with 2e75f23. However, with the addition of `rustc_driver` with d7fa2ee (original upstream[6]) this is required again. Link: https://learn.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order [1] Link: https://www.man7.org/linux/man-pages/man3/dlopen.3.html [2] Link: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/dlopen.3.html [3] Link: https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html [4] Link: #2923 [5] Link: rust-lang/rust@8c000a6 [6]
1 parent 1e6ce1d commit 2c8d2f6

1 file changed

Lines changed: 40 additions & 0 deletions

File tree

Contributing.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,46 @@ If you want to test modified `cargo-fmt`, or run `rustfmt` on the whole project
116116
RUSTFMT="./target/debug/rustfmt" cargo run --bin cargo-fmt -- --manifest-path path/to/project/you/want2test/Cargo.toml
117117
```
118118

119+
#### Running a binary directly
120+
121+
You may want to run one of the built binaries directly, for example to connect
122+
it to a debugger. Since `rustfmt` uses `rustc_driver` it needs to be linked
123+
against the version of that library for the current toolchain, without
124+
configuring anything you are likely to run into errors like:
125+
126+
```
127+
./target/debug/rustfmt: error while loading shared libraries: librustc_driver-63b8deb6c23747dd.so: cannot open shared object file: No such file or directory
128+
```
129+
130+
This library will be in the sysroot of the current toolchain, which will be
131+
printed by `rustc --print sysroot`, so we'll need to include that in the
132+
system's dynamic library search path. On GNU/Linux this can be done by setting
133+
the `LD_LIBRARY_PATH` variable, e.g. using Bash:
134+
135+
```
136+
LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" ./target/debug/rustfmt
137+
```
138+
139+
On MacOS there is the `DYLD_LIBRARY_PATH` variable, e.g. using Bash:
140+
141+
```
142+
DYLD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" ./target/debug/rustfmt
143+
```
144+
145+
And under Windows the `PATH` environment variable, e.g. using Bash:
146+
147+
```
148+
PATH="$(rustc --print sysroot)/bin${PATH:+:${PATH}}"
149+
```
150+
151+
Continuing the GNU/Linux example, you can invoke a debugger, e.g. `rust-gdb`,
152+
like:
153+
154+
```
155+
LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" rust-gdb --args ./target/debug/rustfmt --check some_file.rs
156+
157+
```
158+
119159
### Gate formatting changes
120160

121161
A change that introduces a different code-formatting must be gated on the

0 commit comments

Comments
 (0)