/**
@page building Building the SDK
@brief Guide for building the SDK.

This SDK builds with [CMake](https://cmake.org/), a cross-platform build tool.

@pre
- CMake version 3.5.0 or later and a C99 compiler.

@pre
- A supported operating system. The ports provided with this repo are expected to work with all recent versions of the following operating systems, although we cannot guarantee the behavior on all systems. For reference, the version used by this repo's Travis CI builds are listed in parentheses.
    - Linux system with POSIX thread and timer APIs. (CI tests on Ubuntu 16.04).<br>
    On Linux systems, the OpenSSL network implementation may be used instead of the default network implementation based on mbed TLS. This requires the installation of OpenSSL development libraries and header files, version 1.0.2g or later. The OpenSSL development libraries are usually called something like `libssl-dev` or `openssl-devel` when installed through a package manager.

This SDK uses third-party libraries as Git submodules in the `third_party` directory. If the source code was downloaded via `git clone`, nothing further needs to be done. The CMake build system can automatically clone submodules in this case. However, for any other download, the submodules must be downloaded and placed in their respective `third_party` directory.
- [mbed TLS](https://github.com/ARMmbed/mbedtls/tree/mbedtls-2.17) → `third_party/mbedtls/mbedtls`
- [tinyCBOR](https://github.com/intel/tinycbor) → `third_party/tinycbor/tinycbor`

In addition, credentials and Things for AWS IoT must be provisioned before running the demos. See [this page](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html) for a tutorial on setting up AWS IoT.

@section building_configuration Build system configuration
@brief Configuration of the CMake build system.

The following options may be passed to the CMake build system to modify the build. Options are passed with `-D` on the command line, or selected through [CMake GUI](https://cmake.org/cmake/help/v3.0/manual/cmake-gui.1.html). If an option is not set, the default value will be used.
- [BUILD_SHARED_LIBS](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html) <br>
  <i>Default:</i> `ON` <br>
  Set this to `ON` to build all libraries as shared libraries. When `OFF`, libraries build as static libraries.
- <b>`IOT_ATOMIC_USE_PORT`</b> <br>
  <i>Default:</i> `OFF` <br>
  Set this to `ON` to use a custom atomic port. When `OFF`, the build system will choose an atomic port. This option also sets the preprocessor setting @ref IOT_ATOMIC_USE_PORT.
- <b>`IOT_BUILD_CLONE_SUBMODULES`</b> <br>
  <i>Default:</i> `OFF` <br>
  Set this to `ON` to automatically clone any required Git submodules. When `OFF`, submodules must be manually cloned.
- <b>`IOT_BUILD_TESTS`</b> <br>
  <i>Default:</i> `OFF` <br>
  Set this to `ON` to build both demo and test executables. When `OFF`, only demo executables are built. If enabled, both demos and tests will use the settings defined in `tests/iot_config.h`.
- <b>`IOT_NETWORK_USE_OPENSSL` [Linux only]</b> <br>
  <i>Default:</i> `OFF` <br>
  Set this to `ON` to use a network implementation based on OpenSSL instead of the default mbed TLS network implementation. If this is set to `ON`, OpenSSL development libraries and headers must be installed.

@section building_demo Building the demo applications
@brief How to build the demo applications.

Before building the demos, all desired configuration settings should be defined. Configuration settings include global [library](@ref global_library_config) and [demo](@ref global_demos_config) settings, as well as settings for specific libraries and demos. Settings for demo applications should be placed in `demos/iot_config.h`. Any undefined settings will use a default value when possible.

@subsection building_demo_commmandline Command-line build
@brief How to build the demo applications on the command-line.

In-source CMake builds are not allowed. A build directory should be created under the SDK root directory. Since CMake is cross-platform, build steps will vary depending on host OS. On Linux, the demo applications are built as follows:
@code{sh}
# Create build directory and change to build directory.
mkdir build
cd build

# Configure build using CMake.
cmake ..

# Build the demo applications.
make
@endcode

Demo application executables will be placed in a `output/bin` directory of the CMake build directory, i.e. `build/output/bin` in the example above. The executables will be named `aws_iot_demo_library` or `iot_demo_library`, depending on whether the demo is specific to AWS IoT. For example, the MQTT demo application, which may be used with any MQTT server, will be named `iot_demo_mqtt`. The Thing Shadow demo, which is specific to AWS IoT, will be named `aws_iot_demo_shadow`.

Configuration settings may also be set using CMake by setting `CMAKE_C_FLAGS`. However, placing configuration settings in `demos/iot_demo_config.h` is recommended over setting them using CMake.
@code{sh}
# Example: Set IOT_STATIC_MEMORY_ONLY using CMake
cmake .. -DCMAKE_C_FLAGS=-DIOT_STATIC_MEMORY_ONLY=1
@endcode

By default, CMake may build in `Release` configuration. To enable debugging symbols, set `CMAKE_BUILD_TYPE` to `Debug`.
@code{sh}
cmake .. -DCMAKE_BUILD_TYPE=Debug
@endcode

Delete the build directory to remove all demo application executables and build files.

@subsection building_demo_gui CMake GUI build
@brief How to build the demo applications with CMake GUI.

Alternatively, CMake GUI may be used instead of the command line. Specify the SDK's root directory in <b>Where is the source code</b> and a build directory in <b>Where to build the binaries</b>. Click <b>Configure</b>, then <b>Generate</b>. You may modify @ref building_configuration in the CMake GUI window.

@section demo_commandlineoptions Demo command line options
@brief Command line options of the demo applications.

Demo applications accept the following command line options.

@subsection demo_optionn -n
@brief Disable AWS IoT MQTT mode.

By default, the demo applications expect to run with an AWS IoT MQTT server. Passing this option disables [AWS IoT MQTT mode](@ref IotMqttConnectInfo_t.awsIotMqttMode) and treats the remote MQTT server as a fully-compliant MQTT server. This option should not have an argument.

Because Thing Shadows are specific to AWS IoT, this option is ignored by the [Shadow demo](@ref shadow_demo).

@subsection demo_optionsu -s and -u
@brief Secured or unsecured demo connection, respectively.

Neither `-s` nor `-u` should have an argument, and only one of the two should be used at a time.

See @ref IOT_DEMO_SECURED_CONNECTION for the compile-time default setting of this option.

Because Thing Shadows are specific to AWS IoT (which requires secured connections), this option is ignored by the [Shadow demo](@ref shadow_demo).

@subsection demo_optionh -h host
@brief Remote host for demo application.

Must be followed by a host name.

See @ref IOT_DEMO_SERVER for the compile-time default setting of this option.

@subsection demo_optionp -p port
@brief Remote port for demo application.

Must be followed by a port in the range of `[1,65535]`.

See @ref IOT_DEMO_PORT for the compile-time default setting of this option.

@subsection demo_optionr -r rootCA, -c clientCert, -k privateKey
@brief Paths to trusted server root certificate, client certificate, and client certificate private key, respectively.

Must be followed by a filesystem path to the respective PEM-encoded credential.

See @ref IOT_DEMO_ROOT_CA, @ref IOT_DEMO_CLIENT_CERT, and @ref IOT_DEMO_PRIVATE_KEY for the compile-time default settings of these options.

@subsection demo_optioni -i identifier
@brief MQTT client identifier <i>OR</i> Thing Name.

Must be followed by a string representing either an MQTT client identifier (MQTT demo only) or a Thing Name (all other demos). Because AWS IoT recommends that MQTT client identifier and Thing Name match, demos will use the Thing Name as the MQTT client identifier when possible.

See @ref IOT_DEMO_IDENTIFIER for the compile-time default settings of this option.

@section building_tests Building and running the tests
@brief How to build and run the SDK tests.

Like the demo applications, the tests also build with CMake. [Global test configuration settings](@ref global_tests_config), as well as specific library test settings, should be defined in `tests/iot_config.h`. They are built by passing the option `IOT_BUILD_TESTS=1` to CMake. Note that enabling this option means that <b>both</b> demos and tests will use the settings defined in `tests/iot_config.h`. If distinct configurations for demos and tests are desired, they can be built in separate build directories.

@code{sh}
# Create build directory and change to build directory.
mkdir build
cd build

# Configure build using CMake.
cmake .. -DIOT_BUILD_TESTS=1

# Build both the demos and tests.
make
@endcode

The `IOT_BUILD_TESTS` option can also be set by a checkbox in CMake GUI.

Test executables will be placed in a `output/bin` directory of the CMake build directory (i.e. `build/output/bin`) alongside the demo applications. They will be named `aws_iot_tests_library` or `iot_tests_library`, depending on whether the tests are specific to AWS IoT. For example, the MQTT tests application, which may be used with any MQTT server, will be named `iot_tests_mqtt`. The Thing Shadow tests, which are specific to AWS IoT, will be named `aws_iot_tests_shadow`.

By default, running a test executable with no command line arguments will only run the basic unit tests and system tests. This run is expected to take up to a few minutes per library test. The command line option `-l` may be passed to a test executable to enable long-running tests (such as stress tests) which may run for several hours. The command line option `-n` may be passed to the test executable to disable tests that require network connectivity.
*/
