1"Eggsecutable" Scripts
2----------------------
3
4.. deprecated:: 45.3.0
5
6Occasionally, there are situations where it's desirable to make an ``.egg``
7file directly executable.  You can do this by including an entry point such
8as 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
19Any eggs built from the above setup script will include a short executable
20prelude that imports and calls ``main_func()`` from ``my_package.some_module``.
21The prelude can be run on Unix-like platforms (including Mac and Linux) by
22invoking 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
24Python 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
28IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or
29invoked via symlinks.  They *must* be invoked using their original filename, in
30order to ensure that, once running, ``pkg_resources`` will know what project
31and version is in use.  The header script will check this and exit with an
32error if the ``.egg`` file has been renamed or is invoked via a symlink that
33changes its base name.
34