diff --git a/docs/librarymanager/config.rst b/docs/librarymanager/config.rst index dd565f76..8ef62e43 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 d17de1f7..95679ca9 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 2ddd31a0..14d92f5d 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: