| Dan Willemsen | adad21e | 2022-03-25 17:22:05 -0700 | [diff] [blame^] | 1 | "Eggsecutable" Scripts |
| 2 | ---------------------- |
| 3 | |
| 4 | .. deprecated:: 45.3.0 |
| 5 | |
| 6 | Occasionally, there are situations where it's desirable to make an ``.egg`` |
| 7 | file directly executable. You can do this by including an entry point such |
| 8 | as the following:: |
| 9 | |
| 10 | setup( |
| 11 | # other arguments here... |
| 12 | entry_points={ |
| 13 | "setuptools.installation": [ |
| 14 | "eggsecutable = my_package.some_module:main_func", |
| 15 | ] |
| 16 | } |
| 17 | ) |
| 18 | |
| 19 | Any eggs built from the above setup script will include a short executable |
| 20 | prelude that imports and calls ``main_func()`` from ``my_package.some_module``. |
| 21 | The prelude can be run on Unix-like platforms (including Mac and Linux) by |
| 22 | invoking the egg with ``/bin/sh``, or by enabling execute permissions on the |
| 23 | ``.egg`` file. For the executable prelude to run, the appropriate version of |
| 24 | Python must be available via the ``PATH`` environment variable, under its |
| 25 | "long" name. That is, if the egg is built for Python 2.3, there must be a |
| 26 | ``python2.3`` executable present in a directory on ``PATH``. |
| 27 | |
| 28 | IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or |
| 29 | invoked via symlinks. They *must* be invoked using their original filename, in |
| 30 | order to ensure that, once running, ``pkg_resources`` will know what project |
| 31 | and version is in use. The header script will check this and exit with an |
| 32 | error if the ``.egg`` file has been renamed or is invoked via a symlink that |
| 33 | changes its base name. |