platformio/platformio-core
1
0
Fork 1
mirror of https://github.com/platformio/platformio-core.git synced 2025-10-04 17:40:57 +02:00
Code Issues Packages Projects Releases Wiki Activity

Implemented PLATFORMIO_* environment variables

Browse Source
This commit is contained in:
Ivan Kravets
2015-03-05 01:36:31 +02:00
parent 21c60fdd99
commit ae92cdedea
11 changed files with 304 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
docs/envvars.rst Normal file
View File

@@ -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`.

1
docs/index.rst
View File

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

10
docs/installation.rst
View File

@@ -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 <cmd_settings>` 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 <envvar_PLATFORMIO_SETTING_ENABLE_PROMPTS>`
- disable global setting via :ref:`platformio setting enable_prompts false <cmd_settings>`
command.
Please *choose one of* the following:

88
docs/projectconf.rst
View File

@@ -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,
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 <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
*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 <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``
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 <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

3
docs/quickstart.rst
View File

@@ -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 <https://github.com/ivankravets/platformio/tree/develop/examples>`_.
Further examples can be found in `PlatformIO Repository <https://github.com/ivankravets/platformio/tree/develop/examples>`_.
Also, for more detailed information as for commands please go to
:ref:`userguide` sections.

64
docs/userguide/cmd_settings.rst
View File

@@ -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
~~~~~~~~