forked from platformio/platformio-core
Improvements
This commit is contained in:
Ivan Kravets
@ -3,15 +3,15 @@
|
||||
library.json
|
||||
============
|
||||
|
||||
Libraries are defined by a manifest file ``library.json``. This is a
|
||||
`JSON-style <http://en.wikipedia.org/wiki/JSON>`_ 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 <http://en.wikipedia.org/wiki/JSON>`_.
|
||||
A data in ``library.json`` should be represented via
|
||||
`associative array <http://en.wikipedia.org/wiki/Associative_array>`_
|
||||
(name/value pairs). An order doesn't 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 <http://semver.org>`_ is recommended.
|
||||
* A `CVS <http://en.wikipedia.org/wiki/Concurrent_Versions_System>`_
|
||||
revision from the latest commit. Example: ``13`` (*SVN*) or first 10
|
||||
@ -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 <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
|
||||
*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 <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.
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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 <https://github.com/ivankravets/platformio-libmirror/tree/master/configs>`_).
|
||||
|
||||
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 <https://github.com>`_, then
|
||||
you **need to specify** only these fields in :ref:`library_config`:
|
||||
If a library source code is located at `GitHub <https://github.com>`_, then
|
||||
you **need to specify** only these fields in the :ref:`library_config`:
|
||||
|
||||
* :ref:`libjson_name`
|
||||
* :ref:`libjson_keywords`
|
||||
@ -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 <cmd_lib_register>` your library and allow others
|
||||
to :ref:`install <cmd_lib_install>` it.
|
||||
|
||||
|
||||
@ -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 <https://www.npmjs.org>`_ and `bower <http://bower.io>`_ package managers
|
||||
for web.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user