Custom boards per project with `boards_dir` option in platformio.ini // Resolve #515

HISTORY.rst

@@ -14,7 +14,10 @@ PlatformIO 3.0
 * Inject system environment variables to configuration settings in
   `Project Configuration File "platformio.ini" <http://docs.platformio.org/en/stable/projectconf.html>`__
   (`issue #792 <https://github.com/platformio/platformio/issues/792>`_)
-* Changed default exit combination for Device Monitor from ``Ctrl+]`` to ``Ctrl+C``
+* Custom boards per project with ``boards_dir`` option in
+  `Project Configuration File "platformio.ini" <http://docs.platformio.org/en/stable/projectconf.html>`__
+  (`issue #515 <https://github.com/platformio/platformio/issues/515>`_)
+* Changed a default exit combination for Device Monitor from ``Ctrl+]`` to ``Ctrl+C``
 * Improved detecting of ARM mbed media disk for uploading
 * Improved Project Generator for CLion IDE when source folder contains nested items
 * Improved handling of library dependencies specified in ``library.json`` manifest

docs/envvars.rst

@@ -77,6 +77,9 @@ Allows to override :ref:`projectconf` option :ref:`projectconf_pio_data_dir`.
 
 Allows to override :ref:`projectconf` option :ref:`projectconf_pio_test_dir`.
 
+.. envvar:: PLATFORMIO_BOARDS_DIR
+
+Allows to override :ref:`projectconf` option :ref:`projectconf_pio_boards_dir`.
 
 Building
 --------

docs/platforms/creating_board.rst

@@ -72,13 +72,16 @@ Installation
 
 1. Create ``boards`` directory in :ref:`projectconf_pio_home_dir` if it
    doesn't exist.
-2. Create ``myboard.json`` file and put to ``boards`` directory.
+2. Create ``myboard.json`` file in this ``boards`` directory.
 3. Search available boards via :ref:`cmd_boards` command. You should see
    ``myboard`` board.
 
 Now, you can use ``myboard`` for the :ref:`projectconf_env_board` option in
 :ref:`projectconf`.
 
+.. note::
+  You can have custom boards per project. In this case, please put your
+  board's JSON files to :ref:`projectconf_pio_boards_dir`.
 
 Examples
 --------

docs/projectconf.rst

@@ -103,6 +103,45 @@ A ``platformio`` section is used for overriding default configuration options
 Options
 ~~~~~~~
 
+.. _projectconf_pio_env_default:
+
+``env_default``
+^^^^^^^^^^^^^^^
+
+:ref:`cmd_run` command processes all environments ``[env:***]`` by default
+if :option:`platformio run --environment` option is not specified.
+:ref:`projectconf_pio_env_default` allows to define environments which
+should be processed by default.
+
+Multiple environments are allowed if they are separated with ", "
+(comma+space). For example.
+
+.. code-block:: ini
+
+    [platformio]
+    env_default = uno, nodemcu
+
+    [env:uno]
+    platform = atmelavr
+    framework = arduino
+    board = uno
+
+    [env:nodemcu]
+    platform = espressif8266
+    framework = arduino
+    board = nodemcu
+
+    [env:teensy31]
+    platform = teensy
+    framework = arduino
+    board = teensy31
+
+    [env:lpmsp430g2553]
+    platform = timsp430
+    framework = energia
+    board = lpmsp430g2553
+    build_flags = -D LED_BUILTIN=RED_LED
+
 .. _projectconf_pio_home_dir:
 
 ``home_dir``
@@ -256,44 +295,25 @@ project.
 This option can be overridden by global environment variable
 :envvar:`PLATFORMIO_TEST_DIR`.
 
-.. _projectconf_pio_env_default:
+.. _projectconf_pio_boards_dir:
 
-``env_default``
-^^^^^^^^^^^^^^^
+``boards_dir``
+^^^^^^^^^^^^^^
 
-:ref:`cmd_run` command processes all environments ``[env:***]`` by default
-if :option:`platformio run --environment` option is not specified.
-:ref:`projectconf_pio_env_default` allows to define environments which
-should be processed by default.
+Custom board settings per project. You can change this path with your own.
+A default value is ``boards`` that means that folder is located in the root of
+project.
 
-Multiple environments are allowed if they are separated with ", "
-(comma+space). For example.
+By default, PlatformIO looks for boards in this order:
 
-.. code-block:: ini
+1. Project :ref:`projectconf_pio_boards_dir`
+2. Global :ref:`projectconf_pio_home_dir`/boards
+3. Development platform :ref:`projectconf_pio_home_dir`/platforms/\*/boards.
 
-    [platformio]
-    env_default = uno, nodemcu
+This option can be overridden by global environment variable
+:envvar:`PLATFORMIO_BOARDS_DIR`.
 
-    [env:uno]
-    platform = atmelavr
-    framework = arduino
-    board = uno
-
-    [env:nodemcu]
-    platform = espressif8266
-    framework = arduino
-    board = nodemcu
-
-    [env:teensy31]
-    platform = teensy
-    framework = arduino
-    board = teensy31
-
-    [env:lpmsp430g2553]
-    platform = timsp430
-    framework = energia
-    board = lpmsp430g2553
-    build_flags = -D LED_BUILTIN=RED_LED
+--------
 
 .. _projectconf_section_env:
 

platformio/managers/platform.py

@@ -395,8 +395,12 @@ class PlatformBase(PlatformPackagesMixin, PlatformRunMixin):
             config.manifest['platform'] = self.name
             self._BOARDS_CACHE[board_id] = config
 
-        bdirs = (join(util.get_home_dir(), "boards"),
-                 join(self.get_dir(), "boards"))
+        bdirs = [
+            util.get_projectboards_dir(),
+            join(util.get_home_dir(), "boards"),
+            join(self.get_dir(), "boards"),
+        ]
+
         if id_ is None:
             for boards_dir in bdirs:
                 if not isdir(boards_dir):

platformio/util.py

@@ -258,6 +258,11 @@ def get_projecttest_dir():
                                                      "test"))
 
 
+def get_projectboards_dir():
+    return _get_projconf_option_dir("boards_dir", join(get_project_dir(),
+                                                       "boards"))
+
+
 def get_projectpioenvs_dir(force=False):
     path = _get_projconf_option_dir("envs_dir",
                                     join(get_project_dir(), ".pioenvs"))