From 3069abfe135cbc30c35ef02b5ff3dbf1467f98f8 Mon Sep 17 00:00:00 2001 From: Ivan Kravets Date: Wed, 7 Sep 2016 18:50:25 +0300 Subject: [PATCH] Add migration guide for PIO2 to PIO3 --- docs/index.rst | 2 + docs/librarymanager/ldf.rst | 2 + docs/migration.rst | 213 +++++++++++++++++++++++++++++ docs/userguide/lib/cmd_install.rst | 5 + docs/userguide/lib/cmd_search.rst | 9 +- 5 files changed, 229 insertions(+), 2 deletions(-) create mode 100644 docs/migration.rst diff --git a/docs/index.rst b/docs/index.rst index 9116b5c5..3b006919 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -143,3 +143,5 @@ Contents articles FAQ history + migration + diff --git a/docs/librarymanager/ldf.rst b/docs/librarymanager/ldf.rst index 269b1e6a..ed56dc39 100644 --- a/docs/librarymanager/ldf.rst +++ b/docs/librarymanager/ldf.rst @@ -41,6 +41,8 @@ Library Dependency Finder has controls that can be set up in :ref:`projectconf`: .. contents:: +.. _ldf_storage: + Storage ------- diff --git a/docs/migration.rst b/docs/migration.rst new file mode 100644 index 00000000..9c28647a --- /dev/null +++ b/docs/migration.rst @@ -0,0 +1,213 @@ +.. Copyright 2014-present PlatformIO + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +.. _migration: + +Migrating from 2.x to 3.0 +========================= + +Guidance on how to upgrade from PlatformIO v2.x to v3.x with emphasis on major +changes, what is new, and what is been removed. + +PlatformIO 3 is not backwards compatible with v2.x. Use this section as a +general guide to upgrading from v2.x to v3.0. For a broader overview, see +`what is new `_ in the v3.0 +release announcement. + +.. contents:: + +Major PlatformIO CLI changes +---------------------------- + +.. note:: + PlatformIO 3.x is 100% non-blocking! You do not need to use ``--force`` + option or setup special ``PLATOFMRIO_SETTING_ENABLE_PROMPTS`` environment. + Use PlatformIO 3.0 with sub-processing without any risk! + +This table shows the CLI changes between v2.x and v3.0. + +.. list-table:: + :header-rows: 1 + + * - PlatformIO 2.x + - PlatformIO 3.x + * - platformio platforms + - :ref:`platformio platform ` + * - platformio serialports + - :ref:`cmd_device` + * - platformio settings set enable_prompts false + - Removed! Now, all PlatformIO 3.0 CLI is 100% non-blocking! + + +PlatformIO 2.x commands will be converted to PlatformIO 3.x automatically. +Nevertheless, we recommend to use PlatformIO 3.x commands for the new projects. + +What is new +----------- + +Development Platforms +~~~~~~~~~~~~~~~~~~~~~ + +We have introduced :ref:`platform_creating_manifest_file` and ported +PlatformIO 2.x development platforms according PlatformIO 3.0 decentralized +architecture. Now, platform related things (build scrips, LD scripts, board +configs, package requirements) are located in own repository. Here is the full +list with `PlatformIO 3.0 open source development platforms `__. You can fork it, modify or create custom. +See :ref:`platform_creating` guide for details. + +* :ref:`platform_creating_manifest_file` +* ``espressif`` development platform has been renamed to :ref:`platform_espressif8266` +* PlatformIO 3.0 :ref:`userguide_platform` +* Custom package repositories +* External embedded board configuration files, isolated build scripts +* Embedded Board compatibility with more than one development platform + +Library Manager and Intelligent Build System +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Powerful and super-fast :ref:`ldf` that interprets C/C++ Preprocessor + conditional macros with deep search behavior +* Project dependencies per build environment using `projectconf_lib_deps` option +* Depend on a library using VCS URL (GitHub, Git, ARM mbed code registry, Hg, SVN) +* Install library by name +* Strict search for library dependencies +* Multiple library storages: Project's Local, PlatformIO's Global or Custom +* Allowed :ref:`library_config` to specify sources other than PlatformIO's Repository +* Check library compatibility with project environment before building +* Control Library Dependency Finder for compatibility using :ref:`projectconf_lib_compat_mode` option +* Custom library storages/directories with :ref:`projectconf_lib_extra_dirs` option +* Handle extra build flags, source filters and build script from :ref:`library_config` +* Allowed to disable library archiving (``*.ar``) +* Show detailed build information about dependent libraries (Library Dependency Graph) +* Support for the 3rd party manifests (Arduino IDE "library.properties" and + ARM mbed "module.json") +* Build System: Attach custom Before/Pre and After/Post actions for targets using :ref:`projectconf_extra_script` + +Command Line Interface +~~~~~~~~~~~~~~~~~~~~~~ + +We have added new commands and changed some existing ones. Here are the new or +updated commands and options. + +.. list-table:: + :header-rows: 1 + + * - Command + - Description + * - :ref:`cmd_boards` + - Returns all supported boards by PlatformIO + * - :option:`platformio boards --installed` + - Returns currently installed boards + * - :option:`platformio ci --project-option` + - Pass custom option from :ref:`projectconf` + * - :option:`platformio ci --verbose` + - Print detailed information about build process + * - :option:`platformio init --project-option` + - Pass custom option from :ref:`projectconf` + * - :option:`platformio lib --global` + - Manage PlatformIO :ref:`Global Library Storage ` + * - :option:`platformio lib --storage-dir` + - Manage :ref:`Custom Library Storage ` + * - :ref:`cmd_lib_install` + - New PlatformIO 3.0 Library Manager! Semantic Versioning, VCS support and external URL support + * - :option:`platformio lib install --silent` + - Suppress progress reporting when install library + * - :option:`platformio lib install --interactive` + - Allow to make a choice for all prompts when install library + * - :option:`platformio lib search --header` + - Search library by specific header file name (include) + * - :option:`platformio lib update --only-check` + - Do not update, only check for new version + * - :ref:`platformio platform ` + - New PlatformIO 3.0 Platform Manager! Semantic Versioning, VCS support and external URL support. + * - :option:`platformio platform update --only-packages` + - Update only platform packages + * - :option:`platformio platform update --only-check` + - Do not update, only check for new version + * - :ref:`cmd_run` + - By default, prints only human-readable information when processing environments + * - :option:`platformio run --verbose` + - Print detailed processing information + * - :ref:`platformio settings set force_verbose true ` + - Force verbose output when processing environments (globally) + * - :ref:`cmd_test` + - PlatformIO Plus Unit Testing + * - :option:`platformio update --only-check` + - Do not update, only check for new version + +:ref:`projectconf` +~~~~~~~~~~~~~~~~~~ + +We have added new options and changed some existing ones. Here are the new or +updated options. + +.. list-table:: + :header-rows: 1 + + * - Section + - Option + - Description + * - platformio + - :ref:`projectconf_pio_libdeps_dir` + - Internal storage where :ref:`librarymanager` will install project dependencies + * - platformio + - :ref:`projectconf_pio_test_dir` + - Directory where :ref:`unit_testing` engine will look for the tests + * - env + - :ref:`projectconf_lib_deps` + - Specify project dependencies that should be installed automatically to :ref:`projectconf_pio_libdeps_dir` before environment processing. + * - env + - :ref:`projectconf_env_platform` + - PlatformIO 3.0 allows to use specific version of platform using `Semantic Versioning `_ (X.Y.Z=MAJOR.MINOR.PATCH). + * - env + - :ref:`projectconf_lib_extra_dirs` + - A list with extra directories/storages where :ref:`ldf` will look for dependencies + * - env + - :ref:`projectconf_lib_ldf_mode` + - This option specifies how does :ref:`ldf` should analyze dependencies (``#include`` directives) + * - env + - :ref:`projectconf_lib_compat_mode` + - Library compatibility mode allows to control strictness of :ref:`ldf` + * - env + - :ref:`projectconf_test_ignore` + - Ignore tests where the name matches specified patterns + +What is removed +--------------- + +Command Line Interface +~~~~~~~~~~~~~~~~~~~~~~ + +The following commands have been dropped or changed in v3.0. + +.. list-table:: + :header-rows: 1 + + * - Command + - Description + * - platformio init --enable-auto-uploading + - Use :option:`platformio init --project-option` instead of it with ``targets = upload`` value + +:ref:`projectconf` +~~~~~~~~~~~~~~~~~~ + +The following options have been dropped or changed in v3.0. + +.. list-table:: + :header-rows: 1 + + * - Section + - Option + - Description + * - platformio + - :ref:`projectconf_pio_lib_dir` + - Changed: Project's own/private libraries, where in PlatformIO 2.x it was global library storage + diff --git a/docs/userguide/lib/cmd_install.rst b/docs/userguide/lib/cmd_install.rst index 60a846b3..d407d935 100644 --- a/docs/userguide/lib/cmd_install.rst +++ b/docs/userguide/lib/cmd_install.rst @@ -99,6 +99,11 @@ Options Suppress progress reporting +.. option:: + --interactive + +Allow to make a choice for all prompts + Version control --------------- diff --git a/docs/userguide/lib/cmd_search.rst b/docs/userguide/lib/cmd_search.rst index 4bc5d0ea..4ca0789c 100644 --- a/docs/userguide/lib/cmd_search.rst +++ b/docs/userguide/lib/cmd_search.rst @@ -89,18 +89,23 @@ Filter libraries by specified author Filter libraries by specified keyword - .. option:: -f, --framework Filter libraries by specified framework - .. option:: -p, --platform Filter libraries by specified keyword +.. option:: + -i, --header + +Filter libraries by header file (include) + +For example, ``platformio lib search --header "OneWire.h"`` + .. option:: --json-output