Docs: PlatformIO Core 5.0: new commands, migration guide, other improvements

HISTORY.rst

@@ -8,45 +8,51 @@ PlatformIO Core 5
 
 **A professional collaborative platform for embedded development**
 
+- `Migration guide from 4.x to 5.0 <https://docs.platformio.org/page/core/migration.html>`__
+
 5.0.0 (2020-??-??)
 ~~~~~~~~~~~~~~~~~~
 
-
 * Integration with the new **PlatformIO Trusted Registry**
 
   - Enterprise-grade package storage with high availability (multi replicas)
   - Secure, fast, and reliable global content delivery network (CDN)
-  - Universal support for all embedded packages:
+  - Universal support for all packages:
 
     * Libraries
     * Development platforms
     * Toolchains
 
-  - Built-in fine-grained access control (role based, teams, organizations)
+  - Built-in fine-grained access control (role-based, teams, organizations)
-  - Command Line Interface:
+  - New CLI commands:
 
-    * `pio package publish <https://docs.platformio.org/page/core/userguide/package/cmd_publish.html>`__ – publish a personal or organization package
+    * `pio package <https://docs.platformio.org/page/core/userguide/package/index.html>`__ – manage packages in the registry
-    * `pio package unpublish <https://docs.platformio.org/page/core/userguide/package/cmd_unpublish.html>`__ – remove a pushed package from the registry
+    * `pio access <https://docs.platformio.org/page/core/userguide/access/index.html>`__ – manage package access for users, teams, and maintainers
-    * Grant package access to the team members or maintainers
 
-* Integration with the new `Account Management System <https://docs.platformio.org/page/plus/pio-account.html>`__
+* Integration with the new **Account Management System**
 
-  - Manage own organizations
+  - `Manage organizations and owners of an organization <https://docs.platformio.org/page/core/userguide/org/index.html>`__
-  - Manage organization teams
+  - `Manage teams and team memberships <https://docs.platformio.org/page/core/userguide/team/index.html>`__
-  - Manage resource access
 
 * New **Package Management System**
 
-  - Integrated PlatformIO Core with the new PlatformIO Trusted Registry
+  - Integrated PlatformIO Core with the new PlatformIO Registry
   - Strict dependency declaration using owner name (resolves name conflicts) (`issue #1824 <https://github.com/platformio/platformio-core/issues/1824>`_)
   - Automatically save dependencies to `"platformio.ini" <https://docs.platformio.org/page/projectconf.html>`__ when installing using PlatformIO CLI (`issue #2964 <https://github.com/platformio/platformio-core/issues/2964>`_)
+  - Dropped support for "packageRepositories" section in "platform.json" manifest (please publish packages directly to the registry)
 
-* **PlatformIO Build System**
+* **Build System**
+
+  - Upgraded build engine to the `SCons 4.0 - a next-generation software construction tool <https://scons.org/>`__
+
+    * `Configuration files are Python scripts <https://docs.platformio.org/page/projectconf/advanced_scripting.html>`__ – use the power of a real programming language to solve build problems
+    * Built-in reliable and automatic dependency analysis
+    * Improved support for parallel builds
+    * Ability to `share built files in a cache <https://docs.platformio.org/page/projectconf/section_platformio.html#projectconf-pio-build-cache-dir>`__ to speed up multiple builds
 
-  - Upgraded to `SCons 4.0 - a next-generation software construction tool <https://scons.org/>`__
   - New `Custom Targets <https://docs.platformio.org/page/projectconf/advanced_scripting.html#custom-targets>`__
 
-    * Pre/Post processing based on a dependent sources (other target, source file, etc.)
+    * Pre/Post processing based on dependent sources (another target, source file, etc.)
     * Command launcher with own arguments
     * Launch command with custom options declared in `"platformio.ini" <https://docs.platformio.org/page/projectconf.html>`__
     * Python callback as a target (use the power of Python interpreter and PlatformIO Build API)
@@ -55,12 +61,12 @@ PlatformIO Core 5
   - Enable "cyclic reference" for GCC linker only for the embedded dev-platforms (`issue #3570 <https://github.com/platformio/platformio-core/issues/3570>`_)
   - Automatically enable LDF dependency `chain+ mode (evaluates C/C++ Preprocessor conditional syntax) <https://docs.platformio.org/page/librarymanager/ldf.html#dependency-finder-mode>`__ for Arduino library when "library.property" has "depends" field (`issue #3607 <https://github.com/platformio/platformio-core/issues/3607>`_)
   - Fixed an issue with improper processing of source files added via multiple Build Middlewares (`issue #3531 <https://github.com/platformio/platformio-core/issues/3531>`_)
-  - Fixed an issue with ``clean`` target on Windows when project and build directories are located on different logical drives (`issue #3542 <https://github.com/platformio/platformio-core/issues/3542>`_)
+  - Fixed an issue with the ``clean`` target on Windows when project and build directories are located on different logical drives (`issue #3542 <https://github.com/platformio/platformio-core/issues/3542>`_)
 
 * **Project Management**
 
   - Added support for "globstar/`**`" (recursive) pattern for the different commands and configuration options (`pio ci <https://docs.platformio.org/page/core/userguide/cmd_ci.html>`__, `src_filter <https://docs.platformio.org/page/projectconf/section_env_build.html#src-filter>`__, `check_patterns <https://docs.platformio.org/page/projectconf/section_env_check.html#check-patterns>`__, `library.json > srcFilter <https://docs.platformio.org/page/librarymanager/config.html#srcfilter>`__). Python 3.5+ is required
-  - Added a new ``-e, --environment`` option to `pio project init <https://docs.platformio.org/page/core/userguide/project/cmd_init.html#cmdoption-platformio-project-init-e>`__ command that helps to update a PlatformIO project using existing environment
+  - Added a new ``-e, --environment`` option to `pio project init <https://docs.platformio.org/page/core/userguide/project/cmd_init.html#cmdoption-platformio-project-init-e>`__ command that helps to update a PlatformIO project using the existing environment
   - Dump build system data intended for IDE extensions/plugins using a new `pio project data <https://docs.platformio.org/page/core/userguide/project/cmd_data.html>`__ command
   - Do not generate ".travis.yml" for a new project, let the user have a choice
 
@@ -75,17 +81,16 @@ PlatformIO Core 5
   - Updated analysis tools:
 
     * ``Cppcheck v2.1`` with a new "soundy" analysis option and improved code parser
-    * ``PVS-Studio v7.08`` with a new file list analysis mode and extended list of diagnostic rules
+    * ``PVS-Studio v7.08`` with a new file list analysis mode and an extended list of diagnostic rules
 
   - Added Cppcheck package for ARM-based single-board computers (`issue #3559 <https://github.com/platformio/platformio-core/issues/3559>`_)
-  - Fixed an issue with PIO Check when a defect with multiline error message is not reported in verbose mode (`issue #3631 <https://github.com/platformio/platformio-core/issues/3631>`_)
+  - Fixed an issue with PIO Check when a defect with a multiline error message is not reported in verbose mode (`issue #3631 <https://github.com/platformio/platformio-core/issues/3631>`_)
 
 * **Miscellaneous**
 
   - Display system-wide information using a new `pio system info <https://docs.platformio.org/page/core/userguide/system/cmd_info.html>`__ command (`issue #3521 <https://github.com/platformio/platformio-core/issues/3521>`_)
   - Remove unused data using a new `pio system prune <https://docs.platformio.org/page/core/userguide/system/cmd_prune.html>`__ command (`issue #3522 <https://github.com/platformio/platformio-core/issues/3522>`_)
-  - Do not escape compiler arguments in VSCode template on Windows
+  - Do not escape compiler arguments in VSCode template on Windows.
-
 
 .. _release_notes_4:
 

platformio/app.py

@@ -68,7 +68,7 @@ DEFAULT_SETTINGS = {
         "value": False,
     },
     "projects_dir": {
-        "description": "Default location for PlatformIO projects (PIO Home)",
+        "description": "Default location for PlatformIO projects (PlatformIO Home)",
         "value": get_default_projects_dir(),
         "validator": projects_dir_validate,
     },

platformio/clients/account.py

@@ -27,7 +27,7 @@ class AccountError(PlatformioException):
 
 class AccountNotAuthorized(AccountError):
 
-    MESSAGE = "You are not authorized! Please log in to PIO Account."
+    MESSAGE = "You are not authorized! Please log in to PlatformIO Account."
 
 
 class AccountAlreadyAuthorized(AccountError):

platformio/clients/http.py

@@ -45,7 +45,7 @@ class InternetIsOffline(UserSideException):
     MESSAGE = (
         "You are not connected to the Internet.\n"
         "PlatformIO needs the Internet connection to"
-        " download dependent packages or to work with PIO Account."
+        " download dependent packages or to work with PlatformIO Account."
     )
 
 

platformio/commands/access.py

@@ -33,7 +33,7 @@ def validate_client(value):
     return value
 
 
-@click.group("access", short_help="Manage Resource Access")
+@click.group("access", short_help="Manage resource access")
 def cli():
     pass
 
@@ -75,7 +75,7 @@ def access_private(urn, urn_type):
 @click.argument("level", type=click.Choice(["admin", "maintainer", "guest"]))
 @click.argument(
     "client",
-    metavar="[ORGNAME:TEAMNAME|USERNAME]",
+    metavar="[<ORGNAME:TEAMNAME>|<USERNAME>]",
     callback=lambda _, __, value: validate_client(value),
 )
 @click.argument(
@@ -108,7 +108,7 @@ def access_revoke(client, urn, urn_type):
     )
 
 
-@cli.command("list", short_help="List resources")
+@cli.command("list", short_help="List published resources")
 @click.argument("owner", required=False)
 @click.option("--urn-type", type=click.Choice(["prn:reg:pkg"]), default="prn:reg:pkg")
 @click.option("--json-output", is_flag=True)

platformio/commands/account.py

@@ -24,7 +24,7 @@ from tabulate import tabulate
 from platformio.clients.account import AccountClient, AccountNotAuthorized
 
 
-@click.group("account", short_help="Manage PIO Account")
+@click.group("account", short_help="Manage PlatformIO account")
 def cli():
     pass
 
@@ -60,7 +60,7 @@ def validate_password(value):
     return value
 
 
-@cli.command("register", short_help="Create new PIO Account")
+@cli.command("register", short_help="Create new PlatformIO Account")
 @click.option(
     "-u",
     "--username",
@@ -90,7 +90,7 @@ def account_register(username, email, password, firstname, lastname):
     )
 
 
-@cli.command("login", short_help="Log in to PIO Account")
+@cli.command("login", short_help="Log in to PlatformIO Account")
 @click.option("-u", "--username", prompt="Username or email")
 @click.option("-p", "--password", prompt=True, hide_input=True)
 def account_login(username, password):
@@ -99,7 +99,7 @@ def account_login(username, password):
     return click.secho("Successfully logged in!", fg="green")
 
 
-@cli.command("logout", short_help="Log out of PIO Account")
+@cli.command("logout", short_help="Log out of PlatformIO Account")
 def account_logout():
     client = AccountClient()
     client.logout()
@@ -195,7 +195,7 @@ def account_destroy():
     return click.secho("User account has been destroyed.", fg="green",)
 
 
-@cli.command("show", short_help="PIO Account information")
+@cli.command("show", short_help="PlatformIO Account information")
 @click.option("--offline", is_flag=True)
 @click.option("--json-output", is_flag=True)
 def account_show(offline, json_output):

platformio/commands/boards.py

@@ -22,7 +22,7 @@ from platformio.compat import dump_json_to_unicode
 from platformio.package.manager.platform import PlatformPackageManager
 
 
-@click.command("boards", short_help="Embedded Board Explorer")
+@click.command("boards", short_help="Embedded board explorer")
 @click.argument("query", required=False)
 @click.option("--installed", is_flag=True)
 @click.option("--json-output", is_flag=True)

platformio/commands/check/command.py

@@ -31,7 +31,7 @@ from platformio.project.config import ProjectConfig
 from platformio.project.helpers import find_project_dir_above, get_project_dir
 
 
-@click.command("check", short_help="Run a static analysis tool on code")
+@click.command("check", short_help="Static code analysis")
 @click.option("-e", "--environment", multiple=True)
 @click.option(
     "-d",

platformio/commands/ci.py

@@ -44,7 +44,7 @@ def validate_path(ctx, param, value):  # pylint: disable=unused-argument
         raise click.BadParameter("Found invalid path: %s" % invalid_path)
 
 
-@click.command("ci", short_help="Continuous Integration")
+@click.command("ci", short_help="Continuous integration")
 @click.argument("src", nargs=-1, callback=validate_path)
 @click.option("-l", "--lib", multiple=True, callback=validate_path, metavar="DIRECTORY")
 @click.option("--exclude", multiple=True)

platformio/commands/debug/command.py

@@ -33,7 +33,7 @@ from platformio.project.helpers import is_platformio_project, load_project_ide_d
 @click.command(
     "debug",
     context_settings=dict(ignore_unknown_options=True),
-    short_help="PIO Unified Debugger",
+    short_help="Unified debugger",
 )
 @click.option(
     "-d",

platformio/commands/device/command.py

@@ -26,7 +26,7 @@ from platformio.platform.factory import PlatformFactory
 from platformio.project.exception import NotPlatformIOProjectError
 
 
-@click.group(short_help="Monitor device or list existing")
+@click.group(short_help="Device manager & serial/socket monitor")
 def cli():
     pass
 

platformio/commands/home/command.py

@@ -25,7 +25,7 @@ from platformio.compat import WINDOWS
 from platformio.package.manager.core import get_core_package_dir, inject_contrib_pysite
 
 
-@click.command("home", short_help="PIO Home")
+@click.command("home", short_help="UI to manage PlatformIO")
 @click.option("--port", type=int, default=8008, help="HTTP port, default=8008")
 @click.option(
     "--host",

platformio/commands/lib/command.py

@@ -50,7 +50,7 @@ def get_project_global_lib_dir():
     return ProjectConfig.get_instance().get_optional_dir("globallib")
 
 
-@click.group(short_help="Library Manager")
+@click.group(short_help="Library manager")
 @click.option(
     "-d",
     "--storage-dir",

platformio/commands/org.py

@@ -23,7 +23,7 @@ from platformio.clients.account import AccountClient
 from platformio.commands.account import validate_email, validate_username
 
 
-@click.group("org", short_help="Manage Organizations")
+@click.group("org", short_help="Manage organizations")
 def cli():
     pass
 
@@ -44,11 +44,11 @@ def org_create(orgname, email, displayname):
     client = AccountClient()
     client.create_org(orgname, email, displayname)
     return click.secho(
-        "The organization %s has been successfully created." % orgname, fg="green",
+        "The organization `%s` has been successfully created." % orgname, fg="green",
     )
 
 
-@cli.command("list", short_help="List organizations")
+@cli.command("list", short_help="List organizations and their members")
 @click.option("--json-output", is_flag=True)
 def org_list(json_output):
     client = AccountClient()
@@ -56,7 +56,7 @@ def org_list(json_output):
     if json_output:
         return click.echo(json.dumps(orgs))
     if not orgs:
-        return click.echo("You do not have any organizations")
+        return click.echo("You do not have any organization")
     for org in orgs:
         click.echo()
         click.secho(org.get("orgname"), fg="cyan")
@@ -77,15 +77,17 @@ def org_list(json_output):
 
 
 @cli.command("update", short_help="Update organization")
-@click.argument("orgname")
+@click.argument("cur_orgname")
 @click.option(
-    "--new-orgname", callback=lambda _, __, value: validate_orgname(value),
+    "--orgname",
+    callback=lambda _, __, value: validate_orgname(value),
+    help="A new orgname",
 )
 @click.option("--email")
-@click.option("--displayname",)
+@click.option("--displayname")
-def org_update(orgname, **kwargs):
+def org_update(cur_orgname, **kwargs):
     client = AccountClient()
-    org = client.get_org(orgname)
+    org = client.get_org(cur_orgname)
     del org["owners"]
     new_org = org.copy()
     if not any(kwargs.values()):
@@ -101,9 +103,10 @@ def org_update(orgname, **kwargs):
         new_org.update(
             {key.replace("new_", ""): value for key, value in kwargs.items() if value}
         )
-    client.update_org(orgname, new_org)
+    client.update_org(cur_orgname, new_org)
     return click.secho(
-        "The organization %s has been successfully updated." % orgname, fg="green",
+        "The organization `%s` has been successfully updated." % cur_orgname,
+        fg="green",
     )
 
 
@@ -112,13 +115,13 @@ def org_update(orgname, **kwargs):
 def account_destroy(orgname):
     client = AccountClient()
     click.confirm(
-        "Are you sure you want to delete the %s organization account?\n"
+        "Are you sure you want to delete the `%s` organization account?\n"
         "Warning! All linked data will be permanently removed and can not be restored."
         % orgname,
         abort=True,
     )
     client.destroy_org(orgname)
-    return click.secho("Organization %s has been destroyed." % orgname, fg="green",)
+    return click.secho("Organization `%s` has been destroyed." % orgname, fg="green",)
 
 
 @cli.command("add", short_help="Add a new owner to organization")
@@ -128,7 +131,7 @@ def org_add_owner(orgname, username):
     client = AccountClient()
     client.add_org_owner(orgname, username)
     return click.secho(
-        "The new owner %s has been successfully added to the %s organization."
+        "The new owner `%s` has been successfully added to the `%s` organization."
         % (username, orgname),
         fg="green",
     )
@@ -141,7 +144,7 @@ def org_remove_owner(orgname, username):
     client = AccountClient()
     client.remove_org_owner(orgname, username)
     return click.secho(
-        "The %s owner has been successfully removed from the %s organization."
+        "The `%s` owner has been successfully removed from the `%s` organization."
         % (username, orgname),
         fg="green",
     )

platformio/commands/package.py

@@ -32,7 +32,7 @@ def validate_datetime(ctx, param, value):  # pylint: disable=unused-argument
     return value
 
 
-@click.group("package", short_help="Package Manager")
+@click.group("package", short_help="Package manager")
 def cli():
     pass
 

platformio/commands/platform.py

@@ -26,7 +26,7 @@ from platformio.platform.exception import UnknownPlatform
 from platformio.platform.factory import PlatformFactory
 
 
-@click.group(short_help="Platform Manager")
+@click.group(short_help="Platform manager")
 def cli():
     pass
 

platformio/commands/project.py

@@ -30,7 +30,7 @@ from platformio.project.exception import NotPlatformIOProjectError
 from platformio.project.helpers import is_platformio_project, load_project_ide_data
 
 
-@click.group(short_help="Project Manager")
+@click.group(short_help="Project manager")
 def cli():
     pass
 
@@ -333,7 +333,7 @@ def init_test_readme(test_dir):
     with open(os.path.join(test_dir, "README"), "w") as fp:
         fp.write(
             """
-This directory is intended for PIO Unit Testing and project tests.
+This directory is intended for PlatformIO Unit Testing and project tests.
 
 Unit Testing is a software testing method by which individual units of
 source code, sets of one or more MCU program modules together with associated
@@ -341,7 +341,7 @@ control data, usage procedures, and operating procedures, are tested to
 determine whether they are fit for use. Unit testing finds problems early
 in the development cycle.
 
-More information about PIO Unit Testing:
+More information about PlatformIO Unit Testing:
 - https://docs.platformio.org/page/plus/unit-testing.html
 """,
         )

platformio/commands/remote/client/base.py

@@ -72,7 +72,7 @@ class RemoteClientBase(  # pylint: disable=too-many-instance-attributes
 
     def connect(self):
         self.log.info("Name: {name}", name=self.name)
-        self.log.info("Connecting to PIO Remote Cloud")
+        self.log.info("Connecting to PlatformIO Remote Development Cloud")
 
         # pylint: disable=protected-access
         proto, options = endpoints._parse(__pioremote_endpoint__)

platformio/commands/remote/command.py

@@ -33,14 +33,15 @@ from platformio.package.manager.core import inject_contrib_pysite
 from platformio.project.exception import NotPlatformIOProjectError
 
 
-@click.group("remote", short_help="PIO Remote")
+@click.group("remote", short_help="Remote development")
 @click.option("-a", "--agent", multiple=True)
 @click.pass_context
 def cli(ctx, agent):
     if PY2:
         raise exception.UserSideException(
-            "PIO Remote requires Python 3.5 or above. \nPlease install the latest "
+            "PlatformIO Remote Development requires Python 3.5 or above. \n"
-            "Python 3 and reinstall PlatformIO Core using installation script:\n"
+            "Please install the latest Python 3 and reinstall PlatformIO Core using "
+            "installation script:\n"
             "https://docs.platformio.org/page/core/installation.html"
         )
     ctx.obj = agent

platformio/commands/run/command.py

@@ -36,7 +36,7 @@ except NotImplementedError:
     DEFAULT_JOB_NUMS = 1
 
 
-@click.command("run", short_help="Process project environments")
+@click.command("run", short_help="Run project targets (build, upload, clean, etc.)")
 @click.option("-e", "--environment", multiple=True)
 @click.option("-t", "--target", multiple=True)
 @click.option("--upload-port")

platformio/commands/settings.py

@@ -27,7 +27,7 @@ def format_value(raw):
     return str(raw)
 
 
-@click.group(short_help="Manage PlatformIO settings")
+@click.group(short_help="Manage system settings")
 def cli():
     pass
 

platformio/commands/team.py

@@ -50,7 +50,7 @@ def validate_teamname(value):
     return value
 
 
-@click.group("team", short_help="Manage Teams")
+@click.group("team", short_help="Manage organization teams")
 def cli():
     pass
 
@@ -119,7 +119,9 @@ def team_list(orgname, json_output):
     callback=lambda _, __, value: validate_orgname_teamname(value),
 )
 @click.option(
-    "--name", callback=lambda _, __, value: validate_teamname(value),
+    "--name",
+    callback=lambda _, __, value: validate_teamname(value),
+    help="A new team name",
 )
 @click.option("--description",)
 def team_update(orgname_teamname, **kwargs):
@@ -189,8 +191,8 @@ def team_add_member(orgname_teamname, username):
     metavar="ORGNAME:TEAMNAME",
     callback=lambda _, __, value: validate_orgname_teamname(value),
 )
-@click.argument("username",)
+@click.argument("username")
-def org_remove_owner(orgname_teamname, username):
+def team_remove_owner(orgname_teamname, username):
     orgname, teamname = orgname_teamname.split(":", 1)
     client = AccountClient()
     client.remove_team_member(orgname, teamname, username)

platformio/commands/test/command.py

@@ -28,7 +28,7 @@ from platformio.commands.test.native import NativeTestProcessor
 from platformio.project.config import ProjectConfig
 
 
-@click.command("test", short_help="Unit Testing")
+@click.command("test", short_help="Unit testing")
 @click.option("--environment", "-e", multiple=True, metavar="<environment>")
 @click.option(
     "--filter",

platformio/package/manager/core.py

@@ -26,7 +26,7 @@ from platformio.proc import get_pythonexe_path
 
 def get_core_package_dir(name):
     if name not in __core_packages__:
-        raise exception.PlatformioException("Please upgrade PIO Core")
+        raise exception.PlatformioException("Please upgrade PlatformIO Core")
     pm = ToolPackageManager()
     spec = PackageSpec(
         owner="platformio", name=name, requirements=__core_packages__[name]

platformio/project/options.py

@@ -245,7 +245,7 @@ ProjectOptions = OrderedDict(
                 group="directory",
                 name="test_dir",
                 description=(
-                    "A location where PIO Unit Testing engine looks for "
+                    "A location where PlatformIO Unit Testing engine looks for "
                     "test source files"
                 ),
                 sysenvvar="PLATFORMIO_TEST_DIR",
@@ -262,8 +262,8 @@ ProjectOptions = OrderedDict(
                 group="directory",
                 name="shared_dir",
                 description=(
-                    "A location which PIO Remote uses to synchronize extra files "
+                    "A location which PlatformIO Remote Development service uses to "
-                    "between remote machines"
+                    "synchronize extra files between remote machines"
                 ),
                 sysenvvar="PLATFORMIO_SHARED_DIR",
                 default=os.path.join("$PROJECT_DIR", "shared"),