.. SPDX-FileCopyrightText: 2023-2025 Sony Semiconductor Solutions Corporation
..
.. SPDX-License-Identifier: Apache-2.0

.. _top_level:

Top-level Makefile
==================

This Makefile contains the top-level rules
that fulfill the project targets,
and usually it is the only way to guarantee a correct build,
because nested Makefiles can assume
that actions done by this Makefile are already performed.

.. _all_target:

``all`` target
--------------

This is the default target;
it builds the :ref:`libs_target`
and uses it to compile the Linux agent
defined by the main function in ``src/evp_agent/evp_agent.c``.

.. _config_target:

``config`` target
-----------------

This target is used
to configure the build system based in the :ref:`kconfig`.
It uses the macro ``KBUILD_DEFCONFIG``
to point to the Kconfig definition file
that configures the build system.

This target will generate a file called ``.config``
included by default by :ref:`rules.mk`
that defines a set of macros that
modifies the behavior of the build system,
for example,
selecting the files that are part of
the ``libevp-agent``
and ``libevp-app-sdk`` libraries.

It also generates the file ``include/config.h``
that is included in many C files
including all the macro definitions
that can be modified by the build configuration system.

This target is executed by default
if the build system was not currently configured
and the macro ``KBUILD_DEFCONFIG`` points to the default ``configs/defaults.mk``.
For this reason,
if the kbuild configuration is different then it is usual
that the first step in any build should be something like:

.. code:: shell

	make KBUILD_DEFCONFIG=configs/linux-docker.config config

and after this step, the macro ``KBUILD_DEFCONFIG`` no longer has any effect.
If a different configuration file is required,
the only safe way to get a correct build is first to use the ``distclean`` target
and then run the ``config`` target.

.. code:: shell

	make distclean
	make KBUILD_DEFCONFIG=configs/linux.config config

.. _libs_target:

``libs`` target
---------------

This target builds all the libraries that
are part of the EVP project, including:

	- ``libevp-agent``: Library containing all the functions
	  implementing the agent functionality.
	- ``libevp-app-sdk``: Library containing the **EVP C SDK**.
	- ``libevp-utils``: Library containing a set of independent functions
	  that don\'t have any dependency on the agent or the SDK.

.. _depend_target:

``depend`` target
-----------------

This target builds all the external dependencies
contained in the repository as :ref:`git_submodules`.
The set of dependencies depends on the Kconfig selected,
and it is driven by the file ``deps.mk`` generated by the :ref:`config_target`.

``sdk`` target
--------------

This target just builds the ``libevp-app-sdk`` library and its dependencies.

.. _test_modules_target:

``test_modules`` target
-----------------------

This target builds multiple versions of
all the modules contained in the ``test_modules`` directory:

  * Native ELF
  * WASM module

The set of modules will be used later for the :ref:`test_target`.

``signed_test_modules`` target
------------------------------

This target (if required) builds the test modules using the :ref:`test_modules_target`,
and signs them by default using the key located in *tools/module_key.bin*.
A different key can be selected using the macro ``KEY_FILE``.

.. _test_target:

``test`` target
---------------

This target builds all the dependencies required to run the tests
(such as libraries or external dependencies)
and to run the tests contained in the directory tests.
This target can be customized using the ``RUN_FLAGS`` macro
that is passed to the *run-tests* script (see :ref:`run-tests`).

Examples
--------

If the Kconfig configuration used is not the default,
the recommended way to build the project is:

.. code:: shell

	# configure the build system
	make KBUILD_DEFCONFIG=configs/linux-docker.config config
	# build the reference implementation of the EVP Agent
	make

The build system supports parallel builds and
its usage is highly recommended.
For example, to build and run all the tests in parallel:

.. code:: shell


	make KBUILD_DEFCONFIG=configs/unit-test-all-hubs-wasm.config
	make -j `nproc` test

If it is desired to build only the SDK:

.. code:: shell

	make KBUILD_DEFCONFIG=configs/linux-docker.config config
	make -j `nproc` sdk

If the Kconfig used is the default, then
the ``config`` step can be skipped in all the previous examples.