feedc0de/platformio-core
1
0
Fork 0
forked from platformio/platformio-core
Code Pull Requests Activity

Merge branch 'feature/platformio-30' into develop

Browse Source
This commit is contained in:
Ivan Kravets
2016-08-08 16:04:20 +03:00
parent 795b8be386 65e0daa06d
commit 655efb1fb6
245 changed files with 6858 additions and 14157 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
platformio/platforms/__init__.py → .coveragerc
View File

@ -1,4 +1,4 @@
# Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
# Copyright 2014-present PlatformIO <contact@platformio.org>
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -11,3 +11,16 @@
# 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.
[run]
omit =
platformio/builder/*
source = platformio
[report]
# Regexes for lines to exclude from consideration
exclude_lines =
pragma: no cover
def __repr__
raise AssertionError
raise NotImplementedError

3
.gitignore vendored
View File

@ -6,3 +6,6 @@ docs/_build
dist
build
.cache
coverage.xml
.coverage
htmlcov

2
.isort.cfg
View File

@ -1,3 +1,3 @@
[settings]
line_length=79
known_third_party=bottle,click,lockfile,pytest,requests,serial,SCons
known_third_party=bottle,click,lockfile,pytest,requests,semantic_version,serial,SCons

3
.style.yapf Normal file
View File

@ -0,0 +1,3 @@
[style]
blank_line_before_nested_class_or_def = true
allow_multiline_lambdas = true

9
.travis.yml
View File

@ -5,17 +5,22 @@ python:
env:
- TOX_ENV=docs
- TOX_ENV=lint
- TOX_ENV=py26
- TOX_ENV=py27
install:
- git submodule update --init --recursive
- pip install -U pip setuptools tox
- sudo apt-get install -qq lib32z1 lib32ncurses5 lib32bz2-1.0 # temporarily
# temporary hook to fix issue with gcc-pic32
- sudo apt-get install -qq lib32z1 lib32ncurses5 lib32bz2-1.0
script:
- tox -e $TOX_ENV
after_success:
- tox -e coverage
- bash <(curl -s https://codecov.io/bash)
notifications:
slack:
secure: ksQmXOP5NVsf8IgoDuxD68Q/YNwDpZuwq0V29h2dxYCr38oYdAkq/Os4LSCs0X6P0cQFf6nC1hM/d+cAvU+SmzcHGxEceHNEGCg3/TAj+68KIwooPU93Lfq1zwdfteZWxANjKlCQy4+wZliHLhL8fvCYgfJww/6qKmqSYleBNM=

73
HISTORY.rst
View File

@ -1,6 +1,79 @@
Release Notes
=============
PlatformIO 3.0
--------------
3.0.0 (2016-??-??)
~~~~~~~~~~~~~~~~~~
* PlatformIO Plus
+ `Unit Testing <http://docs.platformio.org/en/latest/platforms/unit_testing.html>`__ for Embedded
(`issue #408 <https://github.com/platformio/platformio/issues/408>`_)
* Decentralized Development Platforms
+ Development platform manifest "platform.json" and
`open source development platforms <https://github.com/platformio?utf8=✓&query=platform->`__
+ `Semantic Versioning <http://semver.org/>`__ for platform commands,
development platforms and dependent packages
+ Custom package repositories
+ External embedded board configuration files, isolated build scripts
(`issue #479 <https://github.com/platformio/platformio/issues/479>`_)
+ Embedded Board compatibility with more than one development platform
(`issue #456 <https://github.com/platformio/platformio/issues/456>`_)
* Library Manager 3.0
+ Project dependencies per build environment using `lib_deps <http://docs.platformio.org/en/latest/projectconf.html#lib-deps>`__ option
(`issue #413 <https://github.com/platformio/platformio/issues/413>`_)
+ `Semantic Versioning <http://semver.org/>`__ for library commands and
dependencies
(`issue #410 <https://github.com/platformio/platformio/issues/410>`_)
+ Multiple library storages: Project's Local, PlatformIO's Global or Custom
(`issue #475 <https://github.com/platformio/platformio/issues/475>`_)
+ Install library by name
(`issue #414 <https://github.com/platformio/platformio/issues/414>`_)
+ Depend on a library using VCS URL (GitHub, Git, ARM mbed code registry, Hg, SVN)
(`issue #498 <https://github.com/platformio/platformio/issues/498>`_)
+ Strict search for library dependencies
(`issue #588 <https://github.com/platformio/platformio/issues/588>`_)
+ Allowed ``library.json`` to specify sources other than PlatformIO's Repository
(`issue #461 <https://github.com/platformio/platformio/issues/461>`_)
* New Intelligent Library Build System
+ `Library Dependency Finder <http://docs.platformio.org/en/latest/faq.html#how-works-library-dependency-finder-ldf>`__
that interprets C/C++ Preprocessor conditional macros with deep search behavior
+ Check library compatibility with project environment before building
(`issue #415 <https://github.com/platformio/platformio/issues/415>`_)
+ Control Library Dependency Finder for compatibility using
`lib_compat_mode <http://docs.platformio.org/en/latest/projectconf.html#lib-compat-mode>`__
option
+ Custom library storages/directories with
`lib_extra_dirs <http://docs.platformio.org/en/latest/projectconf.html#lib-extra-dirs>`__ option
(`issue #537 <https://github.com/platformio/platformio/issues/537>`_)
+ Handle extra build flags, source filters and build script from
`library.json <http://docs.platformio.org/en/latest/librarymanager/config.html>`__
(`issue #289 <https://github.com/platformio/platformio/issues/289>`_)
+ Allowed to disable library archiving (``*.ar``)
(`issue #719 <https://github.com/platformio/platformio/issues/719>`_)
+ Show detailed build information about dependent libraries
(`issue #617 <https://github.com/platformio/platformio/issues/617>`_)
+ Support for the 3rd party manifests (Arduino IDE "library.properties"
and ARM mbed "module.json")
* Print human-readable information when processing environments without
``-v, --verbose`` option
(`issue #721 <https://github.com/platformio/platformio/issues/721>`_)
* Added ``license`` field to `library.json <http://docs.platformio.org/en/latest/librarymanager/config.html>`__
(`issue #522 <https://github.com/platformio/platformio/issues/522>`_)
* Warn about unknown options in project configuration file ``platformio.ini``
(`issue #740 <https://github.com/platformio/platformio/issues/740>`_)
* Stopped supporting Python 2.6
PlatformIO 2.0
--------------

23
Makefile Normal file
View File

@ -0,0 +1,23 @@
lint:
pylint --rcfile=./.pylintrc ./platformio
isort:
isort -rc ./platformio
isort -rc ./tests
yapf:
yapf --recursive --in-place platformio/
before-commit: isort yapf lint
clean-docs:
rm -rf docs/_build
clean: clean-docs
find . -name \*.pyc -delete
find . -name __pycache__ -delete
rm -rf .cache
rm -rf build
rm -rf htmlcov
rm -f .coverage

4
README.rst
View File

@ -7,6 +7,8 @@ PlatformIO
.. image:: https://ci.appveyor.com/api/projects/status/dku0h2rutfj0ctls/branch/develop?svg=true
:target: https://ci.appveyor.com/project/ivankravets/platformio
:alt: AppVeyor.CI Build Status
.. image:: https://codecov.io/gh/platformio/platformio/branch/develop/graph/badge.svg
:target: https://codecov.io/gh/platformio/platformio
.. image:: https://requires.io/github/platformio/platformio/requirements.svg?branch=develop
:target: https://requires.io/github/platformio/platformio/requirements/?branch=develop
:alt: Requirements Status
@ -190,7 +192,7 @@ See `contributing guidelines <https://github.com/platformio/platformio/blob/deve
License
-------
Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
Copyright 2014-present PlatformIO <contact@platformio.org>
The PlatformIO is licensed under the permissive Apache 2.0 license,
so you can use it in both commercial and personal projects with confidence.

2
docs/_static/extra.css vendored
View File

@ -1,5 +1,5 @@
/**
* Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
* Copyright 2014-present PlatformIO <contact@platformio.org>
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.

8
docs/articles.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -38,18 +38,18 @@ Here are recent articles about PlatformIO:
* May 16, 2016 - **Pedro Minatel** - `Controle remoto WiFi com ESP8266 (WiFi remote control using ESP8266, Portuguese) <http://pedrominatel.com.br/esp8266/controle-remoto-wifi-com-esp8266/>`_
* May 11, 2016 - **Jo Vandeginste** - `Using PlatformIO to compile for Jeelabs' Jeenode Micro <http://jovandeginste.github.io/2016/05/11/using-platformio-to-compile-for-jeelabs-jeenode-micro.html>`_
* May 08, 2016 - **Radoslaw Bob** - `Touch controlled buzzer (Nodemcu ESP8266) <https://gettoknowthebob.wordpress.com/2016/05/08/touch-controlled-buzzer-nodemcu-esp8266/>`_
* May 06, 2016 - **Jean Roux** - `The IoT building blocks I use for my home-automation projects <http://iotplay.blogspot.fr/2016/05/the-components-i-use-for-my-projects.html/>`_
* May 06, 2016 - **Jean Roux** - `The IoT building blocks I use for my home-automation projects <http://iotplay.blogspot.com/2016/05/the-components-i-use-for-my-projects.html>`_
* May 05, 2016 - **Ivan Kravets, Ph.D. / Eclipse Virtual IoT Meetup** - `PlatformIO: a cross-platform IoT solution to build them all! <http://www.meetup.com/Virtual-IoT/events/229964142/>`_
* May 01, 2016 - **Pedro Minatel** - `PlatformIO – Uma alternativa ao Arduino IDE (PlatformIO - An alternative to the Arduino IDE, Portuguese) <http://pedrominatel.com.br/ferramentas/platformio-uma-alternativa-ao-arduino-ide/>`_
* Apr 23, 2016 - **Al Williams** - `Hackaday: Atomic Arduino (and Other) Development <http://hackaday.com/2016/04/23/atomic-arduino-and-other-development/>`_
* Apr 16, 2016 - **Sathittham Sangthong** - `[PlatformIO] มาลองเล่น PlatformIO แทน Arduino IDE กัน (Let's play together with PlatformIO IDE [alternative to Arduino IDE], Thai) <http://www.sathittham.com/platformio/platformio-ide/>`_
* Apr 15, 2016 - **Daniel Eichhorn** - `ESP8266: Offline Debugging with the Platformio Environment <http://blog.squix.ch/2016/04/esp8266-offline-debugging-with.html>`_
* Apr 15, 2016 - **Daniel Eichhorn** - `ESP8266: Offline Debugging with the Platformio Environment <http://blog.squix.org/2016/04/esp8266-offline-debugging-with.html>`_
* Apr 11, 2016 - **Matjaz Trcek** - `Top 5 Arduino integrated development environments <https://codeandunicorns.com/top-5-arduino-integrated-development-environments-ide/>`_
* Apr 06, 2016 - **Aleks** - `PlatformIO ausprobiert (Tried PlatformIO, German) <http://5volt-junkie.net/platformio/>`_
* Apr 02, 2016 - **Diego Pinto** - `Você tem coragem de abandonar a IDE do Arduino? PlatformIO + Atom (Do you dare to leave the Arduino IDE? PlatformIO + Atom, Portuguese) <http://www.clubemaker.com.br/?rota=artigo/81>`_
* Mar 30, 2016 - **Brandon Cannaday** - `Getting Started with PlatformIO and ESP8266 NodeMcu <https://www.losant.com/blog/getting-started-with-platformio-esp8266-nodemcu>`_
* Mar 29, 2016 - **Pablo Peñalve** - `PlatformIO + Geany + Raspberry PI, Spanish <http://ret-catriel.blogspot.com/2016/03/framework-platformio-geany-raspberry-pi.html>`_
* Mar 24, 2016 - **NAzT** - `PlatformIO และการปรับแต่ง เพื่อใช้สำหรับพัฒนา Arduino Library (PlatformIO and advanced development for Arduino Library, Thai) <https://cmmakerclub.com/tools-2/config-platformio-for-arduino-framework-developer/>`_
* Mar 24, 2016 - **NAzT** - `PlatformIO และการปรับแต่ง เพื่อใช้สำหรับพัฒนา Arduino Library (PlatformIO and advanced development for Arduino Library, Thai) <http://cmmakerclub.com/2016/03/tools-2/config-platformio-for-arduino-framework-developer/>`_
* Mar 16, 2016 - **Jakub Skořepa** - `Instalace PlatformIO (PlatformIO IDE Installation, Czech) <http://ok1kvk.cz/clanek/2016/instalace-platformio/>`_
* Mar 12, 2016 - **Peter Marks** - `PlatformIO, the Arduino IDE for programmers <http://blog.marxy.org/2016/03/platformio-arduino-ide-for-programmers.html>`_
* Mar 12, 2016 - **Richard Arthurs** - `Getting Started With PlatformIO <http://richarthurs.com/2016/03/12/platformio-review-and-first-thoughts/>`_

2
docs/ci/appveyor.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

4
docs/ci/circleci.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -152,7 +152,7 @@ Examples
- sudo pip install -U platformio
# pre-install PlatformIO development platforms, they will be cached
- platformio platforms install atmelavr atmelsam teensy
- platformio platform install atmelavr atmelsam teensy
#
# Libraries from PlatformIO Library Registry:

2
docs/ci/drone.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ci/index.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ci/shippable.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ci/travis.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

12
docs/demo.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -41,11 +41,11 @@ Platform Manager
Used in demo
~~~~~~~~~~~~
1. :ref:`userguide_platforms`
2. :ref:`cmd_platforms_list` command
3. :ref:`platformio platforms search avr <cmd_platforms_search>` command
4. :ref:`platformio platforms show teensy <cmd_platforms_show>` command
5. :ref:`cmd_platforms_update` command.
1. :ref:`userguide_platform`
2. :ref:`cmd_platform_list` command
3. :ref:`platformio platform search avr <cmd_platform_search>` command
4. :ref:`platformio platform show teensy <cmd_platform_show>` command
5. :ref:`cmd_platform_update` command.
Library Manager
---------------

18
docs/envvars.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -57,6 +57,10 @@ Allows to override :ref:`projectconf` option :ref:`projectconf_pio_home_dir`.
Allows to override :ref:`projectconf` option :ref:`projectconf_pio_lib_dir`.
.. envvar:: PLATFORMIO_LIBDEPS_DIR
Allows to override :ref:`projectconf` option :ref:`projectconf_pio_libdeps_dir`.
.. envvar:: PLATFORMIO_SRC_DIR
Allows to override :ref:`projectconf` option :ref:`projectconf_pio_src_dir`.
@ -69,6 +73,10 @@ Allows to override :ref:`projectconf` option :ref:`projectconf_pio_envs_dir`.
Allows to override :ref:`projectconf` option :ref:`projectconf_pio_data_dir`.
.. envvar:: PLATFORMIO_TEST_DIR
Allows to override :ref:`projectconf` option :ref:`projectconf_pio_test_dir`.
Building
--------
@ -103,6 +111,10 @@ Allows to set :ref:`projectconf` option :ref:`projectconf_src_filter`.
Allows to set :ref:`projectconf` option :ref:`projectconf_extra_script`.
.. envvar:: PLATFORMIO_LIB_EXTRA_DIRS
Allows to set :ref:`projectconf` option :ref:`projectconf_lib_extra_dirs`.
Uploading
---------
@ -149,3 +161,7 @@ Allows to override setting :ref:`setting_enable_prompts`.
.. envvar:: PLATFORMIO_SETTING_ENABLE_TELEMETRY
Allows to override setting :ref:`setting_enable_telemetry`.
.. envvar:: PLATFORMIO_SETTING_FORCE_VERBOSE
Allows to override setting :ref:`setting_force_verbose`.

8
docs/faq.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -155,12 +155,6 @@ Answered in `issue #144 <https://github.com/platformio/platformio/issues/144#iss
Building
~~~~~~~~
Can not compile a library that compiles without issue with Arduino IDE
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
* `#298: Unable to use Souliss library <https://github.com/platformio/platformio/issues/298>`_
* `#331: Unable to use MySensors library <https://github.com/platformio/platformio/issues/331>`_
ARM toolchain: cc1plus: error while loading shared libraries
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

2
docs/frameworks/arduino.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/cmsis.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/cmsis_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/energia.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/index.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/libopencm3.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/libopencm3_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/mbed.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/mbed_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/simba.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/simba_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/spl.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/spl_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/wiringpi.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/frameworks/wiringpi_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/history.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide/_platformio_ide_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide/atom.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide/clion.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide/codeblocks.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide/eclipse.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide/emacs.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide/netbeans.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide/qtcreator.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide/sublimetext.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide/vim.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/ide/visualstudio.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

4
docs/index.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -111,6 +111,7 @@ Contents
platforms/embedded_boards
frameworks/index
platforms/custom_platform_and_board
platforms/unit_testing
.. toctree::
:caption: Library Manager
@ -118,6 +119,7 @@ Contents
Quickstart <librarymanager/index>
User Guide <userguide/lib/index.rst>
librarymanager/ldf
librarymanager/config
librarymanager/creating

2
docs/installation.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

136
docs/librarymanager/config.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -22,6 +22,7 @@ to keep project in own structure and define:
* examples list
* compatible frameworks and platforms
* library dependencies
* advanced build settings
PlatformIO Library Crawler uses ``library.json`` manifest to extract
source code from developer's location and keeps cleaned library in own
@ -221,6 +222,19 @@ Example:
},
"version": "1.0.0"
``license``
-----------
A license of the library. You can check
`the full list of SPDX license IDs <https://spdx.org/licenses/>`_. Ideally you
should pick one that is `OSI <https://opensource.org/licenses/alphabetical>`_
approved.
.. code-block:: javascript
"license": "Apache-2.0"
.. _libjson_downloadurl:
``downloadUrl``
@ -367,6 +381,7 @@ A list of dependent libraries. They will be installed automatically with
Allowed requirements for dependent library:
* ``name`` | Type: ``String``
* ``version`` | Type: ``String``
* ``authors`` | Type: ``String`` or ``Array``
* ``frameworks`` | Type: ``String`` or ``Array``
* ``platforms`` | Type: ``String`` or ``Array``
@ -387,17 +402,30 @@ Example:
},
{
"name": "Library-Bar",
"frameworks": "FrameworkFoo, FrameworkBar"
"version": "~1.2.3"
},
{
"name": "lib-from-repo",
"version": "https://github.com/user/package.git#1.2.3"
}
]
A short definition of dependencies is allowed:
.. code-block:: javascript
"dependencies": {
"mylib": "1.2.3",
"lib-from-repo": "githubuser/package"
}
See more ``library.json`` :ref:`library_creating_examples`.
.. _libjson_examples:
``examples``
----------------
------------
*Optional* | Type: ``String`` or ``Array`` |
`Glob Pattern <http://en.wikipedia.org/wiki/Glob_(programming)>`_
@ -413,3 +441,105 @@ A list of example patterns. This field is predefined with default value:
"[Ee]xamples/*/*.ino",
"[Ee]xamples/*/*.pde"
]
.. _libjson_build:
``build``
------------
*Optional* | Type: ``Object``
Specify advanced settings, options and flags for the build system. Possible
options:
.. list-table::
:header-rows: 1
* - Option
- Type
- Description
* - ``flags``
- ``String`` or ``Array``
- Extra flags to control preprocessing, compilation, assembly and
linking processes. More details :ref:`projectconf_build_flags`
* - ``unflags``
- ``String`` or ``Array``
- Remove base/initial flags which were set by development
platform. More details :ref:`projectconf_build_unflags`
* - ``srcFilter``
- ``String`` or ``Array``
- Specify which source files should be included/excluded
from build process. More details :ref:`projectconf_src_filter`
* - ``extraScript``
- ``String``
- Launch extra script before build process.
More details :ref:`projectconf_extra_script`
* - ``libArchive``
- ``Boolean``
- Archive object files to Static Library. This is default behavior of
PlatformIO Build System (``"libArchive": true``).
**Examples**
1. Custom macros/defines
.. code-block:: javascript
"build": {
"flags": "-D MYLIB_REV=0.1.2 -DRELEASE"
}
2. Extra includes for C preprocessor
.. code-block:: javascript
"build": {
"flags": [
"-I inc",
"-I inc/target_x13"
]
}
3. Force to use ``C99`` standard instead of ``C11``
.. code-block:: javascript
"build": {
"unflags": "-std=gnu++11",
"flags": "-std=c99"
}
4. Build source files (``c, cpp, h``) at the top level of the library
.. code-block:: javascript
"build": {
"srcFilter": [
"+<*.c>",
"+<*.cpp>",
"+<*.h>"
]
}
5. Extend PlatformIO Build System with own extra script
.. code-block:: javascript
"build": {
"extraScript": "generate_headers.py"
}
``generate_headers.py``
.. code-block:: python
Import('env')
# print env.Dump()
env.Append(
CPPDEFINES=["HELLO=WORLD", "TAG=1.2.3", "DEBUG"],
CPPPATH=["inc", "inc/devices"]
)
# some python code that generates header files "on-the-fly"

2
docs/librarymanager/creating.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/librarymanager/index.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

165
docs/librarymanager/ldf.rst Normal file
View File

@ -0,0 +1,165 @@
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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.
.. _ldf:
Library Dependency Finder (LDF)
===============================
.. versionadded:: 3.0
Library Dependency Finder is a core part of PlatformIO Build System that
operates with the C/C++ source files and looks for ``#include ...``
directives.
In spite of the fact that Library Dependency Finder is written in pure Python,
it interprets (emulates) :ref:`ldf_c_cond_syntax` (``#ifdef``, ``if``, ``defined``,
``else``, and ``elif``) without calling ``gcc -E``. This approach allows
significantly reduce total compilation time.
Library Dependency Finder has controls that can be set up in :ref:`projectconf`:
.. hlist::
:columns: 3
* :ref:`projectconf_lib_deps`
* :ref:`projectconf_lib_extra_dirs`
* :ref:`projectconf_lib_force`
* :ref:`projectconf_lib_ignore`
* :ref:`projectconf_lib_compat_mode`
* :ref:`projectconf_lib_ldf_mode`
-----------
.. contents::
Storage
-------
There are different storages where Library Dependency Finder looks for
libraries. These storages (folders) have priority and LDF operates in the next
order:
1. :ref:`projectconf_lib_extra_dirs` - extra storages per build environment
2. :ref:`projectconf_pio_lib_dir` - own/private library storage per project
3. :ref:`projectconf_pio_libdeps_dir` - project dependencies storage used by
:ref:`librarymanager`
4. ":ref:`projectconf_pio_home_dir`/lib" - global storage per all projects.
.. _ldf_mode:
Dependency Finder Mode
----------------------
Library Dependency Finder starts work from analyzing source files of the
project (:ref:`projectconf_pio_src_dir`) and can work in the next modes:
* ``0`` - "manual mode", does not process source files of a project and
dependencies. Builds only the libraries that are specified in
manifests (:ref:`library_config`, ``module.json``) or in the :ref:`projectconf`.
* ``1`` - parses ALL C/C++ source code of the project and follows only by
nested includes/chain (``#include ...``) from the libraries.
* ``2`` - **default** - parses ALL C/C++ source code of the project and parses
ALL C/C++ source code of the each dependency (recursively).
This mode can be changed using :ref:`projectconf_lib_ldf_mode` option in
:ref:`projectconf`.
A difference between ``1`` and ``2`` modes. For example, there are 2 libraries:
* Library "Foo" with files:
- ``Foo/foo.h``
- ``Foo/foo.cpp``
* Library "Bar" with files:
- ``Bar/bar.h``
- ``Bar/bar.cpp``
:Case 1:
* ``lib_ldf_mode = 1``
* ``Foo/foo.h`` depends on "Bar" library (contains ``#include <bar.h>``)
* ``#include <foo.h>`` is located in one of the project source files
Here are nested includes (``project file > foo.h > bar.h``) and ``LDF``
will find both libraries "Foo" and "Bar".
:Case 2:
* ``lib_ldf_mode = 1``
* ``Foo/foo.cpp`` depends on "Bar" library (contains ``#include <bar.h>``)
* ``#include <foo.h>`` is located in one of the project source files
In this case, ``LDF`` will not find "Bar" library because it doesn't know
about CPP file (``Foo/foo.cpp``).
:Case 3:
* ``lib_ldf_mode = 2``
* ``Foo/foo.cpp`` depends on "Bar" library (contains ``#include <bar.h>``)
* ``#include <foo.h>`` is located in one of the project source files
Firstly, ``LDF`` finds "Foo" library, then it parses all sources from "Foo"
library and finds ``Foo/foo.cpp`` that depends on ``#include <bar.h>``.
Secondly, it will parse all sources from "Bar" library and this operation
continues until all dependencies will not be parsed.
.. _ldf_compat_mode:
Compatibility Mode
------------------
Compatibility mode allows to control strictness of Library Dependency Finder.
If library contains one of manifest file (:ref:`library_config`,
``library.properties``, ``module.json``), then LDF check compatibility of this
library with real build environment. Available compatibility modes:
* ``0`` - does not check for compatibility (is not recommended)
* ``1`` - **default** - checks for the compatibility with
:ref:`projectconf_env_framework` from build environment
* ``2`` - checks for the compatibility with :ref:`projectconf_env_framework`
and :ref:`projectconf_env_platform` from build environment.
This mode can be changed using :ref:`projectconf_lib_compat_mode` option in
:ref:`projectconf`.
.. _ldf_c_cond_syntax:
C/C++ Preprocessor conditional syntax
-------------------------------------
In spite of the fact that Library Dependency Finder is written in pure Python,
it interprets (emulates) `C/C++ Preprocessor conditional syntax <https://gcc.gnu.org/onlinedocs/cpp/Conditional-Syntax.html#Conditional-Syntax>`_
(``#ifdef``, ``if``, ``defined``, ``else``, and ``elif``) without calling
``gcc -E``. For example,
``platformio.ini``
.. code-block:: ini
[env:myenv]
build_flags = -D MY_PROJECT_VERSION=13
``mylib.h``
.. code-block:: c
#ifdef PROJECT_VERSION
// include common file for the project
#include "my_common.h"
#endif
#if PROJECT_VERSION < 10
// this include will be ignored because does not satisfy condition above
#include "my_old.h"
#endif

2
docs/platforms/atmelavr.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/atmelavr_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/atmelsam.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

44
docs/platforms/creating_board.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -35,29 +35,44 @@ The key fields:
* ``build`` data will be used by :ref:`platforms` and :ref:`frameworks` builders
* ``frameworks`` is the list with supported :ref:`frameworks`
* ``platform`` main type of :ref:`platforms`
* ``platform`` name of :ref:`platforms`
* ``upload`` upload settings which depend on the ``platform``
.. code-block:: json
{
"myboard": {
"build": {},
"frameworks": ["%LIST_WITH_SUPPORTED_FRAMEWORKS%"],
"name": "My test board",
"platform": "%PLATFORM_TYPE_HERE%",
"upload": {},
"url": "http://example.com",
"vendor": "My Company Ltd."
}
"build": {
"extra_flags": "-DHELLO_PLATFORMIO",
"f_cpu": "16000000L",
"hwids": [
[
"0x1234",
"0x0013"
],
[
"0x4567",
"0x0013"
]
],
"mcu": "%MCU_TYPE_HERE%"
},
"frameworks": ["%LIST_WITH_SUPPORTED_FRAMEWORKS%"],
"name": "My Test Board",
"upload": {
"maximum_ram_size": 2048,
"maximum_size": 32256
},
"url": "http://example.com",
"vendor": "MyCompany"
}
Installation
------------
1. Create ``boards`` directory in :ref:`projectconf_pio_home_dir` if it
doesn't exist.
2. Create ``my_own_boards.json`` file and put to ``boards`` directory.
2. Create ``myboard.json`` file and put to ``boards`` directory.
3. Search available boards via :ref:`cmd_boards` command. You should see
``myboard`` board.
@ -68,5 +83,6 @@ Now, you can use ``myboard`` for the :ref:`projectconf_env_board` option in
Examples
--------
For the examples, please look into built-in ``*.json`` files with boards
settings: https://github.com/platformio/platformio/tree/develop/platformio/boards.
Please take a look at the source code of
`PlatformIO Development Platforms <https://github.com/platformio?query=platform->`_
and navigate to ``boards`` folder of the repository.

285
docs/platforms/creating_platform.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -14,7 +14,7 @@
Custom Development Platform
===========================
*PlatformIO* was developed like a tool which would build the same source code
*PlatformIO* was developed like a tool that may build the same source code
for the different development platforms via single command :ref:`cmd_run`
without any dependent software or requirements.
@ -32,7 +32,7 @@ different/own build scripts, uploader and etc.
**Step-by-Step Manual**
1. Chose :ref:`platform_creating_packages` for platform
1. Choose :ref:`platform_creating_packages` for platform
2. Create :ref:`platform_creating_manifest_file`
3. Create :ref:`platform_creating_build_script`
4. Finish with the :ref:`platform_creating_installation`.
@ -187,89 +187,82 @@ Packages
.. _platform_creating_manifest_file:
Manifest File
-------------
Manifest File ``platform.json``
-------------------------------
A platform manifest file is a `Python <https://www.python.org>`_ script with the
next requirements:
.. code-block:: json
1. The file should have ``.py`` extension
2. The **name of the file** is the **platform name** (lowercase)
3. The source code of this file should contain a ``class`` which describes your
own platform. The name of the ``class`` should start with your
**platform name** (the first letter should be capitalized) + ``Platform``
ending. This ``class`` should be derived from *PlatformIO* ``BasePlatform``
class.
.. warning::
If you are new to *Python* language, please read:
* `Style Guide for Python Code <https://www.python.org/dev/peps/pep-0008>`_.
* A hash sign (#) that is not inside a string literal begins a comment.
All characters after the # and up to the physical line end are part
of the comment and the *Python* interpreter ignores them.
Example of the **test** platform (``test.py``):
.. code-block:: python
import os
from platformio.platforms.base import BasePlatform
class TestPlatform(BasePlatform):
# This is a description of your platform.
# Platformio uses it for the `platformio search / list` commands
"""
My Test platform - test.py
"""
PACKAGES = {
"toolchain-foo": {
# alias is used for quick access to package.
# For example,
# `> platformio install test --without-package=toolchain`
"alias": "toolchain",
# Flag which allows PlatformIO to install this package by
# default via `> platformio install test` command
"default": True
},
"tool-bar": {
"alias": "uploader",
"default": True
},
"framework-baz": {
"default": True
{
"name": "myplatform",
"title": "My Platform",
"description": "My custom development platform",
"url": "http://example.com",
"homepage": "http://platformio.org/platforms/myplatform",
"license": {
"type": "Apache-2.0",
"url": "http://opensource.org/licenses/apache2.0.php"
},
"engines": {
"platformio": "~3.0.0",
"scons": ">=2.3.0,<2.6.0"
},
"repository": {
"type": "git",
"url": "https://github.com/platformio/platform-myplatform.git"
},
"version": "0.0.0",
"packageRepositories": [
"https://dl.bintray.com/platformio/dl-packages/manifest.json",
"https://sourceforge.net/projects/platformio-storage/files/packages/manifest.json/download",
"http://dl.platformio.org/packages/manifest.json",
{
"framework-%FRAMEWORK_NAME_1%": [
{
"url": "http://dl.example.com/packages/framework-%FRAMEWORK_NAME_1%-1.10607.0.tar.gz",
"sha1": "adce2cd30a830d71cb6572575bf08461b7b73c07",
"version": "1.10607.0",
"system": "*"
}
]
}
def get_build_script(self):
""" Returns a path to build script """
# You can return static path
#return "/path/to/test-builder.py"
# or detect dynamically if `test-builder.py` is located in the same
# folder with `test.py`
return os.path.join(
os.path.dirname(os.path.realpath(__file__)),
"test-builder.py"
)
],
"frameworks": {
"%FRAMEWORK_NAME_1%": {
"package": "framework-%FRAMEWORK_NAME_1%",
"script": "builder/frameworks/%FRAMEWORK_NAME_1%.py"
},
"%FRAMEWORK_NAME_N%": {
"package": "framework-%FRAMEWORK_NAME_N%",
"script": "builder/frameworks/%FRAMEWORK_NAME_N%.py"
}
},
"packages": {
"toolchain-gccarmnoneeabi": {
"type": "toolchain",
"version": ">=1.40803.0,<1.40805.0"
},
"framework-%FRAMEWORK_NAME_1%": {
"type": "framework",
"optional": true,
"version": "~1.10607.0"
},
"framework-%FRAMEWORK_NAME_N%": {
"type": "framework",
"optional": true,
"version": "~1.117.0"
}
}
}
.. _platform_creating_build_script:
Build Script
------------
Build Script ``main.py``
------------------------
Platform's build script is based on a next-generation build tool named
`SCons <http://www.scons.org>`_. PlatformIO has own built-in firmware builder
``env.BuildProgram`` with the nested libraries search. Please look into a
base template of ``test-builder.py``.
``env.BuildProgram`` with the deep libraries search. Please look into a
base template of ``main.py``.
.. code-block:: python
@ -347,15 +340,6 @@ base template of ``test-builder.py``.
Default(target_bin)
Please look into the examples with built-in scripts for the popular
platforms:
* `baseavr.py <https://github.com/platformio/platformio/blob/develop/platformio/builder/scripts/baseavr.py>`_
* `basearm.py <https://github.com/platformio/platformio/blob/develop/platformio/builder/scripts/basearm.py>`_
* `atmelavr.py <https://github.com/platformio/platformio/blob/develop/platformio/builder/scripts/atmelavr.py>`_
* `timsp430.py <https://github.com/platformio/platformio/blob/develop/platformio/builder/scripts/timsp430.py>`_
* `ststm32.py <https://github.com/platformio/platformio/blob/develop/platformio/builder/scripts/ststm32.py>`_
.. _platform_creating_installation:
Installation
@ -363,126 +347,17 @@ Installation
1. Create ``platforms`` directory in :ref:`projectconf_pio_home_dir` if it
doesn't exist.
2. Copy ``test.py`` and ``test-builder.py`` files to ``platforms`` directory.
3. Search available platforms via :ref:`cmd_platforms_search` command. You should see
``test`` platform.
4. Install ``test`` platform via :ref:`cmd_platforms_install` command.
2. Create ``myplatform`` directory in ``platforms``
3. Copy ``platform.json`` and ``builder/main.py`` files to ``myplatform`` directory.
4. Search available platforms via :ref:`cmd_platform_search` command. You
should see ``myplatform`` platform.
5. Install ``myplatform`` platform via :ref:`cmd_platform_install` command.
Now, you can use ``test`` for the :ref:`projectconf_env_platform` option in
:ref:`projectconf`.
Now, you can use ``myplatform`` for the :ref:`projectconf_env_platform`
option in :ref:`projectconf`.
Example
-------
Let's use the real example which was requested by our user in `issue 175 <https://github.com/platformio/platformio/issues/175>`_. Need to add support for uploading firmware using GDB to
:ref:`platform_ststm32`.
First of all, need to create new folder ``platforms`` in :ref:`projectconf_pio_home_dir`
and copy there two files:
1. Platform manifest file ``ststm32gdb.py`` with the next content:
.. code-block:: python
import os
from platformio.platforms.ststm32 import Ststm32Platform
class Ststm32gdbPlatform(Ststm32Platform):
"""
ST STM32 using GDB as uploader
http://www.st.com/web/en/catalog/mmc/FM141/SC1169?sc=stm32
"""
def get_build_script(self):
return os.path.join(
os.path.dirname(os.path.realpath(__file__)),
"ststm32gdb-builder.py"
)
2. Build script file ``ststm32gdb-builder.py`` with the next content:
.. code-block:: python
"""
Builder for ST STM32 Series ARM microcontrollers with GDB upload.
"""
from os.path import join
from SCons.Script import (COMMAND_LINE_TARGETS, AlwaysBuild, Default,
DefaultEnvironment, SConscript)
env = DefaultEnvironment()
SConscript(env.subst(join("$PIOBUILDER_DIR", "scripts", "basearm.py")))
env.Replace(
UPLOADER=join(
"$PIOPACKAGES_DIR", "toolchain-gccarmnoneeabi",
"bin", "arm-none-eabi-gdb"
),
UPLOADERFLAGS=[
join("$BUILD_DIR", "firmware.elf"),
"-batch",
"-x", join("$PROJECT_DIR", "upload.gdb")
],
UPLOADCMD="$UPLOADER $UPLOADERFLAGS"
)
env.Append(
CPPDEFINES=[
"${BOARD_OPTIONS['build']['variant'].upper()}"
],
LINKFLAGS=[
"-nostartfiles",
"-nostdlib"
]
)
#
# Target: Build executable and linkable firmware
#
target_elf = env.BuildProgram()
#
# Target: Build the .bin file
#
if "uploadlazy" in COMMAND_LINE_TARGETS:
target_firm = join("$BUILD_DIR", "firmware.bin")
else:
target_firm = env.ElfToBin(join("$BUILD_DIR", "firmware"), target_elf)
#
# Target: Print binary size
#
target_size = env.Alias("size", target_elf, "$SIZEPRINTCMD")
AlwaysBuild(target_size)
#
# Target: Upload by default .bin file
#
upload = env.Alias(
["upload", "uploadlazy"], target_firm, "$UPLOADCMD")
AlwaysBuild(upload)
#
# Target: Define targets
#
Default([target_firm, target_size])
Now, we should see ``ststm32gdb`` platform using :ref:`cmd_platforms_search` command output
and can install it via :ref:`platformio platforms install ststm32gdb <cmd_platforms_install>` command.
Examples
--------
Please take a look at the source code of
`PlatformIO Development Platforms <https://github.com/platformio?query=platform->`_.

2
docs/platforms/custom_platform_and_board.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/embedded_boards.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/espressif.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/espressif_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/freescalekinetis.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/index.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/intel_arc32.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/lattice_ice40.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/linux_arm.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/linux_i686.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/linux_x86_64.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/microchippic32.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/native.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/nordicnrf51.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/nordicnrf51_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/nxplpc.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/siliconlabsefm32.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/ststm32.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/ststm32_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/teensy.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/teensy_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/timsp430.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/timsp430_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/titiva.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

2
docs/platforms/titiva_extra.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

399
docs/platforms/unit_testing.rst Normal file
View File

@ -0,0 +1,399 @@
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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.
.. _unit_testing:
Unit Testing
============
.. versionadded:: 3.0 (PlatformIO Plus)
`Unit Testing (wiki) <https://en.wikipedia.org/wiki/Unit_testing>`_
is a software testing method by which individual units of source code, sets
of one or more MCU program modules together with associated control data,
usage procedures, and operating procedures, are tested to determine whether
they are fit for use. Unit testing finds problems early in the development cycle.
PlatformIO Test System is very interesting for embedded development.
It allows you to write tests locally and run them directly on the target
device (hardware unit testing). Also, you will be able to run the same tests
on the different target devices (:ref:`embedded_boards`).
PlatformIO Test System consists of:
* Project builder
* Test builder
* Firmware uploader
* Test processor
There is special command :ref:`cmd_test` to run tests from PlatformIO Project.
.. contents::
.. _unit_testing_design:
Design
------
PlatformIO Test System design is based on a few isolated components:
1. **Main program**. Contains the independent modules, procedures,
functions or methods that will be the target candidates (TC) for testing.
2. **Unit test**. This a small independent program that is intended to
re-use TC from the main program and apply tests for them.
3. **Test processor**. The set of approaches and tools that will be used
to apply test for the environments from :ref:`projectconf`.
Workflow
--------
1. Create PlatformIO project using :ref:`cmd_init` command.
2. Place source code of main program to ``src`` directory.
3. Wrap ``main()`` or ``setup()/loop()`` methods of main program in ``UNIT_TEST``
guard:
.. code-block:: c
/**
* Arduino Wiring-based Framework
*/
#ifndef UNIT_TEST
void setup () {
// some code...
}
void loop () {
// some code...
}
#endif
/**
* Generic C/C++
*/
#ifndef UNIT_TEST
int main() {
// setup code...
while (1) {
// loop code...
}
}
#endif
4. Create ``test`` directory in the root of project. See :ref:`projectconf_pio_test_dir`.
5. Write test using :ref:`unit_testing_api`. The each test is a small
independent program with own ``main()`` or ``setup()/loop()`` methods. Also,
test should start from ``UNITY_BEGIN()`` and finish with ``UNITY_END()``.
6. Place test to ``test`` directory. If you have more than one test, split them
into sub-folders. For example, ``test/test_1/*.[c,cpp,h]``,
``test_N/*.[c,cpp,h]``, etc. If no such directory in ``test`` folder, then
PlatformIO Test System will treat the source code of ``test`` folder
as SINGLE test.
7. Run tests using :ref:`cmd_test` command.
.. _unit_testing_api:
Test API
--------
The summary of `Unity Test API <https://github.com/ThrowTheSwitch/Unity#unity-test-api>`_:
* `Running Tests <https://github.com/ThrowTheSwitch/Unity#running-tests>`_
- ``RUN_TEST(func, linenum)``
* `Ignoring Tests <https://github.com/ThrowTheSwitch/Unity#ignoring-tests>`_
- ``TEST_IGNORE()``
- ``TEST_IGNORE_MESSAGE (message)``
* `Aborting Tests <https://github.com/ThrowTheSwitch/Unity#aborting-tests>`_
- ``TEST_PROTECT()``
- ``TEST_ABORT()``
* `Basic Validity Tests <https://github.com/ThrowTheSwitch/Unity#basic-validity-tests>`_
- ``TEST_ASSERT_TRUE(condition)``
- ``TEST_ASSERT_FALSE(condition)``
- ``TEST_ASSERT(condition)``
- ``TEST_ASSERT_UNLESS(condition)``
- ``TEST_FAIL()``
- ``TEST_FAIL_MESSAGE(message)``
* `Numerical Assertions: Integers <https://github.com/ThrowTheSwitch/Unity#numerical-assertions-integers>`_
- ``TEST_ASSERT_EQUAL_INT(expected, actual)``
- ``TEST_ASSERT_EQUAL_INT8(expected, actual)``
- ``TEST_ASSERT_EQUAL_INT16(expected, actual)``
- ``TEST_ASSERT_EQUAL_INT32(expected, actual)``
- ``TEST_ASSERT_EQUAL_INT64(expected, actual)``
- ``TEST_ASSERT_EQUAL_UINT(expected, actual)``
- ``TEST_ASSERT_EQUAL_UINT8(expected, actual)``
- ``TEST_ASSERT_EQUAL_UINT16(expected, actual)``
- ``TEST_ASSERT_EQUAL_UINT32(expected, actual)``
- ``TEST_ASSERT_EQUAL_UINT64(expected, actual)``
- ``TEST_ASSERT_EQUAL_HEX(expected, actual)``
- ``TEST_ASSERT_EQUAL_HEX8(expected, actual)``
- ``TEST_ASSERT_EQUAL_HEX16(expected, actual)``
- ``TEST_ASSERT_EQUAL_HEX32(expected, actual)``
- ``TEST_ASSERT_EQUAL_HEX64(expected, actual)``
- ``TEST_ASSERT_EQUAL_HEX8_ARRAY(expected, actual, elements)``
- ``TEST_ASSERT_EQUAL(expected, actual)``
- ``TEST_ASSERT_INT_WITHIN(delta, expected, actual)``
* `Numerical Assertions: Bitwise <https://github.com/ThrowTheSwitch/Unity#numerical-assertions-bitwise>`_
- ``TEST_ASSERT_BITS(mask, expected, actual)``
- ``TEST_ASSERT_BITS_HIGH(mask, actual)``
- ``TEST_ASSERT_BITS_LOW(mask, actual)``
- ``TEST_ASSERT_BIT_HIGH(mask, actual)``
- ``TEST_ASSERT_BIT_LOW(mask, actual)``
* `Numerical Assertions: Floats <https://github.com/ThrowTheSwitch/Unity#numerical-assertions-floats>`_
- ``TEST_ASSERT_FLOAT_WITHIN(delta, expected, actual)``
- ``TEST_ASSERT_EQUAL_FLOAT(expected, actual)``
- ``TEST_ASSERT_EQUAL_DOUBLE(expected, actual)``
* `String Assertions <https://github.com/ThrowTheSwitch/Unity#string-assertions>`_
- ``TEST_ASSERT_EQUAL_STRING(expected, actual)``
- ``TEST_ASSERT_EQUAL_STRING_LEN(expected, actual, len)``
- ``TEST_ASSERT_EQUAL_STRING_MESSAGE(expected, actual, message)``
- ``TEST_ASSERT_EQUAL_STRING_LEN_MESSAGE(expected, actual, len, message)``
* `Pointer Assertions <https://github.com/ThrowTheSwitch/Unity#pointer-assertions>`_
- ``TEST_ASSERT_NULL(pointer)``
- ``TEST_ASSERT_NOT_NULL(pointer)``
* `Memory Assertions <https://github.com/ThrowTheSwitch/Unity#pointer-assertions>`_
- ``TEST_ASSERT_EQUAL_MEMORY(expected, actual, len)``
Example
-------
1. Please follow to :ref:`quickstart` and create "Blink Project". According
to the Unit Testing :ref:`unit_testing_design` it is the **Main program**.
2. Create ``test`` directory in that project (on the same level as ``src``)
and place ``test_main.cpp`` file to it (the source code is located below).
3. Wrap ``setup()`` and ``loop()`` methods of main program in ``UNIT_TEST``
guard.
4. Run tests using :ref:`cmd_test` command.
Project structure
~~~~~~~~~~~~~~~~~
.. code-block:: bash
project_dir
├── lib
│   └── readme.txt
├── platformio.ini
├── src
│   └── main.cpp
└── test
└── test_main.cpp
Source files
~~~~~~~~~~~~
* ``platformio.ini``
.. code-block:: ini
; Project Configuration File
; Docs: http://docs.platformio.org/en/latest/projectconf.html
[env:uno]
platform = atmelavr
framework = arduino
board = uno
[env:nodemcu]
platform = espressif
framework = arduino
board = nodemcu
[env:teensy31]
platform = teensy
framework = arduino
board = teensy31
* ``src/main.cpp``
.. code-block:: cpp
/*
* Blink
* Turns on an LED on for one second,
* then off for one second, repeatedly.
*/
#include "Arduino.h"
#ifndef UNIT_TEST // IMPORTANT LINE!
void setup()
{
// initialize LED digital pin as an output.
pinMode(LED_BUILTIN, OUTPUT);
}
void loop()
{
// turn the LED on (HIGH is the voltage level)
digitalWrite(LED_BUILTIN, HIGH);
// wait for a second
delay(1000);
// turn the LED off by making the voltage LOW
digitalWrite(LED_BUILTIN, LOW);
// wait for a second
delay(1000);
}
#endif // IMPORTANT LINE!
* ``test/test_main.cpp``
.. code-block:: cpp
#include <Arduino.h>
#include <unity.h>
#ifdef UNIT_TEST
// void setUp(void) {
// // set stuff up here
// }
// void tearDown(void) {
// // clean stuff up here
// }
void test_led_builtin_pin_number(void) {
TEST_ASSERT_EQUAL(LED_BUILTIN, 13);
}
void test_led_state_high(void) {
digitalWrite(LED_BUILTIN, HIGH);
TEST_ASSERT_EQUAL(digitalRead(LED_BUILTIN), HIGH);
}
void test_led_state_low(void) {
digitalWrite(LED_BUILTIN, LOW);
TEST_ASSERT_EQUAL(digitalRead(LED_BUILTIN), LOW);
}
void setup() {
UNITY_BEGIN(); // IMPORTANT LINE!
RUN_TEST(test_led_builtin_pin_number);
pinMode(LED_BUILTIN, OUTPUT);
}
uint8_t i = 0;
uint8_t max_blinks = 5;
void loop() {
if (i < max_blinks)
{
RUN_TEST(test_led_state_high);
delay(500);
RUN_TEST(test_led_state_low);
delay(500);
i++;
}
else if (i == max_blinks) {
UNITY_END(); // stop unit testing
}
}
#endif
Test results
~~~~~~~~~~~~
.. code-block:: bash
> platformio test --environment uno
Collected 1 items
========================= [test::*] Building... (1/3) ==============================
[Wed Jun 15 00:27:42 2016] Processing uno (platform: atmelavr, board: uno, framework: arduino)
--------------------------------------------------------------------------------------------------------------------------------------------------------------------
avr-g++ -o .pioenvs/uno/test/test_main.o -c -fno-exceptions -fno-threadsafe-statics -std=gnu++11 -g -Os -Wall -ffunction-sections -fdata-sections -mmcu=atmega328p -DF_CPU=16000000L -DPLATFORMIO=030000 -DARDUINO_ARCH_AVR -DARDUINO_AVR_UNO -DARDUINO=10608 -DUNIT_TEST -DUNITY_INCLUDE_CONFIG_H -I.pioenvs/uno/FrameworkArduino -I.pioenvs/uno/FrameworkArduinoVariant -Isrc -I.pioenvs/uno/UnityTestLib test/test_main.cpp
avr-g++ -o .pioenvs/uno/firmware.elf -Os -mmcu=atmega328p -Wl,--gc-sections,--relax .pioenvs/uno/src/main.o .pioenvs/uno/test/output_export.o .pioenvs/uno/test/test_main.o -L.pioenvs/uno -Wl,--start-group .pioenvs/uno/libUnityTestLib.a .pioenvs/uno/libFrameworkArduinoVariant.a .pioenvs/uno/libFrameworkArduino.a -lm -Wl,--end-group
avr-objcopy -O ihex -R .eeprom .pioenvs/uno/firmware.elf .pioenvs/uno/firmware.hex
avr-size --mcu=atmega328p -C -d .pioenvs/uno/firmware.elf
AVR Memory Usage
----------------
Device: atmega328p
Program: 4702 bytes (14.3% Full)
(.text + .data + .bootloader)
Data: 460 bytes (22.5% Full)
(.data + .bss + .noinit)
========================= [test::*] Uploading... (2/3) ==============================
[Wed Jun 15 00:27:43 2016] Processing uno (platform: atmelavr, board: uno, framework: arduino)
--------------------------------------------------------------------------------------------------------------------------------------------------------------------
avr-g++ -o .pioenvs/uno/firmware.elf -Os -mmcu=atmega328p -Wl,--gc-sections,--relax .pioenvs/uno/src/main.o .pioenvs/uno/test/output_export.o .pioenvs/uno/test/test_main.o -L.pioenvs/uno -Wl,--start-group .pioenvs/uno/libUnityTestLib.a .pioenvs/uno/libFrameworkArduinoVariant.a .pioenvs/uno/libFrameworkArduino.a -lm -Wl,--end-group
MethodWrapper([".pioenvs/uno/firmware.elf"], [".pioenvs/uno/src/main.o", ".pioenvs/uno/test/output_export.o", ".pioenvs/uno/test/test_main.o"])
Check program size...
text data bss dec hex filename
4464 238 222 4924 133c .pioenvs/uno/firmware.elf
BeforeUpload(["upload"], [".pioenvs/uno/firmware.hex"])
Looking for upload port/disk...
avr-size --mcu=atmega328p -C -d .pioenvs/uno/firmware.elf
Auto-detected: /dev/cu.usbmodemFD131
avrdude -v -p atmega328p -C "/Users/ikravets/.platformio/packages/tool-avrdude/avrdude.conf" -c arduino -b 115200 -P "/dev/cu.usbmodemFD131" -D -U flash:w:.pioenvs/uno/firmware.hex:i
[...]
avrdude done. Thank you.
========================= [test::*] Testing... (3/3) =========================
If you do not see any output for the first 10 secs, please reset board (press reset button)
test/test_main.cpp:30:test_led_builtin_pin_number PASSED
test/test_main.cpp:41:test_led_state_high PASSED
test/test_main.cpp:43:test_led_state_low PASSED
test/test_main.cpp:41:test_led_state_high PASSED
test/test_main.cpp:43:test_led_state_low PASSED
test/test_main.cpp:41:test_led_state_high PASSED
test/test_main.cpp:43:test_led_state_low PASSED
test/test_main.cpp:41:test_led_state_high PASSED
test/test_main.cpp:43:test_led_state_low PASSED
test/test_main.cpp:41:test_led_state_high PASSED
test/test_main.cpp:43:test_led_state_low PASSED
-----------------------
11 Tests 0 Failures 0 Ignored
========================= [TEST SUMMARY] =====================================
test:*/env:uno PASSED
========================= [PASSED] Took 13.35 seconds ========================
-------
For the other examples and source code please follow to
`PlatformIO Unit Testing Examples <https://github.com/platformio/platformio-examples/tree/feature/platformio-30/unit-testing>`_ repository.

2
docs/platforms/windows_x86.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

281
docs/projectconf.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -44,8 +44,8 @@ Options
``home_dir``
^^^^^^^^^^^^
Is used to store platform toolchains, frameworks, external libraries,
service data and etc.
Is used to store platform toolchains, frameworks, global libraries for
:ref: `ldf`, service data and etc.
A default value is User's home directory:
@ -60,18 +60,59 @@ This option can be overridden by global environment variable
``lib_dir``
^^^^^^^^^^^
This directory is used to store external libraries downloaded by
:ref:`librarymanager`.
You can put here your own/private libraries. The source code of each library
should be placed in separate directory, like
``lib/private_lib/[here are source files]``. This directory has the highest
priority for :ref:`ldf`.
A default value is ``%home_dir%/lib``.
A default value is ``lib`` that means that folder is located in the root of
project.
This option can be overridden by global environment variable
:envvar:`PLATFORMIO_LIB_DIR`.
.. note::
You can put here your own/private libraries. The source code of each
library should be placed in separate directory. For example,
``%lib_dir%/private_lib/[here are source files]``.
For example, see how can be organized ``Foo`` and ``Bar`` libraries:
.. code::
|--lib
| |--Bar
| | |--docs
| | |--examples
| | |--src
| | |- Bar.c
| | |- Bar.h
| |--Foo
| | |- Foo.c
| | |- Foo.h
|- platformio.ini
|--src
|- main.c
Then in ``src/main.c`` you should use:
.. code-block:: c
#include <Foo.h>
#include <Bar.h>
// rest H/C/CPP code
PlatformIO will find your libraries automatically, configure preprocessor's
include paths and build them.
.. _projectconf_pio_libdeps_dir:
``libdeps_dir``
^^^^^^^^^^^^^^^
Internal storage where :ref:`librarymanager` will install project dependencies
(:ref:`projectconf_lib_deps`). A default value is ``.piolibdeps`` that means
that folder is located in the root of project.
This option can be overridden by global environment variable
:envvar:`PLATFORMIO_LIBDEPS_DIR`.
.. _projectconf_pio_src_dir:
@ -79,10 +120,8 @@ This option can be overridden by global environment variable
^^^^^^^^^^^
A path to project's source directory. PlatformIO uses it for :ref:`cmd_run`
command.
A default value is ``src`` which means that folder is located in the root of
project.
command. A default value is ``src`` that means that folder is located in the
root of project.
This option can be overridden by global environment variable
:envvar:`PLATFORMIO_SRC_DIR`.
@ -110,14 +149,14 @@ fast!
then PlatformIO will remove this folder automatically. It will be created on the
next build operation.
A default value is ``.pioenvs`` which means that folder is located in the root of
A default value is ``.pioenvs`` that means that folder is located in the root of
project.
This option can be overridden by global environment variable
:envvar:`PLATFORMIO_ENVS_DIR`.
.. note::
If you have any problems with building your Project environmets which
If you have any problems with building your Project environments which
are defined in :ref:`projectconf`, then **TRY TO DELETE** this folder. In
this situation you will remove all cached files without any risk.
@ -127,13 +166,24 @@ This option can be overridden by global environment variable
^^^^^^^^^^^^
Data directory to store contents and :ref:`platform_espressif_uploadfs`.
A default value is ``data`` which means that folder is located in the root of
A default value is ``data`` that means that folder is located in the root of
project.
This option can be overridden by global environment variable
:envvar:`PLATFORMIO_DATA_DIR`.
.. _projectconf_pio_test_dir:
``test_dir``
^^^^^^^^^^^^
Directory where :ref:`unit_testing` engine will look for the tests.
A default value is ``test`` that means that folder is located in the root of
project.
This option can be overridden by global environment variable
:envvar:`PLATFORMIO_TEST_DIR`.
.. _projectconf_pio_env_default:
``env_default``
@ -193,20 +243,48 @@ For example, ``[env:hello_world]``.
General options
~~~~~~~~~~~~~~~
.. contents::
:local:
.. _projectconf_env_platform:
``platform``
^^^^^^^^^^^^
:ref:`platforms` type.
:ref:`platforms` name.
PlatformIO allows to use specific version of platform using
`Semantic Versioning <http://semver.org>`_ (X.Y.Z=MAJOR.MINOR.PATCH).
Version specifications can take any of the following forms:
* ``0.1.2``: an exact version number. Use only this exact version
* ``^0.1.2``: any compatible version (exact version for ``0.x.x`` versions
* ``~0.1.2``: any version with the same major and minor versions, and an
equal or greater patch version
* ``>0.1.2``: any version greater than ``0.1.2``. ``>=``, ``<``, and ``<=``
are also possible
* ``>0.1.0,!=0.2.0,<0.3.0``: any version greater than ``0.1.0``, not equal to
``0.2.0`` and less than ``0.3.0``
Examples:
.. code-block:: ini
[env:the_latest_version]
platform = atmelavr
[env:specific_major_version]
platform = atmelavr@^0.1.2
[env:specific_major_and_minor_version]
platform = atmelavr@~0.1.2
.. _projectconf_env_framework:
``framework``
^^^^^^^^^^^^^
:ref:`Framework <frameworks>` type.
:ref:`frameworks` name.
The multiple frameworks are allowed, split them with comma ``,`` separator.
@ -227,6 +305,9 @@ using `PlatformIO Embedded Boards Explorer <http://platformio.org/boards>`_.
Board options
~~~~~~~~~~~~~
.. contents::
:local:
``board_mcu``
^^^^^^^^^^^^^
@ -271,8 +352,11 @@ This option isn't available for the all development platforms. The only
Flash chip interface mode. This option isn't available for the all development
platforms. The only :ref:`platform_espressif` supports it.
Building options
~~~~~~~~~~~~~~~~
Build options
~~~~~~~~~~~~~
.. contents::
:local:
.. _projectconf_build_flags:
@ -388,6 +472,8 @@ but will be applied only for the project source code from
This option can be set by global environment variable
:envvar:`PLATFORMIO_SRC_BUILD_FLAGS`.
.. _projectconf_build_unflags:
``build_unflags``
^^^^^^^^^^^^^^^^^
@ -416,7 +502,7 @@ be applied in theirs order.
By default, ``src_filter`` is predefined to
``+<*> -<.git/> -<svn/> -<example/> -<examples/> -<test/> -<tests/>``,
which means "includes ALL files, then
that means "includes ALL files, then
exclude ``.git`` and ``svn`` repository folders, ``example`` ... folder.
This option can be set by global environment variable
@ -450,9 +536,7 @@ Example, specify own upload command for :ref:`platform_atmelavr`:
.. code-block:: python
from SCons.Script import DefaultEnvironment
env = DefaultEnvironment()
Import('env')
env.Replace(UPLOADHEXCMD='"$UPLOADER" ${ARGUMENTS.get("custom_option")} --uploader --flags')
@ -491,8 +575,11 @@ The list with available targets is located in :option:`platformio run --target`.
When no targets are defined, *PlatformIO* will build only sources by default.
Uploading options
~~~~~~~~~~~~~~~~~
Upload options
~~~~~~~~~~~~~~
.. contents::
:local:
.. _projectconf_upload_port:
@ -549,65 +636,149 @@ development platforms. The only :ref:`platform_espressif` supports it.
Library options
~~~~~~~~~~~~~~~
``lib_install``
^^^^^^^^^^^^^^^
.. contents::
:local:
Specify dependent libraries which should be installed before environment
process. The only library IDs are allowed. Multiple libraries can be passed
using comma ``,`` sign.
.. _projectconf_lib_deps:
You can obtain library IDs using :ref:`cmd_lib_search` command.
``lib_deps``
^^^^^^^^^^^^
Specify project dependencies that should be installed automatically to
:ref:`projectconf_pio_libdeps_dir` before an environment process.
Multiple dependencies are allowed (multi-lines).
**Valid forms**
.. code-block:: ini
[env:***]
lib_deps =
LIBRARY_1
LIBRARY_2
LIBRARY_N
The each line with ``LIBRARY_1... LIBRARY_N`` will be passed automatically to
:ref:`cmd_lib_install` command. Please follow to :ref:`cmd_lib_install` for
detailed documentation about possible values.
Example:
.. code-block:: ini
[env:depends_on_some_libs]
lib_install = 1,13,19
[env:depends_on_some_libs]
lib_deps =
1
PubSubClient
Json@~5.6,!=5.4
https://github.com/gioblu/PJON.git@v2.0
https://github.com/me-no-dev/ESPAsyncTCP.git
``lib_use``
^^^^^^^^^^^
.. _projectconf_lib_force:
Specify libraries which should be used by ``Library Dependency Finder (LDF)`` with
the highest priority.
``lib_force``
^^^^^^^^^^^^^
.. seealso::
Please make sure to read :ref:`ldf` guide first.
Force Library Dependency Finder to depend on the specified library if it even
is not included in the project source code. Also, this library will be
processed in the first order.
The correct value for this option is library name (not folder name). In the
most cases, library name is pre-defined in manifest file
(:ref:`library_config`, ``library.properties``, ``module.json``). The multiple
library names are allowed, split them with comma ``,`` separator.
Example:
.. code-block:: ini
[env:libs_with_highest_priority]
lib_use = OneWire_ID1,SPI
[env:myenv]
lib_force = OneWire, SPI
.. _projectconf_lib_ignore:
``lib_ignore``
^^^^^^^^^^^^^^
Specify libraries which should be ignored by ``Library Dependency Finder (LDF)``
.. seealso::
Please make sure to read :ref:`ldf` guide first.
Specify libraries which should be ignored by Library Dependency Finder.
The correct value for this option is library name (not
folder name). In the most cases, library name is pre-defined in manifest file
(:ref:`library_config`, ``library.properties``, ``module.json``). The multiple
library names are allowed, split them with comma ``,`` separator.
Example:
.. code-block:: ini
[env:ignore_some_libs]
lib_ignore = SPI,EngduinoV3_ID123
lib_ignore = SPI, Ethernet
``lib_dfcyclic``
^^^^^^^^^^^^^^^^
.. _projectconf_lib_extra_dirs:
Control cyclic (recursive) behavior for ``Library Dependency Finder (LDF)``.
By default, this option is turned OFF (``lib_dfcyclic=False``) and means that
``LDF`` will find only libraries which are included in source files from the
project :ref:`projectconf_pio_src_dir`.
``lib_extra_dirs``
^^^^^^^^^^^^^^^^^^
If you want to enable cyclic (recursive, nested) search, please set this option
to ``True``. Founded library will be treated like a new source files and
``LDF`` will search dependencies for it.
.. versionadded:: 3.0
.. seealso::
Please make sure to read :ref:`ldf` guide first.
A list with extra directories/storages where Library Dependency Finder will
look for dependencies. Multiple paths are allowed. Please separate them
using comma ``,`` symbol.
This option can be set by global environment variable
:envvar:`PLATFORMIO_LIB_EXTRA_DIRS`.
.. warning::
This is a not direct path to library with source code. It should be the path
to storage that contains libraries grouped by folders. For example,
``/extra/lib/storage/`` but not ``/extra/lib/storage/MyLibrary``.
Example:
.. code-block:: ini
[env:libs_with_enabled_ldf_cyclic]
lib_dfcyclic = True
[env:custom_lib_dirs]
lib_extra_dirs = /path/to/private/dir1,/path/to/private/dir2
.. _projectconf_lib_ldf_mode:
``lib_ldf_mode``
^^^^^^^^^^^^^^^^
.. versionadded:: 3.0
.. seealso::
Please make sure to read :ref:`ldf` guide first.
Library Dependency Finder starts work from analyzing source files of the
project (:ref:`projectconf_pio_src_dir`) and can work in the different modes
(see :ref:`ldf_mode`).
By default, this value is set to ``lib_ldf_mode = 2`` and means that LDF
will parse ALL C/C++ source code of the project and will parse ALL C/C++
source code of the each dependent library (recursively).
.. _projectconf_lib_compat_mode:
``lib_compat_mode``
^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.0
.. seealso::
Please make sure to read :ref:`ldf` guide first.
Library compatibility mode allows to control strictness of Library Dependency
Finder. More details :ref:`ldf_compat_mode`.
By default, this value is set to ``lib_compat_mode = 1`` and means that LDF
will check only for framework compatibility.
-----------

5
docs/quickstart.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -82,11 +82,10 @@ According to the table above the ID/TYPE for Teensy 3.1 is ``teensy31``. Also,
the ID for Arduino UNO is ``uno`` and for NodeMCU 1.0 (ESP-12E Module)
is ``nodemcuv2``.
Initialize Project
------------------
PlatformIO ecosystem contains huge database with pre-configured settings for the
PlatformIO ecosystem contains big database with pre-configured settings for the
most popular embedded boards. It helps you to forget about installing
toolchains, writing build scripts or configuring uploading process. Just tell
PlatformIO the Board ID and you will receive full working project with

7
docs/userguide/cmd_boards.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -33,6 +33,11 @@ Options
.. program:: platformio boards
.. option::
--installed
List boards only from the installed platforms
.. option::
--json-output

8
docs/userguide/cmd_ci.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -112,8 +112,10 @@ Buid project using pre-configured :ref:`projectconf`.
.. option::
-v, --verbose
Shows details about the results of processing environments. More details
:option:`platformio run --verbose`
Shows detailed information when processing environments.
This option can be set globally using :ref:`setting_force_verbose` setting
or by environment variable :envvar:`PLATFORMIO_SETTING_FORCE_VERBOSE`.
Examples
--------

2
docs/userguide/cmd_init.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

163
docs/userguide/cmd_run.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -64,7 +64,9 @@ Pre-built targets:
--upload-port
Upload port of embedded board. To print all available ports use
:ref:`cmd_serialports` command
:ref:`cmd_serialports` command.
If upload port is not specified, PlatformIO will try to detect it automatically.
.. option::
-d, --project-dir
@ -75,17 +77,10 @@ to current working directory (``CWD``).
.. option::
-v, --verbose
Shows details about the results of processing environments. Each instance of
``--verbose`` on the command line increases the verbosity level by one, so if
you need more details on the output, specify it twice.
Shows detailed information when processing environments.
There 3 levels of verbosity:
1. ``-v`` - output errors only
2. ``-vv`` - output errors and warnings
3. ``-vvv`` - output errors, warnings and additional information
By default, verbosity level is set to 3 (maximum information).
This option can be set globally using :ref:`setting_force_verbose` setting
or by environment variable :envvar:`PLATFORMIO_SETTING_FORCE_VERBOSE`.
.. option::
--disable-auto-clean
@ -101,17 +96,34 @@ Examples
.. code-block:: bash
$ platformio run
Processing arduino_pro5v environment:
scons: `.pioenvs/arduino_pro5v/firmware.elf' is up to date.
scons: `.pioenvs/arduino_pro5v/firmware.hex' is up to date.
[Sun Jul 17 00:09:16 2016] Processing uno (platform: atmelavr, board: uno, framework: arduino)
-----------------------------------------------------------------------------------------------
Looking for dependencies...
Collecting 32 compatible libraries
Processing src/main.cpp
Processing .pioenvs/uno/libFrameworkArduinoVariant.a
Processing .platformio/packages/framework-arduinoavr/cores/arduino/CDC.cpp
Processing .platformio/packages/framework-arduinoavr/cores/arduino/HardwareSerial.cpp
Processing .platformio/packages/framework-arduinoavr/cores/arduino/HardwareSerial0.cpp
...
Processing .platformio/packages/framework-arduinoavr/cores/arduino/wiring_analog.c
Processing .platformio/packages/framework-arduinoavr/cores/arduino/wiring_digital.c
Processing .platformio/packages/framework-arduinoavr/cores/arduino/wiring_pulse.c
Processing .platformio/packages/framework-arduinoavr/cores/arduino/wiring_shift.c
Processing .pioenvs/uno/libFrameworkArduino.a
Processing .pioenvs/uno/firmware.elf
Processing .pioenvs/uno/firmware.hex
Processing size
AVR Memory Usage
----------------
Device: atmega328p
Processing launchpad_msp430g2 environment:
scons: `.pioenvs/launchpad_msp430g2/firmware.elf' is up to date.
scons: `.pioenvs/launchpad_msp430g2/firmware.hex' is up to date.
Program: 1034 bytes (3.2% Full)
(.text + .data + .bootloader)
Data: 9 bytes (0.4% Full)
(.data + .bss + .noinit)
Processing launchpad_lm4f120 environment:
scons: `.pioenvs/launchpad_lm4f120/firmware.elf' is up to date.
scons: `.pioenvs/launchpad_lm4f120/firmware.hex' is up to date
2. Process specific environment
@ -119,13 +131,27 @@ Examples
.. code-block:: bash
$ platformio run -e arduino_pro5v -e launchpad_lm4f120
Processing arduino_pro5v environment:
scons: `.pioenvs/arduino_pro5v/firmware.elf' is up to date.
scons: `.pioenvs/arduino_pro5v/firmware.hex' is up to date.
Processing launchpad_lm4f120 environment:
scons: `.pioenvs/launchpad_lm4f120/firmware.elf' is up to date.
scons: `.pioenvs/launchpad_lm4f120/firmware.hex' is up to date.
[Sun Jul 17 00:10:14 2016] Processing nodemcu (platform: espressif, board: nodemcu, framework: arduino)
--------------------------------------------------------------------------------------------------------
Looking for dependencies...
Collecting 29 compatible libraries
Processing src/main.cpp
Processing .pioenvs/nodemcu/libFrameworkArduinoVariant.a
Processing .platformio/packages/framework-arduinoespressif/cores/esp8266/Esp.cpp
...
Processing .platformio/packages/framework-arduinoespressif/cores/esp8266/pgmspace.cpp
Processing .platformio/packages/framework-arduinoespressif/cores/esp8266/setjmp.S
Processing .pioenvs/nodemcu/libFrameworkArduino.a
Processing .platformio/packages/framework-arduinoespressif/tools/sdk/lib/libmesh.a
...
Processing .platformio/packages/framework-arduinoespressif/tools/sdk/lib/libaxtls.a
Processing .platformio/packages/framework-arduinoespressif/tools/sdk/lib/libstdc++.a
Processing .pioenvs/nodemcu/firmware.elf
Processing .platformio/packages/tool-esptool/esptool
Processing .pioenvs/nodemcu/firmware.bin
Processing size
text data bss dec hex filename
221456 884 29496 251836 3d7bc .pioenvs/nodemcu/firmware.elf
3. Process specific target
@ -133,52 +159,49 @@ Examples
.. code-block:: bash
$ platformio run -t clean
Processing arduino_pro5v environment:
Removed .pioenvs/arduino_pro5v/src/main.o
[Sun Jul 17 00:19:36 2016] Processing uno (platform: atmelavr, board: uno, framework: arduino)
----------------------------------------------------------------------------------------------------------------------------------------------------------------
Looking for dependencies...
Collecting 32 compatible libraries
Removed .pioenvs/uno/FrameworkArduino/CDC.o
Removed .pioenvs/uno/FrameworkArduino/HardwareSerial.o
...
Removed .pioenvs/arduino_pro5v/firmware.hex
Processing launchpad_msp430g2 environment:
Removed .pioenvs/launchpad_msp430g2/src/main.o
...
Removed .pioenvs/launchpad_msp430g2/firmware.hex
Processing launchpad_lm4f120 environment:
Removed .pioenvs/launchpad_lm4f120/src/main.o
...
Removed .pioenvs/launchpad_lm4f120/firmware.hex
Removed .pioenvs/uno/libFrameworkArduinoVariant.a
Removed .pioenvs/uno/src/main.o
Removed .pioenvs/uno/libFrameworkArduino.a
Removed .pioenvs/uno/firmware.elf
Removed .pioenvs/uno/firmware.hex
4. Mix environments and targets
.. code-block:: bash
$ platformio run -e launchpad_msp430g2 -t upload
Processing launchpad_msp430g2 environment:
/Users/ikravets/.platformio/timsp430/tools/mspdebug/mspdebug rf2500 --force-reset "prog .pioenvs/launchpad_msp430g2/firmware.hex"
MSPDebug version 0.20 - debugging tool for MSP430 MCUs
Copyright (C) 2009-2012 Daniel Beer <dlbeer@gmail.com>
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Trying to open interface 1 on 009
Initializing FET...
FET protocol version is 30394216
Configured for Spy-Bi-Wire
Sending reset...
Set Vcc: 3000 mV
Device ID: 0x2553
Code start address: 0xc000
Code size : 16384 byte = 16 kb
RAM start address: 0x200
RAM end address: 0x3ff
RAM size : 512 byte = 0 kb
Device: MSP430G2553/G2403
Code memory starts at 0xc000
Number of breakpoints: 2
Chip ID data: 25 53
Erasing...
Programming...
Writing 646 bytes at c000...
Writing 32 bytes at ffe0...
Done, 678 bytes total
$ platformio run -e teensy31 -t upload
[Sun Jul 17 00:27:14 2016] Processing teensy31 (platform: teensy, board: teensy31, framework: arduino)
-------------------------------------------------------------------------------------------------------
Looking for dependencies...
Collecting 25 compatible libraries
Processing src/main.cpp
Processing .platformio/packages/framework-arduinoteensy/cores/teensy3/AudioStream.cpp
Processing .platformio/packages/framework-arduinoteensy/cores/teensy3/DMAChannel.cpp
Processing .platformio/packages/framework-arduinoteensy/cores/teensy3/HardwareSerial1.cpp
...
Processing .platformio/packages/framework-arduinoteensy/cores/teensy3/yield.cpp
Processing .platformio/packages/tool-teensy/teensy_loader_cli
Processing .pioenvs/teensy31/libFrameworkArduino.a
Processing .pioenvs/teensy31/firmware.elf
Check program size...
text data bss dec hex filename
11080 168 2288 13536 34e0 .pioenvs/teensy31/firmware.elf
Processing .pioenvs/teensy31/firmware.hex
Processing upload
Teensy Loader, Command Line, Version 2.0
Read ".pioenvs/teensy31/firmware.hex": 11248 bytes, 4.3% usage
Soft reboot is not implemented for OSX
Waiting for Teensy device...
(hint: press the reset button)
Found HalfKay Bootloader
Read ".pioenvs/teensy31/firmware.hex": 11248 bytes, 4.3% usage
Programming...........
Booting

2
docs/userguide/cmd_serialports.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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

16
docs/userguide/cmd_settings.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -87,6 +87,20 @@ Check for the new PlatformIO interval.
Check for the platform updates interval.
.. _setting_force_verbose:
``force_verbose``
^^^^^^^^^^^^^^^^^
:Default: No
:Values: Yes/No
Force verbose output when processing environments. This setting overrides
* :option:`platformio run --verbose`
* :option:`platformio ci --verbose`
* :option:`platformio test --verbose`
.. _setting_enable_prompts:
``enable_prompts``

98
docs/userguide/cmd_test.rst Normal file
View File

@ -0,0 +1,98 @@
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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_test:
platformio test
===============
.. versionadded:: 3.0
.. contents::
Usage
-----
.. code-block:: bash
platformio test [OPTIONS]
Description
-----------
Run tests from PlatformIO based project. More details about PlatformIO
:ref:`unit_testing`.
This command allows you to apply the tests for the environments specified
in :ref:`projectconf`.
Options
-------
.. program:: platformio test
.. option::
-e, --environment
Process specified environments. More details :option:`platformio run --environment`
.. option::
--skip
Skip over tests where the name matches specified patterns. More than one
option/pattern is allowed.
.. list-table::
:header-rows: 1
* - Pattern
- Meaning
* - ``*``
- matches everything
* - ``?``
- matches any single character
* - ``[seq]``
- matches any character in seq
* - ``[!seq]``
- matches any character not in seq
For example, ``platformio test --skip "mytest*" -i "test[13]"``
.. option::
--upload-port
Upload port of embedded board. To print all available ports use
:ref:`cmd_serialports` command.
If upload port is not specified, PlatformIO will try to detect it automatically.
.. option::
-d, --project-dir
Specify the path to project directory. By default, ``--project-dir`` is equal
to current working directory (``CWD``).
.. option::
-v, --verbose
Shows detailed information when processing environments.
This option can be set globally using :ref:`setting_force_verbose` setting
or by environment variable :envvar:`PLATFORMIO_SETTING_FORCE_VERBOSE`.
Examples
--------
For the examples please follow to :ref:`unit_testing` page.

250
docs/userguide/cmd_update.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-present Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -21,91 +21,215 @@ Usage
.. code-block:: bash
platformio update
platformio update [OPTIONS]
Description
-----------
Check or update installed :ref:`platforms` and
:ref:`Libraries <librarymanager>`
Check or update installed :ref:`platforms` and global
:ref:`Libraries <librarymanager>`. This command is combination of 2 sub-commands:
* :ref:`cmd_platform_update`
* :ref:`cmd_lib_update`
Options
-------
.. program:: platformio update
.. option::
-c, --only-check
Do not update, only check for new version
Examples
--------
.. code-block:: bash
.. code::
$ platformio update
> platformio update
Platform Manager
================
Platform timsp430
--------
Updating timsp430 @ 0.0.0: [Up-to-date]
Updating toolchain-timsp430 @ 1.40603.0: [Up-to-date]
Updating framework-energiamsp430 @ 1.17.0: [Up-to-date]
Updating framework-arduinomsp430 @ 1.10601.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform freescalekinetis
--------
Updating freescalekinetis @ 0.0.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform ststm32
--------
Updating ststm32 @ 0.0.0: [Up-to-date]
Updating framework-libopencm3 @ 1.1.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-stlink @ 1.10200.0: [Up-to-date]
Updating framework-spl @ 1.10201.0: [Up-to-date]
Updating framework-cmsis @ 1.40300.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform lattice_ice40
--------
Updating lattice_ice40 @ 0.0.0: [Up-to-date]
Updating toolchain-icestorm @ 1.7.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform atmelavr
--------
Updating toolchain-atmelavr package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating tool-avrdude package:
Versions: Current=2, Latest=2 [Up-to-date]
Updating framework-arduinoavr package:
Versions: Current=12, Latest=12 [Up-to-date]
Updating tool-micronucleus package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating atmelavr @ 0.0.0: [Up-to-date]
Updating framework-arduinoavr @ 1.10608.1: [Up-to-date]
Updating tool-avrdude @ 1.60001.1: [Up-to-date]
Updating toolchain-atmelavr @ 1.40801.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform atmelsam
Platform espressif
--------
Updating framework-arduinosam package:
Versions: Current=3, Latest=3 [Up-to-date]
Updating ldscripts package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating toolchain-gccarmnoneeabi package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating tool-bossac package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating espressif @ 0.0.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Updating toolchain-xtensa @ 1.40802.0: [Up-to-date]
Updating tool-esptool @ 1.409.0: [Up-to-date]
Updating tool-mkspiffs @ 1.102.0: [Up-to-date]
Updating framework-arduinoespressif @ 1.20300.0: [Up-to-date]
Updating sdk-esp8266 @ 1.10502.0: [Up-to-date]
Platform stm32
Platform linux_x86_64
--------
Updating toolchain-gccarmnoneeabi package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating tool-stlink package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating framework-spl package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating framework-cmsis package:
Versions: Current=2, Latest=2 [Up-to-date]
Updating framework-opencm3 package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating ldscripts package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating linux_x86_64 @ 0.0.0: [Up-to-date]
Updating toolchain-gcclinux64 @ 1.40801.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform windows_x86
--------
Updating windows_x86 @ 0.0.0: [Up-to-date]
Updating toolchain-gccmingw32 @ 1.40800.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform teensy
--------
Updating toolchain-atmelavr package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating ldscripts package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating framework-arduinoteensy package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating toolchain-gccarmnoneeabi package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating tool-teensy package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating teensy @ 0.0.0: [Up-to-date]
Updating framework-arduinoteensy @ 1.128.0: [Up-to-date]
Updating tool-teensy @ 1.1.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Updating toolchain-atmelavr @ 1.40801.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Platform timsp430
Platform nordicnrf51
--------
Updating toolchain-timsp430 package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating tool-mspdebug package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating framework-energiamsp430 package:
Versions: Current=2, Latest=2 [Up-to-date]
Updating nordicnrf51 @ 0.0.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating framework-arduinonordicnrf51 @ 1.20302.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform titiva
--------
Updating ldscripts package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating toolchain-gccarmnoneeabi package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating tool-lm4flash package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating framework-opencm3 package:
Versions: Current=1, Latest=1 [Up-to-date]
Updating framework-energiativa package:
Versions: Current=4, Latest=4 [Up-to-date]
Updating titiva @ 0.0.0: [Up-to-date]
Updating framework-libopencm3 @ 1.1.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating framework-energiativa @ 1.17.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform atmelsam
--------
Updating atmelsam @ 0.0.0: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-openocd @ 1.900.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Updating tool-avrdude @ 1.60001.1: [Up-to-date]
Updating tool-bossac @ 1.10601.0: [Up-to-date]
Platform siliconlabsefm32
--------
Updating siliconlabsefm32 @ 0.0.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform microchippic32
--------
Updating microchippic32 @ 0.0.0: [Up-to-date]
Updating framework-arduinomicrochippic32 @ 1.10201.0: [Up-to-date]
Updating toolchain-microchippic32 @ 1.40803.0: [Up-to-date]
Updating tool-pic32prog @ 1.200200.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform linux_i686
--------
Updating linux_i686 @ 0.0.0: [Up-to-date]
Updating toolchain-gcclinux32 @ 1.40801.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform intel_arc32
--------
Updating intel_arc32 @ 0.0.0: [Up-to-date]
Updating framework-arduinointel @ 1.10006.0: [Up-to-date]
Updating tool-arduino101load @ 1.124.0: [Up-to-date]
Updating toolchain-intelarc32 @ 1.40805.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform nxplpc
--------
Updating nxplpc @ 0.0.0: [Up-to-date]
Updating framework-mbed @ 1.121.1: [Up-to-date]
Updating toolchain-gccarmnoneeabi @ 1.40804.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform linux_arm
--------
Updating linux_arm @ 0.0.0: [Up-to-date]
Updating toolchain-gccarmlinuxgnueabi @ 1.40802.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Platform native
--------
Updating native @ 0.0.0: [Up-to-date]
Updating tool-scons @ 2.4.1: [Up-to-date]
Library Manager
===============
Updating Adafruit-GFX @ 334e815bc1: [Up-to-date]
Updating Adafruit-ST7735 @ d53d4bf03a: [Up-to-date]
Updating Adafruit-DHT @ 09344416d2: [Up-to-date]
Updating Adafruit-Unified-Sensor @ f2af6f4efc: [Up-to-date]
Updating ESP8266_SSD1306 @ 3.2.3: [Up-to-date]
Updating EngduinoMagnetometer @ 3.1.0: [Up-to-date]
Updating IRremote @ 2.2.1: [Up-to-date]
Updating Json @ 5.6.4: [Up-to-date]
Updating MODSERIAL @ d8422efe47: [Up-to-date]
Updating PJON @ 1fb26fd: [Checking]
git version 2.7.4 (Apple Git-66)
Already up-to-date.
Updating Servo @ 36b69a7ced07: [Checking]
Mercurial Distributed SCM (version 3.8.4)
(see https://mercurial-scm.org for more information)
Copyright (C) 2005-2016 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
pulling from https://developer.mbed.org/users/simon/code/Servo/
searching for changes
no changes found
Updating TextLCD @ 308d188a2d3a: [Checking]
Mercurial Distributed SCM (version 3.8.4)
(see https://mercurial-scm.org for more information)
Copyright (C) 2005-2016 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
pulling from https://developer.mbed.org/users/simon/code/TextLCD/
searching for changes
no changes found

9
docs/userguide/cmd_upgrade.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -33,11 +33,12 @@ Check or upgrade PlatformIO to the latest version
Examples
--------
.. code-block:: bash
.. code::
> platformio upgrade
$ platformio upgrade
You are up-to-date!
PlatformIO x.x.x is currently the newest version available.
# If you have problem with permissions try:
$ sudo platformio upgrade
> sudo platformio upgrade

5
docs/userguide/index.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -62,9 +62,10 @@ Commands
cmd_boards
cmd_ci
cmd_init
platformio platforms <platforms/index>
platformio platform <platforms/index>
cmd_run
cmd_serialports
cmd_settings
cmd_test
cmd_update
cmd_upgrade

225
docs/userguide/lib/cmd_install.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -21,14 +21,68 @@ Usage
.. code-block:: bash
platformio lib install [OPTIONS] [LIBRARY_ID]
platformio lib [STORAGE_OPTIONS] install [OPTIONS] [LIBRARY...]
# install project dependent library
# (run it from a project root where is located "platformio.ini")
platformio lib install [OPTIONS] [LIBRARY...]
# install to global storage
platformio lib --global install [OPTIONS] [LIBRARY...]
platformio lib -g install [OPTIONS] [LIBRARY...]
# install to custom storage
platformio lib --storage-dir /path/to/dir install [OPTIONS] [LIBRARY...]
platformio lib -d /path/to/dir install [OPTIONS] [LIBRARY...]
# [LIBRARY...] forms
platformio lib [STORAGE_OPTIONS] install (with no args, project dependencies)
platformio lib [STORAGE_OPTIONS] install <id>
platformio lib [STORAGE_OPTIONS] install id=<id>
platformio lib [STORAGE_OPTIONS] install <id>@<version>
platformio lib [STORAGE_OPTIONS] install <id>@<version range>
platformio lib [STORAGE_OPTIONS] install <name>
platformio lib [STORAGE_OPTIONS] install <name>@<version>
platformio lib [STORAGE_OPTIONS] install <name>@<version range>
platformio lib [STORAGE_OPTIONS] install <zip or tarball url>
platformio lib [STORAGE_OPTIONS] install file://<zip or tarball file>
platformio lib [STORAGE_OPTIONS] install file://<folder>
platformio lib [STORAGE_OPTIONS] install <repository>
platformio lib [STORAGE_OPTIONS] install <name>=<repository> (name it should have locally)
platformio lib [STORAGE_OPTIONS] install <repository#tag> ("tag" can be commit, branch or tag)
Description
-----------
Install new library by specified
`PlatformIO Library Registry ID <http://platformio.org/lib>`_.
Install a library, and any libraries that it depends on using:
1. Library ``id`` or ``name`` from `PlatformIO Library Registry <http://platformio.org/lib>`_
2. Custom folder, repository or archive.
The ``version`` supports `Semantic Versioning <http://semver.org>`_ (
``<major>.<minor>.<patch>``) and can take any of the following forms:
* ``0.1.2`` - an exact version number. Use only this exact version
* ``^0.1.2`` - any compatible version (exact version for ``0.x.x`` versions
* ``~0.1.2`` - any version with the same major and minor versions, and an
equal or greater patch version
* ``>0.1.2`` - any version greater than ``0.1.2``. ``>=``, ``<``, and ``<=``
are also possible
* ``>0.1.0,!=0.2.0,<0.3.0`` - any version greater than ``0.1.0``, not equal to
``0.2.0`` and less than ``0.3.0``
Also, PlatformIO supports installing from local directory or archive. Need
to use ``file://`` prefix before local path. Also, directory or
archive should contain ``.library.json`` manifest (see :ref:`library_config`).
* ``file:///local/path/to/the/platform/dir``
* ``file:///local/path/to/the/platform.zip``
* ``file:///local/path/to/the/platform.tar.gz``
Storage Options
---------------
See base options for :ref:`userguide_lib`.
Options
-------
@ -36,50 +90,151 @@ Options
.. program:: platformio lib install
.. option::
-v, --version
-q, --quiet
Install specified version of library
Suppress progress reporting
Version control
---------------
PlatformIO supports installing from Git, Mercurial and Subversion, and detects
the type of VCS using url prefixes: "git+", "hg+", or "svn+".
.. note::
PlatformIO requires a working VCS command on your path: ``git``, ``hg``
or ``svn``.
Git
^^^
The supported schemes are: ``git``, ``git+https`` and ``git+ssh``. Here are
the supported forms:
* user/library (short version for GitHub repository)
* https://github.com/user/library.git
* git+git://git.server.org/my-library
* git+https://git.server.org/my-library
* git+ssh://git.server.org/my-library
Passing branch names, a commit hash or a tag name is possible like so:
* https://github.com/user/library.git#master
* git+git://git.server.org/my-library#master
* git+https://git.server.org/my-library#v1.0
* git+ssh://git.server.org/my-library#7846d8ad52f983f2f2887bdc0f073fe9755a806d
Mercurial
^^^^^^^^^
The supported schemes are: ``hg+http``, ``hg+https`` and ``hg+ssh``. Here are
the supported forms:
* https://developer.mbed.org/users/user/code/library/ (install ARM mbed library)
* hg+hg://hg.server.org/my-library
* hg+https://hg.server.org/my-library
* hg+ssh://hg.server.org/my-library
Passing branch names, a commit hash or a tag name is possible like so:
* hg+hg://hg.server.org/my-library#master
* hg+https://hg.server.org/my-library#v1.0
* hg+ssh://hg.server.org/my-library#4cfe2fa00668
Subversion
^^^^^^^^^^
The supported schemes are: ``svn``, ``svn+svn``, ``svn+http``, ``svn+https``
and ``svn+ssh``. Here are the supported forms:
* svn+svn://svn.server.org/my-library
* svn+https://svn.server.org/my-library
* svn+ssh://svn.server.org/my-library
You can also give specific revisions to an SVN URL, like so:
* svn+svn://svn.server.org/my-library#13
Examples
--------
1. Install the latest version of library
1. Install the latest version of library to a global storage using ID or NAME
.. code-block:: bash
.. code::
# IRremote: http://platformio.org/lib/show/4/IRremote
$ platformio lib install 4
# Installing library [ 4 ]:
# Downloading [####################################] 100%
# Unpacking [####################################] 100%
# The library #4 'IRremote' has been successfully installed!
> platformio lib -g install 4
Library Storage: /storage/dir/...
LibraryManager: Installing id=4
Downloading [####################################] 100%
Unpacking [####################################] 100%
IRremote @ 2.2.1 has been successfully installed!
# repeat command with name
> platformio lib -g install IRRemote
Library Storage: /storage/dir/...
Looking for IRRemote library in registry
Found: http://platformio.org/lib/show/4/IRremote
LibraryManager: Installing id=4
IRremote @ 2.2.1 is already installed
2. Install specified version of library
2. Install specified version of a library to a global storage
.. code-block:: bash
.. code::
# XBee: http://platformio.org/lib/show/6/XBee
$ platformio lib install 6 --version=0.5
# Installing library [ 6 ]:
# Downloading [####################################] 100%
# Unpacking [####################################] 100%
# The library #6 'XBee' has been successfully installed!
> platformio lib -g install Json@5.4.0
Library Storage: /storage/dir/...
Looking for Json library in registry
Found: http://platformio.org/lib/show/64/Json
LibraryManager: Installing id=64 @ 5.4.0
Downloading [####################################] 100%
Unpacking [####################################] 100%
Json @ 5.4.0 has been successfully installed!
3. Install library with dependencies
3. Install library with dependencies to custom storage
.. code-block:: bash
.. code::
# Adafruit-ST7735: http://platformio.org/lib/show/12/Adafruit-ST7735
$ platformio lib install 12
# Installing library [ 12 ]:
# Downloading [####################################] 100%
# Unpacking [####################################] 100%
# The library #12 'Adafruit-ST7735' has been successfully installed!
# Installing dependencies:
# Installing library [ 13 ]:
# Downloading [####################################] 100%
# Unpacking [####################################] 100%
# The library #13 'Adafruit-GFX' has been successfully installed!
> platformio lib --storage-dir /my/storage/dir install DallasTemperature
Library Storage: /my/storage/dir
Looking for DallasTemperature library in registry
Found: http://platformio.org/lib/show/54/DallasTemperature
LibraryManager: Installing id=54
Downloading [####################################] 100%
Unpacking [####################################] 100%
DallasTemperature @ 3.7.7 has been successfully installed!
Installing dependencies
Looking for OneWire library in registry
Found: http://platformio.org/lib/show/1/OneWire
LibraryManager: Installing id=1
Downloading [####################################] 100%
Unpacking [####################################] 100%
OneWire @ 8fd2ebfec7 has been successfully installed!
4. Install ARM mbed library to the global storage
.. code::
> platformio lib -g install https://developer.mbed.org/users/simon/code/TextLCD/
Library Storage: /storage/dir/...
LibraryManager: Installing TextLCD
Mercurial Distributed SCM (version 3.8.4)
(see https://mercurial-scm.org for more information)
Copyright (C) 2005-2016 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
requesting all changes
adding changesets
adding manifests
adding file changes
added 9 changesets with 18 changes to 6 files
updating to branch default
2 files updated, 0 files merged, 0 files removed, 0 files unresolved
TextLCD @ 308d188a2d3a has been successfully installed!

42
docs/userguide/lib/cmd_list.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -21,14 +21,30 @@ Usage
.. code-block:: bash
platformio lib [STORAGE_OPTIONS] list [OPTIONS]
# list project dependent libraries
# (run it from a project root where is located "platformio.ini")
platformio lib list [OPTIONS]
# list libraries from global storage
platformio lib --global list [OPTIONS]
platformio lib -g list [OPTIONS]
# list libraries from custom storage
platformio lib --storage-dir /path/to/dir list [OPTIONS]
platformio lib -d /path/to/dir list [OPTIONS]
Description
-----------
List installed libraries
Storage Options
---------------
See base options for :ref:`userguide_lib`.
Options
~~~~~~~
@ -42,18 +58,14 @@ Return the output in `JSON <http://en.wikipedia.org/wiki/JSON>`_ format
Examples
--------
.. code-block:: bash
.. code::
$ platformio lib list
#
# [ ID ] Name Compatibility "Authors": Description
# -------------------------------------------------------------------------------------
# [ 23 ] Adafruit-L3GD20-Unified arduino, atmelavr "Adafruit Industries": Unified sensor driver for the L3GD20 Gyroscope
# [ 12 ] Adafruit-ST7735 arduino, atmelavr "Adafruit Industries": A library for the Adafruit 1.8" SPI display
# [ 31 ] Adafruit-Unified-Sensor arduino, atmelavr "Adafruit Industries": Adafruit Unified Sensor Driver
# [ 26 ] Adafruit-LSM303DLHC-Unified arduino, atmelavr "Adafruit Industries": Unified sensor driver for Adafruit's LSM303 Breakout (Accelerometer + Magnetometer)
# [ 6 ] XBee arduino, atmelavr "Andrew Rapp": Arduino library for communicating with XBees in API mode
# [ 13 ] Adafruit-GFX arduino, atmelavr "Adafruit Industries": A core graphics library for all our displays, providing a common set of graphics primitives (points, lines, circles, etc.)
# [ 4 ] IRremote arduino, atmelavr "Ken Shirriff": Send and receive infrared signals with multiple protocols
# [ 14 ] Adafruit-9DOF-Unified arduino, atmelavr "Adafruit Industries": Unified sensor driver for the Adafruit 9DOF Breakout (L3GD20 / LSM303)
# ...
> platformio lib list
pio lib -g list
Library Storage: /storage/dir/...
[ ID ] Name Compatibility "Authors": Description
-----------------------------------------------------------------------------------------------------------
[ 4 ] IRremote arduino, atmelavr "Rafi Khan, Ken Shirriff": Send and receive infrared signals with multiple protocols | @2.2.1
[ 64 ] Json arduino, atmelavr, atmelsam, timsp430, titiva, teensy, freescalekinetis, ststm32, nordicnrf51, nxplpc, espressif, siliconlabsefm32, linux_arm, native, intel_arc32 "Benoit Blanchon": An elegant and efficient JSON library for embedded systems | @5.4.0
[ VCS ] TextLCD - "Unknown": hg+https://developer.mbed.org/users/simon/code/TextLCD/ | @308d188a2d3a

6
docs/userguide/lib/cmd_register.rst
View File

@ -1,4 +1,4 @@
.. Copyright 2014-2016 Ivan Kravets <me@ikravets.com>
.. Copyright 2014-present PlatformIO <contact@platformio.org>
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
@ -32,6 +32,6 @@ Register new library and allow others to install it.
Examples
--------
.. code-block:: bash
.. code::
$ platformio lib register http://my.example.com/library.json
platformio lib register http://my.example.com/raw-library.json

Some files were not shown because too many files have changed in this diff Show More