Porting the build system

Guide for porting the SDK's build system.

The CMake-based build system present in the SDK's GitHub repo targets desktop systems and builds libraries into shared or static libraries. The build selects the types of the platform layer based on the detected host OS and automatically configures the platform layer. See Building the SDK for more information on the build system.

In general, this SDK should build with C compilers in C99 mode. Currently, we do not guarantee builds with a C++ compiler. Compilers that provide intrinsics for atomic operations are recommended; see Atomics for more information.

Directory layout

The following directories contain the SDK's source code and are relevant for porting.

Of the directories listed below, only ports/ should be modified during porting. Empty templates of a new port are placed in ports/template. Some directories present in the GitHub repo (such as cbmc, doc, and scripts) are not relevant for porting and therefore not listed.

As relative paths from the SDK's root directory:

demos/
SDK sample applications. These files do not need to be ported, but are useful as a starting point.
- app/
  Contains demo applications for various systems, most importantly the main() functions.
- include/
  Headers only needed to build the demos. These do not need to be ported.
- src/
  Platform-independent demo sources. These do not need to be ported.
- iot_config.h
  The config header for the demo applications. Useful as an example.
libraries/
Platform-independent SDK files. This directory (and all its subdirectories) should be copied and not modified.
- aws/
  Client libraries for AWS IoT services. Individual library headers, source files, and tests are contained in directories matching the library name. All source files in the same directory should be built into a shared or static library.
  - defender/
    Defender library headers, source files and tests.
    - include
      Defender library header files.
    - src
      Defender library source files.
    - test
      Defender library tests.
  - common, jobs, shadow, ...
    Other libraries have the same directory structure as the Defender library described above.
- platform/
  Interface of the platform layer, to be implemented in the ports/ directory.
  - types/
    Platform types header.
- standard
  Libraries which are not specific to AWS IoT services. Headers, source files, and tests are contained in directories matching the library name. All source files in the same directory should be built into a shared or static library.
  - common, mqtt, serializer, ...
    These libraries have the same directory structure as the Defender library described above.
ports/
This directory contains the desktop OS ports. Each port implements the functions of the platform layer interface for a specific desktop OS.
- common
  Port files that are not specific to a single port. These headers are used across all of the desktop OS ports.
  - include/
    Port headers that are not specific to a single port, such as the atomic and network headers.
    - atomic/
      Implementations of atomic operations. See Atomics for how to create a new port. New atomic ports should be placed here.
  - src/
    Port sources that are not specific to a single port, such as the network implementations.
- template
  Empty port sources containing stubbed-out functions. The files in this directory may be used as a starting point for a new port.
- posix, ...
  Port sources and headers for a single implementation. The directory is named after the target OS.
tests/
SDK test config file and test runner source. Individual library tests are in each library directory. When building tests, IOT_BUILD_TESTS should be set to 1 globally.
third_party/
Third-party library code. This directory (and all its subdirectories) should be copied and not modified.
- mbedtls/
  mbed TLS, consumed as a Git submodule.
- tinycbor/
  Intel's TinyCBOR, consumed as a Git submodule.
- unity/
  Unity test framework. Modifications were made to make its malloc overrides thread-safe.

Include paths

The following paths should be passed as include paths to the compiler when building this SDK.

SDK include paths that are always required:

The path of the config file, iot_config.h. For example:
- In the SDK demos, iot_config.h is in demos/.
- In the SDK tests, iot_config.h is in tests/.
The path of the port types file. For example, ports/posix/include when using the POSIX port.
libraries/platform/

Each library has its headers in a different include directory. Library include directories are in libraries/aws for AWS IoT client libraries, and libraries/standard for other libraries. For example, the MQTT library's include directory is libraries/standard/mqtt/include/ and the AWS IoT Shadow library's include directory is libraries/aws/shadow/include/. Each library's include directory must be added to the include path if that library is being used.

Third-party submodule include paths:

TinyCBOR: third_party/tinycbor/tinycbor/src
Required when building the serializer library and for the Defender tests.
mbed TLS: third_party/mbedtls and third_party/mbedtls/mbedtls/include
Required when building Networking with the mbed TLS implementation.

Additional include paths required to build the demos:

demos/include

Additional include paths required to build the tests:

third_party/unity/unity
third_party/unity/unity/fixture
libraries/standard/mqtt/test/access (when building the MQTT or Shadow tests)
libraries/standard/mqtt/test/mock (when building tests that use the MQTT mocks, such as Shadow or Jobs)

In addition to the tests include paths, IOT_BUILD_TESTS should be set to 1 globally when building tests.

Config header

Settings that must be set in the config header, iot_config.h

See also: Global configuration
In addition, each library has its own configuration settings.

At the very least, the config header must contain the following defines:

Memory allocation functions must be set in the config header. See IotDefault_Malloc and Iot_DefaultFree for more details.
Assert functions must be set if asserts are enabled for a library. See Iot_DefaultAssert for more details.

The platform types must also be set. See Porting the platform layer for more details.

Porting the platform layer

Guide for porting the SDK's platform layer.

See also: Platform layer

Platform types

Types that must be set in the platform layer.

See also: Platform types for a list of all types that must be set.
ports/posix/include/iot_platform_types_posix.h for an example of setting the types on POSIX systems.

The platform types should be set in the config file, iot_config.h, or in another header included by the config file. As an example, the header iot_platform_types_posix.h sets the platform types to the matching POSIX system types. This header is then included in iot_config.h by the provided CMake build system.

Attention: Any type configuration headers included by the config file must never include other SDK files. Since this file will be included by every SDK source file, take care not to include too many unnecessary symbols.

Platform functions

Functions that must be implemented for the platform layer.

See also: Platform functions for a list of all functions that must be implemented.
libraries/platform for the interfaces of the platform functions.
ports/posix/src for examples of functions implemented for POSIX systems.