Found solution for "pip/scons error: option –single-version-externally-managed not recognized" // Resolve #279

HISTORY.rst

@@ -8,6 +8,9 @@ PlatformIO 2.0
 ~~~~~~~~~~~~~~~~~~
 
 * Allowed to use ST-Link uploader for mbed-based projects
+* Found solution for "pip/scons error: option --single-version-externally-managed not
+  recognized" when install PlatformIO using ``pip`` package manager
+  (`issue #279 <https://github.com/platformio/platformio/issues/279>`_)
 * Fixed `SConsNotInstalled` error for Linux Debian-based distributives
 
 2.3.1 (2015-09-06)

docs/faq.rst

@@ -75,6 +75,27 @@ There are a few options:
 - masking under Continuous Integration system via environment variable
   :envvar:`CI=true <CI>`.
 
+PlatformIO and ``scons`` aren't installed properly
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Try these solutions:
+
+1. Upgrade SCons via `pip <https://pip.pypa.io>`_
+
+.. code-block:: bash
+
+    [sudo] pip uninstall scons
+    [sudo] pip install scons
+
+2. Install PlatformIO using :ref:`installation_installer_script`.
+
+.. _faq_troubleshooting_sconssingverextmanaged:
+
+PIP & SCons Error: option --single-version-externally-managed not recognized
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Answered in `issue #279 <https://github.com/platformio/platformio/issues/279>`_.
+
 .. _faq_troubleshooting_pionotfoundinpath:
 
 Program ``platformio`` not found in PATH
@@ -100,8 +121,8 @@ should contain ``/usr/local/bin`` directory.
 programs to the ``bin`` directory which is included in ``$PATH``. For example,
 see `issue #272 <https://github.com/platformio/platformio/issues/272#issuecomment-133626112>`_.
 
-Windows: ``UnicodeDecodeError: 'ascii' codec can't decode byte``
+Windows UnicodeDecodeError: 'ascii' codec can't decode byte
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Answered in `issue #143 <https://github.com/platformio/platformio/issues/143#issuecomment-88060906>`_.
 
@@ -118,20 +139,20 @@ Please upgrade *SetupTools* package:
 
 .. code-block:: bash
 
-    $ [sudo] pip uninstall setuptools
+    [sudo] pip uninstall setuptools
-    $ [sudo] pip install setuptools
+    [sudo] pip install setuptools
 
     # Then re-install PlatformIO
-    $ [sudo] pip uninstall platformio
+    [sudo] pip uninstall platformio
-    $ [sudo] pip install platformio
+    [sudo] pip install platformio
 
-Windows: ``AttributeError: 'module' object has no attribute 'packages'``
+Windows AttributeError: 'module' object has no attribute 'packages'
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Answered in `issue #252 <https://github.com/platformio/platformio/issues/252#issuecomment-127072039>`_.
 
-ARM toolchain: ``cc1plus: error while loading shared libraries``
+ARM toolchain: cc1plus: error while loading shared libraries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 See related answers for
 `error while loading shared libraries <https://github.com/platformio/platformio/issues?utf8=✓&q=error+while+loading+shared+libraries>`_.

docs/installation.rst

@@ -47,11 +47,14 @@ The latest stable version of PlatformIO may be done via
 .. code-block:: bash
 
     # update dependent packages to the latest versions
-    pip install -U pip setuptools virtualenv
+    pip install -U pip setuptools
 
-    # install the latest version of PlatformIO
+    # install/upgrade the latest version of PlatformIO
     pip install -U platformio
 
+.. warning::
+    Known Issue: :ref:`faq_troubleshooting_sconssingverextmanaged`
+
 Note that you may run into permissions issues running these commands. You have
 a few options here:
 
@@ -61,6 +64,8 @@ a few options here:
 * Run the command in a `virtualenv <https://virtualenv.pypa.io>`_ local to a
   specific project working set.
 
+.. _installation_installer_script:
+
 Installer Script
 ~~~~~~~~~~~~~~~~
 
@@ -134,9 +139,6 @@ For upgrading ``platformio`` to the latest version:
 Development Version
 ~~~~~~~~~~~~~~~~~~~
 
-.. warning::
-    We don't recommend to use ``develop`` version in production.
-
 Install the latest PlatformIO from the ``develop`` branch:
 
 .. code-block:: bash
@@ -163,4 +165,5 @@ Troubleshooting
     **Windows OS**: Please check that you have correctly installed USB driver
     from board manufacturer
 
-For further details, frequently questions, please refer to :ref:`faq`.
+For further details, frequently questions, known issues, please
+refer to :ref:`faq`.

platformio/commands/upgrade.py

@@ -21,7 +21,7 @@ def cli():
                     fg="yellow")
 
         cmds = (
-            ["pip", "install", "--upgrade", "pip", "setuptools", "virtualenv"],
+            ["pip", "install", "--upgrade", "pip", "setuptools"],
             ["pip", "install", "--upgrade", "platformio"],
             ["platformio", "--version"]
         )
@@ -42,7 +42,7 @@ def cli():
                         fg="cyan")
         except (OSError, AssertionError) as e:
             if not r:
-                raise exception.PlatformioException(
+                raise exception.PlatformioUpgradeError(
                     "\n".join([str(cmd), str(e)]))
             if ("Permission denied" in r['err'] and
                     "windows" not in util.get_systype()):
@@ -58,7 +58,7 @@ WARNING! Don't use `sudo` for the rest PlatformIO commands.
 """, fg="yellow", err=True)
                 raise exception.ReturnErrorCode()
             else:
-                raise exception.PlatformioException(
+                raise exception.PlatformioUpgradeError(
                     "\n".join([str(cmd), r['out'], r['err']]))
 
 

platformio/exception.py

@@ -182,6 +182,17 @@ class SConsNotInstalled(PlatformioException):
 
     MESSAGE = (
         "The PlatformIO and `scons` aren't installed properly. "
-        "Please use official installation manual: "
+        "More details in FAQ/Troubleshooting section: "
+        "http://docs.platformio.org/en/latest/faq.html"
+    )
+
+
+class PlatformioUpgradeError(PlatformioException):
+
+    MESSAGE = (
+        "%s \n\n"
+        "1. Please report this issue here: "
+        "https://github.com/platformio/platformio/issues \n"
+        "2. Try different installation/upgrading steps: "
         "http://docs.platformio.org/en/latest/installation.html"
     )