build: support out-of-tree custom boards

This is one way we can support out of tree board definitions. Basically
all this needs is a board definition in the application source directory
that follows the same structure we have in the main Zephyr tree (also
allowing multiple custom boards). An application tree would look like
this for example:

boards/
CMakeLists.txt
prj.conf
README.rst
src/

with boards following the same structure as in Zephyr:

.
├── boards
│   └── x86
│       └── arduino_101
│           ├── doc
│           │   └── img
│           └── support
└── src

To use this, you need to specify the BOARD_ROOT variable on the command
line when building:

cmake -DBOARD=<board name> -DBOARD_ROOT=<path to boards> ..

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2018-02-11 22:30:57 -06:00 committed by Anas Nashif
commit e172fa3b52
5 changed files with 87 additions and 5 deletions

View file

@ -2,5 +2,9 @@
# error if it is missing
if(EXISTS ${BOARD_DIR}/CMakeLists.txt)
add_subdirectory(${BOARD_DIR})
if(BOARD_ROOT)
add_subdirectory(${BOARD_DIR} boards/${ARCH}/${BOARD})
else()
add_subdirectory(${BOARD_DIR})
endif()
endif()

View file

@ -180,7 +180,11 @@ set(CACHED_BOARD ${BOARD} CACHE STRING "Selected board")
# Use BOARD to search zephyr/boards/** for a _defconfig file,
# e.g. zephyr/boards/arm/96b_carbon_nrf51/96b_carbon_nrf51_defconfig. When
# found, use that path to infer the ARCH we are building for.
find_path(BOARD_DIR NAMES "${BOARD}_defconfig" PATHS ${ZEPHYR_BASE}/boards/*/* NO_DEFAULT_PATH)
if(NOT BOARD_ROOT)
set(BOARD_ROOT ${ZEPHYR_BASE})
endif()
find_path(BOARD_DIR NAMES "${BOARD}_defconfig" PATHS ${BOARD_ROOT}/boards/*/* NO_DEFAULT_PATH)
assert_with_usage(BOARD_DIR "No board named '${BOARD}' found")

View file

@ -10,7 +10,7 @@
# See ~/zephyr/doc/dts
set(GENERATED_DTS_BOARD_H ${PROJECT_BINARY_DIR}/include/generated/generated_dts_board.h)
set(GENERATED_DTS_BOARD_CONF ${PROJECT_BINARY_DIR}/include/generated/generated_dts_board.conf)
set_ifndef(DTS_SOURCE ${PROJECT_SOURCE_DIR}/boards/${ARCH}/${BOARD_FAMILY}/${BOARD_FAMILY}.dts)
set_ifndef(DTS_SOURCE ${BOARD_ROOT}/boards/${ARCH}/${BOARD_FAMILY}/${BOARD_FAMILY}.dts)
set_ifndef(DTS_COMMON_OVERLAYS ${PROJECT_SOURCE_DIR}/dts/common/common.dts)
message(STATUS "Generating zephyr/include/generated/generated_dts_board.h")
@ -85,7 +85,7 @@ if(CONFIG_HAS_DTS)
# Run extract_dts_includes.py for the header file
# generated_dts_board.h
set_ifndef(DTS_BOARD_FIXUP_FILE ${PROJECT_SOURCE_DIR}/boards/${ARCH}/${BOARD_FAMILY}/dts.fixup)
set_ifndef(DTS_BOARD_FIXUP_FILE ${BOARD_ROOT}/boards/${ARCH}/${BOARD_FAMILY}/dts.fixup)
if(EXISTS ${DTS_BOARD_FIXUP_FILE})
set(DTS_BOARD_FIXUP -f ${DTS_BOARD_FIXUP_FILE})
endif()

View file

@ -6,7 +6,6 @@ file(MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/include/generated)
set_ifndef(KCONFIG_ROOT ${PROJECT_SOURCE_DIR}/Kconfig)
#set(BOARD_DEFCONFIG ${PROJECT_SOURCE_DIR}/boards/${ARCH}/${BOARD}/${BOARD}_defconfig)
set(BOARD_DEFCONFIG ${BOARD_DIR}/${BOARD}_defconfig)
set(DOTCONFIG ${PROJECT_BINARY_DIR}/.config)

View file

@ -369,6 +369,81 @@ again.
.. _application_debugging:
Custom Board Definition
***********************
In cases where the board or platform you are developing for is not yet supported
by Zephyr, you can add the board definition to your application and build for
this board without having to add it to the Zephyr tree.
The structure needed to support out-of-tree board development
is similar to how boards are maintained in the Zephyr tree. By using
this structure, it will be much easier to upstream your board work into
the Zephyr tree after your initial development is done.
Add the custom board to your application using the following structure:
.. code-block:: console
boards/
CMakeLists.txt
prj.conf
README.rst
src/
where the ``boards`` directory hosts the board you are building for:
.. code-block:: console
.
├── boards
│   └── x86
│   └── my_custom_board
│   ├── doc
│   │   └── img
│   └── support
└── src
Use the proper architecture folder name (e.g., ``x86``, ``arm``, etc.)
under ``boards`` for ``my_custom_board``. (See :ref:`boards` for a
list of board architectures.)
Documentation (under ``doc/``) and support files (under ``support/``) are optional, but
will be needed when submitting to Zephyr.
The contents of ``my_custom_board`` should follow the same guidelines for any
Zephyr board, and provide the following files::
my_custom_board_defconfig
my_custom_board.dts
my_custom_board.yaml
board.cmake
board.h
CMakeLists.txt
doc/
dts.fixup
Kconfig.board
Kconfig.defconfig
pinmux.c
support/
Once the board structure is in place, you can build your application
targeting this board by specifying the location of your custom board
information with the ``-DBOARD_ROOT`` parameter to the CMake
build system::
cmake -DBOARD=<board name> -DBOARD_ROOT=<path to boards> ..
This will use your custom board configuration and will generate the
Zephyr binary into your application directory.
You can also define the ``BOARD_ROOT`` variable in the application
:file:`CMakeLists.txt` file.
Application Debugging
*********************