====================
Custom Boards How-To
====================

As explained in :doc:`../quickstart/configuring`, supported boards (also known
as "in-tree" boards) are configured using a standard syntax:

    .. code-block:: console

      $ cd nuttx
      $ ./tools/configure.sh -l board-name:config-name
        Copy files
        Select CONFIG_HOST_LINUX=y
        Refreshing...

Sometimes it is not appropriate, or not wanted, to add a new or custom board to
the NuttX boards tree itself. If so, the board can be defined out-of-tree in a
custom directory and still be built easily.

Add a Custom Board
==================

The same set of files as provided for in-tree boards is required (i.e. configs,
Kconfig, scripts, etc.) but these can be placed in a directory of your choice.

In this example, the files are assumed to exist in:
 ``../nuttx/CustomBoards/MyCustomBoardName``

    .. code-block:: console

      $pwd
      /home/nuttx/nuttx
      $ ls -1 ../CustomBoards/MyCustomBoardName
      configs
      helpers
      include
      Kconfig
      scripts
      $ ls ../CustomBoards/MyCustomBoardName/configs
      nsh
      MyCustomConfig
      $

At this stage, the contents of the files is not important. The notable exception to this
is file named ``defconfig``, which is stored in the directory ``MyCustomConfig`` (see
the listing above.)

This file is autogenerated and should not be edited manually. However, it should also
not be copied blindly from an existing board as the values within are incorrect
for the custom board. This causes an issue because the configure script called below
is supposed to create some symbolic links in the NuttX source tree and it is using
the contents of the ``defconfig`` file for that. Since the file does not exist,
configure script will fail which prevents the user from creating the ``defconfig``
file automatically.

As a workaround, a minimal ``defconfig`` file needs to be provided. See an example
for AVR architecture:

    .. code-block:: kconfig

      CONFIG_ARCH="avr"
      CONFIG_ARCH_AVR=y
      CONFIG_ARCH_BOARD_CUSTOM=y
      CONFIG_ARCH_BOARD_CUSTOM_DIR_RELPATH=y
      CONFIG_ARCH_BOARD_CUSTOM_DIR="../CustomBoards/MyCustomBoardName/"
      CONFIG_ARCH_BOARD_CUSTOM_NAME="MyCustomBoardName"
      CONFIG_ARCH_CHIP="avrdx"

This minimal file should be sufficient for the configure script to succeed. Additional
changes can be made using ``make menuconfig`` and proper ``defconfig`` file can then
be generated using ``make savedefconfig``.

To build the custom board, alter the contents of the example above to fit your
architecture and chip, then use this syntax, which is slightly different
from in-tree boards and configs:

    .. code-block:: console

      $ ./tools/configure.sh -l ../CustomBoards/MyCustomBoardName/configs/MyCustomConfig
      Copy files
      Select CONFIG_HOST_LINUX=y
      Refreshing...

Kconfig Settings
================

Once the board is configured, to ensure subsequent builds run correctly, there
are two Kconfig settings that need to be set. These are:

:menuselection:`Board Selection --> Custom Board Configuration --> Custom Board Name`

:menuselection:`Board Selection --> Custom Board Configuration --> Relative custom board directory`

They should be set to suit your board name and directory location.

.. Note::
   If you subsequently run a ``make distclean`` operation, then these settings will be lost.
   They should be added back before building, and/or before running ``make menuconfig``.