Update docs with new owner-based dependency form

core/migration.rst

@@ -17,15 +17,20 @@ Migrating from 4.x to 5.0
 Guidance on how to upgrade from :ref:`piocore` v4.x to v5.x with emphasis on
 major changes, what is new, and what has been removed.
 
+**PlatformIO Core 5.0 is fully backward compatible with PlatformIO 4.0 projects.**
+
 Please read :ref:`PlatformIO 5.0 Release Notes <release_notes_5>` before.
 
 .. contents:: Contents
   :local:
 
-Compatibility
--------------
+Migration Steps
+---------------
 
-PlatformIO Core 5.0 is fully backward compatible with PlatformIO 4.0 projects.
+1. Ensure that you do not use a short version of the Github declaration in :ref:`projectconf_lib_deps`.
+   Please use ``https://github.com/username/repo.git`` instead of ``username/repo``.
+2. We recommend updating your project dependency declarations in :ref:`projectconf_lib_deps`
+   using a new owner-based syntax. See  the :ref:`core_migration_libmanager` section for details.
 
 What is new
 -----------
@@ -82,6 +87,8 @@ supports not only the libraries but also :ref:`platforms` and toolchains.
 Package maintainers can publish their libraries, development platforms, and toolchains
 to the registry using :ref:`cmd_package` CLI.
 
+.. _core_migration_libmanager:
+
 Library Manager
 ~~~~~~~~~~~~~~~
 
@@ -93,13 +100,16 @@ via :ref:`projectconf_lib_deps`:
 .. code-block:: ini
 
   [env:myenv]
-  platform = platformio/espressif32
+  platform = ...
   framework = ...
   board = ...
   lib_deps =
     bblanchon/ArduinoJson @ ^6.16.1
     knolleary/PubSubClient @ ^2.8
 
+You can find an owner name of a library in the registry using
+:ref:`piohome` > Libraries > Some Library > Installation tab.
+
 Build System
 ~~~~~~~~~~~~
 
@@ -135,7 +145,7 @@ packageRepositories
 ~~~~~~~~~~~~~~~~~~~
 
 PlatformIO Core 5.0 does not support unofficial package repositories declared through
-``packageRepositories`` in ``platform.json`` that was introduced in PlatformIO 2.0.
+``packageRepositories`` in ``platform.json`` that was introduced in PlatformIO 3.0.
 
 Please publish your development platforms and toolchains to the **PlatformIO Trusted
 Registry** using :ref:`cmd_package` CLI.

core/userguide/lib/cmd_install.rst

@@ -24,6 +24,7 @@ Usage
     platformio lib [STORAGE_OPTIONS] install [OPTIONS] [LIBRARY...]
     pio lib [STORAGE_OPTIONS] install [OPTIONS] [LIBRARY...]
 
+    # RECOMMENDED
     # install all project dependencies declared via "lib_deps"
     # (run it from a project root where is located "platformio.ini")
     platformio lib install [OPTIONS]
@@ -37,7 +38,7 @@ Usage
     platformio lib -e myenv install [OPTIONS] [LIBRARY...]
     platformio lib -d /path/to/platformio/project -e myenv install [OPTIONS] [LIBRARY...]
 
-    # install to global storage
+    # install to global storage (NOT RECOMMENDED)
     platformio lib --global install [OPTIONS] [LIBRARY...]
     platformio lib -g install [OPTIONS] [LIBRARY...]
 
@@ -46,17 +47,10 @@ Usage
     platformio lib -d /path/to/dir1 -d /path/to/dir2 install [OPTIONS] [LIBRARY...]
 
     # [LIBRARY...] forms
-    platformio lib [STORAGE_OPTIONS] install (with no args, project dependencies)
-    platformio lib [STORAGE_OPTIONS] install <id>
-    platformio lib [STORAGE_OPTIONS] install id=<id>
-    platformio lib [STORAGE_OPTIONS] install <id>@<version>
-    platformio lib [STORAGE_OPTIONS] install <id>@<version range>
-    platformio lib [STORAGE_OPTIONS] install <name>
-    platformio lib [STORAGE_OPTIONS] install <name>@<version>
-    platformio lib [STORAGE_OPTIONS] install <name>@<version range>
-    platformio lib [STORAGE_OPTIONS] install <ownernme/name>
-    platformio lib [STORAGE_OPTIONS] install <ownernme/name>@<version>
-    platformio lib [STORAGE_OPTIONS] install <ownernme/name>@<version range>
+    platformio lib [STORAGE_OPTIONS] install (with no args, install project dependencies from "lib_deps")
+    platformio lib [STORAGE_OPTIONS] install <ownername/name>
+    platformio lib [STORAGE_OPTIONS] install <ownername/name>@<version>
+    platformio lib [STORAGE_OPTIONS] install <ownername/name>@<version range>
     platformio lib [STORAGE_OPTIONS] install <zip or tarball url>
     platformio lib [STORAGE_OPTIONS] install file://<zip or tarball file>
     platformio lib [STORAGE_OPTIONS] install file://<folder>
@@ -69,8 +63,6 @@ Usage
   If some libraries are not visible in :ref:`pioide` and Code Completion or
   Code Linting does not work properly, please perform
 
-  * **Atom**: "Menu: PlatformIO > Rebuild C/C++ Project Index (Autocomplete,
-    Linter)"
   * **VSCode**: "Menu: View > Command Palette... > PlatformIO: Rebuild C/C++
     Project Index"
 
@@ -79,23 +71,23 @@ Description
 
 Install a library, and any libraries that it depends on using:
 
-1. Library ``id`` or ``name`` from `PlatformIO Library Registry <https://platformio.org/lib>`_
+1. `PlatformIO Library Registry <https://platformio.org/lib>`_
 2. Custom folder, repository or archive.
 
 The ``version`` supports `Semantic Versioning <http://semver.org>`_ (
 ``<major>.<minor>.<patch>``) and can take any of the following forms:
 
-* ``1.2.3`` - an exact version number. Use only this exact version
-* ``^1.2.3`` - any compatible version (exact version for ``1.x.x`` versions)
+* ``^1.2.3`` - any compatible version (new functionality in a backwards compatible manner and patches are allowed, 1.x.x). **RECOMMENDED**
 * ``~1.2.3`` - any version with the same major and minor versions, and an
   equal or greater patch version
 * ``>1.2.3`` - any version greater than ``1.2.3``. ``>=``, ``<``, and ``<=``
   are also possible
 * ``>0.1.0,!=0.2.0,<0.3.0`` - any version greater than ``0.1.0``, not equal to
   ``0.2.0`` and less than ``0.3.0``
+* ``1.2.3`` - an exact version number. Use only this exact version.
 
 PlatformIO supports installing from local directory or archive.
-Need to use ``file://`` prefix before local path.
+YOu need to use ``file://`` prefix before local path.
 
 * ``file:///local/path/to/the/platform/dir``
 * ``file:///local/path/to/the/platform.zip``
@@ -152,7 +144,6 @@ Git
 The supported schemes are: ``git``, ``git+https`` and ``git+ssh``. Here are
 the supported forms:
 
-* user/library (short version for GitHub repository)
 * https://github.com/user/library.git
 * git+git://git.server.org/my-library
 * git+https://git.server.org/my-library

core/userguide/platforms/cmd_install.rst

@@ -28,6 +28,8 @@ Usage
     platformio platform install <name>
     platformio platform install <name>@<version>
     platformio platform install <name>@<version range>
+    platformio platform install <ownername>@<version>
+    platformio platform install <ownername>@<version range>
     platformio platform install <zip or tarball url>
     platformio platform install file://<zip or tarball file>
     platformio platform install file://<folder>
@@ -75,14 +77,14 @@ Install :ref:`platforms` and dependent packages.
 The ``version`` supports `Semantic Versioning <http://semver.org>`_ (
 ``<major>.<minor>.<patch>``) and can take any of the following forms:
 
-* ``1.2.3`` - an exact version number. Use only this exact version
-* ``^1.2.3`` - any compatible version (exact version for ``1.x.x`` versions)
+* ``^1.2.3`` - any compatible version (new functionality in a backwards compatible manner and patches are allowed, 1.x.x). **RECOMMENDED**
 * ``~1.2.3`` - any version with the same major and minor versions, and an
   equal or greater patch version
 * ``>1.2.3`` - any version greater than ``1.2.3``. ``>=``, ``<``, and ``<=``
   are also possible
 * ``>0.1.0,!=0.2.0,<0.3.0`` - any version greater than ``0.1.0``, not equal to
   ``0.2.0`` and less than ``0.3.0``
+* ``1.2.3`` - an exact version number. Use only this exact version.
 
 Also, PlatformIO supports installing from local directory or archive. Need to
 use ``file://`` prefix before local path. Also, directory or archive should
@@ -108,7 +110,6 @@ Git
 The supported schemes are: ``git``, ``git+https`` and ``git+ssh``. Here are
 the supported forms:
 
-* platformio/platform-NAME (short version for GitHub repository)
 * https://github.com/platformio/platform-NAME.git
 * git+git://git.server.org/my-platform
 * git+https://git.server.org/my-platform

librarymanager/quickstart.rst

@@ -38,8 +38,7 @@ Project dependencies
 *PlatformIO Library Manager* allows one to specify project dependencies
 (:ref:`projectconf_lib_deps`) that will be installed automatically per project
 before environment processing. You do not need to install libraries manually.
-The only one simple step is to define dependencies in :ref:`projectconf`.
-You can use library ID, Name or even repository URL. For example,
+The only one simple step is to define dependencies in :ref:`projectconf`. For example,
 
 .. code-block:: ini
 
@@ -48,9 +47,8 @@ You can use library ID, Name or even repository URL. For example,
   framework = ...
   board = ...
   lib_deps =
-    13
-    PubSubClient
-    ArduinoJson@~5.6,!=5.4
+    knolleary/PubSubClient
+    bblanchon/ArduinoJson @ ~5,!=5.4
     https://github.com/gioblu/PJON.git#v2.0
     https://github.com/me-no-dev/ESPAsyncTCP.git
     https://github.com/adafruit/DHT-sensor-library/archive/master.zip
@@ -63,8 +61,6 @@ possible values.
   If some libraries are not visible in :ref:`pioide` and Code Completion or
   Code Linting does not work properly, please perform
 
-  * **Atom**: "Menu: PlatformIO > Rebuild C/C++ Project Index (Autocomplete,
-    Linter)"
   * **VSCode**: "Menu: View > Command Palette... > PlatformIO: Rebuild C/C++
     Project Index"
 

platforms/creating_platform.rst

@@ -50,16 +50,7 @@ first compiling the tools.
 
 PlatformIO has a registry with pre-built packages for the most popular
 operating systems and you can use them in your platform
-manifest. These packages are stored in the super-fast and reliably CDN
-storage provided by `JFrog Bintray
-<https://bintray.com/platformio/dl-packages>`_.
-
-Each platform definition must define ``packageRepositories`` to link
-to *package manifest files* that lists how PlatformIO can download the
-used packages. To use the pre-built packages, include
-http://dl.platformio.org/packages/manifest.json in the
-``packageRepositories`` list. Platform definitions can also use custom
-packages.
+manifest. Custom packages can be uploaded to the PlatformIO Registry using :ref:`cmd_package_publish` command.
 
 .. _platform_creating_manifest_file:
 
@@ -78,8 +69,9 @@ Here is an example ``platform.json`` for the fictitious platform "myplatform":
       "name": "myplatform",
       "title": "My Platform",
       "description": "My custom development platform",
-      "url": "https://example.com",
+      "homepage": "https://mycompany.com",
       "license": "Apache-2.0",
+      "keywords": ["keyword_1", "keyword_N"],
       "repository": {
         "type": "git",
         "url": "https://github.com/platformio/platform-myplatform.git"
@@ -98,6 +90,7 @@ Here is an example ``platform.json`` for the fictitious platform "myplatform":
       "packages": {
         "toolchain-gccarmnoneeabi": {
           "type": "toolchain",
+          "owner": "platformio",
           "version": ">=1.40803.0,<1.40805.0"
         },
         "framework-%FRAMEWORK_NAME_1%": {

platforms/espressif32.rst

@@ -439,6 +439,9 @@ Packages
     * - `tool-openocd-esp32 <http://openocd.org?utm_source=platformio.org&utm_medium=docs>`__
       - Open On-Chip Debugger for Espressif ESP32
 
+    * - `toolchain-esp32s2ulp <https://github.com/espressif/esp-idf.git?utm_source=platformio.org&utm_medium=docs>`__
+      - Binutils fork with support for the ESP32-S2 ULP co-processor
+
     * - `toolchain-esp32ulp <https://github.com/espressif/binutils-esp32ulp.git?utm_source=platformio.org&utm_medium=docs>`__
       - Binutils fork with support for the Espressif ESP32 ULP co-processor
 

projectconf/dynamic_variables.rst

@@ -41,20 +41,15 @@ Example:
 
 .. code-block:: ini
 
-    [env]
-    ; Unix
-    lib_extra_dirs = ${sysenv.HOME}/Documents/Arduino/libraries
-    ; Windows
-    lib_extra_dirs = ${sysenv.HOMEDRIVE}${sysenv.HOMEPATH}\Documents\Arduino\libraries
-
     ; You MUST inject these options into [env:] section
     ; using ${extra.***} (see below)
     [extra]
     build_flags = -D VERSION=1.2.3 -D DEBUG=1
     lib_deps_builtin =
       SPI
       Wire
-    lib_deps_external = ArduinoJson@>5.6.0
+    lib_deps_external =
+      bblanchon/ArduinoJson@>5.6.0
 
     [env:uno]
     platform = atmelavr
@@ -73,8 +68,8 @@ Example:
     lib_deps =
       ${extra.lib_deps_builtin}
       ${extra.lib_deps_external}
-      PubSubClient@2.6
-      OneWire
+      knolleary/PubSubClient @ ~2.6
+      paulstoffregen/OneWire @ ^2.3.5
 
     ; Keep sensitive data in environment variables
     ;

projectconf/section_env_library.rst

@@ -52,8 +52,7 @@ you can use :ref:`projectconf_dynamic_vars` to use common configuration.
     LIBRARY_N
 
 The each line with ``LIBRARY_1... LIBRARY_N`` will be passed automatically to
-:ref:`cmd_lib_install` command. Please follow to :ref:`cmd_lib_install` for
-detailed documentation about possible values.
+:ref:`cmd_lib_install` command.
 
 Please check :ref:`cmd_lib_install` for the valid declaration formats.
 
@@ -63,14 +62,14 @@ Example:
 
   [env:myenv]
   lib_deps =
-    ; name-based
-    PubSubClient
+    ; name-based (built-in library in framework)
+    SPI
 
     ; owner-based declaration
     knolleary/PubSubClient
 
     ; SemVer specification
-    ArduinoJson @ ~5.6,!=5.4
+    bblanchon/ArduinoJson @ ~5.6,!=5.4
 
     ; external Git resource
     https://github.com/gioblu/PJON.git#v2.0
@@ -79,7 +78,6 @@ Example:
     IRremoteESP8266=https://github.com/markszabo/IRremoteESP8266/archive/master.zip
 
 
-
 .. _projectconf_lib_ignore:
 
 ``lib_ignore``