# Getting started with the AWS SDK for C\$1\$1 AWS SDK for C\$1\$1 is a modularized, cross-platform, open-source library you can use to connect to Amazon Web Services. The AWS SDK for C\$1\$1 uses [CMake](https://cmake.org/) to support multiple platforms over multiple domains, including video games, systems, mobile, and embedded devices. CMake is a build tool that you can use to manage your application’s dependencies and to create makefiles suitable for the platform you’re building on. CMake removes the parts of the build that are not used for your platform or application. Before you run code to access AWS resources, you must establish how your code authenticates with AWS. + [Authenticating with AWS using AWS SDK for C\$1\$1](credentials.md) To use the AWS SDK for C\$1\$1 in your code, obtain the SDK executables by building the SDK source directly or by using a package manager. + [Getting the AWS SDK for C\$1\$1 from source code](sdk-from-source.md) + [Getting the AWS SDK for C\$1\$1 from a package manager](sdk-from-pm.md) If you run into build issues regarding CMake, see [Troubleshooting AWS SDK for C\$1\$1 build issues](troubleshooting-cmake.md). # Authenticating with AWS using AWS SDK for C\$1\$1 You must establish how your code authenticates with AWS when developing with AWS services. You can configure programmatic access to AWS resources in different ways depending on the environment and the AWS access available to you. For choices on all primary methods of authentication, and guidance on configuring it for the SDK, see [Authentication and access](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) in the *AWS SDKs and Tools Reference Guide*. ## Using console credentials For local development, we recommend that new users use their existing AWS Management Console sign-in credentials for programmatic access to AWS services. After a browser-based authentication flow, AWSgenerates temporary credentials that work across local development tools like the AWS CLI, AWS Tools for PowerShell and AWS SDKs. This feature simplifies the process of configuring and managing AWS CLI credentials, especially if you prefer interactive authentication over managing long-term access keys. If you choose this method, follow the instructions to login with console credentials using the AWS CLI. See [Login for AWS local development using console credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html) for more details. Once set up with AWS CLI, [the default credential provider chain](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/credproviders.html#credproviders-default-credentials-provider-chain) will automatically start using the login token cached by AWS CLI to make requests. ## Using IAM Identity Center This method includes installing the AWS CLI for ease of configuration and for regularly signing in to the AWS access portal. If you choose this method, complete the procedure for [IAM Identity Center authentication](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html) in the *AWS SDKs and Tools Reference Guide*. Afterwards, your environment should contain the following elements: + The AWS CLI, which you use to start an AWS access portal session before you run your application. + A [shared AWS`config` file](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) having a `[default]` profile with a set of configuration values that can be referenced from the SDK. To find the location of this file, see [Location of the shared files](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html) in the *AWS SDKs and Tools Reference Guide*. + The shared `config` file sets the [https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html) setting. This sets the default AWS Region that the SDK uses for AWS requests. This Region is used for SDK service requests that aren't specified with a Region to use. + The SDK uses the profile's [SSO token provider configuration](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#feature-sso-credentials-profile) to acquire credentials before sending requests to AWS. The `sso_role_name` value, which is an IAM role connected to an IAM Identity Center permission set, should allow access to the AWS services used in your application. The following sample `config` file shows a default profile set up with SSO token provider configuration. The profile's `sso_session` setting refers to the named [`sso-session` section](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#section-session). The `sso-session` section contains settings to initiate an AWS access portal session. ``` [default] sso_session = my-sso sso_account_id = 111122223333 sso_role_name = SampleRole region = us-east-1 output = json [sso-session my-sso] sso_region = us-east-1 sso_start_url = https://provided-domain.awsapps.com/start sso_registration_scopes = sso:account:access ``` The AWS SDK for C\$1\$1 does not need additional packages (such as `SSO` and `SSOOIDC`) to be added to your application to use IAM Identity Center authentication. ### Start an AWS access portal session Before running an application that accesses AWS services, you need an active AWS access portal session for the SDK to use IAM Identity Center authentication to resolve credentials. Depending on your configured session lengths, your access will eventually expire and the SDK will encounter an authentication error. To sign in to the AWS access portal, run the following command in the AWS CLI. ``` aws sso login ``` Since you have a default profile setup, you do not need to call the command with a `--profile` option. If your SSO token provider configuration is using a named profile, the command is `aws sso login --profile named-profile`. To test if you already have an active session, run the following AWS CLI command. ``` aws sts get-caller-identity ``` The response to this command should report the IAM Identity Center account and permission set configured in the shared `config` file. **Note** If you already have an active AWS access portal session and run `aws sso login`, you will not be required to provide credentials. The sign-in process might prompt you to allow the AWS CLI access to your data. Because the AWS CLI is built on top of the SDK for Python, permission messages may contain variations of the `botocore` name. ## More authentication information Human users, also known as *human identities*, are the people, administrators, developers, operators, and consumers of your applications. They must have an identity to access your AWS environments and applications. Human users that are members of your organization are also known as *workforce identities*, that means you, the developer. Use temporary credentials when accessing AWS. You can use an identity provider for your human users to provide federated access to AWS accounts by assuming roles, which provide temporary credentials. For centralized access management, we recommend that you use AWS IAM Identity Center (IAM Identity Center) to manage access to your accounts and permissions within those accounts. For more alternatives, see the following: + To learn more about best practices, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. + To create short-term AWS credentials, see [Temporary Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) in the *IAM User Guide*. + To learn about other AWS SDK for C\$1\$1 credential providers, see [Standardized credential providers](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) in the *AWS SDKs and Tools Reference Guide*. # Getting the AWS SDK for C\$1\$1 from source code You can use the AWS SDK for C\$1\$1 from your code by first building the SDK from source and then installing it locally. **Process overview** | General process | Detailed process | | --- | --- | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/sdk-from-source.html) | First build the SDK from source and install it. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/sdk-from-source.html) | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/sdk-from-source.html) | Then develop your own application using the SDK. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/sdk-from-source.html) | # Building the AWS SDK for C\$1\$1 on Windows To set up the AWS SDK for C\$1\$1, you can either build the SDK yourself directly from the source or download the libraries using a package manager. The SDK source is separated into individual packages by service. Installing the entire SDK can take up to an hour. Installing only the specific subset of services that your program uses decreases installation time and also reduces size on disk. To choose which services to install, you need to know the package name of each service your program uses. You can see the list of package directories at [https://github.com/aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp) on GitHub. The package name is the suffix of the directory name for the service. ``` aws-sdk-cpp\aws-cpp-sdk- # Repo directory name and packageName aws-sdk-cpp\aws-cpp-sdk-s3 # Example: Package name is s3 ``` ## Prerequisites You need a minimum of 4 GB of RAM to build some of the larger AWS clients. The SDK might fail to build on Amazon EC2 instance types *t2.micro*, *t2.small*, and other small instance types due to insufficient memory. To use the AWS SDK for C\$1\$1, you need one of the following: + Microsoft Visual Studio 2015 or later, + GNU Compiler Collection (GCC) 4.9 or later, or + Clang 3.3 or later. ## Building the SDK for Windows with curl On Windows, the SDK is built with [WinHTTP](https://msdn.microsoft.com/en-us/library/windows/desktop/aa382925%28v=vs.85%29.aspx) as the default HTTP client. However, WinHTTP 1.0 does not support HTTP/2 bidirectional streaming, which is required for some AWS services such as Amazon Transcribe and Amazon Lex. Thus, it is sometimes necessary to build curl support with the SDK. To view all available curl download options, see [curl Releases and Downloads](https://curl.se/download.html). One method for building the SDK with curl support is the following: **To build the SDK with curl library support included** 1. Navigate to [curl for Windows](https://curl.se/windows/) and download the curl binary package for Microsoft Windows. 1. Unpack the package to a folder on your computer, for example, `C:\curl`. 1. Navigate to [CA certificates extracted from Mozilla](http://curl.haxx.se/docs/caextract.html) and download the `cacert.pem` file. This Privacy Enhanced Mail (PEM) file contains a bundle of valid digital certificates that are used to verify the authenticity of secure websites. The certificates are distributed by certificate authority (CA) companies such as GlobalSign and Verisign. 1. Move the `cacert.pem` file to the `bin` subfolder that you unpacked in a previous step, for example, `C:\curl\bin`. Rename the file as `curl-ca-bundle.crt`. Also, the Microsoft Build Engine (MSBuild) must be able to locate the curl `dll` in the procedure that follows. Therefore, you should add the curl `bin` folder path to your Windows `PATH` environment variable, for example, `set PATH=%PATH%;C:\curl\bin`. You must add this each time you open a new command prompt to build the SDK. Alternatively, you can set the environment variable globally in your Windows system settings so that the setting is remembered. When *Building the SDK from source* in the procedure that follows, see Step 5 (Generate build files) for required command syntax to build curl into your SDK. When writing your code, you must set `caFile` in the [Configuring AWS SDK for C\$1\$1 service clients in code](client-config.md) to the location of your certificate file. For an example using Amazon Transcribe, see [https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/transcribe-streaming](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/transcribe-streaming) in the *AWS Code Examples Repository* on GitHub. ## Building the SDK from source You can build the SDK from source using command-line tools. Using this method, you can customize your SDK build. For information about available options, see [CMake Parameters](cmake-params.md). There are three main steps. First, you build the files using CMake. Second, you use MSBuild to build the SDK binaries that work with your operating system and build toolchain. Third, you install or copy the binaries into the correct location on the development machine. **To build the SDK from source** 1. Install [CMake](https://cmake.org/) (minimum version 3.13) and the relevant build tools for your platform. It is recommended to add `cmake` to your `PATH`. To check your version of CMake, open a command prompt and run command **cmake --version** 1. In a command prompt, navigate to a folder where you want to store the SDK. 1. Get the latest source code. Version 1.11 uses git submodules to wrap external dependencies. This includes the [CRT libraries](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html) described in the *AWS SDKs and Tools Reference Guide*. Download or clone the SDK source from [https://github.com/aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp) on GitHub: + Clone with Git: HTTPS ``` git clone --recurse-submodules https://github.com/aws/aws-sdk-cpp ``` + Clone with Git: SSH ``` git clone --recurse-submodules git@github.com:aws/aws-sdk-cpp.git ``` 1. We recommend you store the generated build files outside of the SDK source directory. Create a new directory to store the build files in and navigate to that folder. ``` mkdir sdk_build cd sdk_build ``` 1. Generate the build files by running `cmake`. Specify on the `cmake` command line whether to build a *Debug* or *Release* version. Choose `Debug` throughout this procedure to run a debug configuration of your application code. Choose `Release` throughout this procedure to run a release configuration of your application code. For Windows, the SDK install location is typically `\Program Files (x86)\aws-cpp-sdk-all\`. Command syntax: `{path to cmake if not in PATH} {path to source location of aws-sdk-cpp} -DCMAKE_BUILD_TYPE=[Debug | Release] -DCMAKE_PREFIX_PATH={path to install destination}` For more ways to modify the build output, see [CMake Parameters](cmake-params.md). To generate the build files, do one of the following: + **Generate build files (all AWS services)**: To build the entire SDK, run cmake, specifying whether to build a *Debug* or *Release* version. For example: ``` cmake "..\aws-sdk-cpp" -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH="C:\Program Files (x86)\aws-cpp-sdk-all" ``` + **Generate build files (subset AWS services)**: To build only a particular service or services package(s) for the SDK, add the CMake [BUILD\$1ONLY](cmake-params.md#cmake-build-only) parameter, with the service names separated by semicolons. The following example builds only the Amazon S3 service package: ``` cmake ..\aws-sdk-cpp -DCMAKE_BUILD_TYPE=Debug -DBUILD_ONLY="s3" -DCMAKE_PREFIX_PATH="C:\Program Files (x86)\aws-cpp-sdk-all" ``` + **Generate build files (with curl)**: After completing the curl prerequisites, three additional cmake command line options are required to include curl support in the SDK: [FORCE\$1CURL](cmake-params.md#cmake-force-curl), [CURL\$1INCLUDE\$1DIR](cmake-params.md#cmake-curl-include-dir), and [CURL\$1LIBRARY](cmake-params.md#cmake-curl-library). For example: ``` cmake ..\aws-sdk-cpp -DCMAKE_BUILD_TYPE=Debug -DFORCE_CURL=ON -DCURL_INCLUDE_DIR='C:/curl/include' -DCURL_LIBRARY='C:/curl/lib/libcurl.dll.a' -DCMAKE_PREFIX_PATH="C:\Program Files (x86)\aws-cpp-sdk-all" ``` **Note** If you get an error Failed to build third-party libraries, check your version of CMake by running **cmake --version**. You must use CMake minimum version 3.13. 1. Build the SDK binaries. If you’re building the entire SDK, this step can take one hour or longer. Command syntax: `{path to cmake if not in PATH} --build . --config=[Debug | Release]` ``` cmake --build . --config=Debug ``` **Note** If you encounter the error The code execution cannot proceed ... dll not found. Reinstalling the program may fix this problem.", retry the `cmake` command again. 1. Open a command prompt with **administrator** privileges to install the SDK in the location specified earlier using the `CMAKE_PREFIX_PATH` parameter. Command syntax: `{path to cmake if not in PATH} --install . --config=[Debug | Release]` ``` cmake --install . --config=Debug ``` ## Building for Android on Windows To build for Android, add `-DTARGET_ARCH=ANDROID` to your `cmake` command line. The AWS SDK for C\$1\$1 includes a CMake toolchain file that includes what you need by referencing the appropriate environment variables (`ANDROID_NDK`). To build the SDK for Android on Windows, you need to run `cmake` from a Visual Studio (2015 or later) developer command prompt. You’ll also need NMAKE [NMAKE](https://docs.microsoft.com/en-us/cpp/build/reference/nmake-reference?view=msvc-160)installed and the commands ** `git` ** and ** `patch` ** in your path. If you have git installed on a Windows system, you’ll most likely find ** `patch` ** in a sibling directory (`.../Git/usr/bin/`). Once you’ve verified these requirements, your `cmake` command line will change slightly to use NMAKE. ``` cmake -G "NMake Makefiles" `-DTARGET_ARCH=ANDROID` .. ``` NMAKE builds serially. To build more quickly, we recommend you install JOM as an alternative to NMAKE, and then change the `cmake` invocation as follows: ``` cmake -G "NMake Makefiles JOM" `-DTARGET_ARCH=ANDROID` .. ``` For an example application, see [Setting up an Android application with AWS SDK for C\$1\$1](https://aws.amazon.com/blogs/developer/setting-up-an-android-application-with-aws-sdk-for-c/) # Building the AWS SDK for C\$1\$1 on Linux/macOS To set up the AWS SDK for C\$1\$1, you can either build the SDK yourself directly from the source or download the libraries using a package manager. The SDK source is separated into individual packages by service. Installing the entire SDK can take up to an hour. Installing only the specific subset of services that your program uses decreases installation time and also reduces size on disk. To choose which services to install, you need to know the package name of each service your program uses. You can see the list of package directories at [https://github.com/aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp) on GitHub. The package name is the suffix of the directory name for the service. ``` aws-sdk-cpp\aws-cpp-sdk- # Repo directory name and packageName aws-sdk-cpp\aws-cpp-sdk-s3 # Example: Package name is s3 ``` ## Prerequisites You need a minimum of 4 GB of RAM to build some of the larger AWS clients. The SDK might fail to build on Amazon EC2 instance types *t2.micro*, *t2.small*, and other small instance types due to insufficient memory. To use the AWS SDK for C\$1\$1, you need one of the following: + GNU Compiler Collection (GCC) 4.9 or later, or + Clang 3.3 or later. ## Additional Requirements for Linux Systems You must have the header files (`-dev` packages) for `libcurl`, `libopenssl`, `libuuid`, `zlib`, and, optionally, `libpulse` for Amazon Polly support. You can find the packages by using your system’s package manager. **To install the packages on *Debian/Ubuntu-based systems*** + ``` sudo apt-get install libcurl4-openssl-dev libssl-dev uuid-dev zlib1g-dev libpulse-dev ``` **To install the packages on *Amazon Linux/Redhat/Fedora/CentOS-based systems*** + ``` sudo yum install libcurl-devel openssl-devel libuuid-devel pulseaudio-libs-devel ``` ## Building the SDK from Source You can build the SDK from source using command-line tools as an alternative to using vcpkg. Using this method, you can customize your SDK build. For information about available options, see [CMake Parameters](cmake-params.md). **To build the SDK from source** 1. Install [CMake](https://cmake.org/) (minimum version 3.13) and the relevant build tools for your platform. It is recommended to add `cmake` to your `PATH`. To check your version of CMake, open a command prompt and run command **cmake --version** 1. In a command prompt, navigate to a folder where you want to store the SDK. 1. Get the latest source code. Version 1.11 uses git submodules to wrap external dependencies. This includes the [CRT libraries](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html) described in the *AWS SDKs and Tools Reference Guide*. Download or clone the SDK source from [https://github.com/aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp) on GitHub: + Clone with Git: HTTPS ``` git clone --recurse-submodules https://github.com/aws/aws-sdk-cpp ``` + Clone with Git: SSH ``` git clone --recurse-submodules git@github.com:aws/aws-sdk-cpp.git ``` 1. We recommend you store the generated build files outside of the SDK source directory. Create a new directory to store the build files in and navigate to that folder. ``` mkdir sdk_build cd sdk_build ``` 1. Generate the build files by running `cmake`. Specify on the `cmake` command line whether to build a *Debug* or *Release* version. Choose `Debug` throughout this procedure to run a debug configuration of your application code. Choose `Release` throughout this procedure to run a release configuration of your application code. Command syntax: `{path to cmake if not in PATH} {path to source location of aws-sdk-cpp} -DCMAKE_BUILD_TYPE=[Debug | Release] -DCMAKE_PREFIX_PATH={path to install} -DCMAKE_INSTALL_PREFIX={path to install}` For more ways to modify the build output, see [CMake Parameters](cmake-params.md). **Note** When building on a Mac with a case-insensitive filesystem, check the output of the `pwd` command in the directory where you run the build. Make sure that the `pwd` output uses mixed case for directory names such as `/Users` and `Documents`. To generate the build files, do one of the following: + **Generate build files (all AWS services)**: To build the entire SDK, run cmake, specifying whether to build a *Debug* or *Release* version. For example: ``` cmake ../aws-sdk-cpp -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=/usr/local/ -DCMAKE_INSTALL_PREFIX=/usr/local/ ``` + **Generate build files (subset AWS services)**: To build only a particular service or services package(s) for the SDK, add the CMake [BUILD\$1ONLY](cmake-params.md#cmake-build-only) parameter, with the service names separated by semicolons. The following example builds only the Amazon S3 service package: ``` cmake ../aws-sdk-cpp -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=/usr/local/ -DCMAKE_INSTALL_PREFIX=/usr/local/ -DBUILD_ONLY="s3" ``` **Note** If you get an error Failed to build third-party libraries, check your version of CMake by running **cmake --version**. You must use CMake minimum version 3.13. 1. Build the SDK binaries. If you’re building the entire SDK, the operation can take one hour or longer. ``` cmake --build . --config=Debug ``` 1. Install the SDK. You may need to escalate privileges depending on the location you chose to install to. ``` cmake --install . --config=Debug ``` ## Building for Android on Linux To build for Android, add `-DTARGET_ARCH=ANDROID` to your `cmake` command line. The AWS SDK for C\$1\$1 includes a CMake toolchain file that includes what you need by referencing the appropriate environment variables (`ANDROID_NDK`). For an example application, see [Setting up an Android application with AWS SDK for C\$1\$1](https://aws.amazon.com/blogs/developer/setting-up-an-android-application-with-aws-sdk-for-c/) # Creating a simple application using the AWS SDK for C\$1\$1 [CMake](https://cmake.org/) is a build tool that you use to manage your application’s dependencies and to create makefiles suitable for the platform you’re building on. You can use CMake to create and build projects using the AWS SDK for C\$1\$1. This example reports the Amazon S3 buckets you own. Having an Amazon S3 bucket in your AWS account is not required for this example, but it will be far more interesting if you have at least one. See [Create a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html) in the *Amazon Simple Storage Service User Guide* if you don't already have one. ## Step 1: Write the code This example consists of one folder containing one source file (`hello_s3.cpp`) and one `CMakeLists.txt` file. The program uses Amazon S3 to report storage bucket information. This code is also available in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/s3/hello_s3) on GitHub. You can set many options in a `CMakeLists.txt` build configuration file. For more information, see the [CMake tutorial](https://cmake.org/cmake-tutorial/) on the CMake website. **Note** Deep Dive: Setting `CMAKE_PREFIX_PATH` By default, the AWS SDK for C\$1\$1 on macOS, Linux, Android and other non-Windows platforms is installed into `/usr/local` and on Windows is installed into `\Program Files (x86)\aws-cpp-sdk-all`. When you install the AWS SDK to these standard locations, CMake automatically finds the necessary resources. However, if you install the AWS SDK to a custom location, you must tell CMake where to find the following resources that result from building the SDK: `AWSSDKConfig.cmake`: A configuration file that tells CMake how to find and use the AWS SDK libraries in your project. Without this file, CMake cannot locate AWS SDK header files, link to AWS SDK libraries, or set up the proper compiler flags. (for version 1.8 and earlier) The location of dependencies: `aws-c-event-stream`, `aws-c-common`, `aws-checksums` To set a custom installation path: ``` cmake -DCMAKE_PREFIX_PATH=/path/to/your/aws-sdk-installation /path/to/project/you/are/building ``` If you don't set `CMAKE_PREFIX_PATH` for a custom installation, your build will fail with errors like "Could not find AWSSDK" when CMake tries to process `find_package(AWSSDK)` in your `CMakeLists.txt`. **Note** Deep Dive: Windows Runtime Libraries To run your program, several DLLs are required in your program's executable location: `aws-c-common.dll`, `aws-c-event-stream.dll`, `aws-checksums.dll`, `aws-cpp-sdk-core.dll`, as well as any specific DLLs based on the components of your program (this example also requires `aws-cpp-sdk-s3` because it uses Amazon S3). The second `if` statement in the `CMakeLists.txt` file copies these libraries from the installation location to the executable location to satisfy this requirement. `AWSSDK_CPY_DYN_LIBS` is a macro defined by AWS SDK for C\$1\$1 that copies the SDK's DLLs from the installation location to the executable location of your program. If these DLLs are not in the executable location then runtime exceptions of 'file not found' occur. Review this portion of the `CMakeLists.txt` file for necessary changes for your unique environment if you encounter these errors. **To create the folder and source files** 1. Create a `hello_s3` directory and/or project to hold your source files. **Note** To complete this example in Visual Studio: choose **Create New Project** and then choose **CMake Project**. Name the project `hello_s3`. This project name is used in the `CMakeLists.txt` file. 1. Within that folder, add a `hello_s3.cpp` file that includes the following code, which reports the Amazon S3 buckets you own. ``` #include #include #include #include using namespace Aws; using namespace Aws::Auth; /* * A "Hello S3" starter application which initializes an Amazon Simple Storage Service (Amazon S3) client * and lists the Amazon S3 buckets in the selected region. * * main function * * Usage: 'hello_s3' * */ int main(int argc, char **argv) { Aws::SDKOptions options; // Optionally change the log level for debugging. // options.loggingOptions.logLevel = Utils::Logging::LogLevel::Debug; Aws::InitAPI(options); // Should only be called once. int result = 0; { Aws::Client::ClientConfiguration clientConfig; // Optional: Set to the AWS Region (overrides config file). // clientConfig.region = "us-east-1"; // You don't normally have to test that you are authenticated. But the S3 service permits anonymous requests, thus the s3Client will return "success" and 0 buckets even if you are unauthenticated, which can be confusing to a new user. auto provider = Aws::MakeShared("alloc-tag"); auto creds = provider->GetAWSCredentials(); if (creds.IsEmpty()) { std::cerr << "Failed authentication" << std::endl; } Aws::S3::S3Client s3Client(clientConfig); auto outcome = s3Client.ListBuckets(); if (!outcome.IsSuccess()) { std::cerr << "Failed with error: " << outcome.GetError() << std::endl; result = 1; } else { std::cout << "Found " << outcome.GetResult().GetBuckets().size() << " buckets\n"; for (auto &bucket: outcome.GetResult().GetBuckets()) { std::cout << bucket.GetName() << std::endl; } } } Aws::ShutdownAPI(options); // Should only be called once. return result; } ``` 1. Add a `CMakeLists.txt` file that specifies your project’s name, executables, source files, and linked libraries. ``` # Set the minimum required version of CMake for this project. cmake_minimum_required(VERSION 3.13) # Set the AWS service components used by this project. set(SERVICE_COMPONENTS s3) # Set this project's name. project("hello_s3") # Set the C++ standard to use to build this target. # At least C++ 11 is required for the AWS SDK for C++. set(CMAKE_CXX_STANDARD 11) # Use the MSVC variable to determine if this is a Windows build. set(WINDOWS_BUILD ${MSVC}) if (WINDOWS_BUILD) # Set the location where CMake can find the installed libraries for the AWS SDK. string(REPLACE ";" "/aws-cpp-sdk-all;" SYSTEM_MODULE_PATH "${CMAKE_SYSTEM_PREFIX_PATH}/aws-cpp-sdk-all") list(APPEND CMAKE_PREFIX_PATH ${SYSTEM_MODULE_PATH}) endif () # Find the AWS SDK for C++ package. find_package(AWSSDK REQUIRED COMPONENTS ${SERVICE_COMPONENTS}) if (WINDOWS_BUILD AND AWSSDK_INSTALL_AS_SHARED_LIBS) # Copy relevant AWS SDK for C++ libraries into the current binary directory for running and debugging. # set(BIN_SUB_DIR "/Debug") # if you are building from the command line you may need to uncomment this # and set the proper subdirectory to the executables' location. AWSSDK_CPY_DYN_LIBS(SERVICE_COMPONENTS "" ${CMAKE_CURRENT_BINARY_DIR}${BIN_SUB_DIR}) endif () add_executable(${PROJECT_NAME} hello_s3.cpp) target_link_libraries(${PROJECT_NAME} ${AWSSDK_LINK_LIBRARIES}) ``` ## Step 2: Build with CMake CMake uses the information in `CMakeLists.txt` to build an executable program. We recommend building the application following standard practices for your IDE. **To build the application from the command line** 1. Create a directory where ** `cmake` ** will build your application. ``` mkdir my_project_build ``` 1. Change to the build directory and run ** `cmake` ** using the path to your project’s source directory. ``` cd my_project_build cmake ../ ``` 1. After ** `cmake` ** generates your build directory, you can use ** `make` ** (or ** `nmake` ** on Windows), or MSBUILD (`msbuild ALL_BUILD.vcxproj` or `cmake --build . --config=Debug`) to build your application. ## Step 3: Run When you run this application, it displays console output that lists the total number of Amazon S3 buckets and the name of each bucket. We recommend running the application following standard practices for your IDE. **Note** Remember to sign in\$1 If you are using IAM Identity Center to authenticate, remember to sign in using the AWS CLI `aws sso login` command. **To run the program via command line** 1. Change to the Debug directory where the result of the build was generated. 1. Run the program using the name of the executable. ``` hello_s3 ``` For additional examples using the AWS SDK for C\$1\$1, see [Guided examples for calling AWS services using the AWS SDK for C\$1\$1](programming-services.md). # Getting the AWS SDK for C\$1\$1 from a package manager **Important** If you are using a package manager like homebrew or vcpkg: After updating the SDK for C\$1\$1 to a new version, you must recompile any library or executable that depends on the SDK. To set up the AWS SDK for C\$1\$1, you can either build the SDK yourself directly from the source or download the libraries using a package manager. The SDK source is separated into individual packages by service. Installing the entire SDK can take up to an hour. Installing only the specific subset of services that your program uses decreases installation time and also reduces size on disk. To choose which services to install, you need to know the package name of each service your program uses. You can see the list of package directories at [https://github.com/aws/aws-sdk-cpp](https://github.com/aws/aws-sdk-cpp) on GitHub. The package name is the suffix of the directory name for the service. ``` aws-sdk-cpp\aws-cpp-sdk- # Repo directory name and packageName aws-sdk-cpp\aws-cpp-sdk-s3 # Example: Package name is s3 ``` ## Prerequisites You need a minimum of 4 GB of RAM to build some of the larger AWS clients. The SDK might fail to build on Amazon EC2 instance types *t2.micro*, *t2.small*, and other small instance types due to insufficient memory. ------ #### [ Linux/macOS ] To use the AWS SDK for C\$1\$1 on Linux/macOS, you need one of the following: + GNU Compiler Collection (GCC) 4.9 or later, or + Clang 3.3 or later. ------ #### [ Windows ] To use the AWS SDK for C\$1\$1 on Windows, you need one of the following: + Microsoft Visual Studio 2015 or later, + GNU Compiler Collection (GCC) 4.9 or later, or + Clang 3.3 or later. ------ ## Get the SDK using vcpkg **Important** The available vcpkg distribution is supported by external contributors and is not provided through AWS. The most recent version is always available through [installing from source](sdk-from-source.md). [vcpkg](https://github.com/Microsoft/vcpkg) is a package manager updated and maintained by external contributors. Note that this package manager is not provided through AWS and may not reflect the latest available version for the AWS SDK for C\$1\$1. There is a delay between when a version is released by AWS and when it is available through an external package manager. The most recent version is always available through [installing from source](sdk-from-source.md). You must install [vcpkg](https://github.com/Microsoft/vcpkg) on your system. + Download and bootstrap [vcpkg](https://github.com/Microsoft/vcpkg) by following the instructions on the vcpkg GitHub Readme, substituting the following options when prompted: + As part of those instructions, you are guided to enter: ``` .\vcpkg\vcpkg install [packages to install] ``` To install the entire SDK, enter `.\vcpkg\vcpkg install "aws-sdk-cpp[*]" --recurse` or indicate only specific services of the SDK to install by appending a package name in brackets, for example, `.\vcpkg\vcpkg install "aws-sdk-cpp[s3, ec2]" --recurse` The output displays a messages including the following: ``` CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=C:/dev/vcpkg/vcpkg/scripts/buildsystems/vcpkg.cmake" ``` + Copy the complete `-DCMAKE_TOOLCHAIN_FILE` command to use for CMake later. The vcpkg GitHub Readme also instructs on where to use this for your toolset. + You may also need to note the build configuration type that you installed via vcpkg. The console output shows the build configuration and the version of the SDK. The following example output indicates the build configuration is "x86-windows" and the AWS SDK for C\$1\$1 version installed is 1.8. ``` The following packages will be built and installed: aws-sdk-cpp[core,dynamodb,kinesis,s3]:x86-windows -> 1.8.126#6 ``` After you install the AWS SDK for C\$1\$1, you can develop your own application using the SDK. The example shown in [Creating a simple application](build-cmake.md) reports the Amazon S3 buckets you own. # Troubleshooting AWS SDK for C\$1\$1 build issues When building the AWS SDK for C\$1\$1 from source, some of the following common build issues might arise. **Topics** + [ ## CMake Error: Could not find a package configuration file provided by "AWSSDK" ](#could-not-find-package) + [ ## CMake Error: Could not find load file (and you're on SDK version 1.8) ](#could-not-load-file) + [ ## CMake Error: Could not find load file ](#could-not-load-file2) + [ ## Runtime Error: cannot proceed because `aws-*.dll` was not found ](#dll-was-not-found) ## CMake Error: Could not find a package configuration file provided by "AWSSDK" CMake raises the following error if it cannot find the installed SDK. ``` 1> [CMake] CMake Error at C:\CodeRepos\CMakeProject1\CMakeLists.txt:4 (find_package): 1> [CMake] Could not find a package configuration file provided by "AWSSDK" with any 1> [CMake] of the following names: 1> [CMake] 1> [CMake] AWSSDKConfig.cmake 1> [CMake] awssdk-config.cmake 1> [CMake] 1> [CMake] Add the installation prefix of "AWSSDK" to CMAKE_PREFIX_PATH or set 1> [CMake] "AWSSDK_DIR" to a directory containing one of the above files. If "AWSSDK" 1> [CMake] provides a separate development package or SDK, be sure it has been 1> [CMake] installed. ``` To resolve this error, tell CMake where to find the installed SDK (e.g. the folder that was generated as a result of the SDK install ([Windows](setup-windows.md), [Linux/macOS](setup-linux.md)). Insert the following command before your first call to `find_package()` in your `CMakeLists.txt` file. See [Creating a simple application using the AWS SDK for C\$1\$1](build-cmake.md) for an example. ``` list(APPEND CMAKE_PREFIX_PATH "C:\\Program Files (x86)\\aws-cpp-sdk-all\\lib\\cmake") ``` ## CMake Error: Could not find load file (and you're on SDK version 1.8) CMake raises the following error if it cannot find the installed libraries. ``` 1> [CMake] include could not find load file: 1> [CMake] 1> [CMake] C:/Program Files (x86)/aws-cpp-sdk-all/lib/aws-c-common/cmake/static/aws-c-common-targets.cmake 1> [CMake] include could not find load file: 1> [CMake] 1> [CMake] C:/Program Files (x86)/aws-cpp-sdk-all/lib/aws-checksums/cmake/static/aws-checksums-targets.cmake 1> [CMake] include could not find load file: 1> [CMake] 1> [CMake] C:/Program Files (x86)/aws-cpp-sdk-all/lib/aws-checksums/cmake/static/aws-checksums-targets.cmake ``` To resolve this error, tell CMake where to find the installed SDK (e.g. the folder that was generated as a result of the SDK install ([Windows](setup-windows.md), [Linux/macOS](setup-linux.md)). Insert the following commands before your first call to `find_package()` in your `CMakeLists.txt` file. See [Creating a simple application using the AWS SDK for C\$1\$1](build-cmake.md) for an example. ``` #Set the location of where Windows can find the installed libraries of the SDK. if(MSVC) string(REPLACE ";" "/aws-cpp-sdk-all;" SYSTEM_MODULE_PATH "${CMAKE_SYSTEM_PREFIX_PATH}/aws-cpp-sdk-all") list(APPEND CMAKE_PREFIX_PATH ${SYSTEM_MODULE_PATH}) endif() ``` This solution is only for v1.8 of the SDK because these dependencies are handled differently in later versions. Version 1.9 addresses these issues by introducing an intermediate layer between the `aws-sdk-cpp` and `aws-c-*` libraries. This new layer is called `aws-crt-cpp` , and is a git submodule of the SDK for C\$1\$1. `aws-crt-cpp` also has the `aws-c-*` libraries (including `aws-c-common`, `aws-checksums`,` aws-c-event-stream`, etc.) as its own git submodules. This allows the SDK for C\$1\$1 to get all CRT libraries recursively and improves the build process. ## CMake Error: Could not find load file CMake raises the following error if it cannot find the installed libraries. ``` CMake Error at C:/Program Files (x86)/aws-cpp-sdk-all/lib/aws-c-auth/cmake/aws-c-auth-config.cmake:11 (include): include could not find load file: C:/Program Files (x86)/aws-cpp-sdk-all/lib/aws-c-auth/cmake/static/aws-c-auth-targets.cmake ``` To resolve this error, tell CMake to build shared libraries. Insert the following command before your first call to `find_package()` in your `CMakeLists.txt` file. See [Creating a simple application using the AWS SDK for C\$1\$1](build-cmake.md) for an example. ``` set(BUILD_SHARED_LIBS ON CACHE STRING "Link to shared libraries by default.") ``` ## Runtime Error: cannot proceed because `aws-*.dll` was not found CMake raises an error similar to the following if it cannot find a required DLL. ``` The code execution cannot proceed because aws-cpp-sdk-[dynamodb].dll was not found. Reinstalling the program may fix this problem. ``` This error occurs because the required libraries or executables for the SDK for C\$1\$1 are not available in the same folder as your application executables. To resolve this error, copy the SDK build output in your executable location. The specific DLL filename of the error will vary depending on which AWS services you are using. Do *one* of the following: + Copy the contents of the `/bin` folder of the AWS SDK for C\$1\$1 install to your application's build folder. + In your `CMakeLists.txt` file, use macro AWSSDK\$1CPY\$1DYN\$1LIBS to copy these for you. Add a call to either `AWSSDK_CPY_DYN_LIBS(SERVICE_LIST "" ${CMAKE_CURRENT_BINARY_DIR})` or `AWSSDK_CPY_DYN_LIBS(SERVICE_LIST "" ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_BUILD_TYPE})` to your `CMakeLists.txt` file to use this macro to do the copying for you. See [Creating a simple application using the AWS SDK for C\$1\$1](build-cmake.md) for an example. Choose the correct copy path for your build environment. Building via command line frequently puts the build output into a subfolder (`/Debug`), but Visual Studio and other IDEs often do not. Verify where your output executables are, and ensure the macro is copying to that location. When making these types of changes, it is good practice to delete the contents of your build output directory so that you get a clean starting point for the next build.