From 0323fe7b907f02edfa10a5c3fe8fc995c937d0aa Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 9 Aug 2014 23:29:37 +0300 Subject: [PATCH 01/44] Preparation for 0.7.0-dev --- HISTORY.rst | 3 +++ platformio/__init__.py | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/HISTORY.rst b/HISTORY.rst index a5e000bb45..631991d1b0 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -1,6 +1,9 @@ Release History =============== +0.7.0 (?) +--------- + 0.6.0 (2014-08-09) ------------------ diff --git a/platformio/__init__.py b/platformio/__init__.py index b2f1c430ec..aa4db29f66 100644 --- a/platformio/__init__.py +++ b/platformio/__init__.py @@ -1,7 +1,7 @@ # Copyright (C) Ivan Kravets # See LICENSE for details. -VERSION = (0, 6, 0) +VERSION = (0, 7, "0-dev") __version__ = ".".join([str(s) for s in VERSION]) __title__ = "platformio" From 80e21f61d36268684b1614e306903967d643821c Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 9 Aug 2014 23:40:32 +0300 Subject: [PATCH 02/44] Minor docs improvement --- docs/userguide/cmd_serialports.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userguide/cmd_serialports.rst b/docs/userguide/cmd_serialports.rst index 04b1950bbe..83e476d85e 100644 --- a/docs/userguide/cmd_serialports.rst +++ b/docs/userguide/cmd_serialports.rst @@ -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 From 1b359b7587efc2c5e64622581f1a077f094de61e Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Mon, 11 Aug 2014 12:20:08 +0300 Subject: [PATCH 03/44] Add new examples to ProjectConfFile + improve Quickstart --- docs/projectconf.rst | 50 ++++++++++++++++++++++++++++++++++++++------ docs/quickstart.rst | 11 ++++++++++ 2 files changed, 55 insertions(+), 6 deletions(-) diff --git a/docs/projectconf.rst b/docs/projectconf.rst index 3a1ab0bbc0..6407105171 100644 --- a/docs/projectconf.rst +++ b/docs/projectconf.rst @@ -220,14 +220,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`: 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 -2. :ref:`platform_atmelavr`: Embedded board that is based on ATmega168 MCU with +4. :ref:`platform_atmelavr`: Embedded board that is based on ATmega168 MCU with "arduino" bootloader .. code-block:: ini @@ -238,7 +275,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 +284,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 +296,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 diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 9c947c9989..e69cbbc3de 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -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 From 9cec1069d6f8a53a3ca124cb9a1c189f26b7f482 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Mon, 11 Aug 2014 15:58:39 +0300 Subject: [PATCH 04/44] Rename Miscellaneous section to Raspduino --- docs/platforms/atmelavr.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/platforms/atmelavr.rst b/docs/platforms/atmelavr.rst index a5f979d258..ca10dc56f0 100644 --- a/docs/platforms/atmelavr.rst +++ b/docs/platforms/atmelavr.rst @@ -299,8 +299,8 @@ More detailed information you can find here `Microduino boards `_. -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 `_. From c41be4b294682da90141cfe41cda524a35c37ad5 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Tue, 12 Aug 2014 19:29:57 +0300 Subject: [PATCH 05/44] Add notice about examples on the web --- docs/quickstart.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index e69cbbc3de..6ad1551c78 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -60,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 `_. + +Also, for more detailed information as for commands please go to +:ref:`userguide` sections. From 63d9914652dca13e8ca2a6890d830ac1a590972f Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Wed, 13 Aug 2014 11:37:50 +0300 Subject: [PATCH 06/44] Test passed with new click 3.1 --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index ffd41083bd..80c2ca8cf1 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -click==2.5 +click==3.1 colorama==0.3.1 pyserial==2.7 requests==2.3.0 From ad6acb28ae24c054523f86da997aa05dc4e8fae4 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Wed, 13 Aug 2014 11:55:25 +0300 Subject: [PATCH 07/44] Disable PyLint stupid warning --- platformio/__main__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platformio/__main__.py b/platformio/__main__.py index 3fa96c6f5c..ab1cceb3fa 100644 --- a/platformio/__main__.py +++ b/platformio/__main__.py @@ -15,7 +15,7 @@ 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 = [] From e4ba030a0c7a7b03f2e6427bdcea801309ea3704 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Wed, 13 Aug 2014 16:36:38 +0300 Subject: [PATCH 08/44] Expand an URL to get-platformio.py --- docs/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.rst b/docs/installation.rst index c4b4d0d319..4245c70941 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -33,7 +33,7 @@ An alternative short version for *Mac/Linux* users: .. code-block:: bash - $ curl -L http://bit.ly/1lpanta | python + $ curl -L https://raw.githubusercontent.com/ivankravets/platformio/develop/scripts/get-platformio.py | python On *Windows OS* it may look like: From 768eea8a6dc68afe305373091cfd9418d041e043 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Fri, 22 Aug 2014 17:57:28 +0300 Subject: [PATCH 09/44] Implemented new ``[platformio]`` section for Configuration File | Resolve #14 --- HISTORY.rst | 3 +++ docs/projectconf.rst | 18 ++++++++++++++++++ platformio/util.py | 10 +++++++++- 3 files changed, 30 insertions(+), 1 deletion(-) diff --git a/HISTORY.rst b/HISTORY.rst index 631991d1b0..b005a2db62 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -4,6 +4,9 @@ Release History 0.7.0 (?) --------- +* Implemented new ``[platformio]`` section for Configuration File with ``home_dir`` + option (`issue #14 `_) + 0.6.0 (2014-08-09) ------------------ diff --git a/docs/projectconf.rst b/docs/projectconf.rst index 6407105171..4dcfa6454d 100644 --- a/docs/projectconf.rst +++ b/docs/projectconf.rst @@ -14,6 +14,24 @@ 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 PlatformIO's home directory that is used to store platforms tools chain, +frameworks, libraries, service data and etc. + + +A default value is user's home directory: *Unix* - ``~/.platformio``, +Windows - ``%HOMEPATH%\.platformio``. + [env:NAME] ---------- diff --git a/platformio/util.py b/platformio/util.py index 8fb6363ba9..3db23bde31 100644 --- a/platformio/util.py +++ b/platformio/util.py @@ -26,7 +26,15 @@ def get_systype(): def get_home_dir(): - return expanduser("~/.platformio") + home_dir = expanduser("~/.platformio") + 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 home_dir def get_source_dir(): From 78bf6c0e2313fcb20b84bc1726bbdd33dca36b33 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Fri, 22 Aug 2014 18:05:27 +0300 Subject: [PATCH 10/44] Italic correction --- docs/projectconf.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/projectconf.rst b/docs/projectconf.rst index 4dcfa6454d..151c549f4e 100644 --- a/docs/projectconf.rst +++ b/docs/projectconf.rst @@ -25,7 +25,7 @@ Options ``home_dir`` ^^^^^^^^^^^^ -A PlatformIO's home directory that is used to store platforms tools chain, +A *PlatformIO*'s home directory that is used to store platforms tools chain, frameworks, libraries, service data and etc. From 5f539fdf7ba15f8c74201581145481bf53fff327 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 23 Aug 2014 11:51:18 +0300 Subject: [PATCH 11/44] Re-tested with Click 3.2 --- platformio/util.py | 3 +-- requirements.txt | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/platformio/util.py b/platformio/util.py index 3db23bde31..34a1d785fd 100644 --- a/platformio/util.py +++ b/platformio/util.py @@ -26,7 +26,6 @@ def get_systype(): def get_home_dir(): - home_dir = expanduser("~/.platformio") try: config = get_project_config() if (config.has_section("platformio") and @@ -34,7 +33,7 @@ def get_home_dir(): return config.get("platformio", "home_dir") except NotPlatformProject: pass - return home_dir + return expanduser("~/.platformio") def get_source_dir(): diff --git a/requirements.txt b/requirements.txt index 80c2ca8cf1..bb4f5a8352 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -click==3.1 +click==3.2 colorama==0.3.1 pyserial==2.7 requests==2.3.0 From a7bc72aa41fab699e27a5329d88549e5063dab61 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Thu, 28 Aug 2014 21:20:15 +0300 Subject: [PATCH 12/44] Improve installation section --- docs/installation.rst | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 4245c70941..d0f875bb31 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -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 https://raw.githubusercontent.com/ivankravets/platformio/develop/scripts/get-platformio.py | 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 From 69b73935d04a14093a4abe1ad6790e8e8a397749 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Mon, 1 Sep 2014 10:30:01 +0300 Subject: [PATCH 13/44] Updated "requests" to 2.4.0 --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index bb4f5a8352..b47df8f983 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,5 @@ click==3.2 colorama==0.3.1 pyserial==2.7 -requests==2.3.0 +requests==2.4.0 scons==2.3.0 From 3d179fe1a78fc90856f0fec50122c4688a8719fb Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Wed, 3 Sep 2014 23:03:49 +0300 Subject: [PATCH 14/44] Implement "lib search" command --- platformio/__init__.py | 1 + platformio/commands/lib.py | 41 ++++++++++++++++++++++++++++++++++++++ platformio/exception.py | 5 +++++ 3 files changed, 47 insertions(+) create mode 100644 platformio/commands/lib.py diff --git a/platformio/__init__.py b/platformio/__init__.py index aa4db29f66..ecadb2c2a5 100644 --- a/platformio/__init__.py +++ b/platformio/__init__.py @@ -14,4 +14,5 @@ __license__ = "MIT Licence" __copyright__ = "Copyright (C) 2014 Ivan Kravets" +__apiurl__ = "http://api.platformio.ikravets.com" __pkgmanifesturl__ = "http://platformio.ikravets.com/packages/manifest.json" diff --git a/platformio/commands/lib.py b/platformio/commands/lib.py new file mode 100644 index 0000000000..045c42647d --- /dev/null +++ b/platformio/commands/lib.py @@ -0,0 +1,41 @@ +# Copyright (C) Ivan Kravets +# See LICENSE for details. + +from click import argument, group, echo, style, secho +from requests import get +from requests.exceptions import ConnectionError + +from platformio import __apiurl__ +from platformio.exception import APIRequestError + + +def get_api_result(query): + result = None + r = None + try: + r = get(__apiurl__ + query) + result = r.json() + 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 + + +@group(short_help="Library Manager") +def cli(): + pass + + +@cli.command("search", short_help="Search for library") +@argument("query") +def lib_search(query): + result = get_api_result("/lib/search?query=%s" % query) + secho("Found [ %d ] libraries:" % result['total'], + fg="green" if result['total'] else "yellow") + for item in result['items']: + echo("{name:<30} {info}".format(name=style(item['name'], fg="cyan"), + info=item['description'])) diff --git a/platformio/exception.py b/platformio/exception.py index 046ad0846e..f5d4b81953 100644 --- a/platformio/exception.py +++ b/platformio/exception.py @@ -105,3 +105,8 @@ class GetSerialPortsError(PlatformioException): class GetLatestVersionError(PlatformioException): MESSAGE = "Can't retrieve latest PlatformIO version" + + +class APIRequestError(PlatformioException): + + MESSAGE = "[API] %s" From 855df959eec5c3d0178785dfe7a4aa97a6281ab5 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Thu, 4 Sep 2014 18:55:56 +0300 Subject: [PATCH 15/44] Parse .pde as .ino file --- platformio/builder/tools/platformio.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/platformio/builder/tools/platformio.py b/platformio/builder/tools/platformio.py index 103ca4b559..5285309fec 100644 --- a/platformio/builder/tools/platformio.py +++ b/platformio/builder/tools/platformio.py @@ -165,8 +165,9 @@ def delete_tmpcpp(files): 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 From 35e7c8b3a7a6c58745d1fe613e0c96616915490b Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Thu, 4 Sep 2014 18:56:32 +0300 Subject: [PATCH 16/44] Seek for library in user's lib directory --- platformio/builder/main.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/platformio/builder/main.py b/platformio/builder/main.py index 97c0be782b..07fd7725b6 100644 --- a/platformio/builder/main.py +++ b/platformio/builder/main.py @@ -16,7 +16,8 @@ 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 @@ BUILD_DIR=join("$PIOENVS_DIR", "$PIOENV"), LIBSOURCE_DIRS=[ join("$PROJECT_DIR", "lib"), + get_lib_dir(), join("$PLATFORMFW_DIR", "libraries"), ] ) From 3c030edc386511ae6b474ce6ca1c103e13748fe4 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Thu, 4 Sep 2014 18:57:13 +0300 Subject: [PATCH 17/44] Grammar fix --- platformio/commands/show.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platformio/commands/show.py b/platformio/commands/show.py index 616a7a519e..38cb4212fb 100644 --- a/platformio/commands/show.py +++ b/platformio/commands/show.py @@ -10,7 +10,7 @@ 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) From bac0a5ebb1ab47a6eee717e2e3ec19c67b16161f Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Thu, 4 Sep 2014 18:58:12 +0300 Subject: [PATCH 18/44] Implement lib commands: install, uninstall, show, update, list --- platformio/__init__.py | 3 +- platformio/commands/lib.py | 135 ++++++++++++++++++++++++++++++------- platformio/exception.py | 9 +++ platformio/libmanager.py | 75 +++++++++++++++++++++ platformio/util.py | 42 +++++++++++- 5 files changed, 236 insertions(+), 28 deletions(-) create mode 100644 platformio/libmanager.py diff --git a/platformio/__init__.py b/platformio/__init__.py index ecadb2c2a5..ff142955e9 100644 --- a/platformio/__init__.py +++ b/platformio/__init__.py @@ -1,7 +1,7 @@ # Copyright (C) Ivan Kravets # See LICENSE for details. -VERSION = (0, 7, "0-dev") +VERSION = (0, 7, "0.dev") __version__ = ".".join([str(s) for s in VERSION]) __title__ = "platformio" @@ -14,5 +14,6 @@ __license__ = "MIT Licence" __copyright__ = "Copyright (C) 2014 Ivan Kravets" +# __apiurl__ = "http://127.0.0.1:8080" __apiurl__ = "http://api.platformio.ikravets.com" __pkgmanifesturl__ = "http://platformio.ikravets.com/packages/manifest.json" diff --git a/platformio/commands/lib.py b/platformio/commands/lib.py index 045c42647d..fc5f1bcc8f 100644 --- a/platformio/commands/lib.py +++ b/platformio/commands/lib.py @@ -1,28 +1,13 @@ # Copyright (C) Ivan Kravets # See LICENSE for details. -from click import argument, group, echo, style, secho -from requests import get -from requests.exceptions import ConnectionError - -from platformio import __apiurl__ -from platformio.exception import APIRequestError - - -def get_api_result(query): - result = None - r = None - try: - r = get(__apiurl__ + query) - result = r.json() - 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 +from urllib import quote + +from click import argument, echo, group, option, secho, style + +from platformio.exception import LibAlreadyInstalledError +from platformio.libmanager import LibraryManager +from platformio.util import get_api_result, get_lib_dir @group(short_help="Library Manager") @@ -33,9 +18,107 @@ def cli(): @cli.command("search", short_help="Search for library") @argument("query") def lib_search(query): - result = get_api_result("/lib/search?query=%s" % query) - secho("Found [ %d ] libraries:" % result['total'], + result = get_api_result("/lib/search", dict(query=quote(query))) + secho("Found %d libraries:" % result['total'], fg="green" if result['total'] else "yellow") for item in result['items']: - echo("{name:<30} {info}".format(name=style(item['name'], fg="cyan"), - info=item['description'])) + echo("{name:<30} {description}".format( + name=style(item['name'], fg="cyan"), + description=item['description'] + )) + + +@cli.command("install", short_help="Install library") +@argument("names", nargs=-1) +@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: + echo("Installing %s library:" % style(name, fg="cyan")) + try: + if lm.install(name, version): + secho("The library '%s' has been successfully installed!" % + name, fg="green") + except LibAlreadyInstalledError: + secho("Already installed", fg="yellow") + + +@cli.command("uninstall", short_help="Uninstall libraries") +@argument("names", nargs=-1) +def lib_uninstall_cli(names): + lib_uninstall(names) + + +def lib_uninstall(names): + lm = LibraryManager(get_lib_dir()) + for name in names: + if lm.uninstall(name): + 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) + echo("{name:<30} {description}".format( + name=style(info['name'], fg="cyan"), + description=info['description'] + )) + + +@cli.command("show", short_help="Show details about installed libraries") +@argument("name") +def lib_show(name): + lm = LibraryManager(get_lib_dir()) + info = lm.get_info(name) + secho(info['name'], fg="cyan") + 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) + echo("Author: %s" % " ".join(_data)) + + echo("Keywords: %s" % info['keywords']) + echo("Version: %s" % info['version']) + echo() + echo(info['description']) + 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) + + echo("Updating %s library:" % style(name, fg="yellow")) + + current_version = info['version'] + latest_version = versions[name] + + echo("Versions: Current=%s, Latest=%s \t " % ( + current_version, latest_version), nl=False) + + if current_version == latest_version: + echo("[%s]" % (style("Up-to-date", fg="green"))) + continue + else: + echo("[%s]" % (style("Out-of-date", fg="red"))) + + lib_uninstall([name]) + lib_install([name]) diff --git a/platformio/exception.py b/platformio/exception.py index f5d4b81953..920ee521e3 100644 --- a/platformio/exception.py +++ b/platformio/exception.py @@ -110,3 +110,12 @@ class GetLatestVersionError(PlatformioException): class APIRequestError(PlatformioException): MESSAGE = "[API] %s" + + +class LibAlreadyInstalledError(PlatformioException): + pass + + +class LibNotInstalledError(PlatformioException): + + MESSAGE = "Library '%s' has not been installed yet" diff --git a/platformio/libmanager.py b/platformio/libmanager.py new file mode 100644 index 0000000000..2fb4a18587 --- /dev/null +++ b/platformio/libmanager.py @@ -0,0 +1,75 @@ +# Copyright (C) Ivan Kravets +# 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) diff --git a/platformio/util.py b/platformio/util.py index 34a1d785fd..63a1047508 100644 --- a/platformio/util.py +++ b/platformio/util.py @@ -8,9 +8,14 @@ from subprocess import PIPE, Popen from time import sleep +from requests import get +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 @@ -36,6 +41,17 @@ def get_home_dir(): 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__)) @@ -96,3 +112,27 @@ 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): + result = None + r = None + try: + headers = {"User-Agent": "PlatformIO/%s %s" % ( + __version__, default_user_agent())} + 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 From c784c7ab479ecec9cdeb30738cb0db61bbae735d Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Fri, 5 Sep 2014 21:27:10 +0300 Subject: [PATCH 19/44] Typo fix --- platformio/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platformio/__init__.py b/platformio/__init__.py index aa4db29f66..695d579e28 100644 --- a/platformio/__init__.py +++ b/platformio/__init__.py @@ -11,7 +11,7 @@ __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" From 46fb576c9dcf83c40b67c75dade5b43a4d122e7f Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Fri, 5 Sep 2014 21:55:47 +0300 Subject: [PATCH 20/44] Switch package manifest to dl.platformio --- platformio/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platformio/__init__.py b/platformio/__init__.py index 20a96f5bcd..3765e754b3 100644 --- a/platformio/__init__.py +++ b/platformio/__init__.py @@ -16,4 +16,4 @@ # __apiurl__ = "http://127.0.0.1:8080" __apiurl__ = "http://api.platformio.ikravets.com" -__pkgmanifesturl__ = "http://platformio.ikravets.com/packages/manifest.json" +__pkgmanifesturl__ = "http://dl.platformio.ikravets.com/packages/manifest.json" From a98dc5bc2910e3bf5aba0b8c9ae5dd0a6a9d7a2d Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 6 Sep 2014 12:12:13 +0300 Subject: [PATCH 21/44] Implement --keyword and --author options for library search command --- platformio/commands/lib.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/platformio/commands/lib.py b/platformio/commands/lib.py index fc5f1bcc8f..ad6fba004e 100644 --- a/platformio/commands/lib.py +++ b/platformio/commands/lib.py @@ -1,8 +1,6 @@ # Copyright (C) Ivan Kravets # See LICENSE for details. -from urllib import quote - from click import argument, echo, group, option, secho, style from platformio.exception import LibAlreadyInstalledError @@ -16,9 +14,15 @@ def cli(): @cli.command("search", short_help="Search for library") +@option("-a", "--author", multiple=True) +@option("-k", "--keyword", multiple=True) @argument("query") -def lib_search(query): - result = get_api_result("/lib/search", dict(query=quote(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)) secho("Found %d libraries:" % result['total'], fg="green" if result['total'] else "yellow") for item in result['items']: From be710cefd8d630b9388789d89769544add96c6e0 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 6 Sep 2014 12:53:17 +0300 Subject: [PATCH 22/44] Implement installing dependence libs --- platformio/commands/lib.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/platformio/commands/lib.py b/platformio/commands/lib.py index ad6fba004e..c7815edad9 100644 --- a/platformio/commands/lib.py +++ b/platformio/commands/lib.py @@ -47,6 +47,11 @@ def lib_install(names, version=None): if lm.install(name, version): secho("The library '%s' has been successfully installed!" % name, fg="green") + info = lm.get_info(name) + if "dependencies" in info: + secho("Installing dependencies:", fg="yellow") + lib_install(info['dependencies']) + except LibAlreadyInstalledError: secho("Already installed", fg="yellow") From 849a49f665b10a223fe83f1c75cb900230462925 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 6 Sep 2014 13:44:45 +0300 Subject: [PATCH 23/44] Add Library Manager documentation --- docs/index.rst | 1 + docs/librarymanager/config.rst | 12 +++ docs/librarymanager/index.rst | 11 +++ docs/userguide/index.rst | 1 + docs/userguide/lib/cmd_install.rst | 68 ++++++++++++++ docs/userguide/lib/cmd_list.rst | 31 ++++++ docs/userguide/lib/cmd_search.rst | 136 +++++++++++++++++++++++++++ docs/userguide/lib/cmd_show.rst | 34 +++++++ docs/userguide/lib/cmd_uninstall.rst | 31 ++++++ docs/userguide/lib/cmd_update.rst | 33 +++++++ docs/userguide/lib/index.rst | 22 +++++ 11 files changed, 380 insertions(+) create mode 100644 docs/librarymanager/config.rst create mode 100644 docs/librarymanager/index.rst create mode 100644 docs/userguide/lib/cmd_install.rst create mode 100644 docs/userguide/lib/cmd_list.rst create mode 100644 docs/userguide/lib/cmd_search.rst create mode 100644 docs/userguide/lib/cmd_show.rst create mode 100644 docs/userguide/lib/cmd_uninstall.rst create mode 100644 docs/userguide/lib/cmd_update.rst create mode 100644 docs/userguide/lib/index.rst diff --git a/docs/index.rst b/docs/index.rst index d082ae73ac..be90e81593 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -42,6 +42,7 @@ Contents installation projectconf platforms/index + librarymanager/index userguide/index ide history diff --git a/docs/librarymanager/config.rst b/docs/librarymanager/config.rst new file mode 100644 index 0000000000..dd565f76d1 --- /dev/null +++ b/docs/librarymanager/config.rst @@ -0,0 +1,12 @@ +.. _library_config: + +library.json +============ + +Library Configuration File + +.. warning:: + The filling of this page is currently in progress... + + For more detailed information please go to + `GitHub Issue #6 `_. diff --git a/docs/librarymanager/index.rst b/docs/librarymanager/index.rst new file mode 100644 index 0000000000..d17de1f78e --- /dev/null +++ b/docs/librarymanager/index.rst @@ -0,0 +1,11 @@ +.. _librarymanager: + +Library Manager +=============== + + +.. toctree:: + :maxdepth: 2 + + config + User Guide <../userguide/lib/index> diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst index 5779209aad..3cadb2f55e 100644 --- a/docs/userguide/index.rst +++ b/docs/userguide/index.rst @@ -16,6 +16,7 @@ To print all available commands and options use: cmd_init cmd_install + platformio lib cmd_list cmd_run cmd_search diff --git a/docs/userguide/lib/cmd_install.rst b/docs/userguide/lib/cmd_install.rst new file mode 100644 index 0000000000..81483ff5ae --- /dev/null +++ b/docs/userguide/lib/cmd_install.rst @@ -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! diff --git a/docs/userguide/lib/cmd_list.rst b/docs/userguide/lib/cmd_list.rst new file mode 100644 index 0000000000..757bc7de26 --- /dev/null +++ b/docs/userguide/lib/cmd_list.rst @@ -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 diff --git a/docs/userguide/lib/cmd_search.rst b/docs/userguide/lib/cmd_search.rst new file mode 100644 index 0000000000..2ddd31a04c --- /dev/null +++ b/docs/userguide/lib/cmd_search.rst @@ -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 ``library.json`` 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 `_. + +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 diff --git a/docs/userguide/lib/cmd_show.rst b/docs/userguide/lib/cmd_show.rst new file mode 100644 index 0000000000..b7cca0449a --- /dev/null +++ b/docs/userguide/lib/cmd_show.rst @@ -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 + Keywords: xbee, protocol, radio + Version: 0.5 + + Arduino library for communicating with XBees in API mode diff --git a/docs/userguide/lib/cmd_uninstall.rst b/docs/userguide/lib/cmd_uninstall.rst new file mode 100644 index 0000000000..66a26b75f1 --- /dev/null +++ b/docs/userguide/lib/cmd_uninstall.rst @@ -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! diff --git a/docs/userguide/lib/cmd_update.rst b/docs/userguide/lib/cmd_update.rst new file mode 100644 index 0000000000..68d6b361d8 --- /dev/null +++ b/docs/userguide/lib/cmd_update.rst @@ -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] diff --git a/docs/userguide/lib/index.rst b/docs/userguide/lib/index.rst new file mode 100644 index 0000000000..d1d5802a5d --- /dev/null +++ b/docs/userguide/lib/index.rst @@ -0,0 +1,22 @@ +.. _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_search + cmd_show + cmd_uninstall + cmd_update From 1631770b852938597ac7ffa5a47f22525a11d5c4 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 6 Sep 2014 18:46:19 +0300 Subject: [PATCH 24/44] Describe "lib_dir" option --- docs/projectconf.rst | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/projectconf.rst b/docs/projectconf.rst index 151c549f4e..d63996e85d 100644 --- a/docs/projectconf.rst +++ b/docs/projectconf.rst @@ -25,13 +25,21 @@ Options ``home_dir`` ^^^^^^^^^^^^ -A *PlatformIO*'s home directory that is used to store platforms tools chain, -frameworks, libraries, service data and etc. - +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] ---------- From 23bc5188b3655b30856e4d3668de9f2d0b5495ca Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 6 Sep 2014 22:13:16 +0300 Subject: [PATCH 25/44] Fill Library Config information --- docs/librarymanager/config.rst | 205 +++++++++++++++++++++++++++++- docs/librarymanager/index.rst | 10 ++ docs/userguide/lib/cmd_search.rst | 2 +- 3 files changed, 211 insertions(+), 6 deletions(-) diff --git a/docs/librarymanager/config.rst b/docs/librarymanager/config.rst index dd565f76d1..8ef62e430c 100644 --- a/docs/librarymanager/config.rst +++ b/docs/librarymanager/config.rst @@ -3,10 +3,205 @@ library.json ============ -Library Configuration File +Libraries are defined by a manifest file ``library.json``. This is a +`JSON-style `_ file. Any data in +``library.json`` should be represented via +`associative array `_ +(name/value pairs). An order doesn't make a sense. -.. warning:: - The filling of this page is currently in progress... +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 search/lookup results on the :ref:`cmd_lib_search` +(*CLI*) and the *WebSite* that can be used to search for libraries. - For more detailed information please go to - `GitHub Issue #6 `_. +.. contents:: + +.. _libjson_name: + +``name`` +-------- + +**Required** | Type: ``String`` | Max. Length: 50 + +The 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, can contain dash (but not start/end + with them). +* Consecutive dashes are not allowed. + + +.. _libjson_description: + +``description`` +--------------- + +**Required** | Type: ``String`` | Max. Length: 255 + +Help users 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 + +The keyword should be lowercased, can contain a-z, digits and dash (but not +start/end with them). A list from keywords can be specified with +separator ``,``. + +Used for search by keyword. Helps make your library easier to discover without +people needing to know its name. + + +.. _libjson_version: + +``version`` +----------- + +*Required* if :ref:`libjson_repository` field is not defined | Type: ``String`` +| Max. Length: 20 + +The version of the current library source code. + +* Can contain a-z, digits, dots and dash. +* `Semantic Versioning `_ is recommended. +* A `CVS `_ + 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 situation + *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's 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 situation + *PlatformIO-API Crawler* will use information from + `GitHub API 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`` + +The *HTTP URL* to 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 `_ + +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 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 `_ + +Exclude the directories and files which will match with :ref:`libjson_exclude` +patterns. diff --git a/docs/librarymanager/index.rst b/docs/librarymanager/index.rst index d17de1f78e..95679ca934 100644 --- a/docs/librarymanager/index.rst +++ b/docs/librarymanager/index.rst @@ -3,6 +3,16 @@ Library Manager =============== +*"The missing libraries manager for embedded platforms"*, - inspired by +`npm `_ and `bower `_ package managers +for web. + +*PlatformIO Library Manager* allows you to organize external embedded libraries. +You can search for new libraries via :ref:`Command Line ` +or `WebSite `_ 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 diff --git a/docs/userguide/lib/cmd_search.rst b/docs/userguide/lib/cmd_search.rst index 2ddd31a04c..14d92f5d73 100644 --- a/docs/userguide/lib/cmd_search.rst +++ b/docs/userguide/lib/cmd_search.rst @@ -17,7 +17,7 @@ Description ----------- Search for library over ``name``, ``description`` and ``keywords`` fields from -the ``library.json`` file in the boolean mode. +the :ref:`library_config` file in the boolean mode. The boolean search capability supports the following operators: From 2ac4b9a5905e9cd52ca452298a42f93af1d96d59 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 6 Sep 2014 22:19:51 +0300 Subject: [PATCH 26/44] Fill history with Library Manager record --- HISTORY.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/HISTORY.rst b/HISTORY.rst index b005a2db62..9f53d1861a 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -6,6 +6,7 @@ Release History * Implemented new ``[platformio]`` section for Configuration File with ``home_dir`` option (`issue #14 `_) +* Implemented *Library Manager* (`issue #6 `_) 0.6.0 (2014-08-09) ------------------ From f3163088608f73882bd40160b04650188e85db0c Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 6 Sep 2014 22:27:33 +0300 Subject: [PATCH 27/44] Describe "dependencies" field from library.json --- docs/librarymanager/config.rst | 22 ++++++++++++++++++++++ docs/librarymanager/index.rst | 1 - 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/librarymanager/config.rst b/docs/librarymanager/config.rst index 8ef62e430c..b0baf3bf61 100644 --- a/docs/librarymanager/config.rst +++ b/docs/librarymanager/config.rst @@ -195,6 +195,7 @@ Pattern Meaning * - ``[!seq]`` - matches any character not in seq + .. _libjson_exclude: ``exclude`` @@ -205,3 +206,24 @@ Pattern Meaning Exclude the directories and files which will match with :ref:`libjson_exclude` patterns. + + +.. _libjson_dependencies: + +``dependencies`` +---------------- + +*Optional* | Type: ``Array`` + +The list of dependent libraries. They will be installed automatically with +:ref:`cmd_lib_install` command. + +Example: + +.. code-block:: javascript + + "dependencies": + [ + "Library-Foo", + "Library-Bar" + ] diff --git a/docs/librarymanager/index.rst b/docs/librarymanager/index.rst index 95679ca934..f93a83dee8 100644 --- a/docs/librarymanager/index.rst +++ b/docs/librarymanager/index.rst @@ -18,4 +18,3 @@ You don't need to bother for finding the latest version of library. Due to :maxdepth: 2 config - User Guide <../userguide/lib/index> From 6fdc47bedab4bb9e75c758c16b1dd7ec722112de Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 6 Sep 2014 23:51:28 +0300 Subject: [PATCH 28/44] Describe how to create new library and share it --- docs/librarymanager/create.rst | 129 ++++++++++++++++++++++++++++ docs/librarymanager/index.rst | 1 + docs/userguide/lib/cmd_register.rst | 26 ++++++ docs/userguide/lib/index.rst | 1 + 4 files changed, 157 insertions(+) create mode 100644 docs/librarymanager/create.rst create mode 100644 docs/userguide/lib/cmd_register.rst diff --git a/docs/librarymanager/create.rst b/docs/librarymanager/create.rst new file mode 100644 index 0000000000..0ea70477d2 --- /dev/null +++ b/docs/librarymanager/create.rst @@ -0,0 +1,129 @@ +.. _library_create: +.. |PIOAPICR| replace:: *PlatformIO-API Crawler* + +Create Library +============== + +*PlatformIO* :ref:`librarymanager` doesn't has 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 `_). + +Also, you can hold a lot of libraries inside the one repository/archive in the +different folders. In this case please use :ref:`libjson_include` field to +specify the relative path to your library's source code. + + +Source Code at GitHub +^^^^^^^^^^^^^^^^^^^^^ + +**Recommended** + +If the library source code is located at `GitHub `_, then +you **need to specify** only these fields in :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 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" + } + } + +Source Code under CVS (SVN/GIT) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +|PIOAPICR| can operate with the library source code that is under *CVS* control. +The list of **required** fields in :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/" + } + } + +Source Code Archived (Zip, Tar.Gz) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can manually archive your library source code and host it in the *Internet*. +Then you should specify additional fields, like :ref:`libjson_version` and +:ref:`libjson_downloadurl`. The final list of **required** fields in +: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 library must adhere to the :ref:`library_config` specification. +* There must be public *HTTP* access to library :ref:`library_config` file. + +Now, you can :ref:`register ` your library and allow others +to :ref:`install ` it. + diff --git a/docs/librarymanager/index.rst b/docs/librarymanager/index.rst index f93a83dee8..8f7a857fcf 100644 --- a/docs/librarymanager/index.rst +++ b/docs/librarymanager/index.rst @@ -17,4 +17,5 @@ You don't need to bother for finding the latest version of library. Due to .. toctree:: :maxdepth: 2 + create config diff --git a/docs/userguide/lib/cmd_register.rst b/docs/userguide/lib/cmd_register.rst new file mode 100644 index 0000000000..fddb147812 --- /dev/null +++ b/docs/userguide/lib/cmd_register.rst @@ -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 diff --git a/docs/userguide/lib/index.rst b/docs/userguide/lib/index.rst index d1d5802a5d..6d2c5fead2 100644 --- a/docs/userguide/lib/index.rst +++ b/docs/userguide/lib/index.rst @@ -16,6 +16,7 @@ To print all available commands and options use: cmd_install cmd_list + cmd_register cmd_search cmd_show cmd_uninstall From 369622f3fb27189dd7d113c423972f271e6c7aab Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sat, 6 Sep 2014 23:55:48 +0300 Subject: [PATCH 29/44] Correct source code locations --- docs/librarymanager/create.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/librarymanager/create.rst b/docs/librarymanager/create.rst index 0ea70477d2..633e333706 100644 --- a/docs/librarymanager/create.rst +++ b/docs/librarymanager/create.rst @@ -22,8 +22,8 @@ different folders. In this case please use :ref:`libjson_include` field to specify the relative path to your library's source code. -Source Code at GitHub -^^^^^^^^^^^^^^^^^^^^^ +At GitHub +^^^^^^^^^ **Recommended** @@ -53,8 +53,8 @@ Example: } } -Source Code under CVS (SVN/GIT) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Under CVS (SVN/GIT) +^^^^^^^^^^^^^^^^^^^ |PIOAPICR| can operate with the library source code that is under *CVS* control. The list of **required** fields in :ref:`library_config` will look like: @@ -86,8 +86,8 @@ Example: } } -Source Code Archived (Zip, Tar.Gz) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Packed in achive (Zip, Tar.Gz) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can manually archive your library source code and host it in the *Internet*. Then you should specify additional fields, like :ref:`libjson_version` and From 5fa265374c5695cc0948fb7cc9612a9054e4d2b9 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sun, 7 Sep 2014 15:09:32 +0300 Subject: [PATCH 30/44] Rename "create" page --- docs/librarymanager/create.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/librarymanager/create.rst b/docs/librarymanager/create.rst index 633e333706..88f88c1322 100644 --- a/docs/librarymanager/create.rst +++ b/docs/librarymanager/create.rst @@ -1,8 +1,8 @@ .. _library_create: .. |PIOAPICR| replace:: *PlatformIO-API Crawler* -Create Library -============== +Creating Library +================ *PlatformIO* :ref:`librarymanager` doesn't has any requirements to a library source code structure. The only one requirement is library's manifest file - From 995a25478b980327a871e8fde493421a62b32e69 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sun, 7 Sep 2014 18:14:33 +0300 Subject: [PATCH 31/44] Improvements --- docs/librarymanager/config.rst | 42 +++++++++++++++++----------------- docs/librarymanager/create.rst | 37 +++++++++++++++--------------- docs/librarymanager/index.rst | 2 +- 3 files changed, 41 insertions(+), 40 deletions(-) diff --git a/docs/librarymanager/config.rst b/docs/librarymanager/config.rst index b0baf3bf61..ff048e326c 100644 --- a/docs/librarymanager/config.rst +++ b/docs/librarymanager/config.rst @@ -3,15 +3,15 @@ library.json ============ -Libraries are defined by a manifest file ``library.json``. This is a -`JSON-style `_ file. Any data in -``library.json`` should be represented via +*PlatformIO*-suitable library should be defined by a manifest file +``library.json`` in a `JSON-style `_. +A data in ``library.json`` should be represented via `associative array `_ (name/value pairs). An order doesn't make a sense. 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 search/lookup results on the :ref:`cmd_lib_search` +will be displayed in search results on the :ref:`cmd_lib_search` (*CLI*) and the *WebSite* that can be used to search for libraries. .. contents:: @@ -23,12 +23,12 @@ will be displayed in search/lookup results on the :ref:`cmd_lib_search` **Required** | Type: ``String`` | Max. Length: 50 -The name of the library. +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, can contain dash (but not start/end + Example: *Arduino-SPI* +* Title Case, Aa-z, can contain digits and dashes (but not start/end with them). * Consecutive dashes are not allowed. @@ -52,13 +52,13 @@ with it. **Required** | Type: ``String`` | Max. Length: 255 -The keyword should be lowercased, can contain a-z, digits and dash (but not -start/end with them). A list from keywords can be specified with -separator ``,``. - Used for search by keyword. Helps 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: @@ -68,9 +68,9 @@ people needing to know its name. *Required* if :ref:`libjson_repository` field is not defined | Type: ``String`` | Max. Length: 20 -The version of the current library source code. +A version of the current library source code. -* Can contain a-z, digits, dots and dash. +* Can contain a-z, digits, dots or dash. * `Semantic Versioning `_ is recommended. * A `CVS `_ revision from the latest commit. Example: ``13`` (*SVN*) or first 10 @@ -78,8 +78,8 @@ The version of the current library source code. .. note:: You can omit :ref:`libjson_version` field and define - :ref:`libjson_repository` field. In this situation - *PlatformIO-API Crawler* will use the CVS-revision from the latest commit. + :ref:`libjson_repository` field. In this case + *PlatformIO-API Crawler* will use the *CVS*-revision from the latest commit. .. _libjson_author: @@ -89,7 +89,7 @@ The version of the current library source code. *Required* if :ref:`libjson_repository` field is not defined | Type: ``Object`` -An author's contact information +An author contact information * ``name`` Full name (**Required**) * ``email`` @@ -108,8 +108,8 @@ Example: .. note:: You can omit :ref:`libjson_author` field and define - :ref:`libjson_repository` field. Only *GitHub-based* repository is - supported now. In this situation + :ref:`libjson_repository` field. The only *GitHub-based* repository is + supported now. In this case *PlatformIO-API Crawler* will use information from `GitHub API Users `_. @@ -155,7 +155,7 @@ of archive (``.zip`` or ``.tar.gz``). 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 only +repository/archive to library source code". See example below where the only source code from the relative directory ``LibrarySourceCodeHere`` will be included. @@ -204,7 +204,7 @@ Pattern Meaning *Optional* | Type: ``String`` or ``Array`` | `Glob Pattern `_ -Exclude the directories and files which will match with :ref:`libjson_exclude` +Exclude the directories and files which match with :ref:`libjson_exclude` patterns. @@ -215,7 +215,7 @@ patterns. *Optional* | Type: ``Array`` -The list of dependent libraries. They will be installed automatically with +A list of dependent libraries. They will be installed automatically with :ref:`cmd_lib_install` command. Example: diff --git a/docs/librarymanager/create.rst b/docs/librarymanager/create.rst index 88f88c1322..5e2351eb9f 100644 --- a/docs/librarymanager/create.rst +++ b/docs/librarymanager/create.rst @@ -4,7 +4,7 @@ Creating Library ================ -*PlatformIO* :ref:`librarymanager` doesn't has any requirements to a 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. @@ -17,9 +17,9 @@ Source Code Location There are a several ways how to share your library with the whole world (see `examples `_). -Also, you can hold a lot of libraries inside the one repository/archive in the -different folders. In this case please use :ref:`libjson_include` field to -specify the relative path to your library's source code. +You can hold a lot of libraries (split into separated folders) inside the one +repository/archive. In this case please use :ref:`libjson_include` +field to specify the relative path to your library's source code. At GitHub @@ -27,8 +27,8 @@ At GitHub **Recommended** -If the library source code is located at `GitHub `_, then -you **need to specify** only these fields in :ref:`library_config`: +If a library source code is located at `GitHub `_, then +you **need to specify** only these fields in the :ref:`library_config`: * :ref:`libjson_name` * :ref:`libjson_keywords` @@ -36,7 +36,7 @@ you **need to specify** only these fields in :ref:`library_config`: * :ref:`libjson_repository` |PIOAPICR| will populate the rest fields, like :ref:`libjson_version` or -:ref:`libjson_author` with actual information from *GitHub*. +:ref:`libjson_author` with an actual information from *GitHub*. Example: @@ -56,8 +56,8 @@ Example: Under CVS (SVN/GIT) ^^^^^^^^^^^^^^^^^^^ -|PIOAPICR| can operate with the library source code that is under *CVS* control. -The list of **required** fields in :ref:`library_config` will look like: +|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` @@ -86,13 +86,13 @@ Example: } } -Packed in achive (Zip, Tar.Gz) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Packed into Archive +^^^^^^^^^^^^^^^^^^^ -You can manually archive your library source code and host it in the *Internet*. -Then you should specify additional fields, like :ref:`libjson_version` and -:ref:`libjson_downloadurl`. The final list of **required** fields in -:ref:`library_config` will look like: +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` @@ -121,9 +121,10 @@ Then you should specify additional fields, like :ref:`libjson_version` and Register -------- -* The library must adhere to the :ref:`library_config` specification. -* There must be public *HTTP* access to library :ref:`library_config` file. +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 ` your library and allow others to :ref:`install ` it. - diff --git a/docs/librarymanager/index.rst b/docs/librarymanager/index.rst index 8f7a857fcf..bef1759e27 100644 --- a/docs/librarymanager/index.rst +++ b/docs/librarymanager/index.rst @@ -3,7 +3,7 @@ Library Manager =============== -*"The missing libraries manager for embedded platforms"*, - inspired by +*"The missing library manager for embedded platforms"*, - inspired by `npm `_ and `bower `_ package managers for web. From 727ec2f4dcce645402f58524197e38eddb6a57dd Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sun, 7 Sep 2014 18:22:52 +0300 Subject: [PATCH 32/44] Add citation block --- docs/librarymanager/index.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/librarymanager/index.rst b/docs/librarymanager/index.rst index bef1759e27..26a4eed96c 100644 --- a/docs/librarymanager/index.rst +++ b/docs/librarymanager/index.rst @@ -3,9 +3,11 @@ Library Manager =============== -*"The missing library manager for embedded platforms"*, - inspired by -`npm `_ and `bower `_ package managers -for web. +.. + + *"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 ` @@ -19,3 +21,6 @@ You don't need to bother for finding the latest version of library. Due to create config + +.. [#] Inspired by `npm `_ and `bower + `_ package managers for web. From ac66f622628fadea332db0a04bd1500e1556d971 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Sun, 7 Sep 2014 19:38:00 +0300 Subject: [PATCH 33/44] Rename to "creating" --- docs/librarymanager/{create.rst => creating.rst} | 2 +- docs/librarymanager/index.rst | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) rename docs/librarymanager/{create.rst => creating.rst} (99%) diff --git a/docs/librarymanager/create.rst b/docs/librarymanager/creating.rst similarity index 99% rename from docs/librarymanager/create.rst rename to docs/librarymanager/creating.rst index 5e2351eb9f..7cf55d9859 100644 --- a/docs/librarymanager/create.rst +++ b/docs/librarymanager/creating.rst @@ -1,4 +1,4 @@ -.. _library_create: +.. _library_creating: .. |PIOAPICR| replace:: *PlatformIO-API Crawler* Creating Library diff --git a/docs/librarymanager/index.rst b/docs/librarymanager/index.rst index 26a4eed96c..3840872c87 100644 --- a/docs/librarymanager/index.rst +++ b/docs/librarymanager/index.rst @@ -7,8 +7,6 @@ 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 ` or `WebSite `_ interfaces. @@ -19,7 +17,7 @@ You don't need to bother for finding the latest version of library. Due to .. toctree:: :maxdepth: 2 - create + creating config .. [#] Inspired by `npm `_ and `bower From c4b28ab25269bbc7ca09cf7068f127d881b4a0c6 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Mon, 8 Sep 2014 15:37:04 +0300 Subject: [PATCH 34/44] Rename section of source location --- docs/librarymanager/creating.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/librarymanager/creating.rst b/docs/librarymanager/creating.rst index 7cf55d9859..cc8eccb0ef 100644 --- a/docs/librarymanager/creating.rst +++ b/docs/librarymanager/creating.rst @@ -86,8 +86,8 @@ Example: } } -Packed into Archive -^^^^^^^^^^^^^^^^^^^ +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, From 813c81847759fe8ee5e10758daa447c0143ae978 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Mon, 8 Sep 2014 22:02:57 +0300 Subject: [PATCH 35/44] Implement "lib register" command --- platformio/commands/lib.py | 9 +++++++++ platformio/util.py | 10 +++++++--- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/platformio/commands/lib.py b/platformio/commands/lib.py index c7815edad9..07b696131e 100644 --- a/platformio/commands/lib.py +++ b/platformio/commands/lib.py @@ -131,3 +131,12 @@ def lib_update(): lib_uninstall([name]) lib_install([name]) + + +@cli.command("register", short_help="Register new library") +@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']: + secho(result['message'], fg="green" if "successed" in result and + result['successed'] else "red") diff --git a/platformio/util.py b/platformio/util.py index 63a1047508..c29347d95a 100644 --- a/platformio/util.py +++ b/platformio/util.py @@ -8,7 +8,7 @@ from subprocess import PIPE, Popen from time import sleep -from requests import get +from requests import get, post from requests.exceptions import ConnectionError, HTTPError from requests.utils import default_user_agent from serial import Serial @@ -114,13 +114,17 @@ def get_serialports(): return[{"port": p, "description": d, "hwid": h} for p, d, h in comports()] -def get_api_result(path, params=None): +def get_api_result(path, params=None, data=None): result = None r = None try: headers = {"User-Agent": "PlatformIO/%s %s" % ( __version__, default_user_agent())} - r = get(__apiurl__ + path, params=params, headers=headers) + 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: From fd2571da04272490886023f7286b244f9d2b875d Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Mon, 8 Sep 2014 22:15:05 +0300 Subject: [PATCH 36/44] Updated "click" to 3.3 --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index b47df8f983..650a102b9e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -click==3.2 +click==3.3 colorama==0.3.1 pyserial==2.7 requests==2.4.0 From fbe014f6872ee7acb8e1df33bad7e5b12f0a4827 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Tue, 9 Sep 2014 23:16:36 +0300 Subject: [PATCH 37/44] Corrections --- docs/librarymanager/config.rst | 24 ++++++++++++------------ docs/librarymanager/creating.rst | 4 ++-- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/librarymanager/config.rst b/docs/librarymanager/config.rst index ff048e326c..16dcb4fd37 100644 --- a/docs/librarymanager/config.rst +++ b/docs/librarymanager/config.rst @@ -7,12 +7,12 @@ library.json ``library.json`` in a `JSON-style `_. A data in ``library.json`` should be represented via `associative array `_ -(name/value pairs). An order doesn't make a sense. +(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 search results on the :ref:`cmd_lib_search` -(*CLI*) and the *WebSite* that can be used to search for libraries. +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:: @@ -40,9 +40,9 @@ A name of the library. **Required** | Type: ``String`` | Max. Length: 255 -Help users identify and search for your library with a brief description. -Describe the hardware devices (sensors, boards and etc.) which are suitable -with it. +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: @@ -52,12 +52,12 @@ with it. **Required** | Type: ``String`` | Max. Length: 255 -Used for search by keyword. Helps make your library easier to discover without -people needing to know its name. +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 ``,``. +separator ``,`` .. _libjson_version: @@ -108,7 +108,7 @@ Example: .. note:: You can omit :ref:`libjson_author` field and define - :ref:`libjson_repository` field. The only *GitHub-based* repository is + :ref:`libjson_repository` field. Only *GitHub-based* repository is supported now. In this case *PlatformIO-API Crawler* will use information from `GitHub API Users `_. @@ -141,8 +141,8 @@ Example: *Required* if :ref:`libjson_repository` field is not defined | Type: ``String`` -The *HTTP URL* to archived source code of library. It should end with the type -of archive (``.zip`` or ``.tar.gz``). +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: diff --git a/docs/librarymanager/creating.rst b/docs/librarymanager/creating.rst index cc8eccb0ef..18af7c2c92 100644 --- a/docs/librarymanager/creating.rst +++ b/docs/librarymanager/creating.rst @@ -17,8 +17,8 @@ Source Code Location There are a several ways how to share your library with the whole world (see `examples `_). -You can hold a lot of libraries (split into separated folders) inside the one -repository/archive. In this case please use :ref:`libjson_include` +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. From 70493a7721cac6e48a722b51e30338215fecf647 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Fri, 12 Sep 2014 19:17:31 +0300 Subject: [PATCH 38/44] Update PlatformIO Website URLs --- README.rst | 5 +++-- platformio/__init__.py | 5 ++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index c89e7c8941..d32732d01a 100644 --- a/README.rst +++ b/README.rst @@ -17,8 +17,8 @@ PlatformIO :target: https://pypi.python.org/pypi/platformio/ :alt: License -`Documentation `_ / -`PDF `_ | +`Website `_ | +`Documentation `_ | `Project Examples `_ | `Bugs/Questions `_ | `Blog `_ | @@ -26,6 +26,7 @@ PlatformIO **PlatformIO** is a cross-platform code builder and library manager. +* `Website + Libraries Search `_ * `Quickstart `_ * `Installation `_ * `Project Configuration File `_ diff --git a/platformio/__init__.py b/platformio/__init__.py index 3765e754b3..67cd843e7f 100644 --- a/platformio/__init__.py +++ b/platformio/__init__.py @@ -1,12 +1,12 @@ # Copyright (C) Ivan Kravets # See LICENSE for details. -VERSION = (0, 7, "0.dev") +VERSION = (0, 7, "0-dev") __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" @@ -14,6 +14,5 @@ __license__ = "MIT License" __copyright__ = "Copyright (C) 2014 Ivan Kravets" -# __apiurl__ = "http://127.0.0.1:8080" __apiurl__ = "http://api.platformio.ikravets.com" __pkgmanifesturl__ = "http://dl.platformio.ikravets.com/packages/manifest.json" From f77c195f3d497dd3b2a33eb6f7d2986eda01e0bc Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Fri, 12 Sep 2014 19:18:11 +0300 Subject: [PATCH 39/44] Update "requests" to 2.4.1 --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 650a102b9e..984e12bdab 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,5 @@ click==3.3 colorama==0.3.1 pyserial==2.7 -requests==2.4.0 +requests==2.4.1 scons==2.3.0 From 2dddbfc0744c4a44012b14e112a846740b0c0279 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Fri, 12 Sep 2014 19:18:49 +0300 Subject: [PATCH 40/44] Correction --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index d32732d01a..808382fa96 100644 --- a/README.rst +++ b/README.rst @@ -26,7 +26,7 @@ PlatformIO **PlatformIO** is a cross-platform code builder and library manager. -* `Website + Libraries Search `_ +* `Website + Library Search `_ * `Quickstart `_ * `Installation `_ * `Project Configuration File `_ From 24ec2dc9e42e31d5f8077ec88bd389414941a1e5 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Fri, 12 Sep 2014 19:27:56 +0300 Subject: [PATCH 41/44] Update PlatformIO Website URLs --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index be90e81593..d76fb76d61 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,7 @@ PlatformIO: A cross-platform code builder and library manager ============================================================= +`Website + Library Search `_ | `Project Examples `_ | `Source Code `_ | `Bugs/Questions `_ | From c0c3c8efcde8e4cd37f6288577d942aeddf3a414 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Wed, 24 Sep 2014 21:40:37 +0300 Subject: [PATCH 42/44] Add 'examples' field --- docs/librarymanager/config.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/librarymanager/config.rst b/docs/librarymanager/config.rst index 16dcb4fd37..bfc6692d20 100644 --- a/docs/librarymanager/config.rst +++ b/docs/librarymanager/config.rst @@ -227,3 +227,21 @@ Example: "Library-Foo", "Library-Bar" ] + + +.. _libjson_examples: + +``examples`` +---------------- + +*Optional* | Type: ``String`` or ``Array`` | +`Glob Pattern `_ + +A list of example patterns. This field is predefined with default value: + +.. code-block:: javascript + + "examples": [ + "[Ee]xamples/*/*.ini", + "[Ee]xamples/*/*.pde" + ] From 9c2dbf73f3fe7c8d4e769eef2d4bc7213508c08d Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Wed, 24 Sep 2014 22:18:19 +0300 Subject: [PATCH 43/44] Implement lib-search pagination, dependencies uninstalling --- platformio/commands/lib.py | 111 ++++++++++++++++++++++++------------- 1 file changed, 71 insertions(+), 40 deletions(-) diff --git a/platformio/commands/lib.py b/platformio/commands/lib.py index 07b696131e..9de31be267 100644 --- a/platformio/commands/lib.py +++ b/platformio/commands/lib.py @@ -1,40 +1,53 @@ # Copyright (C) Ivan Kravets # See LICENSE for details. -from click import argument, echo, group, option, secho, style +import click from platformio.exception import LibAlreadyInstalledError from platformio.libmanager import LibraryManager from platformio.util import get_api_result, get_lib_dir -@group(short_help="Library Manager") +@click.group(short_help="Library Manager") def cli(): pass @cli.command("search", short_help="Search for library") -@option("-a", "--author", multiple=True) -@option("-k", "--keyword", multiple=True) -@argument("query") +@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)) - secho("Found %d libraries:" % result['total'], - fg="green" if result['total'] else "yellow") - for item in result['items']: - echo("{name:<30} {description}".format( - name=style(item['name'], fg="cyan"), - description=item['description'] - )) + 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") -@argument("names", nargs=-1) -@option("-v", "--version") +@click.argument("names", nargs=-1) +@click.option("-v", "--version") def lib_install_cli(names, version): lib_install(names, version) @@ -42,32 +55,50 @@ def lib_install_cli(names, version): def lib_install(names, version=None): lm = LibraryManager(get_lib_dir()) for name in names: - echo("Installing %s library:" % style(name, fg="cyan")) + click.echo("Installing %s library:" % click.style(name, fg="cyan")) try: if lm.install(name, version): - secho("The library '%s' has been successfully installed!" % - name, fg="green") + click.secho( + "The library '%s' has been successfully installed!" % + name, fg="green") info = lm.get_info(name) if "dependencies" in info: - secho("Installing dependencies:", fg="yellow") + click.secho("Installing dependencies:", fg="yellow") lib_install(info['dependencies']) except LibAlreadyInstalledError: - secho("Already installed", fg="yellow") + click.secho("Already installed", fg="yellow") @cli.command("uninstall", short_help="Uninstall libraries") -@argument("names", nargs=-1) +@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): - secho("The library '%s' has been successfully " - "uninstalled!" % name, fg="green") + # 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") @@ -75,19 +106,19 @@ def lib_list(): lm = LibraryManager(get_lib_dir()) for name in lm.get_installed(): info = lm.get_info(name) - echo("{name:<30} {description}".format( - name=style(info['name'], fg="cyan"), + 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") -@argument("name") +@click.argument("name") def lib_show(name): lm = LibraryManager(get_lib_dir()) info = lm.get_info(name) - secho(info['name'], fg="cyan") - echo("-" * len(info['name'])) + click.secho(info['name'], fg="cyan") + click.echo("-" * len(info['name'])) if "author" in info: _data = [] @@ -97,13 +128,13 @@ def lib_show(name): if k == "email": _value = "<%s>" % _value _data.append(_value) - echo("Author: %s" % " ".join(_data)) + click.echo("Author: %s" % " ".join(_data)) - echo("Keywords: %s" % info['keywords']) - echo("Version: %s" % info['version']) - echo() - echo(info['description']) - echo() + 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") @@ -115,28 +146,28 @@ def lib_update(): for name in lib_names: info = lm.get_info(name) - echo("Updating %s library:" % style(name, fg="yellow")) + click.echo("Updating %s library:" % click.style(name, fg="yellow")) current_version = info['version'] latest_version = versions[name] - echo("Versions: Current=%s, Latest=%s \t " % ( + click.echo("Versions: Current=%s, Latest=%s \t " % ( current_version, latest_version), nl=False) if current_version == latest_version: - echo("[%s]" % (style("Up-to-date", fg="green"))) + click.echo("[%s]" % (click.style("Up-to-date", fg="green"))) continue else: - echo("[%s]" % (style("Out-of-date", fg="red"))) + click.echo("[%s]" % (click.style("Out-of-date", fg="red"))) lib_uninstall([name]) lib_install([name]) @cli.command("register", short_help="Register new library") -@argument("config_url") +@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']: - secho(result['message'], fg="green" if "successed" in result and - result['successed'] else "red") + click.secho(result['message'], fg="green" if "successed" in result and + result['successed'] else "red") From c14dbb5ef1e565fb3f375a3b101f0869c0444446 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Wed, 24 Sep 2014 22:25:44 +0300 Subject: [PATCH 44/44] Resolve #6. Ready for 0.7.0 --- HISTORY.rst | 4 ++-- platformio/__init__.py | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/HISTORY.rst b/HISTORY.rst index 9f53d1861a..423b0c19ab 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -1,8 +1,8 @@ Release History =============== -0.7.0 (?) ---------- +0.7.0 (2014-09-24) +------------------ * Implemented new ``[platformio]`` section for Configuration File with ``home_dir`` option (`issue #14 `_) diff --git a/platformio/__init__.py b/platformio/__init__.py index 67cd843e7f..dcc97ca2c5 100644 --- a/platformio/__init__.py +++ b/platformio/__init__.py @@ -1,7 +1,7 @@ # Copyright (C) Ivan Kravets # See LICENSE for details. -VERSION = (0, 7, "0-dev") +VERSION = (0, 7, 0) __version__ = ".".join([str(s) for s in VERSION]) __title__ = "platformio"