diff --git a/docs/installation.rst b/docs/installation.rst index 22717b4b..d0c92fde 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -30,7 +30,7 @@ System requirements :Operating System: Mac OS X, Linux (+ARM) or Windows :Python Interpreter: - Python 2.6 or 2.7. Python 2.7 is recommended + Python 2.7 is required. PlatformIO **does not** support Python 3. .. attention:: **Windows Users**: Please `Download the latest Python 2.7.x @@ -141,7 +141,7 @@ Mac OS X Homebrew Packages Manager (`brew `_) as follows: Full Guide ~~~~~~~~~~ -1. Check a ``python`` version (only 2.6-2.7 is supported): +1. Check a ``python`` version (only Python 2.7 is supported): .. code-block:: bash diff --git a/docs/projectconf.rst b/docs/projectconf.rst index 880ad68a..23565183 100644 --- a/docs/projectconf.rst +++ b/docs/projectconf.rst @@ -579,101 +579,6 @@ exclude ``.git`` and ``svn`` repository folders, ``example`` ... folder. This option can be set by global environment variable :envvar:`PLATFORMIO_SRC_FILTER`. -.. _projectconf_extra_script: - -``extra_script`` -^^^^^^^^^^^^^^^^ - -.. contents:: - :local: - -Allows to launch extra script using `SCons `_ software -construction tool. For more details please follow to "Construction Environments" -section of -`SCons documentation `_. - -This option can be set by global environment variable -:envvar:`PLATFORMIO_EXTRA_SCRIPT`. - -Take a look at the multiple snippets/answers for the user questions: - - - `#462 Split C/C++ build flags `_ - - `#365 Extra configuration for ESP8266 uploader `_ - - `#351 Specific reset method for ESP8266 `_ - - `#247 Specific options for avrdude `_. - -Custom Uploader -''''''''''''''' - -Example, specify own upload command for :ref:`platform_atmelavr`: - -``platformio.ini``: - -.. code-block:: ini - - [env:env_custom_uploader] - platform = atmelavr - extra_script = /path/to/extra_script.py - custom_option = hello - -``extra_script.py``: - -.. code-block:: python - - Import('env') - from base64 import b64decode - - env.Replace(UPLOADHEXCMD='"$UPLOADER" ' + b64decode(ARGUMENTS.get("CUSTOM_OPTION")) + ' --uploader --flags') - - # uncomment line below to see environment variables - # print env.Dump() - # print ARGUMENTS - -Before/Pre and After/Post actions -''''''''''''''''''''''''''''''''' - -PlatformIO Build System has rich API that allows to attach different pre-/post -actions (hooks) using ``env.AddPreAction(target, callback)`` function. A first -argument ``target`` can be a name of target that is passed using -:option:`platformio run --target` command or path to file which PlatformIO -processes (ELF, HEX, BIN, etc.). For example, to call function before HEX file -will be created, need to use as a ``$BUILD_DIR/firmware.hex`` target value. - -The example below demonstrates how to call different functions -when :option:`platformio run --target` is called with ``upload`` value. -`extra_script.py` file is located on the same level as ``platformio.ini``. - -``platformio.ini``: - -.. code-block:: ini - - [env:pre_and_post_hooks] - extra_script = extra_script.py - -``extra_script.py``: - -.. code-block:: python - - Import("env") - - def before_upload(source, target, env): - print "before_upload" - # do some actions - - - def after_upload(source, target, env): - print "after_upload" - # do some actions - - print "Current build targets", map(str, BUILD_TARGETS) - - # env.AddPreAction("$BUILD_DIR/firmware.elf", callback...) - # env.AddPostAction("$BUILD_DIR/firmware.hex", callback...) - - env.AddPreAction("upload", before_upload) - env.AddPostAction("upload", after_upload) - - .. _projectconf_targets: ``targets`` @@ -941,6 +846,106 @@ ignore some tests using :option:`platformio test --ignore` command. [env:myenv] test_ignore = footest, bartest_*, test[13] + +Advanced options +~~~~~~~~~~~~~~~~ + +.. _projectconf_extra_script: + +``extra_script`` +^^^^^^^^^^^^^^^^ + +.. contents:: + :local: + +Allows to launch extra script using `SCons `_ software +construction tool. For more details please follow to "Construction Environments" +section of +`SCons documentation `_. + +This option can be set by global environment variable +:envvar:`PLATFORMIO_EXTRA_SCRIPT`. + +Take a look at the multiple snippets/answers for the user questions: + + - `#462 Split C/C++ build flags `_ + - `#365 Extra configuration for ESP8266 uploader `_ + - `#351 Specific reset method for ESP8266 `_ + - `#247 Specific options for avrdude `_. + +Custom Uploader +''''''''''''''' + +Example, specify own upload command for :ref:`platform_atmelavr`: + +``platformio.ini``: + +.. code-block:: ini + + [env:env_custom_uploader] + platform = atmelavr + extra_script = /path/to/extra_script.py + custom_option = hello + +``extra_script.py``: + +.. code-block:: python + + Import('env') + from base64 import b64decode + + env.Replace(UPLOADHEXCMD='"$UPLOADER" ' + b64decode(ARGUMENTS.get("CUSTOM_OPTION")) + ' --uploader --flags') + + # uncomment line below to see environment variables + # print env.Dump() + # print ARGUMENTS + +Before/Pre and After/Post actions +''''''''''''''''''''''''''''''''' + +PlatformIO Build System has rich API that allows to attach different pre-/post +actions (hooks) using ``env.AddPreAction(target, callback)`` function. A first +argument ``target`` can be a name of target that is passed using +:option:`platformio run --target` command or path to file which PlatformIO +processes (ELF, HEX, BIN, etc.). For example, to call function before HEX file +will be created, need to use as a ``$BUILD_DIR/firmware.hex`` target value. + +The example below demonstrates how to call different functions +when :option:`platformio run --target` is called with ``upload`` value. +`extra_script.py` file is located on the same level as ``platformio.ini``. + +``platformio.ini``: + +.. code-block:: ini + + [env:pre_and_post_hooks] + extra_script = extra_script.py + +``extra_script.py``: + +.. code-block:: python + + Import("env") + + def before_upload(source, target, env): + print "before_upload" + # do some actions + + + def after_upload(source, target, env): + print "after_upload" + # do some actions + + print "Current build targets", map(str, BUILD_TARGETS) + + # env.AddPreAction("$BUILD_DIR/firmware.elf", callback...) + # env.AddPostAction("$BUILD_DIR/firmware.hex", callback...) + + env.AddPreAction("upload", before_upload) + env.AddPostAction("upload", after_upload) + + + ----------- .. _projectconf_examples: diff --git a/docs/userguide/account/cmd_forgot.rst b/docs/userguide/account/cmd_forgot.rst new file mode 100644 index 00000000..239aa96f --- /dev/null +++ b/docs/userguide/account/cmd_forgot.rst @@ -0,0 +1,42 @@ +.. Copyright 2014-present PlatformIO + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +.. _cmd_account_forgot: + +platformio account forgot +========================= + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio account forgot [OPTIONS] + + +Description +----------- + +Allows you to reset password for :ref:`userguide_account` using E-Mail that +was specified for registration. + +Options +~~~~~~~ + +.. program:: platformio account forgot + +.. option:: + --username, -u + +User name (E-Mail). You can omit this option and enter E-Mail in Forgot +Wizard later. diff --git a/docs/userguide/account/cmd_login.rst b/docs/userguide/account/cmd_login.rst new file mode 100644 index 00000000..e4e0dfaa --- /dev/null +++ b/docs/userguide/account/cmd_login.rst @@ -0,0 +1,46 @@ +.. Copyright 2014-present PlatformIO + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +.. _cmd_account_login: + +platformio account login +========================= + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio account login [OPTIONS] + + +Description +----------- + +Log in to :ref:`userguide_account`. + +Options +~~~~~~~ + +.. program:: platformio account login + +.. option:: + --username, -u + +User name (E-Mail). You can omit this option and enter E-Mail in Login Wizard +later. + +.. option:: + --password, -p + +You can omit this option and enter securely password in Login Wizard later. diff --git a/docs/userguide/account/cmd_logout.rst b/docs/userguide/account/cmd_logout.rst new file mode 100644 index 00000000..61535714 --- /dev/null +++ b/docs/userguide/account/cmd_logout.rst @@ -0,0 +1,30 @@ +.. Copyright 2014-present PlatformIO + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +.. _cmd_account_logout: + +platformio account logout +========================= + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio account logout + + +Description +----------- + +Log out of :ref:`userguide_account`. diff --git a/docs/userguide/account/cmd_password.rst b/docs/userguide/account/cmd_password.rst new file mode 100644 index 00000000..1d391206 --- /dev/null +++ b/docs/userguide/account/cmd_password.rst @@ -0,0 +1,30 @@ +.. Copyright 2014-present PlatformIO + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +.. _cmd_account_password: + +platformio account password +=========================== + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio account password + + +Description +----------- + +Change password for :ref:`userguide_account`. diff --git a/docs/userguide/account/cmd_register.rst b/docs/userguide/account/cmd_register.rst new file mode 100644 index 00000000..4d6f7032 --- /dev/null +++ b/docs/userguide/account/cmd_register.rst @@ -0,0 +1,41 @@ +.. Copyright 2014-present PlatformIO + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +.. _cmd_account_register: + +platformio account register +=========================== + +.. contents:: + +Usage +----- + +.. code-block:: bash + + platformio account register [OPTIONS] + + +Description +----------- + +Log in to :ref:`userguide_account`. + +Options +~~~~~~~ + +.. program:: platformio account register + +.. option:: + --username, -u + +User name (E-Mail). You can omit this option and enter E-Mail in Register +Wizard later. diff --git a/docs/userguide/account/index.rst b/docs/userguide/account/index.rst new file mode 100644 index 00000000..11c9030f --- /dev/null +++ b/docs/userguide/account/index.rst @@ -0,0 +1,37 @@ +.. Copyright 2014-present PlatformIO + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +.. _userguide_account: + +PIO Account +=========== + +Having **PIO Account** allows you to use extra professional features from +`PlatformIO Plus `__: + +* :ref:`unit_testing` + +To print all available commands and options use: + +.. code-block:: bash + + platformio account --help + platformio account COMMAND --help + + +.. toctree:: + :maxdepth: 2 + + cmd_forgot + cmd_login + cmd_logout + cmd_password + cmd_register diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst index 2a3b0f2a..26efd488 100644 --- a/docs/userguide/index.rst +++ b/docs/userguide/index.rst @@ -58,6 +58,7 @@ Commands .. toctree:: :maxdepth: 2 + platformio account cmd_boards cmd_ci cmd_device