Deprecated Eggsecutable Scripts

Closes: #1557

3 files changed, 9 insertions, 38 deletions

diff --git a/changelog.d/1557.change b/changelog.d/1557.change
new file mode 100644
index 00000000..77d2e3b4
--- /dev/null
+++ b/changelog.d/1557.change
@@ -0,0 +1 @@
+Deprecated eggsecutable scripts and removed related docs.
diff --git a/docs/setuptools.txt b/docs/setuptools.txt
index 64b385cb..f44813d1 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -569,43 +569,6 @@ on "entry points" in general, see the section below on `Dynamic Discovery of
 Services and Plugins`_.
 
 
-"Eggsecutable" Scripts
-----------------------
-
-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
 ======================
 
diff --git a/setuptools/command/bdist_egg.py b/setuptools/command/bdist_egg.py
index 9f8df917..ae44eaa2 100644
--- a/setuptools/command/bdist_egg.py
+++ b/setuptools/command/bdist_egg.py
@@ -11,13 +11,14 @@ import os
 import re
 import textwrap
 import marshal
+import warnings
 
 from setuptools.extern import six
 
 from pkg_resources import get_build_platform, Distribution, ensure_directory
 from pkg_resources import EntryPoint
 from setuptools.extension import Library
-from setuptools import Command
+from setuptools import Command, SetuptoolsDeprecationWarning
 
 try:
     # Python 2.7 or >=3.2
@@ -278,6 +279,12 @@ class bdist_egg(Command):
         if ep is None:
             return 'w'  # not an eggsecutable, do it the usual way.
 
+        warnings.warn(
+            "Eggsecutables are deprecated and will be removed in a future "
+            "version.",
+            SetuptoolsDeprecationWarning
+        )
+
         if not ep.attrs or ep.extras:
             raise DistutilsSetupError(
                 "eggsecutable entry point (%r) cannot have 'extras' "