CMake parameters

Use the CMake parameters listed in this section to customize how your SDK builds.

You can set these options with CMake GUI tools or the command line by using -D. For example:

cmake -DENABLE_UNITY_BUILD=ON -DREGENERATE_CLIENTS=1

General CMake Variables and Options

The following are general cmake variables and options that affect the build process of the SDK source code.

ADD_CUSTOM_CLIENTS

Builds any arbitrary clients based on the API definition. Place your definition in the code-generation/api-definitions folder, and then pass this argument to cmake . The cmake configure step generates your client and includes it as a subdirectory in your build. This is particularly useful to generate a C++ client for using one of your API Gateway services. For example:

-DADD_CUSTOM_CLIENTS="serviceName=myCustomService,version=2015-12-21;serviceName=someOtherService,version=2015-08-15"

AUTORUN_UNIT_TESTS

If ON, run unit tests automatically after building.

AWS_AUTORUN_LD_LIBRARY_PATH

The path to append into LD_LIBRARY_PATH for unit tests autorun by CMake. Set this path if custom runtime libraries are required for overridden dependencies.

AWS_SDK_WARNINGS_ARE_ERRORS

If ON, treat compiler warnings as errors. Try turning this OFF if observing errors on a new or uncommon compiler.

AWS_USE_CRYPTO_SHARED_LIBS

Forces FindCrypto to use a shared crypto library if found. Turn this OFF to use BUILD_SHARED_LIBS's setting instead.

AWS_TEST_REGION

The AWS Region to use for integration tests.

BUILD_BENCHMARKS

If ON, build the benchmark executable.

BUILD_DEPS

If ON, build third-party dependencies.

BUILD_ONLY

Builds only the clients you want to use. If set to a high-level SDK such as aws-cpp-sdk-transfer, BUILD_ONLY resolves any low-level client dependencies. It also builds integration and unit tests related to the projects you select, if they exist. This is a list argument, with values separated by semicolon (;) characters. For example:

-DBUILD_ONLY="s3;cognito-identity"

BUILD_OPTEL

If ON, builds the open telemetry implementation of tracing.

BUILD_SHARED_LIBS

A built-in CMake option, re-exposed here for visibility. If ON, it builds shared libraries; otherwise, it builds only static libraries.

BYPASS_DEFAULT_PROXY

If ON, bypass the machine's default proxy settings when using IXmlHttpRequest2.

CPP_STANDARD

Specifies a custom C++ standard for use with C++ 14 and 17 code bases.

CURL_INCLUDE_DIR

Path to curl include directory containing libcurl headers.

CURL_LIBRARY

Path to curl library file to link against. This library can be a static library or an import library, depending on the needs of your application.

CUSTOM_MEMORY_MANAGEMENT

To use a custom memory manager, set the value to 1. You can install a custom allocator so that all STL types use the custom allocation interface. If you set the value 0, you still might want to use the STL template types to help with DLL safety on Windows.

If static linking is ON, custom memory management defaults to off (0). If dynamic linking is ON, custom memory management defaults to on (1) and avoids cross-DLL allocation and deallocation.

To install your own memory manager to handle allocations made by the SDK, you must set -DCUSTOM_MEMORY_MANAGEMENT and define AWS_CUSTOM_MEMORY_MANAGEMENT for all build targets that depend on the SDK.

DISABLE_INTERNAL_IMDSV1_CALLS

If ON, no internal calls are made to the V1 API of the Instance Metadata Service. If OFF, IMDSv2 calls will fallback to using IMDSv1 if the IMDSv2 call fails. For more information on IMDSv1 and IMDSv2, see Use the Instance Metadata Service to access instance metadata in the Amazon EC2 User Guide.

ENABLE_ADDRESS_SANITIZER

If ON, turns on Address Sanitizer for gcc or clang.

ENABLE_CURL_LOGGING

If ON, pipe the internal log for curl to the SDK logger.

ENABLE_HTTP_CLIENT_TESTING

If ON, build and run corresponding HTTP client test suites.

ENABLE_RTTI

Controls whether the SDK is built to enable run-time type information (RTTI).

ENABLE_TESTING

Controls whether unit and integration test projects are built during the SDK build.

ENABLE_UNITY_BUILD

If ON, most SDK libraries are built as a single, generated .cpp file. This can significantly reduce static library size and speed up compilation time.

ENABLE_VIRTUAL_OPERATIONS

This parameter usually works together with REGENERATE_CLIENTS for code generation.

If ENABLE_VIRTUAL_OPERATIONS is ON and REGENERATE_CLIENTS is ON, operation-related functions in service clients will be marked as virtual.

If ENABLE_VIRTUAL_OPERATIONS is OFF and REGENERATE_CLIENTS is ON, virtual won't be added to operation functions and service client classes will be marked as final.

If ENABLE_VIRTUAL_OPERATIONS is OFF, the SDK will also add -ffunction-sections and -fdata-sections compiler flags for gcc and clang when compiling.

For more information, see CMake Parameters on GitHub.

ENABLE_ZLIB_REQUEST_COMPRESSION

For services that support it, request content will be compressed. On by default if dependency is available.

FORCE_CURL

Windows only. If ON, forces usage of the curl client instead of the default WinHTTP data transfer provider.

FORCE_SHARED_CRT

If ON, the SDK links to the C runtime dynamically; otherwise, it uses the BUILD_SHARED_LIBS setting (sometimes necessary for backward compatibility with earlier versions of the SDK).

G

Generates build artifacts, such as Visual Studio solutions and Xcode projects.

For example, on Windows:

-G "Visual Studio 12 Win64"

For more information, see the CMake documentation for your platform.

MINIMIZE_SIZE

A superset of ENABLE_UNITY_BUILD. If ON, this option turns on ENABLE_UNITY_BUILD and additional binary size reduction settings.

NO_ENCRYPTION

If ON, prevents the default platform-specific cryptography implementation from being built into the library. Turn this ON to inject your own cryptography implementation.

NO_HTTP_CLIENT

If ON, prevents the default platform-specific HTTP client from being built into the library. If ON, you will need to provide your own platform-specific HTTP client implementation.

REGENERATE_CLIENTS

If ON, this parameter deletes all generated code and generates the client directories from the code-generation/api-definitions folder. For example:

-DREGENERATE_CLIENTS=1

REGENERATE_DEFAULTS

If ON, this parameter deletes all generated defaults code and generates it again from the code-generation/defaults folder. For example:

-DREGENERATE_DEFAULTS=1

SIMPLE_INSTALL

If ON, the install process does not insert platform-specific intermediate directories underneath bin/ and lib/. Turn OFF if you need to make multiplatform releases under a single install directory.

TARGET_ARCH

To cross-compile or build for a mobile platform, you must specify the target platform. By default, the build detects the host operating system and builds for the detected operating system.

USE_CRT_HTTP_CLIENT

If ON, use the common runtime HTTP client, and the legacy systems such as WinHttp and libcurl are not built or included.

USE_IXML_HTTP_REQUEST_2

Windows only. If ON, use the com object IXmlHttpRequest2 for the HTTP stack.

USE_OPENSSL

If ON, the SDK builds using OpenSSL; otherwise, it uses awslabs/aws-lc. AWS-LC is a general-purpose cryptographic library maintained by the AWS Cryptography team for AWS and their customers. Turning OFF the parameter installs AWS-LC as replacement of OpenSSL in the system default directory. Don't use if you already have an OpenSSL installation in your system.

USE_TLS_V1_2

If ON, the HTTP client enforces TLS 1.2.

USE_TLS_V1_3

If ON, the HTTP client enforces TLS 1.3.

Android CMake Variables and Options

Use the following variables when you are creating an Android build of the SDK (when TARGET_ARCH is set to ANDROID).

ANDROID_ABI

Android only. Controls which Application Binary Interface (ABI) to output code for.

ANDROID_BUILD_CURL

Android only. If ON, build curl also.

ANDROID_BUILD_OPENSSL

Android only. If ON, build Openssl also.

ANDROID_BUILD_ZLIB

Android only. If ON, build Zlib also.

ANDROID_NATIVE_API_LEVEL

Android only. Controls what API level the SDK builds against. If you set ANDROID_STL to gnustl, you can choose any API level. If you use libc++, you must use an API level of at least 21.

ANDROID_STL

Android only. Controls what flavor of the C++ standard library the SDK uses.

ANDROID_TOOLCHAIN_NAME

Android only. Controls which compiler is used to build the SDK.

DISABLE_ANDROID_STANDALONE_BUILD

Android only. By default, Android builds use a standalone clang-based toolchain constructed via NDK scripts. To use your own toolchain, turn this option ON.

NDK_DIR

Android only. Specifies an override path where the build system should find the Android NDK. By default, the build system checks environment variables (ANDROID_NDK) if this variable is not set.