From b62d07c2b2ca80256b94e0df32ecdb93e98ac258 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Thu, 16 May 2019 14:27:30 +0200 Subject: Put deprecation in section rather then removing it (updated changelog as well) --- docs/setuptools.txt | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'docs') diff --git a/docs/setuptools.txt b/docs/setuptools.txt index f44813d1..e4e56fb0 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -569,6 +569,45 @@ on "entry points" in general, see the section below on `Dynamic Discovery of Services and Plugins`_. +"Eggsecutable" Scripts +---------------------- + +.. warning:: Eggsecutable Scripts are deprecated. + +Occasionally, there are situations where it's desirable to make an ``.egg`` +file directly executable. You can do this by including an entry point such +as the following:: + + setup( + # other arguments here... + entry_points={ + 'setuptools.installation': [ + 'eggsecutable = my_package.some_module:main_func', + ] + } + ) + +Any eggs built from the above setup script will include a short executable +prelude that imports and calls ``main_func()`` from ``my_package.some_module``. +The prelude can be run on Unix-like platforms (including Mac and Linux) by +invoking the egg with ``/bin/sh``, or by enabling execute permissions on the +``.egg`` file. For the executable prelude to run, the appropriate version of +Python must be available via the ``PATH`` environment variable, under its +"long" name. That is, if the egg is built for Python 2.3, there must be a +``python2.3`` executable present in a directory on ``PATH``. + +This feature is primarily intended to support ez_setup the installation of +setuptools itself on non-Windows platforms, but may also be useful for other +projects as well. + +IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or +invoked via symlinks. They *must* be invoked using their original filename, in +order to ensure that, once running, ``pkg_resources`` will know what project +and version is in use. The header script will check this and exit with an +error if the ``.egg`` file has been renamed or is invoked via a symlink that +changes its base name. + + Declaring Dependencies ====================== -- cgit v1.2.3