.. _kbuild_project: Developing an Application and the Build System ********************************************** The build system is an application centric system. The application drives the configuration and build process of the kernel binary. Application development can be organized in three independent directories: the kernel base directory, the project directory, and the project source code directory. The Zephyr Kernel's base directory hosts the kernel source code, the configuration options, and the kernel build definitions. The application directory is the directory that puts together the kernel with the developer's application. It hosts the definitions of the developers' applications. For example, application-specific configuration options and the application's source code. The Application Project ======================= A common application project is composed of the following files: * **Makefile**: Defines the application's build process and integrates the developer's application with the kernel's build system. * **Configuration file**: Allows the developer to override the board's default configuration. * **MDEF**: Defines the set of kernel objects that the the application instantiates. Required only by the microkernel. * **The :file:`src/` directory**: By default, this directory hosts the application's source code. This location can be overridden and defined in a different directory. * **Makefile**: Adds the developer's source code into the build system's recursion model. The application's source code can be organized in subdirectories. Each directory must follow the Kbuild Makefile conventions; see :ref:`kbuild_makefiles`. Application Definition ====================== The developer defines the relationship of application to build system through the Makefiles. The application is integrated into the build system by including the Makefile.inc file provided. .. code-block:: make include $(ZEPHYR_BASE)/Makefile.inc The following predefined variables configure the development project: * :makevar:`ARCH`: Specifies the build architecture for the kernel. The architectures currently supported are x86, arm and arc. The build system sets C flags, selects the default configuration and uses the appropriate toolchain tools. The default value is x86. * :makevar:`ZEPHYR_BASE`: Sets the path to the kernel's base directory. This variable is usually set by the :file:`zephyr_env.sh` script. It can be used to get the kernel's base directory, as used in the Makefile.inc inclusion above, or it can be overridden to select an specific instance of the kernel. * :makevar:`PROJECT_BASE`: Provides the developer's application project directory path. It is set by the :file:`Makefile.inc` file. * :makevar:`SOURCE_DIR`: Overrides the default value for the application's source code directory. The developer source code directory is set to :file:`$(PROJECT_BASE/)src/` by default. This directory name should end with slash **'/'**. * :makevar:`BOARD`: Selects the board that the application's build will use for the default configuration. * :makevar:`KERNEL_TYPE`: Selects the kernel type that the application's build will use for the default configuration. It indicates whether to use a nanokernel or microkernel architecture. The supported values are **nano** and **micro**. * :makevar:`MDEF_FILE`: Indicates the name of the MDEF file; required for microkernel architectures only. * :makevar:`CONF_FILE`: Indicates the name of a configuration fragment file. This file includes the kconfig configuration values that override the default configuration values. * :makevar:`O`: Optional. Indicates the output directory that Kconfig uses. The output directory stores all the files generated during the build process. The default output directory is the :file:`$(PROJECT_BASE)/outdir` directory. Application Debugging ===================== This section is a quick hands-on reference to start debugging your application with QEMU. Most content in this section is already covered on `QEMU`_ and `GNU_Debugger`_ reference manuals. .. _QEMU: http://wiki.qemu.org/Main_Page .. _GNU_Debugger: http://www.gnu.org/software/gdb In this quick reference you find shortcuts, specific environmental variables and parameters that can help you to quickly set up your debugging environment. The simplest way to debug an application running in QEMU is using the GNU Debugger and setting a local GDB server in your development system through QEMU. You will need an ELF binary image for debugging purposes. The build system generates the image in the output directory. By default, the kernel binary name is :file:`zephyr.elf`. The name can be changed using Kconfig. .. note:: We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)` server instance. This port number can be changed for a port that best suits the development system. QEMU is the supported emulation system of the kernel. QEMU must be invoked with the -s and -S options. * ``-S`` Do not start CPU at startup; rather, you must type 'c' in the monitor. * ``-s`` Shorthand for :literal:`-gdb tcp::1234`: open a GDB server on TCP port 1234. The build system can build the elf binary and call the QEMU process with the :makevar:`qemu` target. The QEMU debug options can be set using the environment variable :envvar:`QEMU_EXTRA_FLAGS`. To set the ``-s`` and ``-S`` options: .. code-block:: bash export QEMU_EXTRA_FLAGS="-s -S" The build and emulation processes are called with the Makefile ``qemu`` target: .. code-block:: bash make qemu The build system will start a QEMU instance with the CPU halted at startup and with a GDB server instance listening at the TCP port 1234. The :file:`.gdbinit` will help initialize your GDB instance on every run. In this example, the initialization file points to the GDB server instance. It configures a connection to a remote target at the local host on the TCP port 1234. The initialization sets the kernel's root directory as a reference. The :file:`.gdbinit` file contains the following lines: .. code-block:: bash target remote localhost:1234 dir ZEPHYR_BASE .. note:: Substitute ZEPHYR_BASE for the current kernel's root directory. Execute the application to debug from the same directory that you chose for the :file:`gdbinit` file. The command can include the ``--tui`` option to enable the use of a terminal user interface. The following commands connects to the GDB server using :file:`gdb`. The command loads the symbol table from the elf binary file. In this example, the elf binary file name corresponds to :file:`zephyr.elf` file: .. code-block:: bash gdb --tui zephyr.elf .. note:: The GDB version on the development system might not support the --tui option. Finally, this command connects to the GDB server using the Data Displayer Debugger (:file:`ddd`). The command loads the symbol table from the elf binary file, in this instance, the :file:`zephyr.elf` file. .. note:: The :abbr:`DDD (Data Displayer Debugger)` may not be installed in your development system by default. Follow your system instructions to install it. .. code-block:: bash ddd --gdb --debugger "gdb zephyr.elf" .. note:: Both commands execute the :abbr:`gdb (GNU Debugger)`. The command name might change depending on the toolchain you are using and your cross-development tools.