Third-party Module Adaptation

To use third-party modules in the third_party directory, you may need to adapt the modules. This section uses mbedTLS as an example to describe how to integrate the adaptation code with the OpenHarmony compilation framework. For the principles of mbedTLS and the specific logic of the adaptation code, see the adaptation guide on the mbedTLS official website.

  1. Write the adaptation layer code.

    Write the required adaptation layer code based on the mbedTLS adaptation guide. In this example, adaptation of the hardware random number is used for illustration, and the paths are relative to third_party/mbedtls:

    1. Copy the include/mbedtls/config.h file to the ports directory, and enable MBEDTLS_ENTROPY_HARDWARE_ALT in the file.

    2. In the ports directory, create the entropy_poll_alt.c file under include and implement the hardware random number API in entropy_poll.h.

    3. Add the path of the adapted entropy_poll_alt.c file to mbedtls_sources in the BUILD.gn file.

    4. Add the line MBEDTLS_CONFIG_FILE to lite_library("mbedtls_static") in the BUILD.gn file to specify the path of the new configuration file.

      lite_library("mbedtks_static") {
        ...  
        defines += ["MBEDTLS_CONFIG_FILE=<../port/config.h>"]
        ...
      }
      

    You are advised to make the preceding modifications in a new config.h file or xxx_alt.c file. Do not directly edit the code in the original file. Intrusive modifications may cause a large number of scattered conflicts during subsequent version updates, increasing the update maintenance costs.

  2. Create a patch.

    The preceding adaptation is hardware-specific. Therefore, when uploading code to the library, you cannot directly store the code in the third_party/mbedtls directory. Instead, you need to integrate the preceding modifications into a patch and inject the patch into the code for a build.

    1. Add the patch configuration file device/<company>/<board>/patch.yml.

    2. In the device/<company>/<board>/patch.yml file, add the information about the patch to apply.

      # Path of the patch to apply. This path is relative to the code root directory.
      third_party/mbedtls:
        # Directory in which the patch is stored.
        - device/<company>/<board>/third_party/mbedtls/adapter.patch
      third_party/wpa_supplicant:
        # When there are multiple patches in a path, the patches are executed in sequence.
        - device/<company>/<board>/third_party/wpa_supplicant/xxxxx.patch
        - device/<company>/<board>/third_party/wpa_supplicant/yyyyy.patch
      ...
      
    3. Create a patch file as described in step 1 and save it to the corresponding directory.

  3. Start a build with the patch.

    Add --patch when triggering a build. The following is the command for executing a full build with a patch:

    hb build -f --patch
    

    CAUTION: The information about the product to which the patch is most recently applied will be recorded. Next time the build is performed, the previous patch is rolled back (that is, `patch -p1 -R < xxx` is executed). If the patch fails to be rolled back or a patch fails to be added, the build process is terminated. In this case, resolve the patch conflict and try again.