.. include:: /keyword.rst

======================
Build from Source Code
======================

The |IOT-YOCTO| BSP is based on the `Yocto project <https://www.yoctoproject.org/>`_.
The ``rity-demo-image`` image recipe is provided as part of this BSP contains a set of tools, applications, and configurations for evaluation of Genio devices.
The demo image also demonstrates how to build a custom image on top of the |IOT-YOCTO| BSP.

.. hint::

   For general Yocto concept introductions, please refer to the `Yocto Project Overview <https://docs.yoctoproject.org/3.1.12/overview-manual/overview-manual.html>`_.


.. note::
    
   Please ensure you have :doc:`setup the build environment on a Linux host computer </sw/yocto/get-started/env-setup/build-env-linux>` before continuing with this guide.
   If you do not wish to build an image at this time, prebuilt demo images can be downloaded from the :doc:`/sw/yocto/download` page.

.. important::
    You need permission to access the |AIOT-NDA| to build fully functioned ``rity-demo-image``.
    You can still build image using only publicly available packages through
    configuration, but the resulting images have only limited feature set.

    To request for the permission, please contact your MediaTek sales.


Project Root
============

Choose a directory as the root of your |IOT-YOCTO| project:

.. prompt:: bash

    mkdir iot-yocto; cd iot-yocto
    export PROJ_ROOT=`pwd`

In the following sections, we use ``$PROJ_ROOT`` as the root directory of your Yocto project.

.. _download-the-recipes:

Download the Recipes
====================

.. important:: 

	Please read and agree :ref:`AIoT Software License Agreement <license-ref>` before accessing or using |IOT-YOCTO| software.
	If you do not agree to the terms and conditions of :ref:`AIoT Software License Agreement <license-ref>`, you must not access or use the software.

|IOT-YOCTO| uses `manifest files <https://gerrit.googlesource.com/git-repo/+/master/docs/manifest-format.md>`_ to store locations of `Yocto recipes <https://docs.yoctoproject.org/3.1.12/overview-manual/overview-manual-concepts.html#recipes>`_.

To download the |IOT-YOCTO|, please run the following ``repo`` command to initialize which version or branch of |IOT-YOCTO| you'd like to download:

.. prompt:: bash

    repo init -u https://gitlab.com/mediatek/aiot/bsp/manifest.git -b refs/tags/rity-kirkstone-v24.1


The ``-b refs/tags/rity-kirkstone-v24.1`` option specifies use of the ``rity-kirkstone-v24.1`` **release tag**,

.. note:: 

    Since this is a tag, it is frozen and ``repo sync`` always download the same recipes.
    Please note that since this is a static version, you will not receive important security and bug fixes or feature improvements.

    There are other branches also listed in https://gitlab.com/mediatek/aiot/bsp/manifest/.
    For example the branch ``critical-fixes/rity-kirkstone-v24.0`` contains critical patches based on the ``rity-kirkstone-v24.0``
    release tag.

    Others development branches can break frequently. For example, ``rity/kirkstone`` is
    actively developed in |IOT-YOCTO|. The maintainers continuously update the recipes in this branch every week.

Next, please run the following command to download all the Yocto layers of the |IOT-YOCTO| SDK into the ``$PROJ_ROOT/src/`` directory:

.. prompt:: bash
    
    repo sync

Unlike an Android codebase, this step only downloads the |IOT-YOCTO| layers and the recipes. The actual packages, such as the Linux kernel code, are not downloaded to your local disk yet.

Troubleshooting
---------------

If the repo tool reports manifest syntax error, you might want to install the latest `repo tool <https://gerrit.googlesource.com/git-repo/+/refs/heads/master/README.md>`_ manually with:

.. prompt:: bash

    mkdir -p ~/bin
    PATH="${HOME}/bin:${PATH}"
    curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
    chmod a+rx ~/bin/repo


.. _configure-build-environment:

Configure Build Environment
===========================

After the recipes are downloaded, use the following commands to initialize a Yocto project build environment:

.. prompt:: bash

    export TEMPLATECONF=$PROJ_ROOT/src/meta-rity/meta/conf/
    source src/poky/oe-init-build-env <build-directory>
    export BUILD_DIR=`pwd`

The ``<build-directory>`` defaults to ``build`` if omitted. You can use a different name for the build directory, and even have multiple build directories.
This step creates a Yocto build environment in the ``$PROJ_ROOT/<build-directory>`` directory. 
The ``oe-init-build-env`` will change current directory to the ``<build-directory>`` of your choice automatically. 
The Yocto project allows you to switch between multiple build environments, each build environment is a directory.

In the following sections, ``$BUILD_DIR`` is pointed to the build environment directory of your choice.

Initially, the build directory structure should look like this:

.. code:: bash

    $BUILD_DIR
             └── conf
                     ├── bblayers.conf
                     ├── local.conf
                     └── templateconf.cfg

When building the project image, all the source code, intermediate files and the output binaries are located under this ``$BUILD_DIR``.

.. note::

    ``oe-init-build-env`` not only creates a build directory, it also sets up several environment variables required by subsequent ``bitbake`` commands. If you re-start the console session, make sure you run ``source src/poky/oe-init-build-env <build-directory>`` again to properly set the environment variables. The script is smart enough to keep the content of the build directory untouched if you've made some modifications.


.. _build-with-nda:

Setup with NDA Repository
=========================

By default the |IOT-YOCTO| will be built only with packages that are publicly available on Internet.
To build |IOT-YOCTO| with MediaTek proprietary packages, access to private repositories under |AIOT-NDA| is required.

.. note::

    For more information on applying for access permission to NDA repositories, please contact your
    local MediaTek support window.


To enable NDA build, please add following setting to the ``site.conf`` file after :ref:`configuring the
build environment <configure-build-environment>`:

.. prompt:: bash $ auto

        $ echo 'NDA_BUILD = "1"' >> $BUILD_DIR/conf/site.conf

.. note::

   This can be skipped if you don't have NDA repository access or if you'd like to build a public configuration.


Setup DL_DIR and SSTATE_DIR
===========================

If you have already built |IOT-YOCTO| before, you might notice there are two folders
``downloads`` and ``sstate-cache`` created during the build process. These two folders
serve for different purposes:

* ``downloads`` folder is a central place for storing source tarballs downloaded during
  the build process. The build process searches in this folder for finding sources first
  before downloading from the Internet.
* ``sstate-cache`` is a directory stores `shared state
  <https://docs.yoctoproject.org/overview-manual/concepts.html#shared-state>`_ during
  the build process. |IOT-YOCTO| uses the shared state to quickly reconstruct
  built artifacts if things haven't changed since the last build.

By default the ``downloads`` and ``sstate-cache`` are located under ``$BUILD_DIR``. We recommend
to setup these folders to be outside of ``$BUILD_DIR`` for several reasons:

* In default setup, after removing ``$BUILD_DIR``, it usually takes several hours to
  rebuild |IOT-YOCTO|, because those caching folders are also deleted when deleting
  ``$BUILD_DIR``. By separating caching folders from ``$BUILD_DIR``, if something goes
  wrong, it's easy to just delete ``$BUILD_DIR`` and rebuild.
  Since ``downloads`` and ``sstate-cache`` are in different places, it takes less time
  to reconstruct built artifacts.
* It is not recommended to reuse the same ``$BUILD_DIR`` after changing build
  configurations (e.g. changing MACHINE, updating DISTRO_FEATURES, etc.). Sometimes
  reusing ``$BUILD_DIR`` may cause subtle issues that are hard to diagnose. But
  users tend to take a shortcut because it saves hours of build time.
  After separating caching folders from ``$BUILD_DIR``, removing ``$BUILD_DIR`` becomes
  less expensive, which encourages users to reconstruct ``$BUILD_DIR`` more often
  instead of reusing the same folder when changing configurations.

Run the following commands to add these variables to your ``site.conf`` file:

.. code-block:: bash

    $ echo 'DL_DIR = "${TOPDIR}/../downloads"' >> $BUILD_DIR/conf/site.conf
    $ echo 'SSTATE_DIR = "${TOPDIR}/../sstate-cache"' >> $BUILD_DIR/conf/site.conf

.. note::

    The variable ``${TOPDIR}`` is a Bitbake variable used in |IOT-YOCTO|, which indicates the build
    folder (that is, ``$BUILD_DIR``).

.. hint::

   * To learn more about ``DL_DIR``, please refer to `Yocto Reference Manual <https://docs.yoctoproject.org/4.0.22/ref-manual/variables.html?highlight=dl_dir#term-DL_DIR>`_.
   * For details about the content in the ``conf`` directory, please refer to `Yocto Project Concepts <https://docs.yoctoproject.org/overview-manual/concepts.html#user-configuration>`_.


.. _build-image-command:

Fetch and Build the Packages
============================

The previous steps does not actually fetch source code of packages in |IOT-YOCTO|. Instead, we need to use ``bitbake`` command to execute recipes. Each recipe defines:

* How and where to fetch the package source code
* What patches have to be applied to the source code
* What are the dependencies and toolchain required by the package
* How to setup the build environment of the package

Typically the desired outcome from a build is an image that can be flashed to a device.
This is what we specify for ``bitbake`` to build.
By parsing the recipes it builds up a chain of dependencies that it works through to build the specified item.
In this guide we will tell ``bitbake`` to build the ``rity-demo-image`` recipe.

Depending on which board you'd like to build for, assign the ``MACHINE`` config variable:

.. tabs::

   .. group-tab:: |G350-EVK|

      .. prompt:: bash $ auto

         $ export MACHINE=genio-350-evk
         $ bitbake rity-demo-image
      
   .. group-tab:: |G510-EVK|

      .. prompt:: bash $ auto
      
         $ export MACHINE=genio-510-evk
         $ bitbake rity-demo-image
      
   .. group-tab:: |G700-EVK|

      .. prompt:: bash $ auto
      
         $ export MACHINE=genio-700-evk
         $ bitbake rity-demo-image
      
   .. group-tab:: |G1200-EVK|

      .. prompt:: bash $ auto
      
         $ export MACHINE=genio-1200-evk
         $ bitbake rity-demo-image
      
.. note::

   Please see :ref:`sw/yocto/yocto-development:build for other boards` for information on building with other boards.

.. warning::

   As the ``bitbake`` command analyzes all the dependencies and fetches the required packages, building each down to the required cross-toolchain, this step can :ref:`take a very long time<faq-yocto-build-time>`.


Build Result and Images
=======================

If everything works as expected, a summary log would be printed:

.. code::

    NOTE: Tasks Summary: Attempted 7180 tasks of which 11 didn't need to be rerun and all succeeded.

The exact task number may vary, but if all succeeded, your image is located in:

.. code:: bash

    $BUILD_DIR/tmp/deploy/images/$MACHINE

If something goes wrong, you can look for the error logs by search for these patterns in the log:

.. code:: text

    ERROR: Logfile of failure stored in: '<path-to-logfile>'

For details and additional parameters of the ``bitbake`` command, please refer to the Yocto project's `bitbake manual`_.

.. _bitbake manual: https://docs.yoctoproject.org/bitbake/1.46/bitbake-user-manual/bitbake-user-manual-intro.html#introduction