Implemented PLATFORMIO_* environment variables

HISTORY.rst

@@ -1,12 +1,17 @@
 Release History
 ===============
 
-1.0.2 (2015-03-??)
+1.1.0 (2015-03-??)
 ------------------
 
+* Implemented ``PLATFORMIO_*`` environment variables
+  (`issue #102 <https://github.com/ivankravets/platformio/issues/102>`_)
 * Added support for *SainSmart* boards to
   `atmelsam <http://docs.platformio.org/en/latest/platforms/atmelsam.html#boards>`__
   development platform
+* Added
+  `Project Configuration <http://docs.platformio.org/en/latest/projectconf.html>`__
+  option named `envs_dir <http://docs.platformio.org/en/latest/projectconf.html#envs-dir>`__
 * Fixed firmware uploading for
   `atmelavr <http://docs.platformio.org/en/latest/platforms/atmelavr.html#boards>`__
   boards which work within ``usbtiny`` protocol
@@ -230,7 +235,7 @@ Release History
   `srcbuild_flags <http://docs.platformio.org/en/latest/projectconf.html#srcbuild-flags>`_
   environment option
 * Allowed to override some of settings via system environment variables
-  such as: ``$PIOSRCBUILD_FLAGS`` and ``$PIOENVS_DIR``
+  such as: ``PLATFORMIO_SRCBUILD_FLAGS`` and ``PLATFORMIO_ENVS_DIR``
 * Added ``--upload-port`` option for `platformio run <http://docs.platformio.org/en/latest/userguide/cmd_run.html#cmdoption--upload-port>`__ command
 * Implemented (especially for `SmartAnthill <http://docs.smartanthill.ikravets.com/>`_)
   `platformio run -t uploadlazy <http://docs.platformio.org/en/latest/userguide/cmd_run.html>`_

docs/envvars.rst

@@ -0,0 +1,107 @@
+.. _envvars:
+
+Environment variables
+=====================
+
+`Environment variables <http://en.wikipedia.org/wiki/Environment_variable>`_
+are a set of dynamic named values that can affect the way running processes
+will behave on a computer.
+
+*PlatformIO* handles variables which start with ``PLATFORMIO_`` prefix. They
+have the **HIGHEST PRIORITY**.
+
+.. contents::
+
+General
+-------
+
+PlatformIO uses *General* environment variables for the common
+operations/commands.
+
+.. _envvar_PLATFORMIO_HOME_DIR:
+
+PLATFORMIO_HOME_DIR
+~~~~~~~~~~~~~~~~~~~
+
+Allows to override :ref:`projectconf` option
+:ref:`projectconf_pio_home_dir`.
+
+.. _envvar_PLATFORMIO_LIB_DIR:
+
+PLATFORMIO_LIB_DIR
+~~~~~~~~~~~~~~~~~~
+
+Allows to override :ref:`projectconf` option
+:ref:`projectconf_pio_lib_dir`.
+
+.. _envvar_PLATFORMIO_SRC_DIR:
+
+PLATFORMIO_SRC_DIR
+~~~~~~~~~~~~~~~~~~
+
+Allows to override :ref:`projectconf` option
+:ref:`projectconf_pio_src_dir`.
+
+.. _envvar_PLATFORMIO_ENVS_DIR:
+
+PLATFORMIO_ENVS_DIR
+~~~~~~~~~~~~~~~~~~~
+
+Allows to override :ref:`projectconf` option
+:ref:`projectconf_pio_envs_dir`.
+
+
+Builder
+-------
+
+.. _envvar_PLATFORMIO_SRCBUILD_FLAGS:
+
+PLATFORMIO_SRCBUILD_FLAGS
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows to override :ref:`projectconf` option
+:ref:`projectconf_srcbuild_flags`.
+
+Settings
+--------
+
+Allows to override PlatformIO settings. You can manage them via
+:ref:`cmd_settings` command.
+
+
+PLATFORMIO_SETTING_AUTO_UPDATE_LIBRARIES
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows to override setting :option:`auto_update_libraries`.
+
+PLATFORMIO_SETTING_AUTO_UPDATE_PLATFORMS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows to override setting :option:`auto_update_platforms`.
+
+PLATFORMIO_SETTING_CHECK_LIBRARIES_INTERVAL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows to override setting :option:`check_libraries_interval`.
+
+PLATFORMIO_SETTING_CHECK_PLATFORMIO_INTERVAL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows to override setting :option:`check_platformio_interval`.
+
+PLATFORMIO_SETTING_CHECK_PLATFORMS_INTERVAL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows to override setting :option:`check_platforms_interval`.
+
+.. _envvar_PLATFORMIO_SETTING_ENABLE_PROMPTS:
+
+PLATFORMIO_SETTING_ENABLE_PROMPTS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows to override setting :option:`enable_prompts`.
+
+PLATFORMIO_SETTING_ENABLE_TELEMETRY
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows to override setting :option:`enable_telemetry`.

docs/index.rst

@@ -57,6 +57,7 @@ Contents
     quickstart
     installation
     projectconf
+    envvars
     platforms/index
     librarymanager/index
     userguide/index

docs/installation.rst

@@ -30,9 +30,13 @@ application:
   application.
 
 .. warning::
-    If you are going to use *PlatformIO* for "*Cloud Compiling*", please
+    If you are going to run *PlatformIO* from **subprocess**, you **MUST
-    don't forget to turn off :ref:`enable_prompts <cmd_settings>` setting. It
+    DISABLE** all prompts. It will allow you to avoid blocking.
-    will allow you to avoid blocking when call ``platformio`` like subprocess.
+    There are 2 options:
+
+    - using environment variable :ref:`PLATFORMIO_SETTING_ENABLE_PROMPTS=false <envvar_PLATFORMIO_SETTING_ENABLE_PROMPTS>`
+    - disable global setting via :ref:`platformio setting enable_prompts false <cmd_settings>`
+      command.
 
 Please *choose one of* the following:
 

docs/projectconf.rst

@@ -1,7 +1,7 @@
 .. _projectconf:
 
-Project Configuration File
+Project Configuration File ``platformio.ini``
-==========================
+=============================================
 
 The Project configuration file is named ``platformio.ini``. This is a
 `INI-style <http://en.wikipedia.org/wiki/INI_file>`_ file.
@@ -33,11 +33,18 @@ Options
 ``home_dir``
 ^^^^^^^^^^^^
 
-A ``$PIO_HOME_DIR`` is used to store platform tool chains, frameworks,
+Is used to store platform tool chains, frameworks, external libraries,
-external libraries, service data and etc.
+service data and etc.
 
-A default value is user's home directory: *Unix* - ``~/.platformio``,
+A default value is User's home directory:
-Windows - ``%HOMEPATH%\.platformio``.
+
+* Unix ``~/.platformio``
+* Windows ``%HOMEPATH%\.platformio``
+
+This option can be overridden by global environment variable
+:ref:`envvar_PLATFORMIO_HOME_DIR`.
+
+.. _projectconf_pio_lib_dir:
 
 ``lib_dir``
 ^^^^^^^^^^^
@@ -45,21 +52,53 @@ Windows - ``%HOMEPATH%\.platformio``.
 This directory is used to store external libraries downloaded by
 :ref:`librarymanager`.
 
-A default value is ``$PIO_HOME_DIR/lib``.
+A default value is ``%home_dir%/lib``.
+
+This option can be overridden by global environment variable
+:ref:`envvar_PLATFORMIO_LIB_DIR`.
+
+.. _projectconf_pio_src_dir:
 
 ``src_dir``
 ^^^^^^^^^^^
 
-The path to project's source directory. PlatformIO uses it for :ref:`cmd_run`
+A path to project's source directory. PlatformIO uses it for :ref:`cmd_run`
 command.
 
-A default value is ``$PROJECT_DIR/src``.
+A default value is ``%project_dir%/src``.
+
+This option can be overridden by global environment variable
+:ref:`envvar_PLATFORMIO_SRC_DIR`.
 
 .. note::
     This option is useful for people who migrate from Arduino/Energia IDEs where
     source directory should have the same name like the main source file.
     See `example <https://github.com/ivankravets/platformio/tree/develop/examples/atmelavr-and-arduino/arduino-own-src_dir>`__ project with own source directory.
 
+.. _projectconf_pio_envs_dir:
+
+``envs_dir``
+^^^^^^^^^^^^
+
+*PlatformIO Builder* within :ref:`cmd_run` command uses this folder for project
+environments to store compiled object files, static libraries, firmwares and
+other cached information. It allows PlatformIO to build source code extremely
+fast!
+
+*You can delete this folder without any risk!* If you modify :ref:`projectconf`,
+then PlatformIO will remove this folder automatically. It will be created on the
+next build operation.
+
+A default value is ``%project_dir%/.pioenvs``.
+
+This option can be overridden by global environment variable
+:ref:`envvar_PLATFORMIO_ENVS_DIR`.
+
+.. note::
+    If you have any problems with building your Project environmets which
+    are defined in :ref:`projectconf`, then **TRY TO DELETE** this folder. In
+    this situation you will remove all cached files without any risk.
+
 [env:NAME]
 ----------
 
@@ -99,7 +138,7 @@ See ``framework`` type in *Frameworks* section of :ref:`platforms`
 ``board``
 ^^^^^^^^^
 
-*PlatformIO* has pre-configured settings for most popular boards. You don't
+*PlatformIO* has pre-configured settings for the most popular boards. You don't
 need to specify ``board_mcu``, ``board_f_cpu``, ``upload_protocol`` or
 ``upload_speed`` options. Just define a ``board`` type and *PlatformIO* will
 pre-fill options described above with appropriate values.
@@ -115,8 +154,8 @@ recognize MCU architecture. The correct type of ``board_mcu`` depends on
 platform library. For example, the list of ``board_mcu`` for "megaAVR Devices"
 is described `here <http://www.nongnu.org/avr-libc/user-manual/>`_.
 
-The full list of ``board_mcu`` for popular embedded platforms you can find in
+The full list of ``board_mcu`` for the popular embedded platforms you can find
-*Boards* section of :ref:`platforms`. See "Microcontroller" column.
+in *Boards* section of :ref:`platforms`. See "Microcontroller" column.
 
 
 ``board_f_cpu``
@@ -126,21 +165,21 @@ An option ``board_f_cpu`` is used to define MCU frequency (Hertz, Clock). A
 format of this option is ``C-like long integer`` value with ``L`` suffix. The
 1 Hertz is equal to ``1L``, then 16 Mhz (Mega Hertz) is equal to ``16000000L``.
 
-The full list of ``board_f_cpu`` for popular embedded platforms you can find in
+The full list of ``board_f_cpu`` for the popular embedded platforms you can
-*Boards* section of :ref:`platforms`. See "Frequency" column.
+find in *Boards* section of :ref:`platforms`. See "Frequency" column.
 
 
 ``upload_port``
 ^^^^^^^^^^^^^^^
 
-This option is used by "uploader" tool to send firmware to the board via
+This option is used by "uploader" tool when sending firmware to board via
 ``upload_port``. For example,
 
 * ``/dev/ttyUSB0`` - Unix-based OS
 * ``COM3`` - Windows OS
 
-If ``upload_port`` isn't specified, then *PlatformIO* will try to detect
+If ``upload_port`` isn't specified, then *PlatformIO* will try to detect it
-``upload_port`` automatically.
+automatically.
 
 To print all available serial ports use :ref:`cmd_serialports` command.
 
@@ -155,7 +194,7 @@ A protocol that "uploader" tool uses to talk to the board.
 ^^^^^^^^^^^^^^^^
 
 A connection speed (`baud rate <http://en.wikipedia.org/wiki/Baud>`_)
-which "uploader" tool uses when sending firmware to the board.
+which "uploader" tool uses when sending firmware to board.
 
 
 ``targets``
@@ -256,12 +295,17 @@ For more detailed information about available flags/options go to:
 * `Options for Directory Search
   <https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html>`_
 
+.. _projectconf_srcbuild_flags:
 
 ``srcbuild_flags``
 ^^^^^^^^^^^^^^^^^^
 
-This is option ``srcbuild_flags`` has the same behaviour like ``build_flags``
+An option ``srcbuild_flags`` has the same behaviour like ``build_flags``
-but will be applied only for project source code from ``src`` directory.
+but will be applied only for the project source code from
+:ref:`projectconf_pio_src_dir` directory.
+
+This option can be overridden by global environment variable
+:ref:`envvar_PLATFORMIO_SRCBUILD_FLAGS`.
 
 ``ignore_libs``
 ^^^^^^^^^^^^^^^
@@ -281,6 +325,10 @@ Example:
 Examples
 --------
 
+.. note::
+    A full list with project examples can be found in
+    `PlatformIO Repository <https://github.com/ivankravets/platformio/tree/develop/examples>`_.
+
 1. :ref:`platform_atmelavr`: Arduino UNO board with auto pre-configured
    ``board_*`` and ``upload_*`` options (use only ``board`` option) and Arduino
    Wiring-based Framework

docs/quickstart.rst

@@ -58,8 +58,7 @@ Change working directory to the project's root where is located
 If you don't have installed required platforms, then *PlatformIO* will propose
 you to install them automatically.
 
-Further examples can be found in the ``examples/`` directory in the source
+Further examples can be found in `PlatformIO Repository <https://github.com/ivankravets/platformio/tree/develop/examples>`_.
-distribution or `on the web <https://github.com/ivankravets/platformio/tree/develop/examples>`_.
 
 Also, for more detailed information as for commands please go to
 :ref:`userguide` sections.

docs/userguide/cmd_settings.rst

@@ -23,6 +23,70 @@ Description
 
 Get/List existing settings
 
+Options
+~~~~~~~
+
+.. option:: auto_update_libraries
+
+:Default:   Yes
+:Values:    Yes/No
+
+Automatically update libraries.
+
+.. option:: auto_update_platforms
+
+:Default:   Yes
+:Values:    Yes/No
+
+Automatically update platforms.
+
+.. option:: check_libraries_interval
+
+:Default:   7
+:Values:    Days (Number)
+
+Check for the library updates interval.
+
+.. option:: check_platformio_interval
+
+:Default:   3
+:Values:    Days (Number)
+
+Check for the new PlatformIO interval.
+
+.. option:: check_platforms_interval
+
+:Default:   7
+:Values:    Days (Number)
+
+Check for the platform updates interval.
+
+.. option:: enable_prompts
+
+:Default:   Yes
+:Values:    Yes/No
+
+Can PlatformIO communicate with you via prompts?
+
+* propose to install platforms which aren't installed yet
+* paginate over library search results
+* and etc.
+
+.. warning::
+    If you are going to run *PlatformIO* from **subprocess**, you **MUST
+    DISABLE** all prompts. It will allow you to avoid blocking.
+
+.. option:: enable_telemetry
+
+:Default:   Yes
+:Values:    Yes/No
+
+Shares commands, platforms and libraries usage to help us make PlatformIO
+better.
+
+
+.. note::
+    You can override these settings using :ref:`envvars`.
 
 Examples
 ~~~~~~~~

platformio/__init__.py

@@ -1,7 +1,7 @@
 # Copyright (C) Ivan Kravets <me@ikravets.com>
 # See LICENSE for details.
 
-VERSION = (1, 0, "2.dev0")
+VERSION = (1, 1, "0.dev0")
 __version__ = ".".join([str(s) for s in VERSION])
 
 __title__ = "platformio"

platformio/app.py

@@ -2,6 +2,7 @@
 # See LICENSE for details.
 
 import json
+from os import environ, getenv
 from os.path import isfile, join
 
 from platformio import __version__
@@ -71,6 +72,24 @@ class State(object):
                 json.dump(self._state, fp)
 
 
+def sanitize_setting(name, value):
+    if name not in DEFAULT_SETTINGS:
+        raise InvalidSettingName(name)
+
+    defdata = DEFAULT_SETTINGS[name]
+    try:
+        if "validator" in defdata:
+            value = defdata['validator']()
+        elif isinstance(defdata['value'], bool):
+            if not isinstance(value, bool):
+                value = str(value).lower() in ("true", "yes", "y", "1")
+        elif isinstance(defdata['value'], int):
+            value = int(value)
+    except Exception:
+        raise InvalidSettingValue(value, name)
+    return value
+
+
 def get_state_item(name, default=None):
     with State() as data:
         return data.get(name, default)
@@ -82,8 +101,9 @@ def set_state_item(name, value):
 
 
 def get_setting(name):
-    if name not in DEFAULT_SETTINGS:
+    _env_name = "PLATFORMIO_SETTING_%s" % name.upper()
-        raise InvalidSettingName(name)
+    if _env_name in environ:
+        return sanitize_setting(name, getenv(_env_name))
 
     with State() as data:
         if "settings" in data and name in data['settings']:
@@ -93,25 +113,10 @@ def get_setting(name):
 
 
 def set_setting(name, value):
-    if name not in DEFAULT_SETTINGS:
-        raise InvalidSettingName(name)
-
-    defdata = DEFAULT_SETTINGS[name]
-    try:
-        if "validator" in defdata:
-            value = defdata['validator']()
-        elif isinstance(defdata['value'], bool):
-            if not isinstance(value, bool):
-                value = str(value).lower() in ("yes", "y", "1")
-        elif isinstance(defdata['value'], int):
-            value = int(value)
-    except Exception:
-        raise InvalidSettingValue(value, name)
-
     with State() as data:
         if "settings" not in data:
             data['settings'] = {}
-        data['settings'][name] = value
+        data['settings'][name] = sanitize_setting(name, value)
 
 
 def reset_settings():

platformio/builder/tools/platformio.py

@@ -59,7 +59,7 @@ def BuildFirmware(env, corelibs):
         _LIBFLAGS=" -Wl,--end-group"
     )
 
-    firmenv.MergeFlags(getenv("PIOSRCBUILD_FLAGS", "$SRCBUILD_FLAGS"))
+    firmenv.MergeFlags(getenv("PLATFORMIO_SRCBUILD_FLAGS", "$SRCBUILD_FLAGS"))
 
     return firmenv.Program(
         join("$BUILD_DIR", "firmware"),

platformio/util.py

@@ -56,25 +56,29 @@ def get_systype():
     return ("%s_%s" % (data[0], data[4])).lower()
 
 
-def _get_projconf_option_dir(option_name):
+def _get_projconf_option_dir(name, default=None):
+    _env_name = "PLATFORMIO_%s" % name.upper()
+    if _env_name in os.environ:
+        return os.getenv(_env_name)
+
     try:
         config = get_project_config()
         if (config.has_section("platformio") and
-                config.has_option("platformio", option_name)):
+                config.has_option("platformio", name)):
-            option_dir = config.get("platformio", option_name)
+            option_dir = config.get("platformio", name)
             if option_dir.startswith("~"):
                 option_dir = expanduser(option_dir)
             return abspath(option_dir)
     except exception.NotPlatformProject:
         pass
-    return None
+    return default
 
 
 def get_home_dir():
-    home_dir = _get_projconf_option_dir("home_dir")
+    home_dir = _get_projconf_option_dir(
-
+        "home_dir",
-    if not home_dir:
+        join(expanduser("~"), ".platformio")
-        home_dir = join(expanduser("~"), ".platformio")
+    )
 
     if not isdir(home_dir):
         os.makedirs(home_dir)
@@ -84,12 +88,10 @@ def get_home_dir():
 
 
 def get_lib_dir():
-    lib_dir = _get_projconf_option_dir("lib_dir")
+    return _get_projconf_option_dir(
-
+        "lib_dir",
-    if not lib_dir:
+        join(get_home_dir(), "lib")
-        lib_dir = join(get_home_dir(), "lib")
+    )
-
-    return lib_dir
 
 
 def get_source_dir():
@@ -101,16 +103,17 @@ def get_project_dir():
 
 
 def get_projectsrc_dir():
-    src_dir = _get_projconf_option_dir("src_dir")
+    return _get_projconf_option_dir(
-
+        "src_dir",
-    if not src_dir:
+        join(get_project_dir(), "src")
-        src_dir = join(get_project_dir(), "src")
+    )
-
-    return src_dir
 
 
 def get_pioenvs_dir():
-    return os.getenv("PIOENVS_DIR", join(get_project_dir(), ".pioenvs"))
+    return _get_projconf_option_dir(
+        "envs_dir",
+        join(get_project_dir(), ".pioenvs")
+    )
 
 
 def get_project_config():