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

Improvements

Browse Source
This commit is contained in:
Ivan Kravets
2014-09-07 18:14:33 +03:00
parent 5fa265374c
commit 995a25478b
3 changed files with 41 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/librarymanager/config.rst
View File

@ -3,15 +3,15 @@
library.json library.json
============ ============
Libraries are defined by a manifest file ``library.json``. This is a *PlatformIO*-suitable library should be defined by a manifest file
`JSON-style <http://en.wikipedia.org/wiki/JSON>`_ file. Any data in ``library.json`` in a `JSON-style <http://en.wikipedia.org/wiki/JSON>`_.
``library.json`` should be represented via A data in ``library.json`` should be represented via
`associative array <http://en.wikipedia.org/wiki/Associative_array>`_ `associative array <http://en.wikipedia.org/wiki/Associative_array>`_
(name/value pairs). An order doesn't make a sense. (name/value pairs). An order doesn't make a sense.
The allowable fields (names from pairs) are described below. The fields The allowable fields (names from pairs) are described below. The fields
(:ref:`libjson_name`, :ref:`libjson_description` and :ref:`libjson_keywords`) (: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. (*CLI*) and the *WebSite* that can be used to search for libraries.
.. contents:: .. contents::
@ -23,12 +23,12 @@ will be displayed in search/lookup results on the :ref:`cmd_lib_search`
**Required** | Type: ``String`` | Max. Length: 50 **Required** | Type: ``String`` | Max. Length: 50
The name of the library. A name of the library.
* Must be unique. * Must be unique.
* Should be slug style for simplicity, consistency and compatibility. * Should be slug style for simplicity, consistency and compatibility.
Example: Arduino-SPI Example: *Arduino-SPI*
* Title Case, Aa-z, can contain digits, can contain dash (but not start/end * Title Case, Aa-z, can contain digits and dashes (but not start/end
with them). with them).
* Consecutive dashes are not allowed. * Consecutive dashes are not allowed.
@ -52,13 +52,13 @@ with it.
**Required** | Type: ``String`` | Max. Length: 255 **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 Used for search by keyword. Helps make your library easier to discover without
people needing to know its name. 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: .. _libjson_version:
@ -68,9 +68,9 @@ people needing to know its name.
*Required* if :ref:`libjson_repository` field is not defined | Type: ``String`` *Required* if :ref:`libjson_repository` field is not defined | Type: ``String``
| Max. Length: 20 | 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 <http://semver.org>`_ is recommended. * `Semantic Versioning <http://semver.org>`_ is recommended.
* A `CVS <http://en.wikipedia.org/wiki/Concurrent_Versions_System>`_ * A `CVS <http://en.wikipedia.org/wiki/Concurrent_Versions_System>`_
revision from the latest commit. Example: ``13`` (*SVN*) or first 10 revision from the latest commit. Example: ``13`` (*SVN*) or first 10
@ -78,8 +78,8 @@ The version of the current library source code.
.. note:: .. note::
You can omit :ref:`libjson_version` field and define You can omit :ref:`libjson_version` field and define
:ref:`libjson_repository` field. In this situation :ref:`libjson_repository` field. In this case
*PlatformIO-API Crawler* will use the CVS-revision from the latest commit. *PlatformIO-API Crawler* will use the *CVS*-revision from the latest commit.
.. _libjson_author: .. _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`` *Required* if :ref:`libjson_repository` field is not defined | Type: ``Object``
An author's contact information An author contact information
* ``name`` Full name (**Required**) * ``name`` Full name (**Required**)
* ``email`` * ``email``
@ -108,8 +108,8 @@ Example:
.. note:: .. note::
You can omit :ref:`libjson_author` field and define You can omit :ref:`libjson_author` field and define
:ref:`libjson_repository` field. Only *GitHub-based* repository is :ref:`libjson_repository` field. The only *GitHub-based* repository is
supported now. In this situation supported now. In this case
*PlatformIO-API Crawler* will use information from *PlatformIO-API Crawler* will use information from
`GitHub API Users <https://developer.github.com/v3/users/>`_. `GitHub API Users <https://developer.github.com/v3/users/>`_.
@ -155,7 +155,7 @@ of archive (``.zip`` or ``.tar.gz``).
If :ref:`libjson_include` field is a type of ``String``, then If :ref:`libjson_include` field is a type of ``String``, then
*PlatformIO-API Crawler* will recognize it like a "relative path inside *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 source code from the relative directory ``LibrarySourceCodeHere`` will be
included. included.
@ -204,7 +204,7 @@ Pattern Meaning
*Optional* | Type: ``String`` or ``Array`` | *Optional* | Type: ``String`` or ``Array`` |
`Glob Pattern <http://en.wikipedia.org/wiki/Glob_(programming)>`_ `Glob Pattern <http://en.wikipedia.org/wiki/Glob_(programming)>`_
Exclude the directories and files which will match with :ref:`libjson_exclude` Exclude the directories and files which match with :ref:`libjson_exclude`
patterns. patterns.
@ -215,7 +215,7 @@ patterns.
*Optional* | Type: ``Array`` *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. :ref:`cmd_lib_install` command.
Example: Example:

37
docs/librarymanager/create.rst
View File

@ -4,7 +4,7 @@
Creating Library 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 - 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 :ref:`library_config`. It can be located inside your library or in the another
location where |PIOAPICR| will have *HTTP* access. 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 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>`_). (see `examples <https://github.com/ivankravets/platformio-libmirror/tree/master/configs>`_).
Also, you can hold a lot of libraries inside the one repository/archive in the You can hold a lot of libraries (split into separated folders) inside the one
different folders. In this case please use :ref:`libjson_include` field to repository/archive. In this case please use :ref:`libjson_include`
specify the relative path to your library's source code. field to specify the relative path to your library's source code.
At GitHub At GitHub
@ -27,8 +27,8 @@ At GitHub
**Recommended** **Recommended**
If the library source code is located at `GitHub <https://github.com>`_, then If a library source code is located at `GitHub <https://github.com>`_, then
you **need to specify** only these fields in :ref:`library_config`: you **need to specify** only these fields in the :ref:`library_config`:
* :ref:`libjson_name` * :ref:`libjson_name`
* :ref:`libjson_keywords` * :ref:`libjson_keywords`
@ -36,7 +36,7 @@ you **need to specify** only these fields in :ref:`library_config`:
* :ref:`libjson_repository` * :ref:`libjson_repository`
|PIOAPICR| will populate the rest fields, like :ref:`libjson_version` or |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: Example:
@ -56,8 +56,8 @@ Example:
Under CVS (SVN/GIT) Under CVS (SVN/GIT)
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
|PIOAPICR| can operate with the library source code that is under *CVS* control. |PIOAPICR| can operate with a library source code that is under *CVS* control.
The list of **required** fields in :ref:`library_config` will look like: The list of **required** fields in the :ref:`library_config` will look like:
* :ref:`libjson_name` * :ref:`libjson_name`
* :ref:`libjson_keywords` * :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*. You can manually archive (*Zip, Tar.Gz*) your library source code and host it
Then you should specify additional fields, like :ref:`libjson_version` and in the *Internet*. Then you should specify the additional fields,
:ref:`libjson_downloadurl`. The final list of **required** fields in like :ref:`libjson_version` and :ref:`libjson_downloadurl`. The final list
:ref:`library_config` will look like: of **required** fields in the :ref:`library_config` will look like:
* :ref:`libjson_name` * :ref:`libjson_name`
* :ref:`libjson_keywords` * :ref:`libjson_keywords`
@ -121,9 +121,10 @@ Then you should specify additional fields, like :ref:`libjson_version` and
Register Register
-------- --------
* The library must adhere to the :ref:`library_config` specification. The registration requirements:
* There must be public *HTTP* access to library :ref:`library_config` file.
* 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 Now, you can :ref:`register <cmd_lib_register>` your library and allow others
to :ref:`install <cmd_lib_install>` it. to :ref:`install <cmd_lib_install>` it.

2
docs/librarymanager/index.rst
View File

@ -3,7 +3,7 @@
Library Manager Library Manager
=============== ===============
*"The missing libraries manager for embedded platforms"*, - inspired by *"The missing library manager for embedded platforms"*, - inspired by
`npm <https://www.npmjs.org>`_ and `bower <http://bower.io>`_ package managers `npm <https://www.npmjs.org>`_ and `bower <http://bower.io>`_ package managers
for web. for web.