.. _kbuild_project: Developing an Application Project Using Kbuild ********************************************** The build system is a project centric system. The |codename| must have a defined project that allows the build of the kernel binary. A project can be organized in three independent directories: the kernel base directory, the project directory, and the project source code directory. The kernel base directory is the |codename| base directory. This directory hosts the kernel source code, the configuration options and the kernel build definitions. The project directory is the directory that puts together the kernel project with the developer project. This directory hosts the definition of the developers' projects, for example: specific configuration options and file location of the source code. The project source code directory hosts the source code of the developers' projects. The Application Project ======================= A common application project is composed of the following files: * Makefile: Configures the project and integrates the developer's project with the |codename| Kbuild system. * Configuration file: Allows the user to override the standard configuration. * MDEF file: Defines the set of kernel objects instantiated by the project. Required only by microkernel architectures. * The :file:`src/` directory: Hosts by default the project source code. This directory can be overridden and defined in a different directory. * Makefile: Adds the developer's source code into the Kbuild recursion model. The project source code can be organized in subdirectories. Each directory should follow the Kbuild Makefile conventions. Project Definition ================== The application project is defined through the project Makefile. The project is integrated into the Kbuild 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 |codename| The architectures currently supported are x86, arm and arc. The build system sets C flags, selects the default configuration and the toolchain tools. The default value is x86. * :makevar:`ZEPHYR_BASE`: Sets the path to the |project| base directory. This variable is usually set by the :file:`timo_env.sh` script. It can be used to get the |project| base directory (as used in the Makefile.inc inclusion) or it can be overridden to select an specific instance of the |codename|. * :makevar:`PROJECT_BASE`: Provides the developer project directory path. It is set by the :file:`Makefile.inc`, * :makevar:`SOURCE_DIR`: Overrides the default value for the developer source code directory. The developer source code directory is set to :file:`$(PROJECT_BASE/)src/` by default. This directory name should end with backslash **'/'**. * :makevar:`PLATFORM_CONFIG`:Selects the platform of the default configuration used by the project build. * :makevar:`KERNEL_TYPE`: Select the kernel type of the default configuration used by the project build. It indicates if this is a nanokernel or microkernel architecture. The supported values are **nano** and **micro**. * :makevar:`MDEF_FILE`: Indicates the name of the MDEF file. It is required for microkernel architectures only. * :makevar:`CONF_FILE`: Indicates the name of a configuration snippet file. This file includes the kconfig values that are overridden from the default configuration. * :makevar:`O`: Optional. Indicates the output directory used by Kconfig. The output directory stores all the Kconfig generated files. The default output directory is set to the :file:`$(PROJECT_BASE)/output` directory. Project Debugging ================= This section is a quick hands-on reference to start debugging |project| with QEMU. Most of the 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 setup 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. This image will be generated by the build system in the output directory. By default, the kernel binaries names are :file:`microkernel.elf` and :file:`nanokernel.elf`. The names can be changed using Kconfig. .. note:: We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)` server instance in this reference manual. This port number can be changed for a port that best suits your development system. |codename| uses QEMU as the supported emulation system. QEMU must be invoked with the -s and -S parameters. * -S Do not start CPU at startup (you must type 'c' in the monitor). * -s Shorthand for -gdb tcp::1234, i.e. 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 parameters can be set using the environment variable :makevar `QEMU_EXTRA_FLAGS`. To set the -s and -S parameters type: .. 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 instace. It configures a connection to a remote target at the local host on the TCP port 1234. The initialization should set 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 your debug application from the same directory that you chose for the :file:`gdbinit` file. The command may include the --tui option to enable the use if a teminal user interface. The following commands connects to the GDB server using :file:`gdb`. --tui).The command loads the symbol table from the elf binary file. In this example, the elf binary file name corresponds to :file:`microkernel.elf` file: .. code-block:: bash gdb --tui microkernel.elf .. note:: The --tui option might not be supported by the GDB version installed in your development system. 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:`nanokernel.elf` file. .. note:: The 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 nanokernel.elf" .. note:: Both commands use the :command:`gdb` to execute the GNU Debugger. The command name might change depending on the toolchain you are using and your cross-development tools.