doc: application: CMake updates for overview and creation docs

Application Development Primer

##############################

.. note::

   In this document, we'll assume your **application directory** is

   :file:`~/app`, and that its **build directory** is :file:`~/app/build`.

   (These terms are defined in the following Overview.)

Overview

********

The Zephyr Kernel's build system is based on CMake.

The build system is an application-centric system and requires an application

build to initiate building the kernel source tree. The application build drives

the configuration and build process of both the application and kernel,

Zephyr's build system is based on CMake.

The build system is application-centric, and requires Zephyr-based applications

to initiate building the kernel source tree. The application build controls

the configuration and build process of both the application and Zephyr itself,

compiling them into a single binary.

The Zephyr Kernel's base directory hosts the kernel source code, the

configuration options, and the kernel build definitions.

Zephyr's base directory hosts Zephyr's own source code, its kernel

configuration options, and its build definitions.

The files in the application directory links the kernel with the

application. It hosts the definitions of the application, for example,

application-specific configuration options and the application's source code.

The files in the **application directory** link Zephyr with the

application. This directory contains all application-specific files, such as

configuration options and source code.

An application in the simplest form has the following structure:

An application in its simplest form has the following contents:

* **Application source code files**: An application typically provides one

  or more application-specific files, written in C or assembly language. These

  files are usually located in a sub-directory called :file:`src`.

.. code-block:: none

   ~/app

   ├── CMakeLists.txt

   ├── prj.conf

   └── src

       └── main.c

These contents are:

* **CMakeLists.txt**: This file tells the build system where to find the other

  application files, and links the application directory with Zephyr's CMake

  build system. This link provides features supported by Zephyr's build system,

  such as board-specific kernel configuration files, the ability to run and

  debug compiled binaries on real or emulated hardware, and more.

* **Kernel configuration files**: An application typically provides

  a configuration file (:file:`.conf`) that specifies values for one or more

  kernel configuration options. If omitted, the application's existing kernel

  configuration option values are used; if no existing values are provided,

  the kernel's default configuration values are used.

  a configuration file (ending in :file:`.conf`) that specifies values for one

  or more kernel configuration options. If omitted, the application's existing

  kernel configuration option values are used; if no existing values are

  provided, the kernel's default configuration values are used.

* **CMakeLists.txt**: This file tells the build system where to find the files

  mentioned above, as well as the desired target board configuration.

* **Application source code files**: An application typically provides one

  or more application-specific files, written in C or assembly language. These

  files are usually located in a sub-directory called :file:`src`.

Once the application has been defined, project files for building it

can be generated by calling cmake. The project files will be written

to the directory where cmake was called, this directory is known as

the build directory.

Once an application has been defined, project files for building it can be

generated by calling ``cmake ~/app``. Project files will be written to the

directory where ``cmake`` is called. This directory is known as the

**build directory**.

The most notable files in the build directory are listed below.

The most notable files in the build directory are:

* The :file:`Makefile` (or :file:`build.ninja`) project file that can

  be invoked to build the application.

* :file:`build.ninja` (or :file:`Makefile`), which can be invoked to build

  the application.

* The :file:`zephyr` directory is the working directory of the

  generated build system and where most generated files are located.

* A :file:`zephyr` directory, which is the working directory of the

  generated build system, and where most generated files are created and

  stored.

After the underlying build tool has been invoked the build output will

be written to the :file:`zephyr` directory.

After the underlying build tool has been invoked, the following build output

files will be written to the :file:`zephyr` sub-directory of the build

directory. (This is different than the Zephyr base directory, which contains

the Zephyr source code etc. and is described above.)

* The :file:`.config` file that contains the configuration settings

* :file:`.config`, which contains the configuration settings

  used to build the application.

* The various object files (:file:`.o` files and :file:`.a` files) containing

  custom-built kernel and application-specific code.

* The :file:`zephyr.elf` file that contains the final combined application and

  kernel binary.

* Various object files (:file:`.o` files and :file:`.a` files) containing

  compiled kernel and application code.

* :file:`zephyr.elf`, which contains the final combined application and

  kernel binary. Other binary output formats, such as :file:`.hex` and

  :file:`.bin`, are also supported.

Application Structure

*********************

Creating an Application

***********************

Create one directory for your application and a sub-directory for the

application's source code; this makes it easier to distinguish between

project files and source code.

#. Create an application directory structure outside of the kernel's

   installation directory tree. Often this is your workspace directory.

Follow these steps to create a new application directory. (Refer to

:ref:`samples-and-demos` for existing applications provided as part of Zephyr.)

#. In a console terminal, navigate to a location where you want your

   application to reside.

#. Create an application directory on your workstation computer, outside of the

   Zephyr base directory.  Usually you'll want to create it somewhere under

   your user's home directory.

#. Create the application's directory, enter:

   For example, in a Unix shell, navigate to a location where you want your

   application to reside, then enter:

   .. code-block:: console

      $ mkdir app

   .. note::

      This directory and the path to it, are referred to in the documentation

      as :file:`~/app`.

#. It's recommended to place all application source code in a subdirectory

   named :file:`src`.  This makes it easier to distinguish between project

   files and sources.

#. Create a source code directory in your :file:`~/app`, enter:

   Continuing the Unix shell example from the previous step, enter:

   .. code-block:: console

      $ cd app

      $ mkdir src

   The source code directory :file:`~/app/src` is created.

   .. code-block:: console

#. Create a :file:`CMakeLists.txt` file in your application directory with the

   following contents:

      -- app

         |-- src

   .. code-block:: cmake

      include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)

      project(NONE)

Application Definition

**********************

#. Place your application source code in the :file:`src` sub-directory. For

   this example, we'll assume you created a file named :file:`src/main.c`.

An application is integrated into the build system with two lines of

boilerplate code in it's :file:`CMakeLists.txt` file and by having the

environment variable :makevar:`ZEPHYR_BASE` set.

#. Add your source code files to the ``app`` target in your application

   directory's :file:`CMakeLists.txt`. For example, to add :file:`src/main.c`,

   add the following line to your :file:`CMakeLists.txt`:

   .. code-block:: cmake

   include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)

   project(NONE)

      target_sources(app PRIVATE src/main.c)

#. Create one or more files containing your application's configuration

   options. Zephyr's configuration uses the same Kconfig system used by the

   Linux kernel, but with its own configuration tree.

   If you followed the above steps, you can now create a file named

   ``prj.conf`` in your application directory. It will be used automatically by

   the Zephyr build system.

   More information on Zephyr configuration is available below.

Applications integrate with the Zephyr build system using the boilerplate code

shown above in :file:`CMakeLists.txt`. The following important variables

configure the Zephyr build system:

* :makevar:`ZEPHYR_BASE`: Sets the path to the Zephyr base directory.  This is

  usually an environment variable set by the :file:`zephyr-env.sh` script, as

  you learned when getting started with Zephyr in

  :ref:`getting_started_run_sample`. You can also select a specific Zephyr base

  directory by replacing ``$ENV{ZEPHYR_BASE}`` with the specific base you'd

  like to use instead.

The following predefined variables configure the development project:

* :makevar:`BOARD`: Selects the board that the application's build will use for

  the default configuration. This can be defined in the environment, in your

  application's :file:`CMakeLists.txt` file, or in the ``cmake`` command line.

* :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 boilerplate above, or it can be

  overridden to select an specific instance of the kernel.

* :makevar:`CONF_FILE`: Indicates the name of one or more configuration

  fragment files.  Each file includes kconfig configuration values that

  override the default configuration values.  Like :makevar:`BOARD`, this can

  also be defined in the environment, in your application's

  :file:`CMakeLists.txt` file, or in the ``cmake`` command line.

* :makevar:`BOARD`: Selects the board that the application's

  build will use for the default configuration.

The following sections provide more details on Zephyr's use of CMake, how to

manage your application's configuration, and how to build and run it.

* :makevar:`CONF_FILE`: Indicates the name of a configuration fragment file.

  This file includes the kconfig configuration values that override the

  default configuration values.

CMake

*********