b12f/nixpkgs
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Rephrase documentation for both makeWrapper implementations

Browse source
This commit is contained in:
Doron Behar 2021-12-09 16:02:02 +02:00
parent df13841609
commit c42e6741b2
1 changed files with 5 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
doc/stdenv/stdenv.chapter.md
View file

@ -774,7 +774,7 @@ The standard environment provides a number of useful functions.
### `makeWrapper` \<executable\> \<wrapperfile\> \<args\> {#fun-makeWrapper} ### `makeWrapper` \<executable\> \<wrapperfile\> \<args\> {#fun-makeWrapper}
Constructs a wrapper for a program with various possible arguments. It is defined as part of a setup-hook by the same name, so to use it you have to add `makeWrapper` to your `nativeBuildInputs`. Here's a usage example: Constructs a wrapper for a program with various possible arguments. It is defined as part of 2 setup-hooks named `makeWrapper` and `makeBinaryWrapper` that implement the same bash functions. Hence, to use it you have to add `makeWrapper` to your `nativeBuildInputs`. Here's an example usage:
```bash ```bash
# adds `FOOBAR=baz` to `$out/bin/foo`’s environment # adds `FOOBAR=baz` to `$out/bin/foo`’s environment
@ -786,17 +786,11 @@ makeWrapper $out/bin/foo $wrapperfile --set FOOBAR baz
makeWrapper $out/bin/foo $wrapperfile --prefix PATH : ${lib.makeBinPath [ hello git ]} makeWrapper $out/bin/foo $wrapperfile --prefix PATH : ${lib.makeBinPath [ hello git ]}
``` ```
There’s many more kinds of arguments, they are documented in `nixpkgs/pkgs/build-support/setup-hooks/make-wrapper.sh`. There’s many more kinds of arguments, they are documented in `nixpkgs/pkgs/build-support/setup-hooks/make-wrapper.sh` for the `makeWrapper` implementation and in `nixpkgs/pkgs/build-support/setup-hooks/make-binary-wrapper.sh` for the `makeBinaryWrapper` implementation.
`wrapProgram` is a convenience function you probably want to use most of the time. `wrapProgram` is a convenience function you probably want to use most of the time, implemented by both `makeWrapper` and `makeBinaryWrapper`.
### `makeBinaryWrapper` \<executable\> \<wrapperfile\> \<args\> {#fun-makeBinaryWrapper} Using the `makeBinaryWrapper` implementation is usually preferred, as it creates a tiny _compiled_ wrapper executable, that can be used as a shebang interpreter. This is needed mostly on Darwin, where shebangs cannot point to scripts, [due to a limitation with the `execve`-syscall](https://stackoverflow.com/questions/67100831/macos-shebang-with-absolute-path-not-working). Compiled wrappers generated by `makeBinaryWrapper` can be inspected with `less <path-to-wrapper>` - by scrolling past the binary data you should be able to see the shell command that generated the executable and there see the environment variables that were injected into the wrapper.
A setup-hook very similar to `makeWrapper`, only it creates a tiny _compiled_ wrapper executable, that can be used as a shebang interpreter. This is needed mostly on Darwin, where shebangs cannot point to scripts, [due to a limitation with the `execve`-syscall](https://stackoverflow.com/questions/67100831/macos-shebang-with-absolute-path-not-working). The arguments it accepts are similar to those of `makeWrapper` and they are documented in `nixpkgs/pkgs/build-support/setup-hooks/make-binary-wrapper.sh`.
Compiled wrappers generated by `makeBinaryWrapper` can be inspected with `less <path-to-wrapper>` - by scrolling past the binary data you should be able to see the C code that generated the executable and there see the environment variables that were injected into the wrapper.
Similarly to `wrapProgram`, the `makeBinaryWrapper` setup-hook provides a `binaryWrapProgram` with similar command line arguments.
### `substitute` \<infile\> \<outfile\> \<subs\> {#fun-substitute} ### `substitute` \<infile\> \<outfile\> \<subs\> {#fun-substitute}
@ -871,13 +865,7 @@ someVar=$(stripHash $name)
### `wrapProgram` \<executable\> \<makeWrapperArgs\> {#fun-wrapProgram} ### `wrapProgram` \<executable\> \<makeWrapperArgs\> {#fun-wrapProgram}
Convenience function for `makeWrapper` that replaces `<\executable\>` with a wrapper that executes the original program. It takes all the same arguments as `makeWrapper`, except for `--argv0`. Convenience function for `makeWrapper` that replaces `<\executable\>` with a wrapper that executes the original program. It takes all the same arguments as `makeWrapper`, except for `--inherit-argv0` (used by the `makeBinaryWrapper` implementation and `--argv0` (used by both `makeWrapper` and `makeBinaryWrapper` wrapper implementations).
If you will apply it multiple times, it will overwrite the wrapper file and you will end up with double wrapping, which should be avoided.
### `binaryWrapProgram` \<executable\> \<makeBinaryWrapperArgs\> {#fun-binaryWrapProgram}
Convenience function for `makeBinaryWrapper` that replaces `<\executable\>` with a wrapper that executes the original program. It takes all the same arguments as `makeBinaryWrapper`, except for `--argv0`.
If you will apply it multiple times, it will overwrite the wrapper file and you will end up with double wrapping, which should be avoided. If you will apply it multiple times, it will overwrite the wrapper file and you will end up with double wrapping, which should be avoided.