All Products
Search
Document Center

:Cross Building

Last Updated:Jan 26, 2019

In this chapter, a complete cross-building process is shown by compiling the SDK on arm-Linux platform as an example.

Cross-compiling to embedded hardware platform

For embedded hardware platforms, to compile libiot_sdk.a for the target platform, you need to take the following steps:

  • Add a corresponding configuration file in the src/board/directory. The file name is specified as config.XXX.YYY, where the XXX section corresponds to the HAL code of the src/ref-impl/hal/os/XXX directory.

  • In the configuration file, you need to specify at least:

    • The path of the cross compiler OVERRIDE_CC
    • The path of the cross linker OVERRIDE_LD
    • The path of the static library compressor OVERRIDE_AR
    • Compilation option CONFIG_ENV_CFLAGS, used to compile C files
    • Link option CONFIG_ENV_LDFLAGS, used to link the runnable programs
  • Try to compile the SDK and fix possible cross-platform issues until the target format of libiot_sdk.a is successfully generated

  • Finally, you need to build the libiot_hal.a for the target schema by using your preferred compilation method

  • If the target platform has not been adapted, then the corresponding source code of libiot_hal.a is not included in C-SDK. In this case, you need to implement the HAL_*() interface yourself.


The following example is of an arm-Linux target platform that has not been officially adapted. We will use it to demonstrate how to compile a libiot_sdk.a for the platform.

Install cross-compilation tool chain

Still use the Ubuntu16.04 development environment as an example

  1. $ sudo apt-get install -y gcc-arm-linux-gnueabihf
  2. $ arm-linux-gnueabihf-gcc --version
  3. arm-linux-gnueabihf-gcc (Ubuntu/Linaro 5.4.0-6ubuntu1~16.04.9) 5.4.0 20160609
  4. Copyright (C) 2015 Free Software Foundation, Inc.
  5. This is free software; see the source for copying conditions. There is NO
  6. warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Add a configuration file

  1. $ touch src/board/config.arm-linux.demo
  2. $ ls src/board/
  3. config.arm-linux.demo config.macos.make config.rhino.make config.ubuntu.x86 config.win7.mingw32

Edit the configuration file

In this step, you need to set the compilation options and tool chains, as well as the directories to skip in compilation.

  1. $ vim src/board/config.arm-linux.demo
  2. CONFIG_ENV_CFLAGS = \
  3. -D_PLATFORM_IS_LINUX_ \
  4. -Wall
  5. OVERRIDE_CC = arm-linux-gnueabihf-gcc
  6. OVERRIDE_AR = arm-linux-gnueabihf-ar
  7. OVERRIDE_LD = arm-linux-gnueabihf-ld
  8. CONFIG_src/ref-impl/hal :=
  9. CONFIG_examples :=
  10. CONFIG_tests :=
  11. CONFIG_src/tools/linkkit_tsl_convert :=

Note that the preceding four lines indicate which directories to skip in the compilation: “src/ref-impl/hal”, “examples”, “tests”, “src/tools/linkkit_tsl_convert”

You need to start by compiling libraries that have not been adapted to the platform in order to avoid making too many mistakes.

Select a configuration file

  1. $ make reconfig
  2. SELECT A CONFIGURATION:
  3.  
  4. 1) config.arm-linux.demo 3) config.rhino.make 5) config.win7.mingw32
  5. 2) config.macos.make 4) config.ubuntu.x86
  6. #? 1
  7.  
  8. SELECTED CONFIGURATION:
  9.  
  10. VENDOR: arm-linux
  11. MODEL: demo
  12.  
  13. CONFIGURE .............................. [examples]
  14. CONFIGURE .............................. [src/infra/log]
  15. CONFIGURE .............................. [src/infra/system]
  16. CONFIGURE .............................. [src/infra/utils]
  17. CONFIGURE .............................. [src/protocol/alcs]
  18. CONFIGURE .............................. [src/protocol/coap]
  19. CONFIGURE .............................. [src/protocol/http]
  20. CONFIGURE .............................. [src/protocol/http2]
  21. CONFIGURE .............................. [src/protocol/mqtt]
  22. CONFIGURE .............................. [src/ref-impl/hal]
  23. CONFIGURE .............................. [src/ref-impl/tls]
  24. CONFIGURE .............................. [src/sdk-impl]

Cross-compile to generate library file libiot_sdk.a

Note: This step does not compile HAL. The purpose of this step is to verify that the cross-compilation parameters in the configuration file are correct. If an error occurs, please continue to modify the configuration file until the compilation is successful.

  1. $ make
  2. BUILDING WITH EXISTING CONFIGURATION:
  3. VENDOR : arm-linux
  4. MODEL : demo
  5. [CC] guider.o <= ...
  6. [CC] utils_epoch_time.o <= ...
  7. [CC] iotx_log.o <= ...
  8. [CC] lite_queue.o <= ...
  9. ...
  10. ...
  11. [AR] libiot_sdk.a <= ...
  12. [AR] libiot_tls.a <= ...

Get cross-compiled products, including static libraries and header files

  1. $ ls -1 output/release/lib/
  2. libiot_sdk.a
  3. libiot_tls.a

Here, the libiot_sdk.a file is the compiled IoT Kit SDK, which is already in the ELF 32-bit LSB relocatable, ARM, EABI5 version 1 (SYSV) format, and is the cross-compilation format of the arm-Linux format.

In addition, libiot_tls.a is a trimmed encryption and decryption library. You can choose to use this library, or you can use the encryption and decryption library built into the platform to reduce the final size of the firmware.

  1. $ ls -1 output/release/include/
  2. exports
  3. imports
  4. iot_export.h
  5. iot_import.h

Here, in order to use SDK, you need to include the iot_import.h and iot_export.h header files. They contain different sub-files by function point, listed in the imports/ directory and theexports/ directory respectively

Develop HAL that is not adapted for the platform

Do not restrict how the library libiot_hal.a that implements the platform abstraction layer interface HAL_XXX_YYY()is compiled and generated.

However, if you like, you can still develop and generate this library by using the IoT suite compiler for the device-side C-SDK.


We can use the arm-Linux target platform from the preceding section as an example. Assuming that the difference between the platform and Ubuntu is very small, and you can use HAL code developed and tested on Ubuntu as the basis for your development, then you can do the following:

Make a copy of the HAL implementation code

Note: Under src/ref-impl/hal/os, you need to create a directory that is similar to XXX in src/board/confg.XXX.YYY to store the HAL implementation.

  1. $ cd src/ref-impl/hal/os/
  2. $ ls
  3. macos ubuntu win7
  4. src/ref-impl/hal/os$ cp -rf ubuntu arm-linux
  5. src/ref-impl/hal/os$ ls
  6. arm-linux macos ubuntu win7
  7. src/ref-impl/hal/os$ tree -A arm-linux/
  8. arm-linux/
  9. +-- base64.c
  10. +-- base64.h
  11. +-- cJSON.c
  12. +-- cJSON.h
  13. +-- HAL_Crypt_Linux.c
  14. +-- HAL_OS_linux.c
  15. +-- HAL_TCP_linux.c
  16. +-- HAL_UDP_linux.c
  17. +-- kv.c
  18. +-- kv.h

To enable the options which were disabled before

  1. $ vim src/board/config.arm-linux.demo
  2. CONFIG_ENV_CFLAGS = \
  3. -D_PLATFORM_IS_LINUX_ \
  4. -Wall
  5. OVERRIDE_CC = arm-linux-gnueabihf-gcc
  6. OVERRIDE_AR = arm-linux-gnueabihf-ar
  7. OVERRIDE_LD = arm-linux-gnueabihf-ld
  8. # CONFIG_src/ref-impl/hal :=
  9. CONFIG_examples :=
  10. CONFIG_tests :=
  11. CONFIG_src/tools/linkkit_tsl_convert :=

You can see that a # symbol was added before the CONFIG_src/ref-impl/hal := line. This indicates that the line is commented out and src/ref-impl/hal will enter the compilation process.

Attempt to cross-compile the copied HAL code

  1. $ make reconfig
  2. SELECT A CONFIGURATION:
  3. 1) config.arm-linux.demo 3) config.rhino.make 5) config.win7.mingw32
  4. 2) config.macos.make 4) config.ubuntu.x86
  5. #? 1
  6. SELECTED CONFIGURATION:
  7. VENDOR : arm-linux
  8. MODEL : demo
  9. ...
  10. ...
  11. $ make
  12. [CC] utils_md5.o <= ...
  13. [CC] utils_event.o <= ...
  14. [CC] string_utils.o <= ...
  15. ...
  16. ...
  17. [AR] libiot_sdk.a <= ...
  18. [AR] libiot_hal.a <= ...
  19. [AR] libiot_tls.a <= ...

You can see that we are progressing quite well, we have complied the copied code src/ref-impl/hal/os/arm-linux/*.c and we have generatedlibiot_hal.a in the arm-Linux<> format.`

Allow the cross-compilation of sample programs

Now that we have libiot_hal.a, libiot_tls.a, and libiot_sdk.a, you can try to cross-compile the sample and run it on the target embedded hardware.

The method is the same as in the previous step. Turn on the CONFIG_example switch in the config.arm-linux.demo to compile the sample source code in the examples/ directory.

  1. $ vi src/board/config.arm-linux.demo
  2. CONFIG_ENV_CFLAGS = \
  3. -D_PLATFORM_IS_LINUX_ \
  4. -Wall
  5. CONFIG_ENV_LDFLAGS = \
  6. -lpthread -lrt
  7. OVERRIDE_CC = arm-linux-gnueabihf-gcc
  8. OVERRIDE_AR = arm-linux-gnueabihf-ar
  9. OVERRIDE_LD = arm-linux-gnueabihf-ld
  10. # CONFIG_src/ref-impl/hal :=
  11. # CONFIG_examples :=
  12. CONFIG_tests :=
  13. CONFIG_src/tools/linkkit_tsl_convert :=

You can see that a # symbol was added before the CONFIG_examples = line. This indicate that the line is commented out and the examples/ directory (which is the example runnable) goes into the compilation scope.

Another change that requires attention is the addition of:

  1. CONFIG_ENV_LDFLAGS = \
  2. -lpthread -lrt

This is because these sample programs are created not only to link libiot_hal.a and libiot_hal.a, but also to connect the libtthread library and the librt library.

Reload configuration file, cross-compile runnables

  1. $ make reconfig
  2. SELECT A CONFIGURATION:
  3.  
  4. 1) config.arm-linux.demo 3) config.rhino.make 5) config.win7.mingw32
  5. 2) config.macos.make 4) config.ubuntu.x86
  6. #? 1
  7.  
  8. SELECTED CONFIGURATION:
  9.  
  10. VENDOR: arm-linux
  11. MODEL: demo
  12. ...

Note: To compile the sample programs, you need to use the

  1. make all

command instead of the

  1. make

command to compile the products. For example:

  1. $ make all
  2. BUILDING WITH EXISTING CONFIGURATION:
  3. VENDOR : arm-linux
  4. MODEL : demo
  5. [CC] base64.o <= base64.c
  6. [CC] cJSON.o <= cJSON.c
  7. [CC] HAL_UDP_linux.o <= HAL_UDP_linux.c
  8. ...
  9. ...

If the compilation output is as follows, it means that a series of sample programs (for example, mqtt-example) has been successfully compiled. They are stored in the output/release/bin directory.

  1. [LD] mqtt_rrpc-example <= mqtt_rrpc-example.o
  2. [LD] uota_app-example <= uota_app-example.o
  3. [LD] http-example <= http-example.o
  4. [LD] mqtt-example <= mqtt-example.o
  5. [LD] mqtt_multi_thread-example <= mqtt_multi_thread-example.o
  6. [LD] ota-example-mqtt <= ota-example-mqtt.o
  7. [LD] linkkit-example-sched <= linkkit_example_sched.o
  8. [LD] linkkit-example-solo <= linkkit_example_solo.o
  9. $ cd output/release/bin/
  10. $ ls
  11. http-example linkkit-example-sched linkkit-example-solo mqtt-example mqtt_multi_thread-example mqtt_rrpc-example ota-example-mqtt uota_app-example
  12. $ file *
  13. http-example: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, for GNU/Linux 3.2.0, ...
  14. linkkit-example-sched: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, for GNU/Linux 3.2.0, ...
  15. linkkit-example-solo: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, for GNU/Linux 3.2.0, ...
  16. mqtt-example: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, for GNU/Linux 3.2.0, ...
  17. mqtt_multi_thread-example: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so. For GNU/Linux 3.2.0, ...
  18. mqtt_rrpc-example: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, for GNU/Linux 3.2.0, ...
  19. ota-example-mqtt: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, for GNU/Linux 3.2.0, ...
  20. uota_app-example: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, for GNU/Linux 3.2.0, ...

This can be verified with the file command. These runnable programs are also cross-compiled to the arm-Linux architecture.

Try to run the sample program

Next, you can use SCP, TFTP, or other methods to copy and download sample programs (for example, mqtt-example) to your target demoboard for debugging.

  • If the sample program and the same routine work equally well on Ubuntu, then the HAL code of the src/ref-impl/hal/os/arm-linux section is working correctly.
  • If the sample program and the same routine work differently on Ubuntu, then you need to modify the debugging HAL implementation again.
  • That is the HAL code of the src/ref-impl/hal/os/arm-linux directory. Because we copy the code from the Ubuntu host section, it might not work for arm-linux.

Repeat these steps until you are confident there are no issues with libiot_hal.a.