Contrib docs: note how to run a binary directly by matthewhughes934 · Pull Request #6823 · rust-lang/rustfmt

matthewhughes934 · 2026-03-11T20:09:55Z

Because it took me a moment to figure this out when I was wanting to run rustfmt through a debugger.

Setting LD_LIBRARY_PATH uses some Bash parameter expansion, specifically the form ${parameter:+word}[1], to avoid potentially adding an empty element to LD_LIBRARY_PATH that could be a security issue (see[2])

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[3]) this is required again.

Link: https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html [1]
Link: #2923 [2]
Link: rust-lang/rust@8c000a6 [3]

Because it took me a moment to figure this out when I was wanting to run `rustfmt` through a debugger. Setting `LD_LIBRARY_PATH` uses some Bash parameter expansion, specifically the form `${parameter:+word}`[1], to avoid potentially adding an empty element to `LD_LIBRARY_PATH` that could be a security issue (see[2]) 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[3]) this is required again. Link: https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html [1] Link: rust-lang#2923 [2] Link: rust-lang/rust@8c000a6 [3]

ytmimi · 2026-03-11T21:27:45Z

Contributing.md

+#### Running a binary directly
+
+You may want to run one of the built binaries directly, for example to connect
+it to a debugger. Since `rustfmt` uses `rustc_driver` it needs to be linked
+against the version of that library for the current toolchain, without
+configuring anything you are likely to run into errors like:
+
+    $ ./target/debug/rustfmt
+    ./target/debug/rustfmt: error while loading shared libraries: librustc_driver-63b8deb6c23747dd.so: cannot open shared object file: No such file or directory
+
+This library will be in the sysroot of the current toolchain, so we can fix this
+by telling the linker to look there. For example on Linux with Bash:
+
+    LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" ./target/debug/rustfmt
+
+Equivalently, you could set the variable for the current environment:
+
+    $ export LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
+    $ ./target/debug/rustfm
+
+Then, you can invoke a debugger like `rust-gdb`:
+
+    LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" rust-gdb --args ./target/debug/rustfmt --check some_file.rs
+


We encourage user to run with cargo because cargo sets the necessary environment variables for you. Also note that LD_LIBRARY_PATH is only relevant on linux. windows and macos use different environment variables and that should be called out.

We encourage user to run with cargo because cargo sets the necessary environment variables for you.

👍 I don't want this change to suggest otherwise, the use case I was looking at was attaching a debugger. This can be done when running under cargo, but it's a bit clunky (extra lines start with # inserted by me):

Reading symbols from cargo... # symbols loaded for 'cargo' but not 'rustfmt' (yet), need to run until we start rustfmt to read those (No debugging symbols found in cargo) (gdb) b src/bin/main.rs:31 ❌️ No symbol table is loaded. Use the "file" command. Make breakpoint pending on future shared library load? (y or [n]) y Breakpoint 1 (src/bin/main.rs:31) pending.

Compared to running directly:

$ LD_LIBRARY_PATH="$(rustc --print sysroot)/lib" rust-gdb --quiet --args ./target/debug/rustfmt file.rs Reading symbols from ./target/debug/rustfmt... # symbols already loaded, can tab-complete file names, inspect functions etc. before running (gdb) b src/bin/main.rs:31 Breakpoint 1 at 0x2d53ba: src/bin/main.rs:31. (2 locations)

Also note that LD_LIBRARY_PATH is only relevant on linux. windows and macos use different environment variables and that should be called out.

Indeed, I tried to make it clear before using LD_LIBRARY_PATH that the example was for Linux only. I'd be happy to go and see how to make it work on MacOS + Windows too.

It would be nice to include examples for MacOS + Windows too.

ytmimi

Let's wrap code blocks in code fences and remove leading $ in code examples. It would also be great to include examples for MacOS + Windows.

View changes since this review

ytmimi · 2026-03-12T17:13:16Z

Contributing.md

+    $ ./target/debug/rustfmt
+    ./target/debug/rustfmt: error while loading shared libraries: librustc_driver-63b8deb6c23747dd.so: cannot open shared object file: No such file or directory


Let's wrap this in a code fence to make the code block clearer. Also, probably enough to just show the example error message:

Suggested change

$ ./target/debug/rustfmt

./target/debug/rustfmt: error while loading shared libraries: librustc_driver-63b8deb6c23747dd.so: cannot open shared object file: No such file or directory

```

./target/debug/rustfmt: error while loading shared libraries: librustc_driver-63b8deb6c23747dd.so: cannot open shared object file: No such file or directory

```

ytmimi · 2026-03-12T17:15:40Z

Contributing.md

+This library will be in the sysroot of the current toolchain, so we can fix this
+by telling the linker to look there. For example on Linux with Bash:
+
+    LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" ./target/debug/rustfmt


Again, I'd prefer we wrap this in a code fence.

Suggested change

LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" ./target/debug/rustfmt

```

LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" ./target/debug/rustfmt

```

ytmimi · 2026-03-12T17:21:05Z

Contributing.md

+    $ export LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
+    $ ./target/debug/rustfm


Wrap in code fence and drop the leading $ since those will also get copied when using the copy feature on GitHub code blocks:

Suggested change

$ export LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"

$ ./target/debug/rustfm

```

export LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"

./target/debug/rustfm

```

ytmimi · 2026-03-12T17:21:31Z

Contributing.md

+
+Then, you can invoke a debugger like `rust-gdb`:
+
+    LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" rust-gdb --args ./target/debug/rustfmt --check some_file.rs


Suggested change

LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" rust-gdb --args ./target/debug/rustfmt --check some_file.rs

```

LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" rust-gdb --args ./target/debug/rustfmt --check some_file.rs

```

ytmimi · 2026-03-12T17:22:58Z

Contributing.md

+#### Running a binary directly
+
+You may want to run one of the built binaries directly, for example to connect
+it to a debugger. Since `rustfmt` uses `rustc_driver` it needs to be linked
+against the version of that library for the current toolchain, without
+configuring anything you are likely to run into errors like:
+
+    $ ./target/debug/rustfmt
+    ./target/debug/rustfmt: error while loading shared libraries: librustc_driver-63b8deb6c23747dd.so: cannot open shared object file: No such file or directory
+
+This library will be in the sysroot of the current toolchain, so we can fix this
+by telling the linker to look there. For example on Linux with Bash:
+
+    LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" ./target/debug/rustfmt
+
+Equivalently, you could set the variable for the current environment:
+
+    $ export LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
+    $ ./target/debug/rustfm
+
+Then, you can invoke a debugger like `rust-gdb`:
+
+    LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" rust-gdb --args ./target/debug/rustfmt --check some_file.rs
+


It would be nice to include examples for MacOS + Windows too.

rustbot · 2026-03-12T17:24:35Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

rustbot added the S-waiting-on-review Status: awaiting review from the assignee but also interested parties. label Mar 11, 2026

ytmimi reviewed Mar 11, 2026

View reviewed changes

ytmimi requested changes Mar 12, 2026

View reviewed changes

rustbot added S-waiting-on-author Status: awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: awaiting review from the assignee but also interested parties. labels Mar 12, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contrib docs: note how to run a binary directly#6823

Contrib docs: note how to run a binary directly#6823
matthewhughes934 wants to merge 1 commit intorust-lang:mainfrom
matthewhughes934:document-running-binary-directly

matthewhughes934 commented Mar 11, 2026

Uh oh!

ytmimi Mar 11, 2026

Uh oh!

matthewhughes934 Mar 12, 2026

Uh oh!

ytmimi Mar 12, 2026

Uh oh!

ytmimi left a comment •

edited by rustbot

Loading

Uh oh!

ytmimi Mar 12, 2026

Uh oh!

ytmimi Mar 12, 2026

Uh oh!

ytmimi Mar 12, 2026

Uh oh!

ytmimi Mar 12, 2026

Uh oh!

ytmimi Mar 12, 2026

Uh oh!

rustbot commented Mar 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		$ ./target/debug/rustfmt
		./target/debug/rustfmt: error while loading shared libraries: librustc_driver-63b8deb6c23747dd.so: cannot open shared object file: No such file or directory

		$ export LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
		$ ./target/debug/rustfm


		Then, you can invoke a debugger like `rust-gdb`:

		LD_LIBRARY_PATH="$(rustc --print sysroot)/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" rust-gdb --args ./target/debug/rustfmt --check some_file.rs

Conversation

matthewhughes934 commented Mar 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ytmimi left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustbot commented Mar 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ytmimi left a comment •

edited by rustbot

Loading