services/llext/build.html · services/llext/build.rst 공식 원문 ↗

Zephyr 3.7.0 · LLEXT · Build

LLEXT Extension Build

Main application과 같은 header·compiler flag로 extension을 만들고 .llext package를 생성합니다.

Official pathservices/llext/build.html
Source fileservices/llext/build.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

add_llext_target, custom PRE/POST step, target property, EDK tarball과 여섯 compile flag 묶음을 설명합니다.

Native

Zephyr CMake

Standalone

EDK tarball

Output

.llext

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 38AE4F33D3557FE397DBE0A37FCE5B70874DCC9BB1FB98FD21EE580B7401F009
Building extensions
###################

The LLEXT subsystem allows for the creation of extensions that can be loaded
into a running Zephyr application. When building these extensions, it's very
often useful to have access to the headers and compiler flags used by the main
Zephyr application.

The easiest path to achieve this is to build the extension as part of the
Zephyr application, using the `native Zephyr CMake features
<llext_build_native_>`_. This will result in a single build providing both the
main Zephyr application and the extension(s), which will all automatically be
built with the same parameters.

In some cases, involving the full Zephyr build system may not be feasible or
convenient; maybe the extension is built using a different compiler suite or as
part of a different project altogether. In this case, the extension developer
needs to export the headers and compiler flags used by the main Zephyr
application. This can be done using the `LLEXT Extension Development Kit
<llext_build_edk_>`_.

.. _llext_build_native:

Using the Zephyr CMake features
*******************************

The Zephyr build system provides a set of features that can be used to build
extensions as part of the Zephyr application. This is the simplest way to build
extensions, as it requires minimal additions to an application build system.

Building the extension
----------------------

An extension can be defined in the app's ``CMakeLists.txt`` by invoking the
``add_llext_target`` function, providing the target name, the output and the
source files. Usage is similar to the standard ``add_custom_target`` CMake
function:

.. code-block:: cmake

   add_llext_target(
       <target_name>
       OUTPUT <ext_file.llext>
       SOURCES <src1> [<src2>...]
   )

where:

- ``<target_name>`` is the name of the final CMake target that will result in
  the LLEXT binary being created;
- ``<ext_file.llext>`` is the name of the output file that will contain the
  packaged extension;
- ``<src1> [<src2>...]`` is the list of source files that will be compiled to
  create the extension.

The exact steps of the extension building process depend on the currently
selected :ref:`ELF object format <llext_kconfig_type>`.

The following custom properties of ``<target_name>`` are defined and can be
retrieved using the ``get_target_property()`` CMake function:

``lib_target``

    Target name for the source compilation and/or link step.

``lib_output``

    The binary file resulting from compilation and/or linking steps.

``pkg_input``

     The file to be used as input for the packaging step.

``pkg_output``

    The final extension file name.

Tweaking the build process
--------------------------

The following CMake functions can be used to modify the build system behavior
during the extension build process to a fine degree. Each of the below
functions takes the LLEXT target name as its first argument; it is otherwise
functionally equivalent to the common Zephyr ``target_*`` version.

* ``llext_compile_definitions``
* ``llext_compile_features``
* ``llext_compile_options``
* ``llext_include_directories``
* ``llext_link_options``

Custom build steps
------------------

The ``add_llext_command`` CMake function can be used to add custom build steps
that will be executed during the extension build process. The command will be
run at the specified build step and can refer to the properties of the target
for build-specific details.

The function signature is:

.. code-block:: cmake

   add_llext_command(
       TARGET <target_name>
       [PRE_BUILD | POST_BUILD | POST_PKG]
       COMMAND <command> [args...]
   )

The different build steps are:

``PRE_BUILD``

    Before the extension code is linked, if the architecture uses dynamic
    libraries. This step can access `lib_target` and its own properties.

``POST_BUILD``

    After the extension code is built, but before packaging it in an ``.llext``
    file. This step is expected to create a `pkg_input` file by reading the
    contents of `lib_output`.

``POST_PKG``

    After the extension output file has been created. The command can operate
    on the final llext file `pkg_output`.

Anything else after ``COMMAND`` will be passed to ``add_custom_command()`` as-is
(including multiple commands and other options).

.. _llext_build_edk:

LLEXT Extension Development Kit (EDK)
*************************************

When building extensions as a standalone project, outside of the main Zephyr
build system, it's important to have access to the same set of generated
headers and compiler flags used by the main Zephyr application, since they have
a direct impact on how Zephyr headers are interpreted and the extension is
compiled in general.

This can be achieved by asking Zephyr to generate an Extension Development Kit
(EDK) from the build artifacts of the main Zephyr application, by running the
following command which uses the ``llext-edk`` target:

.. code-block:: shell

    west build -t llext-edk

The generated EDK can be found in the build directory under the ``zephyr``
directory. It's a tarball that contains the headers and compile flags needed
to build extensions. The extension developer can then include the headers
and use the compile flags in their build system to build the extension.

Compile flags
-------------

The EDK includes the convenience files ``cmake.cflags`` (for CMake-based
projects) and ``Makefile.cflags`` (for Make-based ones), which define a set of
variables that contain the compile flags needed by the project. The full list
of flags needed to build an extension is provided by ``LLEXT_CFLAGS``. Also
provided is a more granular set of flags that can be used in support of
different use cases, such as when building mocks for unit tests:

``LLEXT_INCLUDE_CFLAGS``

        Compiler flags to add directories containing non-autogenerated headers
        to the compiler's include search paths.

``LLEXT_GENERATED_INCLUDE_CFLAGS``

        Compiler flags to add directories containing autogenerated headers to
        the compiler's include search paths.

``LLEXT_ALL_INCLUDE_CFLAGS``

        Compiler flags to add all directories containing headers used in the
        build to the compiler's include search paths. This is a combination of
        ``LLEXT_INCLUDE_CFLAGS`` and ``LLEXT_GENERATED_INCLUDE_CFLAGS``.

``LLEXT_GENERATED_IMACROS_CFLAGS``

        Compiler flags for autogenerated headers that must be included in the
        build via ``-imacros``.

``LLEXT_BASE_CFLAGS``

        Other compiler flags that control code generation for the target CPU.
        None of these flags are included in the above lists.

``LLEXT_CFLAGS``

        All flags required to build an extension. This is a combination of
        ``LLEXT_ALL_INCLUDE_CFLAGS``, ``LLEXT_GENERATED_IMACROS_CFLAGS`` and
        ``LLEXT_BASE_CFLAGS``.

.. _llext_kconfig_edk:

LLEXT EDK Kconfig options
-------------------------

The LLEXT EDK can be configured using the following Kconfig options:

:kconfig:option:`CONFIG_LLEXT_EDK_NAME`
    The name of the generated EDK tarball.

:kconfig:option:`CONFIG_LLEXT_EDK_USERSPACE_ONLY`
    If set, the EDK will include headers that do not contain code to route
    syscalls to the kernel. This is useful when building extensions that will
    run exclusively in user mode.

EDK Sample
----------

Refer to :zephyr:code-sample:`llext-edk` for an example of how to use the
LLEXT EDK.

Part 3

한국어 전문 번역

LLEXT subsystem은 실행 중인 Zephyr application에 load할 extension을 만들 수 있게 합니다. Extension을 build할 때 main Zephyr application이 사용한 header와 compiler flag에 접근해야 하는 경우가 많습니다.

가장 간단한 방법은 Zephyr native CMake 기능으로 extension을 application build에 포함하는 것입니다. Main application과 extension을 build 하나에서 만들며 모든 target에 같은 parameter가 자동 적용됩니다.

Zephyr build system 전체를 사용하기 어렵거나 extension이 다른 compiler suite 또는 별도 project에서 build되는 경우에는 main application의 header와 compiler flag를 export해야 합니다. 이때 LLEXT Extension Development Kit(EDK)를 사용합니다.

Zephyr CMake 기능 사용

Zephyr build system은 application의 일부로 extension을 build하는 기능을 제공합니다. Application build system에 최소한의 항목만 추가하면 되는 가장 단순한 방식입니다.

Extension build

Application CMakeLists.txt에서 add_llext_target()을 호출하고 target name, output file, source file을 전달합니다. Standard add_custom_target()과 사용법이 비슷합니다.

add_llext_target(
    <target_name>
    OUTPUT <ext_file.llext>
    SOURCES <src1> [<src2>...]
)
  • <target_name>: LLEXT binary를 만드는 최종 CMake target name입니다.
  • <ext_file.llext>: Package된 extension을 담을 output file name입니다.
  • <src1> [<src2>...]: Extension을 만들기 위해 compile할 source file 목록입니다.

정확한 build 단계는 현재 선택한 ELF object format에 따라 달라집니다.

<target_name>에는 get_target_property()로 읽을 수 있는 custom property가 정의됩니다.

lib_target
Source compile 또는 link 단계의 target name입니다.
lib_output
Compile 또는 link 결과 binary file입니다.
pkg_input
Packaging 단계 input으로 사용할 file입니다.
pkg_output
최종 extension file name입니다.

Build process 조정

다음 CMake function으로 extension build 동작을 세밀하게 바꿀 수 있습니다. 모두 첫 argument로 LLEXT target name을 받으며 나머지는 일반 Zephyr target_* version과 같은 기능을 합니다.

  • llext_compile_definitions
  • llext_compile_features
  • llext_compile_options
  • llext_include_directories
  • llext_link_options

Custom build 단계

add_llext_command()로 extension build 중 실행할 custom step을 추가할 수 있습니다. 지정한 build step에서 command가 실행되며 target property를 참조해 build-specific detail을 얻을 수 있습니다.

add_llext_command(
    TARGET <target_name>
    [PRE_BUILD | POST_BUILD | POST_PKG]
    COMMAND <command> [args...]
)
PRE_BUILD
Architecture가 dynamic library를 사용할 때 extension code link 전에 실행합니다. lib_target과 그 property에 접근할 수 있습니다.
POST_BUILD
Extension code build가 끝나고 .llext packaging을 하기 전에 실행합니다. lib_output을 읽어 pkg_input file을 만들어야 합니다.
POST_PKG
Extension output file이 생성된 뒤 실행하며 최종 pkg_output을 조작할 수 있습니다.

COMMAND 뒤의 항목은 multiple command와 다른 option을 포함해 그대로 add_custom_command()에 전달됩니다.

LLEXT Extension Development Kit (EDK)

Main Zephyr build 밖의 standalone project에서 extension을 만들 때도 main application과 같은 generated header와 compiler flag가 필요합니다. 이 항목들은 Zephyr header 해석과 extension code generation에 직접 영향을 줍니다.

Main application build artifact에서 EDK를 만들려면 llext-edk target을 실행합니다.

west build -t llext-edk

생성된 EDK는 build directory의 zephyr directory에 있습니다. Extension build에 필요한 header와 compile flag를 담은 tarball이며, standalone build system에서 이를 풀어 header와 flag를 사용할 수 있습니다.

Compile flag

EDK에는 CMake project용 cmake.cflags와 Make project용 Makefile.cflags가 들어 있습니다. 전체 extension build flag는 LLEXT_CFLAGS에 있으며 unit test mock 같은 use case를 위해 더 세분화된 변수도 제공합니다.

LLEXT_INCLUDE_CFLAGS
자동 생성되지 않은 header directory를 compiler include search path에 추가합니다.
LLEXT_GENERATED_INCLUDE_CFLAGS
Autogenerated header directory를 include search path에 추가합니다.
LLEXT_ALL_INCLUDE_CFLAGS
Build가 사용하는 모든 header directory입니다. 앞의 두 include flag를 합친 값입니다.
LLEXT_GENERATED_IMACROS_CFLAGS
-imacros로 포함해야 하는 autogenerated header flag입니다.
LLEXT_BASE_CFLAGS
Target CPU code generation을 제어하는 나머지 compiler flag입니다. 앞의 목록에는 포함되지 않습니다.
LLEXT_CFLAGS
Extension build에 필요한 모든 flag입니다. All include, generated imacros, base flag의 조합입니다.

LLEXT EDK Kconfig option

CONFIG_LLEXT_EDK_NAME
생성할 EDK tarball name입니다.
CONFIG_LLEXT_EDK_USERSPACE_ONLY
활성화하면 syscall을 kernel로 route하는 code를 포함하지 않는 header만 EDK에 넣습니다. User mode에서만 실행할 extension build에 유용합니다.

EDK Sample

LLEXT EDK 사용 예는 llext-edk code sample을 참고합니다.

Source

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.