docs: mention shebang rewrite in the formula cookbook #11244
Conversation
|
Review period will end on 2021-04-27 at 00:00:00 UTC. |
BrewTestBot
added
the
waiting for feedback
Co-authored-by: Rylan Polster <rslpolster@gmail.com>
docs/Formula-Cookbook.md
Outdated
| @@ -750,6 +750,10 @@ ln_s libexec/"name", bin | |||
|
|
|||
| The symlinks created by [`install_symlink`](https://rubydoc.brew.sh/Pathname#install_symlink-instance_method) are guaranteed to be relative. `ln_s` will only produce a relative symlink when given a relative path. | |||
|
|
|||
| ### Rewriting a script shebang | |||
|
|
|||
| In some cases, the formula goal is to install a script written in an interpreted language, such as Python or Perl, to be used as an executable. Homebrew provides a `rewrite_shebang` method to rewrite the shebang of a script to point to the correct interpreter path. For example, the [`icdiff` formula](https://github.com/Homebrew/homebrew-core/blob/7beae5ab57c65249403699b2b0700fbccf14e6cb/Formula/icdiff.rb#L16) uses such utility. | |||
There was a problem hiding this comment.
It might be worth adding a mention of what it's rewritten from/to/why?
There was a problem hiding this comment.
I committed some changes to cover this.
BrewTestBot
removed
the
waiting for feedback
|
Review period ended. |
|
@carlocab : I was debating between describing the different parts needed to use the utility or if pointing to an example was enough. |
|
I think pointing to the example is mostly enough, just that I suspect many readers will miss the |
|
👍 I added a sentence to cover this. |
Co-authored-by: Carlo Cabrera <30379873+carlocab@users.noreply.github.com>
docs/Formula-Cookbook.md
Outdated
| @@ -750,6 +750,12 @@ ln_s libexec/"name", bin | |||
|
|
|||
| The symlinks created by [`install_symlink`](https://rubydoc.brew.sh/Pathname#install_symlink-instance_method) are guaranteed to be relative. `ln_s` will only produce a relative symlink when given a relative path. | |||
|
|
|||
| ### Rewriting a script shebang | |||
|
|
|||
| Some formulae install executable scripts written in an interpreted language such as Python or Perl. Homebrew provides a `rewrite_shebang` method to rewrite the shebang of a script. This replaces a script's original interpreter path with the one installed by Homebrew and guarantees that the correct interpreter is used at execution time. | |||
There was a problem hiding this comment.
This replaces a script's original interpreter path with the one installed by Homebrew
I'm not sure this is correct? It depends on the relevant OS, I think? CC @Bo98
There was a problem hiding this comment.
Ah, yes. It's not entirely accurate. I think it depends on the dependencies a formula declares.
There was a problem hiding this comment.
For Python it's right since we don't allow system Python. For Perl, it is indeed not correct as if uses_from_macos "perl" is used then it will use system Perl as the shebang on macOS.
It's perhaps also worth clarifying that rewrite_shebang is only needed where build system doesn't already do it (it's not needed under many pip and ExtUtils::MakeMaker cases).
Moisan
dismissed stale reviews from Rylan12, carlocab, and BrewTestBot
via
665b864
Co-authored-by: Rylan Polster <rslpolster@gmail.com>
|
Thanks @Moisan! |
brew stylewith your changes locally?brew typecheckwith your changes locally?brew testswith your changes locally?I was recently working on a formula involving the use of
rewrite_shebangand I noticed there was no mention of it in the documentation. This is a very simple paragraph about it, I am open to go into more detail if needed.