AWS IoT Device SDK C: Main
Return to main page ↑
Building the SDK

Guide for building the SDK.

This SDK builds with CMake, a cross-platform build tool.

Precondition
  • CMake version 3.5.0 or later and a C99 compiler.
  • 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).
      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 → third_party/mbedtls/mbedtls
  • tinyCBOR → third_party/tinycbor/tinycbor

In addition, credentials and Things for AWS IoT must be provisioned before running the demos. See this page for a tutorial on setting up AWS IoT.

Build system configuration

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. If an option is not set, the default value will be used.

  • BUILD_SHARED_LIBS
    Default: ON
    Set this to ON to build all libraries as shared libraries. When OFF, libraries build as static libraries.
  • IOT_ATOMIC_USE_PORT
    Default: OFF
    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 IOT_ATOMIC_USE_PORT.
  • IOT_BUILD_CLONE_SUBMODULES
    Default: OFF
    Set this to ON to automatically clone any required Git submodules. When OFF, submodules must be manually cloned.
  • IOT_BUILD_TESTS
    Default: OFF
    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.
  • IOT_NETWORK_USE_OPENSSL [Linux only]
    Default: OFF
    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.

Building the demo applications

How to build the demo applications.

Before building the demos, all desired configuration settings should be defined. Configuration settings include global library and demo 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.

Command-line build

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:

# Create build directory and change to build directory.
mkdir build
cd build
# Configure build using CMake.
cmake ..
# Build the demo applications.
make

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.

# Example: Set IOT_STATIC_MEMORY_ONLY using CMake
cmake .. -DCMAKE_C_FLAGS=-DIOT_STATIC_MEMORY_ONLY=1

By default, CMake may build in Release configuration. To enable debugging symbols, set CMAKE_BUILD_TYPE to Debug.

cmake .. -DCMAKE_BUILD_TYPE=Debug

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

CMake GUI build

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 Where is the source code and a build directory in Where to build the binaries. Click Configure, then Generate. You may modify Build system configuration in the CMake GUI window.

Demo command line options

Command line options of the demo applications.

Demo applications accept the following command line options.

-n

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 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.

-s and -u

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 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.

-h host

Remote host for demo application.

Must be followed by a host name.

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

-p port

Remote port for demo application.

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

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

-r rootCA, -c clientCert, -k privateKey

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 IOT_DEMO_ROOT_CA, IOT_DEMO_CLIENT_CERT, and IOT_DEMO_PRIVATE_KEY for the compile-time default settings of these options.

-i identifier

MQTT client identifier OR 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 IOT_DEMO_IDENTIFIER for the compile-time default settings of this option.

Building and running the tests

How to build and run the SDK tests.

Like the demo applications, the tests also build with CMake. Global test configuration settings, 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 both 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.

# 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

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.