From ae92cdedeaadeae51b34bd3e22ac177102aa5dcb Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Thu, 5 Mar 2015 01:36:31 +0200 Subject: [PATCH] Implemented PLATFORMIO_* environment variables --- HISTORY.rst | 9 ++- docs/envvars.rst | 107 +++++++++++++++++++++++++ docs/index.rst | 1 + docs/installation.rst | 10 ++- docs/projectconf.rst | 88 +++++++++++++++----- docs/quickstart.rst | 3 +- docs/userguide/cmd_settings.rst | 64 +++++++++++++++ platformio/__init__.py | 2 +- platformio/app.py | 41 +++++----- platformio/builder/tools/platformio.py | 2 +- platformio/util.py | 45 ++++++----- 11 files changed, 304 insertions(+), 68 deletions(-) create mode 100644 docs/envvars.rst diff --git a/HISTORY.rst b/HISTORY.rst index cf42ba19..c092cfcf 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -1,12 +1,17 @@ Release History =============== -1.0.2 (2015-03-??) +1.1.0 (2015-03-??) ------------------ +* Implemented ``PLATFORMIO_*`` environment variables + (`issue #102 `_) * Added support for *SainSmart* boards to `atmelsam `__ development platform +* Added + `Project Configuration `__ + option named `envs_dir `__ * Fixed firmware uploading for `atmelavr `__ boards which work within ``usbtiny`` protocol @@ -230,7 +235,7 @@ Release History `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 `__ command * Implemented (especially for `SmartAnthill `_) `platformio run -t uploadlazy `_ diff --git a/docs/envvars.rst b/docs/envvars.rst new file mode 100644 index 00000000..6caead8e --- /dev/null +++ b/docs/envvars.rst @@ -0,0 +1,107 @@ +.. _envvars: + +Environment variables +===================== + +`Environment variables `_ +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`. diff --git a/docs/index.rst b/docs/index.rst index f0b272f2..3f7bd777 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -57,6 +57,7 @@ Contents quickstart installation projectconf + envvars platforms/index librarymanager/index userguide/index diff --git a/docs/installation.rst b/docs/installation.rst index bd860f10..7f403690 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -30,9 +30,13 @@ application: application. .. warning:: - If you are going to use *PlatformIO* for "*Cloud Compiling*", please - don't forget to turn off :ref:`enable_prompts ` setting. It - will allow you to avoid blocking when call ``platformio`` like subprocess. + If you are going to run *PlatformIO* from **subprocess**, you **MUST + DISABLE** all prompts. It will allow you to avoid blocking. + There are 2 options: + + - using environment variable :ref:`PLATFORMIO_SETTING_ENABLE_PROMPTS=false ` + - disable global setting via :ref:`platformio setting enable_prompts false ` + command. Please *choose one of* the following: diff --git a/docs/projectconf.rst b/docs/projectconf.rst index 6f531002..bf741fe4 100644 --- a/docs/projectconf.rst +++ b/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 `_ file. @@ -33,11 +33,18 @@ Options ``home_dir`` ^^^^^^^^^^^^ -A ``$PIO_HOME_DIR`` is used to store platform tool chains, frameworks, -external libraries, service data and etc. +Is used to store platform tool chains, frameworks, external libraries, +service data and etc. -A default value is user's home directory: *Unix* - ``~/.platformio``, -Windows - ``%HOMEPATH%\.platformio``. +A default value is User's home directory: + +* 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 `__ 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 `_. -The full list of ``board_mcu`` for popular embedded platforms you can find in -*Boards* section of :ref:`platforms`. See "Microcontroller" column. +The full list of ``board_mcu`` for the popular embedded platforms you can find +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 -*Boards* section of :ref:`platforms`. See "Frequency" column. +The full list of ``board_f_cpu`` for the popular embedded platforms you can +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 -``upload_port`` automatically. +If ``upload_port`` isn't specified, then *PlatformIO* will try to detect it +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 `_) -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 `_ +.. _projectconf_srcbuild_flags: ``srcbuild_flags`` ^^^^^^^^^^^^^^^^^^ -This is option ``srcbuild_flags`` has the same behaviour like ``build_flags`` -but will be applied only for project source code from ``src`` directory. +An option ``srcbuild_flags`` has the same behaviour like ``build_flags`` +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 `_. + 1. :ref:`platform_atmelavr`: Arduino UNO board with auto pre-configured ``board_*`` and ``upload_*`` options (use only ``board`` option) and Arduino Wiring-based Framework diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 1ad7e264..16e20e36 100644 --- a/docs/quickstart.rst +++ b/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 -distribution or `on the web `_. +Further examples can be found in `PlatformIO Repository `_. Also, for more detailed information as for commands please go to :ref:`userguide` sections. diff --git a/docs/userguide/cmd_settings.rst b/docs/userguide/cmd_settings.rst index c001c16f..4fabe52e 100644 --- a/docs/userguide/cmd_settings.rst +++ b/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 ~~~~~~~~ diff --git a/platformio/__init__.py b/platformio/__init__.py index 6f55293d..b231aace 100644 --- a/platformio/__init__.py +++ b/platformio/__init__.py @@ -1,7 +1,7 @@ # Copyright (C) Ivan Kravets # See LICENSE for details. -VERSION = (1, 0, "2.dev0") +VERSION = (1, 1, "0.dev0") __version__ = ".".join([str(s) for s in VERSION]) __title__ = "platformio" diff --git a/platformio/app.py b/platformio/app.py index 60d7d827..6be9665d 100644 --- a/platformio/app.py +++ b/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: - raise InvalidSettingName(name) + _env_name = "PLATFORMIO_SETTING_%s" % name.upper() + 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(): diff --git a/platformio/builder/tools/platformio.py b/platformio/builder/tools/platformio.py index a50b566f..37931953 100644 --- a/platformio/builder/tools/platformio.py +++ b/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"), diff --git a/platformio/util.py b/platformio/util.py index ea48f79b..b4f0473c 100644 --- a/platformio/util.py +++ b/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)): - option_dir = config.get("platformio", option_name) + config.has_option("platformio", 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") - - if not home_dir: - home_dir = join(expanduser("~"), ".platformio") + home_dir = _get_projconf_option_dir( + "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") - - if not lib_dir: - lib_dir = join(get_home_dir(), "lib") - - return lib_dir + return _get_projconf_option_dir( + "lib_dir", + join(get_home_dir(), "lib") + ) def get_source_dir(): @@ -101,16 +103,17 @@ def get_project_dir(): def get_projectsrc_dir(): - src_dir = _get_projconf_option_dir("src_dir") - - if not src_dir: - src_dir = join(get_project_dir(), "src") - - return src_dir + return _get_projconf_option_dir( + "src_dir", + join(get_project_dir(), "src") + ) 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():