/**
@page guide_developer_porting Porting Guide
@brief Guide for porting this SDK to a new platform.

This SDK has three components that must be ported to a new system:
1. [The build system](@ref guide_developer_porting_build)
2. [The config header](@ref guide_developer_config)
3. [The platform layer](@ref guide_developer_porting_platform)

@section guide_developer_porting_build Porting the build system
@brief Guide for porting the SDK's build system.

The CMake-based build system present in [the SDK's GitHub repo](https://github.com/aws/aws-iot-device-sdk-embedded-C) targets desktop systems and builds libraries into shared or static libraries. The build selects the [types of the platform layer](@ref platform_datatypes_handles) based on the detected host OS and automatically configures the platform layer. See @ref building 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 @ref platform_atomic for more information.

@subsection guide_developer_porting_directory_layout Directory layout
@brief The following directories contain the SDK's source code and are relevant for porting.

Of the directories listed below, only <b style="color:#ff0000">`ports/`</b> 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/` <br>
  SDK sample applications. These files do not need to be ported, but are useful as a starting point.
    - `app/` <br>
      Contains demo applications for various systems, most importantly the `main()` functions.
    - `include/` <br>
      Headers only needed to build the demos. These do not need to be ported.
    - `src/` <br>
      Platform-independent demo sources. These do not need to be ported.
    - `iot_config.h` <br>
      The config header for the demo applications. Useful as an example.
- `libraries/` <br>
  Platform-independent SDK files. This directory (and all its subdirectories) should be copied and not modified.
    - `aws/` <br>
      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/` <br>
          Defender library headers, source files and tests.
            - `include` <br>
              Defender library header files.
            - `src` <br>
              Defender library source files.
            - `test` <br>
              Defender library tests.
        - `common, jobs, shadow, ...` <br>
          Other libraries have the same directory structure as the Defender library described above.
    - <b>`platform/` <br>
      Interface of the platform layer, to be implemented in the `ports/` directory. </b>
        - `types/` <br>
          Platform types header.
    - `standard` <br>
      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, ...` <br>
          These libraries have the same directory structure as the Defender library described above.
- <b style="color:#ff0000">`ports/` <br>
  This directory contains the desktop OS ports. Each port implements the functions of the platform layer interface for a specific desktop OS. </b>
    - `common` <br>
      Port files that are not specific to a single port. These headers are used across all of the desktop OS ports.
        - `include/` <br>
          Port headers that are not specific to a single port, such as the atomic and network headers.
            - <b style="color:#ff0000">`atomic/` <br>
              Implementations of atomic operations. See @ref platform_atomic for how to create a new port. New atomic ports should be placed here. </b>
        - `src/` <br>
          Port sources that are not specific to a single port, such as the network implementations.
    - <b style="color:#ff0000">`template` <br>
      Empty port sources containing stubbed-out functions. The files in this directory may be used as a starting point for a new port.</b>
    - <b style="color:#ff0000">`posix, ...` <br>
      Port sources and headers for a single implementation. The directory is named after the target OS.</b>
- `tests/` <br>
  SDK test config file and test runner source. Individual library tests are in each library directory. When building tests, @ref IOT_BUILD_TESTS should be set to `1` globally.
- `third_party/` <br>
  Third-party library code. This directory (and all its subdirectories) should be copied and not modified.
    - `mbedtls/` <br>
      [mbed TLS](https://github.com/ARMmbed/mbedtls/tree/mbedtls-2.17), consumed as a Git submodule.
    - `tinycbor/` <br>
      [Intel's TinyCBOR](https://github.com/intel/tinycbor), consumed as a Git submodule.
    - `unity/` <br>
      [Unity test framework](https://github.com/ThrowTheSwitch/Unity). Modifications were made to make its `malloc` overrides thread-safe.

@subsection guide_developer_porting_include_paths Include paths
@brief 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](@ref global_config), `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` <br>
  Required when building the serializer library and for the Defender tests.
- mbed TLS: `third_party/mbedtls` and `third_party/mbedtls/mbedtls/include` <br>
  Required when building @ref platform_network 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, @ref IOT_BUILD_TESTS should be set to `1` globally when building tests.

@section guide_developer_config Config header
@brief Settings that must be set in the config header, iot_config.h

@see [Global configuration](@ref global_config)<br>
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 @ref Iot_DefaultMalloc for more details.
 - Assert functions must be set if asserts are enabled for a library. See @ref Iot_DefaultAssert for more details.

The platform types must also be set. See @ref guide_developer_porting_platform for more details.

@section guide_developer_porting_platform Porting the platform layer
@brief Guide for porting the SDK's [platform layer](@ref platform).

@see [Platform layer](@ref platform)

@subsection guide_developer_porting_platform_types Platform types
@brief [Types](@ref platform_datatypes_handles) that must be set in the platform layer.

@see [Platform types](@ref platform_datatypes_handles) for a list of all types that must be set. <br>
`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](@ref global_config), `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.

@subsection guide_developer_porting_platform_functions Platform functions
@brief [Functions](@ref platform_functions) that must be implemented for the platform layer.

@see [Platform functions](@ref platform_functions) for a list of all functions that must be implemented. <br>
`libraries/platform` for the interfaces of the platform functions. <br>
`ports/posix/src` for examples of functions implemented for POSIX systems.
*/
