Skip to content

Revise README for better structure and content #3812

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Rushikesh-Gade wants to merge 1 commit into
base: main
Choose a base branch
from
+149 −118
Open

Revise README for better structure and content #3812

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
267 changes: 149 additions & 118 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,168 +1,199 @@
# AWS SDK for C++
The AWS SDK for C++ provides a modern C++ (version C++ 11 or later) interface for Amazon Web Services (AWS). It is meant to be performant and fully functioning with low- and high-level SDKs, while minimizing dependencies and providing platform portability (Windows, OSX, Linux, and mobile).

AWS SDK for C++ is now in General Availability and recommended for production use. We invite our customers to join the development efforts by submitting pull requests and sending us feedback and ideas via GitHub Issues.
A modern, performant C++11 interface for Amazon Web Services — fully featured, low-dependency, and cross-platform.

## __Jump To:__
* [Change log](https://github.com/aws/aws-sdk-cpp/tags)
* [API Docs](https://sdk.amazonaws.com/cpp/api/LATEST/index.html)
* [Getting Started](#getting-started)
* [Getting Help](#getting-help)
* [Using the SDK and Other Topics](#using-the-sdk-and-other-topics)
> **Status:** Generally Available — production-ready. Contributions welcome via pull requests and [GitHub Issues](https://github.com/aws/aws-sdk-cpp/issues/new/choose).

# Getting Started
---

## Building the SDK:
## Contents

### Minimum Requirements:
* Visual Studio 2015 or later
* OR GNU Compiler Collection (GCC) 4.9 or later
* OR Clang 3.3 or later
* 4GB of RAM (required for building some of the larger clients; SDK build may fail on EC2 instance types t2.micro, t2.small, and other small instance types due to insufficient memory)
* Supported platforms
* Amazon Linux
* Windows
* Mac
- [Minimum Requirements](#minimum-requirements)
- [Building from Source](#building-from-source)
- [Platform-Specific Guides](#platform-specific-guides)
- [Package Managers](#package-managers)
- [Maintenance & Support](#maintenance--support)
- [Getting Help](#getting-help)
- [SDK Reference](#sdk-reference)

### Building From Source:
---

#### To create an **out-of-source build**:
1. Install CMake and the relevant build tools for your platform. Ensure these are available in your executable path.
2. Clone this repository with submodules
## Minimum Requirements

```sh
git clone --recurse-submodules https://github.com/aws/aws-sdk-cpp
```
| Requirement | Minimum Version |
|---|---|
| Visual Studio | 2015 or later |
| GCC | 4.9 or later |
| Clang | 3.3 or later |
| RAM | 4 GB (larger clients may fail on `t2.micro`/`t2.small`) |

3. Create your build directory. Replace `<BUILD_DIR>` with your build directory name:
4. Build the project:
**Supported platforms:** Amazon Linux · Windows · macOS

```sh
cd <BUILD_DIR>
cmake <path-to-root-of-this-source-code> \
-DCMAKE_BUILD_TYPE=Debug \
-DCMAKE_INSTALL_PREFIX=<path-to-install> \
-DBUILD_ONLY="s3"
cmake --build . --config=Debug
cmake --install . --config=Debug
```
---

**_NOTE:_** BUILD_ONLY is an optional flag used to list only the services you are using. Building the whole SDK can take a long time. Also, check out the list of [CMake parameters](./docs/CMake_Parameters.md)
## Building from Source

#### Other Dependencies:
To compile in Linux, you must have the header files for libcurl, libopenssl. The packages are typically available in your package manager.
### 1. Install dependencies

Debian based Linux distributions example:
`sudo apt-get install libcurl-dev`
On **Debian/Ubuntu:**
```sh
sudo apt-get install libcurl-dev
```

RPM based Linux distributions example:
`sudo [yum|dnf|zypper] install libcurl-devel`
On **RPM-based Linux** (RHEL, Fedora, SUSE):
```sh
sudo yum install libcurl-devel # or dnf / zypper
```

### **Zlib (Optional — for Request Compression Support)**
### 2. Clone with submodules

Zlib is **optional** and only required if you enable **request compression** for specific AWS services that support gzip/deflate encoding.
* `-DENABLE_ZLIB_REQUEST_COMPRESSION=ON` — enables gzip/deflate request compression (disabled by default).
```sh
git clone --recurse-submodules https://github.com/aws/aws-sdk-cpp
```

If you do not enable this option, **zlib is not required** at build time.
If you do enable it, install zlib as follows:
### 3. Build

* **Debian/Ubuntu:** `sudo apt-get install zlib1g-dev`
* **RPM-based systems:** `sudo yum install zlib-devel` or `sudo dnf install zlib-devel`
Replace `<BUILD_DIR>` and `<path-to-*>` with your actual paths:

**Reference:**
```sh
cd <BUILD_DIR>
cmake <path-to-root-of-this-source-code> \
-DCMAKE_BUILD_TYPE=Debug \
-DCMAKE_INSTALL_PREFIX=<path-to-install> \
-DBUILD_ONLY="s3"

* [CMakeLists.txt (lines 179–192)](https://github.com/aws/aws-sdk-cpp/blob/main/CMakeLists.txt#L179-L192)
* [CMake Parameters Documentation](https://github.com/aws/aws-sdk-cpp/blob/main/docs/CMake_Parameters.md#enable_zlib_request_compression)
cmake --build . --config=Debug
cmake --install . --config=Debug
```

### Building for MacOS
> **Tip:** `BUILD_ONLY` limits compilation to the services you need. Building the full SDK takes a long time. See all available [CMake parameters](./docs/CMake_Parameters.md).

Building for macOS is largely the same as building on a *nix system except for how the system consumes the curl dependency and compilers.
### Optional: Request Compression (zlib)

You must install the [xcode command line tools](https://mac.install.guide/commandlinetools/4.html). This is required for Apple clang and gcc. This also installs libcurl as well.
Zlib is only needed if you enable gzip/deflate request compression:

> :warning: If you are using macOS Sonoma, there is a [known issue](https://github.com/aws/aws-sdk-cpp/issues/2804) where using libcurl version 8.4.0 on macOS can lead to issues. [This issue is being tracked with curl and Apple](https://github.com/curl/curl/issues/12525). In the meanwhile, please use an updated version of [curl from Homebrew](https://formulae.brew.sh/formula/curl). You can include this in your project via the CMAKE_PREFIX_PATH.
>
> ```
```cmake
-DENABLE_ZLIB_REQUEST_COMPRESSION=ON
```

Install zlib if using this flag:

| Platform | Command |
|---|---|
| Debian/Ubuntu | `sudo apt-get install zlib1g-dev` |
| RPM-based | `sudo yum install zlib-devel` |

---

## Platform-Specific Guides

### macOS

Building on macOS follows the standard Unix flow. First, install the Xcode command line tools (required for Apple Clang, GCC, and libcurl):

```sh
xcode-select --install
```

> **⚠️ macOS Sonoma:** libcurl 8.4.0 has a [known issue](https://github.com/aws/aws-sdk-cpp/issues/2804). Use [curl from Homebrew](https://formulae.brew.sh/formula/curl) instead:
> ```sh
> cmake -DCMAKE_PREFIX_PATH="/opt/homebrew/opt/curl/" \
> -DAUTORUN_UNIT_TESTS=OFF \
> -DBUILD_ONLY="s3" \
> -DCMAKE_INSTALL_PREFIX="~/sdk-install" \
> ..
> -DAUTORUN_UNIT_TESTS=OFF \
> -DBUILD_ONLY="s3" \
> -DCMAKE_INSTALL_PREFIX="~/sdk-install" \
> ..
> ```

### Building for Android
To build for Android, add `-DTARGET_ARCH=ANDROID` to your CMake command line. Currently, we support Android APIs from 19 to 28 with Android NDK 19c, and we are using the built-in CMake toolchain file supplied by Android NDK, assuming you have the appropriate environment variables (ANDROID_NDK) set.
### Android

Add `-DTARGET_ARCH=ANDROID` to your CMake command. Supported API levels: 19–28 with NDK 19c. Set the `ANDROID_NDK` environment variable before building.

**Building for Android on Windows** requires a Visual Studio developer command prompt (2015+) with `git` and `patch` in your PATH (check `.../Git/usr/bin/`).

Use NMake:
```sh
cmake -G "NMake Makefiles" -DTARGET_ARCH=ANDROID <other options> ..
```

For faster parallel builds, use [JOM](https://wiki.qt.io/Jom) instead of NMake:
```sh
cmake -G "NMake Makefiles JOM" -DTARGET_ARCH=ANDROID <other options> ..
```

##### Android on Windows
Building for Android on Windows requires some additional setup. In particular, you will need to run CMake from a Visual Studio developer command prompt (2015 or higher). Additionally, you will need 'git' and 'patch' in your path. If you have Git installed on a Windows system, then the patch is likely found in a sibling directory (.../Git/usr/bin/). Once you've verified these requirements, your CMake command line will change slightly to use nmake:
For Docker, ensure your container meets the [minimum requirements](#minimum-requirements). See the [Docker build files](https://github.com/aws/aws-sdk-cpp/tree/master/CI/docker-file).

```sh
cmake -G "NMake Makefiles" `-DTARGET_ARCH=ANDROID` <other options> ..
```
---

Nmake builds targets in a serial fashion. To make things quicker, we recommend installing JOM as an alternative to nmake and then changing the CMake invocation to:
## Package Managers

```sh
cmake -G "NMake Makefiles JOM" `-DTARGET_ARCH=ANDROID` <other options> ..
```
### vcpkg

### Building aws-sdk-cpp - Using vcpkg
```sh
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install aws-sdk-cpp
```

You can download and install aws-sdk-cpp using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
The vcpkg port is maintained by Microsoft and community contributors. To report an outdated version, [open an issue on vcpkg](https://github.com/Microsoft/vcpkg).

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install aws-sdk-cpp
### Conan

The aws-sdk-cpp port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
```sh
conan install --requires="aws-sdk-cpp/[*]" --build="aws-*"
```

### Building aws-sdk-cpp - Using Conan
The Conan recipe is maintained by JFrog and community contributors. To report an outdated version, [open an issue on ConanCenterIndex](https://github.com/conan-io/conan-center-index).

You can download and install aws-sdk-cpp using [Conan](https://conan.io/). Use the following command:
---

conan install --requires="aws-sdk-cpp/[*]" --build="aws-*"
## Maintenance & Support

The aws-sdk-cpp Conan recipe is kept up to date by JFrog's Conan team members and community contributors.
If the version is out of date, please [create an issue or pull request](https://github.com/conan-io/conan-center-index) on the ConanCenterIndex repository.
See the AWS SDKs and Tools Shared Configuration Reference for details on versioning policy and support timelines:

# Maintenance and support for SDK major versions
- [AWS SDKs and Tools Maintenance Policy](https://docs.aws.amazon.com/credref/latest/refdocs/maint-policy.html)
- [AWS SDKs and Tools Version Support Matrix](https://docs.aws.amazon.com/credref/latest/refdocs/version-support-matrix.html)

For information about maintenance and support for SDK major versions and our underlying dependencies, see the following in the AWS SDKs and Tools Shared Configuration and Credentials Reference Guide
---

* [AWS SDKs and Tools Maintenance Policy](https://docs.aws.amazon.com/credref/latest/refdocs/maint-policy.html)
* [AWS SDKs and Tools Version Support Matrix](https://docs.aws.amazon.com/credref/latest/refdocs/version-support-matrix.html)
## Getting Help

| Channel | Use for |
|---|---|
| [GitHub Discussions](https://github.com/aws/aws-sdk-cpp/discussions/new/choose) | Questions and guidance |
| [GitHub Issues](https://github.com/aws/aws-sdk-cpp/issues/new/choose) | Bug reports and feature requests |
| [Stack Overflow `#aws-sdk-cpp`](https://stackoverflow.com/questions/tagged/aws-sdk-cpp) | Community Q&A |
| [AWS Support](https://aws.amazon.com/premiumsupport/) | If you have a support plan |

# Getting Help
Before opening an issue, please check:
- [Developer Guide](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/welcome.html) and [API Reference](http://sdk.amazonaws.com/cpp/api/LATEST/index.html)
- [Changelog](./CHANGELOG.md) for recent breaking changes
- [Contribution Guide](./CONTRIBUTING.md)
- [Code Samples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/cpp)

The best way to interact with our team is through GitHub. You can open a [discussion](https://github.com/aws/aws-sdk-cpp/discussions/new/choose) for guidance questions or an [issue](https://github.com/aws/aws-sdk-cpp/issues/new/choose) for bug reports or feature requests.
---

You may also find help on community resources such as [StackOverFlow](https://stackoverflow.com/) with the tag [#aws-sdk-cpp](https://stackoverflow.com/questions/tagged/aws-sdk-cpp). If you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case.
## SDK Reference

Please make sure to check out our resources too before opening an issue:
* [Developer Guide](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/welcome.html) and [API reference](http://sdk.amazonaws.com/cpp/api/LATEST/index.html)
* [Changelog](./CHANGELOG.md) for recent breaking changes.
* [Contribution](./CONTRIBUTING.md) guide.
* [samples repo](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/cpp).
### Build & Configuration
- [CMake Parameters](./docs/CMake_Parameters.md)
- [CMake External Project](./docs/CMake_External_Project.md)
- [Building on EC2](https://github.com/aws/aws-sdk-cpp/wiki/Building-the-SDK-from-source-on-EC2)
- [Visual Studio Setup](./docs/Visual_Studio_building_and_debugging.md)

### Usage
- [API Docs](https://sdk.amazonaws.com/cpp/api/LATEST/index.html)
- [SDK Usage Guide](./docs/SDK_usage_guide.md)
- [Credentials Providers](./docs/Credentials_Providers.md)
- [Client Configuration](./docs/ClientConfiguration_Parameters.md)
- [Service Client](./docs/Service_Client.md)
- [Memory Management](./docs/Memory_Management.md)
- [Advanced Topics](./docs/Advanced_topics.md)

# Using the SDK and Other Topics
* Other docs for how to build the sdk
* [CMake Parameters](./docs/CMake_Parameters.md)
* [Add as CMake external project](./docs/CMake_External_Project.md)
* [Building for Docker](https://github.com/aws/aws-sdk-cpp/tree/master/CI/docker-file) (To build for Docker, ensure your container meets the [minimum requirements](#minimum-requirements))
* [Building on an EC2 instance](https://github.com/aws/aws-sdk-cpp/wiki/Building-the-SDK-from-source-on-EC2)
* [Visual Studio building and debugging](./docs/Visual_Studio_building_and_debugging.md)
* SDK usage
* [API Docs](https://sdk.amazonaws.com/cpp/api/LATEST/index.html)
* [Using the SDK](./docs/SDK_usage_guide.md)
* [Credentials Providers](./docs/Credentials_Providers.md)
* [Client Configuration Parameters](./docs/ClientConfiguration_Parameters.md)
* [Service Client](./docs/Service_Client.md)
* [Memory Management](./docs/Memory_Management.md)
* [Advanced Topics](./docs/Advanced_topics.md)
* [Coding Standards](./docs/CODING_STANDARDS.md)
* [License](./LICENSE)
* [Code of Conduct](./CODE_OF_CONDUCT.md)
### Project
- [Changelog](https://github.com/aws/aws-sdk-cpp/tags)
- [Coding Standards](./docs/CODING_STANDARDS.md)
- [License](./LICENSE)
- [Code of Conduct](./CODE_OF_CONDUCT.md)
-