rtos/freertos/doc/guide/building.txt - mcuxpresso_sdk - Git at Google

 /**
 @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 supported C compiler.
 - One of the following security libraries:
   - OpenSSL development libraries and header files, version 1.0.2g or later.

 @pre
 Additional requirements for POSIX systems:
 - POSIX threads, mutexes, and semaphores.
 - POSIX timers.

 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_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_demo_config.h`. Any undefined settings will use a default value when possible.

 The demo applications build with CMake.

 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 `bin` directory of the CMake build directory, i.e. `build/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.

 @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_tests_config.h`.

 Unlike the demos, the tests are currently only supported on POSIX systems that support all of the POSIX prerequisites. They are built by passing the option `IOT_BUILD_TESTS=1` to CMake.
 @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

 Test executables will be placed in a `bin` directory of the CMake build directory (i.e. `build/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. Individual tests may support other command line options; see the test application files for more information.
 */
	/**
	@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 supported C compiler.
	- One of the following security libraries:
	- OpenSSL development libraries and header files, version 1.0.2g or later.

	@pre
	Additional requirements for POSIX systems:
	- POSIX threads, mutexes, and semaphores.
	- POSIX timers.

	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_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_demo_config.h`. Any undefined settings will use a default value when possible.

	The demo applications build with CMake.

	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 `bin` directory of the CMake build directory, i.e. `build/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.

	@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_tests_config.h`.

	Unlike the demos, the tests are currently only supported on POSIX systems that support all of the POSIX prerequisites. They are built by passing the option `IOT_BUILD_TESTS=1` to CMake.
	@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

	Test executables will be placed in a `bin` directory of the CMake build directory (i.e. `build/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. Individual tests may support other command line options; see the test application files for more information.
	*/