platformio/platformio-core
1
0
Fork 1
mirror of https://github.com/platformio/platformio-core.git synced 2025-07-29 17:47:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'release/v0.7.0'

Browse Source
This commit is contained in:
Ivan Kravets
2014-09-24 22:25:58 +03:00
parent e48c6744ed c14dbb5ef1
commit da0e901884
30 changed files with 1223 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
HISTORY.rst
View File

@ -1,6 +1,13 @@
Release History
===============
0.7.0 (2014-09-24)
------------------
* Implemented new ``[platformio]`` section for Configuration File with ``home_dir``
option (`issue #14 <https://github.com/ivankravets/platformio/issues/14>`_)
* Implemented *Library Manager* (`issue #6 <https://github.com/ivankravets/platformio/issues/6>`_)
0.6.0 (2014-08-09)
------------------

5
README.rst
View File

@ -17,8 +17,8 @@ PlatformIO
:target: https://pypi.python.org/pypi/platformio/
:alt: License
`Documentation <http://docs.platformio.ikravets.com>`_ /
`PDF <https://media.readthedocs.org/pdf/platformio/latest/platformio.pdf>`_ |
`Website <http://platformio.ikravets.com>`_ |
`Documentation <http://docs.platformio.ikravets.com>`_ |
`Project Examples <https://github.com/ivankravets/platformio/tree/develop/examples>`_ |
`Bugs/Questions <https://github.com/ivankravets/platformio/issues>`_ |
`Blog <http://www.ikravets.com/category/computer-life/platformio>`_ |
@ -26,6 +26,7 @@ PlatformIO
**PlatformIO** is a cross-platform code builder and library manager.
* `Website + Library Search <http://platformio.ikravets.com>`_
* `Quickstart <http://docs.platformio.ikravets.com/en/latest/quickstart.html>`_
* `Installation <http://docs.platformio.ikravets.com/en/latest/installation.html>`_
* `Project Configuration File <http://docs.platformio.ikravets.com/en/latest/projectconf.html>`_

2
docs/index.rst
View File

@ -1,6 +1,7 @@
PlatformIO: A cross-platform code builder and library manager
=============================================================
`Website + Library Search <http://platformio.ikravets.com>`_ |
`Project Examples <https://github.com/ivankravets/platformio/tree/develop/examples>`_ |
`Source Code <https://github.com/ivankravets/platformio>`_ |
`Bugs/Questions <https://github.com/ivankravets/platformio/issues>`_ |
@ -42,6 +43,7 @@ Contents
installation
projectconf
platforms/index
librarymanager/index
userguide/index
ide
history

16
docs/installation.rst
View File

@ -27,13 +27,7 @@ Then run the following (which may require administrator access):
.. code-block:: bash
$ python get-platformio.py
An alternative short version for *Mac/Linux* users:
.. code-block:: bash
$ curl -L http://bit.ly/1lpanta | python
$ [sudo] python get-platformio.py
On *Windows OS* it may look like:
@ -43,9 +37,11 @@ On *Windows OS* it may look like:
C:\Python27\python.exe get-platformio.py
.. warning::
If you have an error ``pkg_resources.DistributionNotFound`` try to
uninstall *PlatformIO* ``$ pip uninstall platformio``, then install it via
``$ easy_install platformio``.
**Mac OS Users**: If you have an error ``pkg_resources.DistributionNotFound`` please
upgrade *SetupTools* package: ``$ [sudo] pip uninstall setuptools``
and ``$ [sudo] pip install setuptools``.
Then re-install *PlatformIO*: ``$ [sudo] pip uninstall platformio``
and ``$ [sudo] pip install platformio``.
Full Guide

247
docs/librarymanager/config.rst Normal file
View File

@ -0,0 +1,247 @@
.. _library_config:
library.json
============
*PlatformIO*-suitable library should be defined by a manifest file
``library.json`` in a `JSON-style <http://en.wikipedia.org/wiki/JSON>`_.
A data in ``library.json`` should be represented via
`associative array <http://en.wikipedia.org/wiki/Associative_array>`_
(name/value pairs). An order doesn't matter.
The allowable fields (names from pairs) are described below. The fields
(:ref:`libjson_name`, :ref:`libjson_description` and :ref:`libjson_keywords`)
will be displayed in the search results at the :ref:`cmd_lib_search` (*CLI*)
and at the *WebSite*. Also, they can be used for searching for libraries.
.. contents::
.. _libjson_name:
``name``
--------
**Required** | Type: ``String`` | Max. Length: 50
A name of the library.
* Must be unique.
* Should be slug style for simplicity, consistency and compatibility.
Example: *Arduino-SPI*
* Title Case, Aa-z, can contain digits and dashes (but not start/end
with them).
* Consecutive dashes are not allowed.
.. _libjson_description:
``description``
---------------
**Required** | Type: ``String`` | Max. Length: 255
The field helps users to identify and search for your library with a brief
description. Describe the hardware devices (sensors, boards and etc.) which
are suitable with it.
.. _libjson_keywords:
``keywords``
------------
**Required** | Type: ``String`` | Max. Length: 255
Used for search by keyword. Helps to make your library easier to discover
without people needing to know its name.
The keyword should be lowercased, can contain a-z, digits and dash (but not
start/end with them). A list from the keywords can be specified with
separator ``,``
.. _libjson_version:
``version``
-----------
*Required* if :ref:`libjson_repository` field is not defined | Type: ``String``
| Max. Length: 20
A version of the current library source code.
* Can contain a-z, digits, dots or dash.
* `Semantic Versioning <http://semver.org>`_ is recommended.
* A `CVS <http://en.wikipedia.org/wiki/Concurrent_Versions_System>`_
revision from the latest commit. Example: ``13`` (*SVN*) or first 10
chars of *SHA* digest ``e4564b7da4`` (*Git*).
.. note::
You can omit :ref:`libjson_version` field and define
:ref:`libjson_repository` field. In this case
*PlatformIO-API Crawler* will use the *CVS*-revision from the latest commit.
.. _libjson_author:
``author``
----------
*Required* if :ref:`libjson_repository` field is not defined | Type: ``Object``
An author contact information
* ``name`` Full name (**Required**)
* ``email``
* ``url`` An author's contact page
Example:
.. code-block:: javascript
"author":
{
"name": "John Smith",
"email": "me@john-smith.com",
"url": "http://www.john-smith/contact"
}
.. note::
You can omit :ref:`libjson_author` field and define
:ref:`libjson_repository` field. Only *GitHub-based* repository is
supported now. In this case
*PlatformIO-API Crawler* will use information from
`GitHub API Users <https://developer.github.com/v3/users/>`_.
.. _libjson_repository:
``repository``
--------------
*Required* if :ref:`libjson_downloadurl` field is not defined | Type: ``Object``
The repository in which the source code can be found.
Example:
.. code-block:: javascript
"repository":
{
"name": "git",
"url": "https://github.com/foo/bar.git"
}
.. _libjson_downloadurl:
``downloadUrl``
---------------
*Required* if :ref:`libjson_repository` field is not defined | Type: ``String``
It is the *HTTP URL* to the archived source code of library. It should end
with the type of archive (``.zip`` or ``.tar.gz``).
.. _libjson_include:
``include``
-----------
*Optional* | Type: ``String`` or ``Array`` |
`Glob Pattern <http://en.wikipedia.org/wiki/Glob_(programming)>`_
If :ref:`libjson_include` field is a type of ``String``, then
*PlatformIO-API Crawler* will recognize it like a "relative path inside
repository/archive to library source code". See example below where the only
source code from the relative directory ``LibrarySourceCodeHere`` will be
included.
.. code-block:: javascript
"include": "some/child/dir/LibrarySourceCodeHere"
If :ref:`libjson_include` field is a type of ``Array``, then
*PlatformIO-API Crawler* firstly will apply :ref:`libjson_exclude` filter and
then include only directories/files which match with :ref:`libjson_include`
patterns.
Example:
.. code-block:: javascript
"include":
[
"dir/*.[ch]pp",
"dir/examples/*",
"*/*/*.h"
]
Pattern Meaning
.. 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
.. _libjson_exclude:
``exclude``
-----------
*Optional* | Type: ``String`` or ``Array`` |
`Glob Pattern <http://en.wikipedia.org/wiki/Glob_(programming)>`_
Exclude the directories and files which match with :ref:`libjson_exclude`
patterns.
.. _libjson_dependencies:
``dependencies``
----------------
*Optional* | Type: ``Array``
A list of dependent libraries. They will be installed automatically with
:ref:`cmd_lib_install` command.
Example:
.. code-block:: javascript
"dependencies":
[
"Library-Foo",
"Library-Bar"
]
.. _libjson_examples:
``examples``
----------------
*Optional* | Type: ``String`` or ``Array`` |
`Glob Pattern <http://en.wikipedia.org/wiki/Glob_(programming)>`_
A list of example patterns. This field is predefined with default value:
.. code-block:: javascript
"examples": [
"[Ee]xamples/*/*.ini",
"[Ee]xamples/*/*.pde"
]

130
docs/librarymanager/creating.rst Normal file
View File

@ -0,0 +1,130 @@
.. _library_creating:
.. |PIOAPICR| replace:: *PlatformIO-API Crawler*
Creating Library
================
*PlatformIO* :ref:`librarymanager` doesn't have any requirements to a library
source code structure. The only one requirement is library's manifest file -
:ref:`library_config`. It can be located inside your library or in the another
location where |PIOAPICR| will have *HTTP* access.
.. contents::
Source Code Location
--------------------
There are a several ways how to share your library with the whole world
(see `examples <https://github.com/ivankravets/platformio-libmirror/tree/master/configs>`_).
You can hold a lot of libraries (split into separated folders) inside one of
the repository/archive. In this case please use :ref:`libjson_include`
field to specify the relative path to your library's source code.
At GitHub
^^^^^^^^^
**Recommended**
If a library source code is located at `GitHub <https://github.com>`_, then
you **need to specify** only these fields in the :ref:`library_config`:
* :ref:`libjson_name`
* :ref:`libjson_keywords`
* :ref:`libjson_description`
* :ref:`libjson_repository`
|PIOAPICR| will populate the rest fields, like :ref:`libjson_version` or
:ref:`libjson_author` with an actual information from *GitHub*.
Example:
.. code-block:: javascript
{
"name": "Arduino-IRremote",
"keywords": "infrared, ir, remote",
"description": "Send and receive infrared signals with multiple protocols",
"repository":
{
"type": "git",
"url": "https://github.com/shirriff/Arduino-IRremote.git"
}
}
Under CVS (SVN/GIT)
^^^^^^^^^^^^^^^^^^^
|PIOAPICR| can operate with a library source code that is under *CVS* control.
The list of **required** fields in the :ref:`library_config` will look like:
* :ref:`libjson_name`
* :ref:`libjson_keywords`
* :ref:`libjson_description`
* :ref:`libjson_author`
* :ref:`libjson_repository`
Example:
.. code-block:: javascript
{
"name": "Arduino-XBee",
"keywords": "xbee, protocol, radio",
"description": "Arduino library for communicating with XBees in API mode",
"author":
{
"name": "Andrew Rapp",
"email": "andrew.rapp@gmail.com",
"url": "https://code.google.com/u/andrew.rapp@gmail.com/"
},
"repository":
{
"type": "git",
"url": "https://code.google.com/p/xbee-arduino/"
}
}
Self-hosted
^^^^^^^^^^^
You can manually archive (*Zip, Tar.Gz*) your library source code and host it
in the *Internet*. Then you should specify the additional fields,
like :ref:`libjson_version` and :ref:`libjson_downloadurl`. The final list
of **required** fields in the :ref:`library_config` will look like:
* :ref:`libjson_name`
* :ref:`libjson_keywords`
* :ref:`libjson_description`
* :ref:`libjson_author`
* :ref:`libjson_version`
* :ref:`libjson_downloadurl`
.. code-block:: javascript
{
"name": "Arduino-OneWire",
"keywords": "onewire, 1-wire, bus, sensor, temperature, ibutton",
"description": "Control devices (from Dallas Semiconductor) that use the One Wire protocol (DS18S20, DS18B20, DS2408 and etc)",
"author":
{
"name": "Paul Stoffregen",
"url": "http://www.pjrc.com/teensy/td_libs_OneWire.html"
},
"version": "2.2",
"downloadUrl": "http://www.pjrc.com/teensy/arduino_libraries/OneWire.zip",
"include": "OneWire"
}
Register
--------
The registration requirements:
* A library must adhere to the :ref:`library_config` specification.
* There must be public *HTTP* access to the library :ref:`library_config` file.
Now, you can :ref:`register <cmd_lib_register>` your library and allow others
to :ref:`install <cmd_lib_install>` it.

24
docs/librarymanager/index.rst Normal file
View File

@ -0,0 +1,24 @@
.. _librarymanager:
Library Manager
===============
..
*"The missing library manager for embedded platforms"* [#]_
*PlatformIO Library Manager* allows you to organize external embedded libraries.
You can search for new libraries via :ref:`Command Line <cmd_lib_search>`
or `WebSite <http://platformio.ikravets.com>`_ interfaces.
You don't need to bother for finding the latest version of library. Due to
:ref:`cmd_lib_update` command you will have up-to-date external libraries.
.. toctree::
:maxdepth: 2
creating
config
.. [#] Inspired by `npm <https://www.npmjs.org>`_ and `bower
<http://bower.io>`_ package managers for web.

7
docs/platforms/atmelavr.rst
View File

@ -299,8 +299,8 @@ More detailed information you can find here
`Microduino boards <http://www.microduino.cc/wiki/index.php?title=Main_Page>`_.
Miscellaneous
~~~~~~~~~~~~~
Raspduino
~~~~~~~~~
.. list-table::
:header-rows: 1
@ -318,3 +318,6 @@ Miscellaneous
- 16 MHz ``16000000L``
- 32 Kb
- 2 Kb
More detailed information you can find in
`Wiki <http://www.bitwizard.nl/wiki/index.php/Raspduino>`_.

76
docs/projectconf.rst
View File

@ -14,6 +14,32 @@ The sections and their allowable values are described below.
.. contents::
[platformio]
------------
A ``platformio`` section is used for overriding default configuration options
Options
~~~~~~~
``home_dir``
^^^^^^^^^^^^
A ``$PIO_HOME_DIR`` is used to store platform tool chains, frameworks,
external libraries, service data and etc.
A default value is user's home directory: *Unix* - ``~/.platformio``,
Windows - ``%HOMEPATH%\.platformio``.
``lib_dir``
^^^^^^^^^^^^
This directory is used to store external libraries downloaded by
:ref:`librarymanager`.
A default value is ``$PIO_HOME_DIR/lib``.
[env:NAME]
----------
@ -220,14 +246,51 @@ Examples
framework = arduino
board = uno
upload_port = /dev/ ttyUSB0
# upload_port = COM3 # for Windows OS
upload_port = /dev/ttyUSB0
# for Windows OS
# upload_port = COM3
# enable auto-uploading
targets = upload
2. :ref:`platform_atmelavr`: Embedded board that is based on ATmega168 MCU with
2. :ref:`platform_atmelavr`: Microduino Core (ATmega168P, 3.3V) board with
auto pre-configured ``board_*`` and ``upload_*`` options (use only
``board`` option) and Arduino Wiring-based Framework
.. code-block:: ini
[env:atmelavr_microduino_core_board]
platform = atmelavr
framework = arduino
board = 168pa8m
upload_port = /dev/ttyUSB0
# for Windows OS
# upload_port = COM3
# enable auto-uploading
targets = upload
3. :ref:`platform_atmelavr`: Raspduino board with
auto pre-configured ``board_*`` and ``upload_*`` options (use only
``board`` option) and Arduino Wiring-based Framework
.. code-block:: ini
[env:atmelavr_raspduino_board]
platform = atmelavr
framework = arduino
board = raspduino
upload_port = /dev/ttyS0
# enable auto-uploading
targets = upload
4. :ref:`platform_atmelavr`: Embedded board that is based on ATmega168 MCU with
"arduino" bootloader
.. code-block:: ini
@ -238,7 +301,8 @@ Examples
board_f_cpu = 16000000L
upload_port = /dev/ttyUSB0
# upload_port = COM3 # for Windows OS
# for Windows OS
# upload_port = COM3
upload_protocol = arduino
upload_speed = 19200
@ -246,7 +310,7 @@ Examples
targets = upload
3. :ref:`platform_timsp430`: TI MSP430G2553 LaunchPad with auto pre-configured
5. :ref:`platform_timsp430`: TI MSP430G2553 LaunchPad with auto pre-configured
``board_*`` and ``upload_*`` options (use only ``board`` option) and Energia
Wiring-based Framework
@ -258,7 +322,7 @@ Examples
board = lpmsp430g2553
4. :ref:`platform_timsp430`: Embedded board that is based on MSP430G2553 MCU
6. :ref:`platform_timsp430`: Embedded board that is based on MSP430G2553 MCU
.. code-block:: ini

17
docs/quickstart.rst
View File

@ -36,6 +36,17 @@ Initialize new PlatformIO based project
and setup environments in `platformio.ini` file.
Then process project with `platformio run` command.
Setup environments in ``platformio.ini``. For more examples go to
:ref:`projectconf`
.. code-block:: ini
# Simple and base environment
[env:mybaseenv]
platform = %INSTALLED_PLATFORM_NAME_HERE%
Process the project's environments
.. code-block:: bash
@ -49,4 +60,8 @@ Process the project's environments
$ platformio run --target clean
For more detailed information please go to :ref:`userguide` sections.
Further examples can be found in the ``examples/`` directory in the source
distribution or `on the web <https://github.com/ivankravets/platformio/tree/develop/examples>`_.
Also, for more detailed information as for commands please go to
:ref:`userguide` sections.

2
docs/userguide/cmd_serialports.rst
View File

@ -171,7 +171,7 @@ Diagnostics: suppress non-error messages, default ``Off``
Examples
~~~~~~~~
1. Show available option for command
1. Show available options for *monitor*
.. code-block:: bash

1
docs/userguide/index.rst
View File

@ -16,6 +16,7 @@ To print all available commands and options use:
cmd_init
cmd_install
platformio lib <lib/index>
cmd_list
cmd_run
cmd_search

68
docs/userguide/lib/cmd_install.rst Normal file
View File

@ -0,0 +1,68 @@
.. _cmd_lib_install:
platformio lib install
======================
.. contents::
Usage
-----
.. code-block:: bash
platformio lib install [OPTIONS] [NAMES]
Description
-----------
Install new library
Options
-------
.. option::
-v, --version
Install specified version of library
Examples
--------
1. Install the latest version of library
.. code-block:: bash
$ platformio lib install Arduino-IRremote
Installing Arduino-IRremote library:
Downloading [####################################] 100%
Unpacking [####################################] 100%
The library 'Arduino-IRremote' has been successfully installed!
2. Install specified version of library
.. code-block:: bash
$ platformio lib install Arduino-XBee --version=0.5
Installing Arduino-XBee library:
Downloading [####################################] 100%
Unpacking [####################################] 100%
The library 'Arduino-XBee' has been successfully installed!
3. Install library with dependencies
.. code-block:: bash
$ platformio lib install Adafruit-Arduino-ST7735
Installing Adafruit-Arduino-ST7735 library:
Downloading [####################################] 100%
Unpacking [####################################] 100%
The library 'Adafruit-Arduino-ST7735' has been successfully installed!
Installing dependencies:
Installing Adafruit-Arduino-GFX library:
Downloading [####################################] 100%
Unpacking [####################################] 100%
The library 'Adafruit-Arduino-GFX' has been successfully installed!

31
docs/userguide/lib/cmd_list.rst Normal file
View File

@ -0,0 +1,31 @@
.. _cmd_lib_list:
platformio lib list
===================
.. contents::
Usage
-----
.. code-block:: bash
platformio lib list
Description
-----------
List installed libraries
Examples
--------
.. code-block:: bash
$ platformio lib list
Arduino-IRremote Send and receive infrared signals with multiple protocols
...
Arduino-Webduino An extensible web server library (for use with the Arduino Ethernet Shield)
Arduino-XBee Arduino library for communicating with XBees in API mode

26
docs/userguide/lib/cmd_register.rst Normal file
View File

@ -0,0 +1,26 @@
.. _cmd_lib_register:
platformio lib register
=======================
.. contents::
Usage
-----
.. code-block:: bash
platformio lib regiter [HTTP_URL_TO_LIBRARY.JSON]
Description
-----------
Register new library and allow others to install it.
Examples
--------
.. code-block:: bash
$ platformio lib register http://my.example.com/library.json

136
docs/userguide/lib/cmd_search.rst Normal file
View File

@ -0,0 +1,136 @@
.. _cmd_lib_search:
platformio lib search
=====================
.. contents::
Usage
-----
.. code-block:: bash
platformio lib search [OPTIONS] [QUERY]
Description
-----------
Search for library over ``name``, ``description`` and ``keywords`` fields from
the :ref:`library_config` file in the boolean mode.
The boolean search capability supports the following operators:
.. list-table::
:header-rows: 1
* - Operator
- Description
* - ``+``
- A leading or trailing plus sign indicates that this word must be present
in library fields (see above) that is returned.
* - ``-``
- A leading or trailing minus sign indicates that this word must not be
present in any of the libraries that are returned.
* - ``(no operator)``
- By default (when neither ``+`` nor ``-`` is specified), the
word is optional, but the libraries that contain it are rated higher.
* - ``> <``
- These two operators are used to change a word's contribution to the
relevance value that is assigned to a library. The ``>`` operator
increases the contribution and the ``<`` operator decreases it.
* - ``( )``
- Parentheses group words into subexpressions. Parenthesized groups can
be nested.
* - ``~``
- A leading tilde acts as a negation operator, causing the word's
contribution to the library's relevance to be negative. This is useful for
marking "noise" words. A library containing such a word is rated lower than
others, but is not excluded altogether, as it would be with the ``-`` operator.
* - ``*``
- The asterisk serves as the truncation (or wildcard) operator. Unlike the
other operators, it is appended to the word to be affected. Words match if
they begin with the word preceding the ``*`` operator.
* - ``"``
- A phrase that is enclosed within double quote (``"``) characters matches
only libraries that contain the phrase literally, as it was typed.
For more detail information please go to
`MySQL Boolean Full-Text Searches <http://dev.mysql.com/doc/refman/5.6/en/fulltext-boolean.html>`_.
Options
-------
.. option::
-a, --author
Filter libraries by specified author
.. option::
-k, --keyword
Filter libraries by specified keyword
Examples
--------
1. Search for "1-Wire" library
.. code-block:: bash
$ platformio lib search 1-wire
Found N libraries:
Arduino-OneWire Control devices (from Dallas Semiconductor) that use the One Wire protocol
...
2. Search for Arduino-based "I2C" libraries. The ``+`` sign is here like ``AND``
operator.
.. code-block:: bash
$ platformio lib search "+i2c +arduino"
Found N libraries:
i2cdevlib-Arduino-i2cdev The I2C Device Library (i2cdevlib) is a collection of uniform and well-documented classes to provide simple and intuitive interfaces to I2C devices.
i2cdevlib-Arduino-AK8975 AK8975 is 3-axis electronic compass IC with high sensitive Hall sensor technology
...
3. Search for libraries by "web" and "http" keywords. The ``""`` here is for
"empty" query argument.
.. code-block:: bash
$ platformio lib search "" --keyword web --keyword http
Found N libraries:
Arduino-Webduino An extensible web server library (for use with the Arduino Ethernet Shield)
Arduino-aJson An Arduino library to enable JSON processing with Arduino
...
4. Search for libraries from "Adafruit Industries" author.
.. code-block:: bash
$ platformio lib search "" --author "Adafruit Industries"
Found N libraries:
Adafruit-Arduino-ST7735 A library for the Adafruit 1.8" SPI display
Adafruit-Arduino-GFX A core graphics library for all our displays, providing a common set of graphics primitives (points, lines, circles, etc.)
...
5. Search for libraries that are compatible with Dallas temperature sensors
like DS18B20, DS18S20 and etc.
.. code-block:: bash
$ platformio lib search "DS*"
Found N libraries:
Arduino-OneWire Control devices (from Dallas Semiconductor) that use the One Wire protocol
...
6. Search for Arduino-based *X10* or *XBee* libraries. The search query that is
described below can be interpreted like ``arduino x10 OR arduino xbee``.
.. code-block:: bash
$ platformio lib search "+arduino +(x10 xbee)"
Found 2 libraries:
Arduino-X10 Sending X10 signals over AC power lines
Arduino-XBee Arduino library for communicating with XBees in API mode

34
docs/userguide/lib/cmd_show.rst Normal file
View File

@ -0,0 +1,34 @@
.. _cmd_lib_show:
platformio lib show
===================
.. contents::
Usage
-----
.. code-block:: bash
platformio lib show NAME
Description
-----------
Show details about the installed library
Examples
--------
.. code-block:: bash
$ platformio lib show Arduino-XBee
Arduino-XBee
------------
Author: Andrew Rapp <andrew.rapp@gmail.com>
Keywords: xbee, protocol, radio
Version: 0.5
Arduino library for communicating with XBees in API mode

31
docs/userguide/lib/cmd_uninstall.rst Normal file
View File

@ -0,0 +1,31 @@
.. _cmd_lib_uninstall:
platformio lib uninstall
========================
.. contents::
Usage
-----
.. code-block:: bash
platformio lib uninstall NAME
Description
-----------
Uninstall specified library
Examples
--------
.. code-block:: bash
$ platformio lib install Arduino-IRremote
Installing Arduino-IRremote library:
Downloading [####################################] 100%
Unpacking [####################################] 100%
The library 'Arduino-IRremote' has been successfully installed!

33
docs/userguide/lib/cmd_update.rst Normal file
View File

@ -0,0 +1,33 @@
.. _cmd_lib_update:
platformio lib update
=====================
.. contents::
Usage
-----
.. code-block:: bash
platformio lib update
Description
-----------
Check or update installed libraries
Examples
--------
.. code-block:: bash
$ platformio lib update
Updating Arduino-IRremote library:
Versions: Current=24ba950f5c, Latest=24ba950f5c [Up-to-date]
Updating Arduino-Webduino library:
Versions: Current=3631af8e02, Latest=3631af8e02 [Up-to-date]
Updating Arduino-XBee library:
Versions: Current=0.5, Latest=0.5 [Up-to-date]

23
docs/userguide/lib/index.rst Normal file
View File

@ -0,0 +1,23 @@
.. _userguide_lib:
Library Manager
===============
To print all available commands and options use:
.. code-block:: bash
$ platformio lib --help
$ platformio lib COMMAND --help
.. toctree::
:maxdepth: 2
cmd_install
cmd_list
cmd_register
cmd_search
cmd_show
cmd_uninstall
cmd_update

9
platformio/__init__.py
View File

@ -1,17 +1,18 @@
# Copyright (C) Ivan Kravets <me@ikravets.com>
# See LICENSE for details.
VERSION = (0, 6, 0)
VERSION = (0, 7, 0)
__version__ = ".".join([str(s) for s in VERSION])
__title__ = "platformio"
__description__ = ("A cross-platform code builder and library manager")
__url__ = "https://github.com/ivankravets/platformio"
__url__ = "http://platformio.ikravets.com"
__author__ = "Ivan Kravets"
__email__ = "me@ikravets.com"
__license__ = "MIT Licence"
__license__ = "MIT License"
__copyright__ = "Copyright (C) 2014 Ivan Kravets"
__pkgmanifesturl__ = "http://platformio.ikravets.com/packages/manifest.json"
__apiurl__ = "http://api.platformio.ikravets.com"
__pkgmanifesturl__ = "http://dl.platformio.ikravets.com/packages/manifest.json"

2
platformio/__main__.py
View File

@ -15,7 +15,7 @@ from platformio.exception import PlatformioException, UnknownCLICommand
from platformio.util import get_home_dir, get_source_dir
class PlatformioCLI(MultiCommand):
class PlatformioCLI(MultiCommand): # pylint: disable=R0904
def list_commands(self, ctx):
cmds = []

4
platformio/builder/main.py
View File

@ -16,7 +16,8 @@ from os.path import isdir, join
from SCons.Script import (DefaultEnvironment, Exit, SConscript,
SConscriptChdir, Variables)
from platformio.util import get_pioenvs_dir, get_project_dir, get_source_dir
from platformio.util import (get_lib_dir, get_pioenvs_dir, get_project_dir,
get_source_dir)
# AllowSubstExceptions()
@ -57,6 +58,7 @@ DefaultEnvironment(
BUILD_DIR=join("$PIOENVS_DIR", "$PIOENV"),
LIBSOURCE_DIRS=[
join("$PROJECT_DIR", "lib"),
get_lib_dir(),
join("$PLATFORMFW_DIR", "libraries"),
]
)

5
platformio/builder/tools/platformio.py
View File

@ -165,8 +165,9 @@ def ConvertInotoCpp(env):
remove(f)
tmpcpp = []
for item in env.Glob(join("$PROJECT_DIR", "src", "*.ino")):
items = (env.Glob(join("$PROJECT_DIR", "src", "*.ino")) +
env.Glob(join("$PROJECT_DIR", "src", "*.pde")))
for item in items:
cppfile = item.get_path()[:-3] + "cpp"
if isfile(cppfile):
continue

173
platformio/commands/lib.py Normal file
View File

@ -0,0 +1,173 @@
# Copyright (C) Ivan Kravets <me@ikravets.com>
# See LICENSE for details.
import click
from platformio.exception import LibAlreadyInstalledError
from platformio.libmanager import LibraryManager
from platformio.util import get_api_result, get_lib_dir
@click.group(short_help="Library Manager")
def cli():
pass
@cli.command("search", short_help="Search for library")
@click.option("-a", "--author", multiple=True)
@click.option("-k", "--keyword", multiple=True)
@click.argument("query")
def lib_search(query, author, keyword):
for key, values in dict(author=author, keyword=keyword).iteritems():
for value in values:
query += ' %s:"%s"' % (key, value)
result = get_api_result("/lib/search", dict(query=query))
click.secho("Found %d libraries:" % result['total'],
fg="green" if result['total'] else "yellow")
while True:
for item in result['items']:
click.echo("{name:<30} {description}".format(
name=click.style(item['name'], fg="cyan"),
description=item['description']
))
if int(result['page'])*int(result['perpage']) >= int(result['total']):
break
if click.confirm("Show next libraries?"):
result = get_api_result(
"/lib/search",
dict(query=query, page=str(int(result['page']) + 1))
)
else:
break
@cli.command("install", short_help="Install library")
@click.argument("names", nargs=-1)
@click.option("-v", "--version")
def lib_install_cli(names, version):
lib_install(names, version)
def lib_install(names, version=None):
lm = LibraryManager(get_lib_dir())
for name in names:
click.echo("Installing %s library:" % click.style(name, fg="cyan"))
try:
if lm.install(name, version):
click.secho(
"The library '%s' has been successfully installed!" %
name, fg="green")
info = lm.get_info(name)
if "dependencies" in info:
click.secho("Installing dependencies:", fg="yellow")
lib_install(info['dependencies'])
except LibAlreadyInstalledError:
click.secho("Already installed", fg="yellow")
@cli.command("uninstall", short_help="Uninstall libraries")
@click.argument("names", nargs=-1)
def lib_uninstall_cli(names):
lib_uninstall(names)
def lib_uninstall_dependency(dependency):
lm = LibraryManager(get_lib_dir())
for name in lm.get_installed():
info = lm.get_info(name)
if dependency in info.get("dependencies", []):
return
lib_uninstall([dependency])
def lib_uninstall(names):
lm = LibraryManager(get_lib_dir())
for name in names:
info = lm.get_info(name)
if lm.uninstall(name):
# find dependencies
if "dependencies" in info:
for d in info['dependencies']:
lib_uninstall_dependency(d)
click.secho("The library '%s' has been successfully "
"uninstalled!" % name, fg="green")
@cli.command("list", short_help="List installed libraries")
def lib_list():
lm = LibraryManager(get_lib_dir())
for name in lm.get_installed():
info = lm.get_info(name)
click.echo("{name:<30} {description}".format(
name=click.style(info['name'], fg="cyan"),
description=info['description']
))
@cli.command("show", short_help="Show details about installed libraries")
@click.argument("name")
def lib_show(name):
lm = LibraryManager(get_lib_dir())
info = lm.get_info(name)
click.secho(info['name'], fg="cyan")
click.echo("-" * len(info['name']))
if "author" in info:
_data = []
for k in ("name", "email"):
if k in info['author'] and info['author'][k] is not None:
_value = info['author'][k]
if k == "email":
_value = "<%s>" % _value
_data.append(_value)
click.echo("Author: %s" % " ".join(_data))
click.echo("Keywords: %s" % info['keywords'])
click.echo("Version: %s" % info['version'])
click.echo()
click.echo(info['description'])
click.echo()
@cli.command("update", short_help="Update installed libraries")
def lib_update():
lm = LibraryManager(get_lib_dir())
lib_names = lm.get_installed()
versions = get_api_result("/lib/version/" + ",".join(lib_names))
for name in lib_names:
info = lm.get_info(name)
click.echo("Updating %s library:" % click.style(name, fg="yellow"))
current_version = info['version']
latest_version = versions[name]
click.echo("Versions: Current=%s, Latest=%s \t " % (
current_version, latest_version), nl=False)
if current_version == latest_version:
click.echo("[%s]" % (click.style("Up-to-date", fg="green")))
continue
else:
click.echo("[%s]" % (click.style("Out-of-date", fg="red")))
lib_uninstall([name])
lib_install([name])
@cli.command("register", short_help="Register new library")
@click.argument("config_url")
def lib_register(config_url):
result = get_api_result("/lib/register", data=dict(config_url=config_url))
if "message" in result and result['message']:
click.secho(result['message'], fg="green" if "successed" in result and
result['successed'] else "red")

2
platformio/commands/show.py
View File

@ -10,7 +10,7 @@ from platformio.pkgmanager import PackageManager
from platformio.platforms.base import PlatformFactory
@command("show", short_help="Show details about an installed platforms")
@command("show", short_help="Show details about installed platforms")
@argument("platform")
def cli(platform):
p = PlatformFactory().newPlatform(platform)

14
platformio/exception.py
View File

@ -105,3 +105,17 @@ class GetSerialPortsError(PlatformioException):
class GetLatestVersionError(PlatformioException):
MESSAGE = "Can't retrieve latest PlatformIO version"
class APIRequestError(PlatformioException):
MESSAGE = "[API] %s"
class LibAlreadyInstalledError(PlatformioException):
pass
class LibNotInstalledError(PlatformioException):
MESSAGE = "Library '%s' has not been installed yet"

75
platformio/libmanager.py Normal file
View File

@ -0,0 +1,75 @@
# Copyright (C) Ivan Kravets <me@ikravets.com>
# See LICENSE for details.
import json
from os import listdir, makedirs, remove
from os.path import isdir, isfile, join
from shutil import rmtree
from tempfile import gettempdir
from platformio.downloader import FileDownloader
from platformio.exception import LibAlreadyInstalledError, LibNotInstalledError
from platformio.unpacker import FileUnpacker
from platformio.util import get_api_result
class LibraryManager(object):
CONFIG_NAME = "library.json"
def __init__(self, lib_dir):
self.lib_dir = lib_dir
@staticmethod
def download(url, dest_dir):
fd = FileDownloader(url, dest_dir)
fd.start()
return fd.get_filepath()
@staticmethod
def unpack(pkgpath, dest_dir):
fu = FileUnpacker(pkgpath, dest_dir)
return fu.start()
def get_installed(self):
items = []
for item in listdir(self.lib_dir):
conf_path = join(self.lib_dir, item, self.CONFIG_NAME)
if isfile(conf_path):
items.append(item)
return items
def get_info(self, name):
conf_path = join(self.lib_dir, name, self.CONFIG_NAME)
if not isfile(conf_path):
raise LibNotInstalledError(name)
with open(conf_path, "r") as f:
return json.load(f)
def is_installed(self, name):
return isfile(join(self.lib_dir, name, self.CONFIG_NAME))
def install(self, name, version=None):
if self.is_installed(name):
raise LibAlreadyInstalledError()
_lib_dir = join(self.lib_dir, name)
if not isdir(_lib_dir):
makedirs(_lib_dir)
dlinfo = get_api_result("/lib/download/" + name, dict(version=version)
if version else None)
try:
dlpath = self.download(dlinfo['url'], gettempdir())
self.unpack(dlpath, _lib_dir)
finally:
remove(dlpath)
return self.is_installed(name)
def uninstall(self, name):
if self.is_installed(name):
rmtree(join(self.lib_dir, name))
return True
else:
raise LibNotInstalledError(name)

53
platformio/util.py
View File

@ -8,9 +8,14 @@ from platform import system, uname
from subprocess import PIPE, Popen
from time import sleep
from requests import get, post
from requests.exceptions import ConnectionError, HTTPError
from requests.utils import default_user_agent
from serial import Serial
from platformio.exception import GetSerialPortsError, NotPlatformProject
from platformio import __apiurl__, __version__
from platformio.exception import (APIRequestError, GetSerialPortsError,
NotPlatformProject)
try:
from configparser import ConfigParser
@ -26,9 +31,27 @@ def get_systype():
def get_home_dir():
try:
config = get_project_config()
if (config.has_section("platformio") and
config.has_option("platformio", "home_dir")):
return config.get("platformio", "home_dir")
except NotPlatformProject:
pass
return expanduser("~/.platformio")
def get_lib_dir():
try:
config = get_project_config()
if (config.has_section("platformio") and
config.has_option("platformio", "lib_dir")):
return config.get("platformio", "lib_dir")
except NotPlatformProject:
pass
return join(get_home_dir(), "lib")
def get_source_dir():
return dirname(realpath(__file__))
@ -89,3 +112,31 @@ def get_serialports():
else:
raise GetSerialPortsError(os_name)
return[{"port": p, "description": d, "hwid": h} for p, d, h in comports()]
def get_api_result(path, params=None, data=None):
result = None
r = None
try:
headers = {"User-Agent": "PlatformIO/%s %s" % (
__version__, default_user_agent())}
if data:
r = post(__apiurl__ + path, params=params, data=data,
headers=headers)
else:
r = get(__apiurl__ + path, params=params, headers=headers)
result = r.json()
r.raise_for_status()
except HTTPError as e:
if result and "errors" in result:
raise APIRequestError(result['errors'][0]['title'])
else:
raise APIRequestError(e)
except ConnectionError:
raise APIRequestError("Could not connect to PlatformIO API Service")
except ValueError:
raise APIRequestError("Invalid response: %s" % r.text)
finally:
if r:
r.close()
return result

4
requirements.txt
View File

@ -1,5 +1,5 @@
click==2.5
click==3.3
colorama==0.3.1
pyserial==2.7
requests==2.3.0
requests==2.4.1
scons==2.3.0