paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-05 14:35:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

py3: Revise and update shebang discussion in docs/shell-tips.

Browse Source 
This keeps the examples in line with our actual codebase.

Also while I'm here revise it to explain the actual motivation for our
use of `env`, and to correct some subtle details -- it's actually the
kernel that interprets the shebang (as visible in e.g. a `strace` log),
not the shell, and when the program is executed as `./my_program.py`
the exact name including `./` is passed to the interpreter.
This commit is contained in:
Greg Price
2017-08-02 14:17:39 -07:00
committed by Tim Abbott
parent 33430f83eb
commit 78b41f375d
1 changed files with 30 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/shell-tips.md
View File

@@ -260,8 +260,8 @@ all the arguments for every single command. There are
You can run some files directly, without specifying a program to interpret You can run some files directly, without specifying a program to interpret
them. them.
That's why you may have seen cases when some Python scripts are called with That's why you may have seen cases, in the Zulip codebase or
`python`: elsewhere, when some Python scripts are called with `python`:
``` ```
$ python my_program.py $ python my_program.py
@@ -273,35 +273,44 @@ While other times, `python` isn't used:
$ ./my_program.py $ ./my_program.py
``` ```
In the latter, it's skipped because `my_program.py` already specifies in it In the latter case, the operating system will look at the beginning of
which interpreter should be used (in this case, `python`). the script to identify what interpreter (like `python` in this
example) to run it with.
This is indicated in the very first line of the script files, and it's called The note telling the OS how to interpret the file goes on the file's
a **shebang**. In Python scripts, it looks like this: very first line, and it's called a **shebang**. In our Python scripts,
it looks like this:
``` ```
#!/usr/bin/env python #!/usr/bin/env python3
``` ```
With this, you're telling the shell: "if I tell you to run this, ask With this, you're telling the operating system: "if I tell you to run
`/usr/bin/env python` how to understand it". this, ask `/usr/bin/env python3` how to understand it".
`/usr/bin/env` is a way to identify where `python` is installed. If it was in The result is that the operating system is asked to run the script, it
`/usr/bin/python`, you could use the shebang `#!/usr/bin/python`, but `env` runs the command specified in the shebang, with the script filename
allows more flexibility (since not everyone has their Python interpreter added as a command-line argument. So, returning to our example with
there). `my_program.py`, when you run `./my_program.py`, what happens under
the hood is equivalent to:
Another example of shebang is the one used in Bash scripts. In those cases,
`#!/bin/sh` is used.
The result is that the shell calls the program specified in the shebang, with
the script as a parameter. So, returning to our example with `my_program.py`,
when you run `./my_program.py`, what happens under the hood is:
``` ```
$ /usr/bin/env python my_program.py $ /usr/bin/env python3 ./my_program.py
``` ```
The purpose of `/usr/bin/env` in our shebangs is as a way to locate
the `python3` program in your current environment, the same one the
shell would use if you ran `python3 my_program.py`. You may see
Python scripts outside of Zulip with a shebang like
`#!/usr/bin/python3`; but because of the way Python virtualenvs work,
this has the effect of running the script outside of any currently
activated virtualenv. We use `/usr/bin/env` to keep our scripts
running inside the virtualenv where we've installed all our
dependencies.
Another example of a shebang is the one used in Bash scripts. In those
cases, `#!/bin/bash` or `#!/bin/sh` is used.
## Understanding commands ## Understanding commands
Frequently, you may find commands that you don't understand, or don't Frequently, you may find commands that you don't understand, or don't