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 asconfig.XXX.YYY
, where theXXX
section corresponds to the HAL code of thesrc/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
- The path of the cross compiler
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 theHAL_*()
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
$ sudo apt-get install -y gcc-arm-linux-gnueabihf
$ arm-linux-gnueabihf-gcc --version
arm-linux-gnueabihf-gcc (Ubuntu/Linaro 5.4.0-6ubuntu1~16.04.9) 5.4.0 20160609
Copyright (C) 2015 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Add a configuration file
$ touch src/board/config.arm-linux.demo
$ ls src/board/
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.
$ vim src/board/config.arm-linux.demo
CONFIG_ENV_CFLAGS = \
-D_PLATFORM_IS_LINUX_ \
-Wall
OVERRIDE_CC = arm-linux-gnueabihf-gcc
OVERRIDE_AR = arm-linux-gnueabihf-ar
OVERRIDE_LD = arm-linux-gnueabihf-ld
CONFIG_src/ref-impl/hal :=
CONFIG_examples :=
CONFIG_tests :=
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
- $ make reconfig
- SELECT A CONFIGURATION:
- 1) config.arm-linux.demo 3) config.rhino.make 5) config.win7.mingw32
- 2) config.macos.make 4) config.ubuntu.x86
- #? 1
- SELECTED CONFIGURATION:
- VENDOR: arm-linux
- MODEL: demo
- CONFIGURE .............................. [examples]
- CONFIGURE .............................. [src/infra/log]
- CONFIGURE .............................. [src/infra/system]
- CONFIGURE .............................. [src/infra/utils]
- CONFIGURE .............................. [src/protocol/alcs]
- CONFIGURE .............................. [src/protocol/coap]
- CONFIGURE .............................. [src/protocol/http]
- CONFIGURE .............................. [src/protocol/http2]
- CONFIGURE .............................. [src/protocol/mqtt]
- CONFIGURE .............................. [src/ref-impl/hal]
- CONFIGURE .............................. [src/ref-impl/tls]
- 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.
$ make
BUILDING WITH EXISTING CONFIGURATION:
VENDOR : arm-linux
MODEL : demo
[CC] guider.o <= ...
[CC] utils_epoch_time.o <= ...
[CC] iotx_log.o <= ...
[CC] lite_queue.o <= ...
...
...
[AR] libiot_sdk.a <= ...
[AR] libiot_tls.a <= ...
Get cross-compiled products, including static libraries and header files
$ ls -1 output/release/lib/
libiot_sdk.a
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.
$ ls -1 output/release/include/
exports
imports
iot_export.h
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 toXXX
insrc/board/confg.XXX.YYY
to store the HAL implementation.
$ cd src/ref-impl/hal/os/
$ ls
macos ubuntu win7
src/ref-impl/hal/os$ cp -rf ubuntu arm-linux
src/ref-impl/hal/os$ ls
arm-linux macos ubuntu win7
src/ref-impl/hal/os$ tree -A arm-linux/
arm-linux/
+-- base64.c
+-- base64.h
+-- cJSON.c
+-- cJSON.h
+-- HAL_Crypt_Linux.c
+-- HAL_OS_linux.c
+-- HAL_TCP_linux.c
+-- HAL_UDP_linux.c
+-- kv.c
+-- kv.h
To enable the options which were disabled before
$ vim src/board/config.arm-linux.demo
CONFIG_ENV_CFLAGS = \
-D_PLATFORM_IS_LINUX_ \
-Wall
OVERRIDE_CC = arm-linux-gnueabihf-gcc
OVERRIDE_AR = arm-linux-gnueabihf-ar
OVERRIDE_LD = arm-linux-gnueabihf-ld
# CONFIG_src/ref-impl/hal :=
CONFIG_examples :=
CONFIG_tests :=
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
$ make reconfig
SELECT A CONFIGURATION:
1) config.arm-linux.demo 3) config.rhino.make 5) config.win7.mingw32
2) config.macos.make 4) config.ubuntu.x86
#? 1
SELECTED CONFIGURATION:
VENDOR : arm-linux
MODEL : demo
...
...
$ make
[CC] utils_md5.o <= ...
[CC] utils_event.o <= ...
[CC] string_utils.o <= ...
...
...
[AR] libiot_sdk.a <= ...
[AR] libiot_hal.a <= ...
[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.
$ vi src/board/config.arm-linux.demo
CONFIG_ENV_CFLAGS = \
-D_PLATFORM_IS_LINUX_ \
-Wall
CONFIG_ENV_LDFLAGS = \
-lpthread -lrt
OVERRIDE_CC = arm-linux-gnueabihf-gcc
OVERRIDE_AR = arm-linux-gnueabihf-ar
OVERRIDE_LD = arm-linux-gnueabihf-ld
# CONFIG_src/ref-impl/hal :=
# CONFIG_examples :=
CONFIG_tests :=
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:
CONFIG_ENV_LDFLAGS = \
-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
- $ make reconfig
- SELECT A CONFIGURATION:
- 1) config.arm-linux.demo 3) config.rhino.make 5) config.win7.mingw32
- 2) config.macos.make 4) config.ubuntu.x86
- #? 1
- SELECTED CONFIGURATION:
- VENDOR: arm-linux
- MODEL: demo
- ...
Note: To compile the sample programs, you need to use the
make all
command instead of the
make
command to compile the products. For example:
$ make all
BUILDING WITH EXISTING CONFIGURATION:
VENDOR : arm-linux
MODEL : demo
[CC] base64.o <= base64.c
[CC] cJSON.o <= cJSON.c
[CC] HAL_UDP_linux.o <= HAL_UDP_linux.c
...
...
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.
[LD] mqtt_rrpc-example <= mqtt_rrpc-example.o
[LD] uota_app-example <= uota_app-example.o
[LD] http-example <= http-example.o
[LD] mqtt-example <= mqtt-example.o
[LD] mqtt_multi_thread-example <= mqtt_multi_thread-example.o
[LD] ota-example-mqtt <= ota-example-mqtt.o
[LD] linkkit-example-sched <= linkkit_example_sched.o
[LD] linkkit-example-solo <= linkkit_example_solo.o
$ cd output/release/bin/
$ ls
http-example linkkit-example-sched linkkit-example-solo mqtt-example mqtt_multi_thread-example mqtt_rrpc-example ota-example-mqtt uota_app-example
$ file *
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, ...
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, ...
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, ...
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, ...
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, ...
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, ...
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, ...
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 thesrc/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 theUbuntu
host section, it might not work forarm-linux.
Repeat these steps until you are confident there are no issues with libiot_hal.a
.