diff --git a/README.md b/README.md index cc952d1d..a756fa65 100644 --- a/README.md +++ b/README.md @@ -1,89 +1,122 @@ -# AWS IoT Device SDK v2 for Python +# AWS IoT Device SDK for Python v2 [![Version](https://img.shields.io/pypi/v/awsiotsdk.svg?style=flat)](https://pypi.org/project/awsiotsdk/) -This document provides information about the AWS IoT Device SDK v2 for Python. This SDK is built on the [AWS Common Runtime](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html) +The AWS IoT Device SDK for Python v2 connects your Python applications and devices to the AWS IoT platform. It handles the complexities of secure communication, authentication, and device management so you can focus on your IoT solution. The SDK makes it easy to use AWS IoT services like Device Shadows, Jobs, and Fleet Provisioning. -*__Jump To:__* +**Supported Platforms**: Linux, Windows 11+, macOS 14+ + +> **Note**: The SDK is known to work on older platform versions, but we only guarantee compatibility for the platforms listed above. + +*__Topics:__* +* [Features](#features) * [Installation](#installation) + * [Minimum Requirements](#minimum-requirements) + * [Installing from PyPI](#installing-from-pypi) +* [Getting Started](#getting-started) * [Samples](samples) -* [Mac-Only TLS Behavior](#mac-only-tls-behavior) -* [Getting Help](#getting-help) -* [FAQ](./documents/FAQ.md) -* [API Docs](https://aws.github.io/aws-iot-device-sdk-python-v2/) * [MQTT5 User Guide](./documents/MQTT5_Userguide.md) -* [Migration Guide from the AWS IoT SDK for Python v1](./documents/MIGRATION_GUIDE.md) +* [Getting Help](#getting-help) +* [Resources](#resources) + +## Features + +The primary purpose of the AWS IoT Device SDK for Python v2 is to simplify the process of connecting devices to AWS IoT Core and interacting with AWS IoT services on various platforms. The SDK provides: +* Integrated service clients for AWS IoT Core services +* Secure device connections to AWS IoT Core using MQTT protocol including MQTT 5.0 +* Support for [multiple authentication methods and connection types](./documents/MQTT5_Userguide.md#how-to-create-an-mqtt5-client-based-on-desired-connection-method) + +#### Supported AWS IoT Core services + +* The [AWS IoT Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) service manages device state information in the cloud. +* The [AWS IoT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) service sends remote operations to connected devices. +* The [AWS IoT fleet provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) service generates and delivers device certificates automatically. ## Installation +The recommended way to use the AWS IoT Device SDK for Python v2 in your project is to install it from PyPI. + ### Minimum Requirements + +To develop applications with the AWS IoT Device SDK for Python v2, you need: + * Python 3.8+ -[Step-by-step instructions](./documents/PREREQUISITES.md) +See [detailed setup instructions](./documents/PREREQUISITES.md) for more information. -### Install from PyPI +### Installing from PyPI -#### MacOS and Linux: +#### macOS and Linux: -``` +```bash python3 -m pip install awsiotsdk ``` #### Windows: -``` +```bash python -m pip install awsiotsdk ``` -### Install from source +### Building from source -```bash -# 1. Create a workspace directory to hold all the SDK files -mkdir sdk-workspace -cd sdk-workspace +See the [Development Guide](./documents/DEVELOPING.md) for detailed instructions on building from source and using local builds. -# 2. Clone the repository. You could select the version of the SDK you desire to use. -git clone -b https://github.com/aws/aws-iot-device-sdk-python-v2.git +## Getting Started -# 3. (Optional) Setup the version number of your local build. The default version -# for awsiotsdk is set to "1.0.0-dev", you can set the version number of the -# local build in "aws-iot-device-sdk-python-v2/awsiot/__init__.py" -sed -i "s/__version__ = '1.0.0-dev'/__version__ = ''/" \ - aws-iot-device-sdk-python-v2/awsiot/__init__.py +To get started with the AWS IoT Device SDK for Python v2: -# 4. Install using Pip (use 'python' instead of 'python3' on Windows) -python3 -m pip install ./aws-iot-device-sdk-python-v2 -``` +1. **Install the SDK** - See the [Installation](#installation) section for installation details + +2. **Choose your connection method** - The SDK supports multiple authentication methods including X.509 certificates, AWS credentials, and custom authentication. [MQTT5 User Guide connection section](./documents/MQTT5_Userguide.md#how-to-create-an-mqtt5-client-based-on-desired-connection-method) and [MQTT5 X509 sample](./samples/mqtt/mqtt5_x509.md) provide more guidance + +3. **Follow a complete example** - Check out the [samples](samples) directory + +4. **Learn MQTT5 features** - For advanced usage and configuration options, see the [MQTT5 User Guide](./documents/MQTT5_Userguide.md) ## Samples -[Samples README](samples) +Check out the [samples](samples) directory for working code examples that demonstrate: +- [Basic MQTT connection and messaging](./samples/mqtt/mqtt5_x509.md) +- [AWS IoT Device Shadow operations](./samples/service_clients/shadow.md) +- [AWS IoT Jobs](./samples/service_clients/jobs.md) +- AWS IoT Fleet provisioning: [basic](./samples/service_clients/fleet_provisioning_basic.md) and [with CSR](./samples/service_clients/fleet_provisioning_csr.md) + +The samples provide ready-to-run code with detailed setup instructions for each authentication method and use case. + +## Getting Help + +The best way to interact with our team is through GitHub. +* Open [discussion](https://github.com/aws/aws-iot-device-sdk-python-v2/discussions): Share ideas and solutions with the SDK community +* Search [issues](https://github.com/aws/aws-iot-device-sdk-python-v2/issues): Find created issues for answers based on a topic +* Create an [issue](https://github.com/aws/aws-iot-device-sdk-python-v2/issues/new/choose): New feature request or file a bug + +If you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case. + +#### Mac-Only TLS Behavior -### Mac-Only TLS Behavior +> [!NOTE] +> This SDK does not support TLS 1.3 on macOS. Support for TLS 1.3 on macOS is planned for a future release. Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically. Beginning in v1.7.3, when a stored private key from the Keychain is used, the following will be logged at the "info" log level: ``` -static: certificate has an existing certificate-key pair that was previously imported into the Keychain. Using key from Keychain instead of the one provided. +static: certificate has an existing certificate-key pair that was previously imported into the Keychain. + Using key from Keychain instead of the one provided. ``` -## Getting Help - -The best way to interact with our team is through GitHub. You can open a [discussion](https://github.com/aws/aws-iot-device-sdk-python-v2/discussions) for guidance questions or an [issue](https://github.com/aws/aws-iot-device-sdk-python-v2/issues/new/choose) for bug reports, or feature requests. You may also find help on community resources such as [StackOverFlow](https://stackoverflow.com/questions/tagged/aws-iot) with the tag [#aws-iot](https://stackoverflow.com/questions/tagged/aws-iot) or if you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case. +## Resources -Please make sure to check out our resources too before opening an issue: +Check out our resources for additional guidance too before opening an issue: * [FAQ](./documents/FAQ.md) +* [AWS IoT Core Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) +* [MQTT5 User Guide](./documents/MQTT5_Userguide.md) * [API Docs](https://aws.github.io/aws-iot-device-sdk-python-v2/) -* [IoT Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) ([source](https://github.com/awsdocs/aws-iot-docs)) -* Check for similar [Issues](https://github.com/aws/aws-iot-device-sdk-python-v2/issues) * [AWS IoT Core Documentation](https://docs.aws.amazon.com/iot/) -* [Dev Blog](https://aws.amazon.com/blogs/?awsf.blog-master-iot=category-internet-of-things%23amazon-freertos%7Ccategory-internet-of-things%23aws-greengrass%7Ccategory-internet-of-things%23aws-iot-analytics%7Ccategory-internet-of-things%23aws-iot-button%7Ccategory-internet-of-things%23aws-iot-device-defender%7Ccategory-internet-of-things%23aws-iot-device-management%7Ccategory-internet-of-things%23aws-iot-platform) -* Integration with AWS IoT Services such as -[Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) -and [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) -is provided by code that been generated from a model of the service. +* [Dev Blog](https://aws.amazon.com/blogs/iot/category/internet-of-things/) +* [Migration Guide from the AWS IoT SDK for Python v1](./documents/MIGRATION_GUIDE.md) * [Contributions Guidelines](./documents/CONTRIBUTING.md) ## License diff --git a/documents/DEVELOPING.md b/documents/DEVELOPING.md new file mode 100644 index 00000000..6bb95ad9 --- /dev/null +++ b/documents/DEVELOPING.md @@ -0,0 +1,23 @@ +# Development Guide + +This document provides instructions for building the AWS IoT Device SDK for Python v2. + +## Building from source + +```bash +# 1. Create a workspace directory to hold all the SDK files +mkdir sdk-workspace +cd sdk-workspace + +# 2. Clone the repository. You could select the version of the SDK you desire to use. +git clone -b https://github.com/aws/aws-iot-device-sdk-python-v2.git + +# 3. (Optional) Setup the version number of your local build. The default version +# for awsiotsdk is set to "1.0.0-dev", you can set the version number of the +# local build in "aws-iot-device-sdk-python-v2/awsiot/__init__.py" +sed -i "s/__version__ = '1.0.0-dev'/__version__ = ''/" \ + aws-iot-device-sdk-python-v2/awsiot/__init__.py + +# 4. Install using Pip (use 'python' instead of 'python3' on Windows) +python3 -m pip install ./aws-iot-device-sdk-python-v2 +``` diff --git a/documents/PREREQUISITES.md b/documents/PREREQUISITES.md index 0a8797b7..00ca3736 100644 --- a/documents/PREREQUISITES.md +++ b/documents/PREREQUISITES.md @@ -1,271 +1,180 @@ -# PREREQUISITES +# Prerequisites -## Python 3.8 or higher +## Quick Setup -How you install Python varies from platform to platform. Below are the instructions for Windows, MacOS, and Linux: +**Requirements:** +- Python 3.8+ -* On Windows: - * Download the Python installer from the official Python website: [Python Website](https://www.python.org/downloads/windows/) -* On MacOS: - * Using `brew` (steps to [install `brew`](##cmake-31-on-mac)): `brew install python`. - * Download the Python installer from the official Python website: [Python Website](https://www.python.org/downloads/macos/) -* On Linux: - * Ubuntu: `sudo apt-get install python3` - * Arch Linux: `sudo pacman -S python3` - * Linux Distros that support `yum`: `sudo yum install python3` +**Installation:** +```bash +# macOS/Linux +python3 -m pip install awsiotsdk -## Installation Issues - -`awsiotsdk` depends on [awscrt](https://github.com/awslabs/aws-crt-python), which makes use of C extensions. Precompiled wheels are downloaded when installing on major platforms (Mac, Windows, Linux, Raspberry Pi OS). If wheels are unavailable for your platform, your machine must compile some C libraries. If you encounter issues, please install the following dependencies: - -* C++ 11 or higher - * Clang 3.9+ or GCC 4.8+ or MSVC 2015+ -* CMake 3.1+ -* Python headers and development libraries - -Steps to install these dependencies are below, as well as per platform instructions for [Windows](#windows-instructions), [MacOS](#macos-instructions), and [Linux](#linux-instructions). - -## C++ 11 Compiler - -To build the SDK, you will need a compiler that can compile C++ 11 code or higher. C++ compilers vary based on platform, but listed below are a few of the most common and the minimum version required: - -* Clang: 3.9 or higher -* GCC: 4.8 or higher -* MSVC: 2015 or higher - -Listed below are ways to install C++ 11 compilers on [Windows](#windows-c-compilers), [MacOS](#macos-c-compiler), and [Linux](#linux-c-compilers). - -## CMake 3.1+ - -You will also need CMake to build the SDK. The minimum required version is CMake 3.1. - -Below are the instructions to install CMake in a non-platform specific way: - -1. Download CMake3.1+ for your platform: https://cmake.org/download/ -2. Run the Cmake Installer. Make sure you add CMake into **PATH**. -3. Restart the command prompt / terminal. - -Listed below are also instructions to install CMake on [Windows](#windows-cmake), [MacOS](#macos-cmake), and [Linux](#linux-cmake). - -## Python headers and development libraries - -For Windows and MacOS, the development headers and libraries should be installed automatically. - -On Linux, the development headers and libaries are installed seperately and can be installed using the following commands depending on your Linux distro: -* Ubuntu: `sudo apt-get install python3-dev` -* Arch Linux: `sudo pacman -S python3-dev` -* Distros supporting `yum`: `sudo yum install python3-devel` - -## Windows Instructions - -### Windows C++ Compilers - -#### MinGW-w64 - -MinGW-w64 is a project that allows for `GCC` compiler support on Windows. There are several ways to install MinGW-w64, and this document will explain the workflow for adding MinGW-w64 using MSYS2, a software distribution and building platform for Windows. - -MinGW-w64 is fully supported on [Visual Studio Code](https://code.visualstudio.com/), a programming IDE that is a lightweight alternative to Visual Studio that supports many programming languages. The steps below are loosely based on the documentation for [installing MinGW-w64 for Visual Studio code](https://code.visualstudio.com/docs/cpp/config-mingw). - -1. Download and run the MSYS2 installer from the [MSYS2 website](https://www.msys2.org/). -2. Follow the install instructions on the [MSYS2 website](https://www.msys2.org/). - * Make sure to follow the instructions on the website for updating the database and base packages! - * Installing MinGW-w64 may be part of these instructions. If so, install MinGW-w64 using the instructions there. -3. If MinGW-w64 was not part of the install instructions for MSYS2, run `pacman -S --needed base-devel mingw-w64-x85_64-toolchain`. -4. Next you need to add MinGW to your windows `PATH` environment variables so you can run it from the terminal. -5. Open the Windows Settings. You can do this by typing `settings` into the search bar or by opening the Windows start menu and navigating to the Windows Settings (should be called "Settings") application. -6. Once the Windows Settings window is open, search for `Edit environment variables for your account`. -7. Select the `Path` variable in the `User variables` property and press the `Edit` button. -8. Select `New` and then add the MinGW-w64 `bin` folder to this path. If you used the command in step 3, it should be located in `C:\msys64\mingw64\bin`. If you installed using a different method, you will need to find the `mingw64/bin` folder on your computer. -9. Once you have added the path to the `Path` variable in the `User variables` property, select `OK` and save. -10. Close any console/terminal windows you have open. This is because the console/terminal will not see the updated `PATH` variable unless it is restarted by closing and reopening. -11. Confirm that MingW-w64 is installed by running either `g++ --version` or `gdb --version`. You should get a print out showing the installed version of the C++ compiler. - -#### MSVC - -Microsoft Visual C++ (MSVC) is a C++ compiler that is supported and maintained by Microsoft, and is supported by the C++ SDK. To install MSVC, you will need to install Visual Studio using the instructions below. - -Install Visual Studio with MSVC -1. Download **Visual Studio Installer** https://visualstudio.microsoft.com/downloads/ -2. Run the installer, check the **Desktop development with C++** workload and select Install. -3. Verify your MSVC installation - * In Windows Start up Menu, try open "Developer Command Prompt for VS". - * In the opened terminal/console window, type `cl.exe` and it *should* output the compiler version. - * You can also find the compiler version by opening Visual Studio by selecting `help` and then `about`. - -If using MSVC, you will need to use the Developer Command Prompt instead of the standard terminal when compiling the SDK and samples. - -### Windows CMake - -#### MinGW-w64 - -If you installed MinGW-w64 via `MSYS32` in the steps above, you can easily install CMake using the following: - -1. Run `pacman -S mingw-w64-x86_64-cmake`. -2. You will also need to install a build tool. You can install `ninja` or `make`. -3. To install `ninja` run `pacman -S mingw-w64-x86_64-ninja`. -4. To install `make` run `pacman -S mingw-w64-x86_64-make`. -5. Run `cmake --version` to check that CMake is properly installed. +# Windows +python -m pip install awsiotsdk +``` -#### Manual Install +Precompiled wheels are automatically downloaded for most platforms (macOS, Windows, Linux). -You can also install CMake manually by following the install instructions on the CMake website: +## Compilation Dependencies -1. Download CMake3.1+ for Windows: https://cmake.org/download/ -2. Run the Cmake Installer. -4. Next you need to add CMake to your windows `PATH` environment variables so you can run it from the terminal. - * Note: The installer should include an option to add CMake to the system path for all users. If you have checked this box, you can skip steps `5` through `9`. -5. Open the Windows Settings. You can do this by typing `settings` into the search bar or by opening the Windows start menu and navigating to the Windows Settings (should be called "Settings") application. -6. Once the Windows Settings window is open, search for `Edit environment variables for your account`. -7. Select the `Path` variable in the `User variables` property and press the `Edit` button. -8. Select `New` and then add the CMake `bin` folder to this path. If you do not modify the install path, it should be located around `C:\Program Files (x86)\CMake.x.x` where `x.x` is the version. If you installed CMake to a different directory, then you will need to modify the path accordingly. -9. Once you have added the path to the `Path` variable in the `User variables` property, select `OK` and save. -10. Close any console/terminal windows you have open. This is because the console/terminal will not see the updated `PATH` variable unless it is restarted by closing and reopening. -11. Run `cmake --version` to check that CMake is properly installed. +### When Compilation is Needed -### Windows Python headers and development libraries +Precompiled wheels are downloaded when installing on major platforms (Mac, Windows, Linux). If wheels are unavailable for your platform, your machine must compile AWS Common Runtime C libraries. -You will need to install Python to get the development libraries, if you do not already have Python installed. To download Python on Windows, go to the official website and download the Python installer for Windows: [Python Website](https://www.python.org/downloads/windows/) +### Requirements for Compilation -The development headers and libraries should be installed automatically when you install Python. +- C compiler (Clang 6+, GCC 5+, or MSVC 15+) +- CMake 3.9+ +- Python development headers +
+Windows Compilation Setup -## MacOS Instructions +### C Compiler (MSVC) -### MacOS C++ Compiler +1. Download [Visual Studio Installer](https://visualstudio.microsoft.com/downloads/) +2. Run installer and select **Desktop development with C++** workload +3. Verify installation: + - Open "Developer Command Prompt for VS" from Start Menu + - Run `cl.exe` - should show compiler version -#### XCode Command Line Tools using `brew` +**Note:** Use Developer Command Prompt (not regular terminal) when building. -XCode Command Line Tools is the easiest way to install C++ compilers on MacOS, as it is officially supported and maintained by Apple. By installing the XCode Command Line tools, you will automatically install `clang`, which can compile C++ 11 code. One way to install XCode Command Line Tools is using `brew`. +### C Compiler (MinGW-w64) -[Brew](https://brew.sh/) is a command line package manager that makes it easy to install packages and software dependencies. The instructions to install through `brew` are below: +Alternative to MSVC using GCC on Windows: -1. Open a new terminal and input the following command: -``` sh -bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -``` -2. If XCode Command Line Tools are not installed, the `brew` install process will ask if you want to install. Type `y` to install. -3. Wait for `brew` to install the XCode Command Line Tools. This make take some time. -4. Once `brew` is finished, confirm the XCode Command Line Tools have installed by opening a new terminal and inputting `clang --version`. +1. Download and run MSYS2 installer from [msys2.org](https://www.msys2.org/) +2. Follow MSYS2 instructions to update database and base packages +3. Install MinGW-w64 toolchain: + ```bash + pacman -S --needed base-devel mingw-w64-x86_64-toolchain + ``` +4. Add to Windows PATH: `C:\msys64\mingw64\bin` +5. Verify: `gcc --version` -If stuck waiting for `brew` to install XCode Command Line Tools for over 15-20 minutes, you many need to cancel the installation (`CTRL-C` in the terminal) and install XCode Command Line Tools though the installer. +### CMake -##### XCode Command Line Tools using installer +1. Download [CMake 3.9+](https://cmake.org/download/) for Windows +2. Run installer and check "Add CMake to system PATH" option +3. Restart terminal and verify: `cmake --version` -You can also install XCode Command Line Tools manually through an installer download on Apple's website. The instructions to install through the installer are below: +### Python Headers +Automatically installed with Python on Windows. -1. Go to [developer.apple.com/downloads](https://developer.apple.com/download/all/). -2. Input your AppleID to access the developer downloads. -3. From the presented list, scroll until you find `Command Line Tools for Xcode `. -4. Select `view more details` and then select `Additionals Tools for Xcode .dmg`. -5. Once downloaded, double click the `.dmg` and follow the installer instructions. -6. Confirm XCode Command Line Tools have installed by opening a new terminal and inputting `clang --version`. +
-### MacOS CMake -#### CMake using `brew` +
+macOS Compilation Setup -CMake can easily be installed using `brew`, so if you installed `brew` for XCode Command Line Tools, you can run the following to install CMake: +### C Compiler (Xcode Command Line Tools) -1. Confirm you have `brew` installed: -``` sh -brew --version -``` -2. Install CMake by running `brew install cmake`. -3. Close any console/terminal windows you have open. This is to refresh the console/terminal so it uses the latest changes. -4. Confirm CMake is installed by running `cmake --version`. +**Using Homebrew:** +1. During brew installation, it will prompt to install Xcode Command Line Tools +2. Type `y` to install +3. Verify: `clang --version` -#### Manual Install +**Manual Installation:** +1. Go to [developer.apple.com/downloads](https://developer.apple.com/download/all/) +2. Sign in with Apple ID +3. Download "Command Line Tools for Xcode" +4. Install and verify: `clang --version` -You can also install CMake manually by following the install instructions on the CMake website: +### CMake -1. Go to [cmake.org/install](https://cmake.org/install/). -2. Follow the install instructions for MacOS on the website page. -3. Drag and drop the CMake application from the downloaded installer into your Applications folder. A window should open once you have mounted the CMake installer that easily allows you to do this via drag-and-drop. -4. You may need to manually add CMake to your `path` so you can run it in the terminal. To do this, run the following command: -``` sh -sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install +**Using Homebrew:** +```bash +brew install cmake +cmake --version ``` -5. This will create the symlinks so you can run CMake from the terminal. -6. Close any console/terminal windows you have open. This is to refresh the console/terminal so it uses the latest changes. -### MacOS Python headers and development libraries +**Manual Installation:** +1. Download from [cmake.org](https://cmake.org/install/) +2. Drag CMake.app to Applications folder +3. Add to PATH: + ```bash + sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install + ``` +4. Restart terminal and verify: `cmake --version` -You will need to install Python to get the development libraries, if you do not already have Python installed. There are two ways to install Python on MacOS, depending on how you want to install it: -* Using `brew` (steps to [install `brew`](##cmake-31-on-mac)): `brew install python`. -* Download the Python installer from the official Python website: [Python Website](https://www.python.org/downloads/macos/) +### Python Headers +Automatically installed with Python on macOS. -The development headers and libraries should be installed automatically when you install Python. +
+
+Linux Compilation Setup -## Linux instructions +### C Compiler -### Linux C++ Compilers - -Many Linux operating systems have C++ compilers installed by default, so you might already `clang` or `gcc` preinstalled. -To test, try running the following in a new terminal: - -``` sh +Check if already installed: +```bash clang --version -``` -``` sh gcc --version ``` -If these commands fail, then please follow the instructions below for installing a C++ compiler on your Linux operating system. - -If your Linux operating system is not in the list, please use a search engine to find out how to install either `clang` or `gcc` on your Linux operating system. - -#### Install GCC or Clang on Ubuntu - -1. Open a new terminal -2. (optional) Run `sudo apt-get update` to get latest package updates. -3. (optional) Run `sudo apt-get upgrade` to install latest package updates. -4. Run `sudo apt-get install build-essential` to install GCC or `sudo apt-get install clang` to install Clang. -5. Once the install is finished, close the terminal and reopen it. -6. Confirm GCC is installed by running `gcc --version` or Clang is installed by running `clang --version`. - -#### Install GCC or Clang on Arch Linux +**Ubuntu:** +```bash +sudo apt update +sudo apt install build-essential # for GCC +# OR +sudo apt install clang # for Clang +``` -1. Open a new terminal. -2. Run `sudo pacman -S gcc` to install GCC or `sudo pacman -S clang` to install Clang. -3. Once the install is finished, close the terminal and reopen it. -4. Confirm Clang is installed by running `gcc --version`. +**Arch Linux:** +```bash +sudo pacman -S gcc # for GCC +# OR +sudo pacman -S clang # for Clang +``` -### Linux CMake +### CMake -There are several ways to install CMake depending on the Linux operating system. Several Linux operating systems include CMake in their software repository applications, like the Ubuntu Software Center for example, so you may want to check there first. Below are the instructions to install CMake for Ubuntu and Arch Linux. +**Ubuntu:** +```bash +# Via Software Center: search for "cmake" +# OR via command line: +sudo snap install cmake +``` -If your Linux operating system is not in the list below, please use a search engine to find out how to install CMake on your Linux operating system. You can also always try to install CMake manually using the generic install instructions at the top of this page. +**Arch Linux:** +```bash +sudo pacman -S cmake +``` -#### Install CMake on Ubuntu +### Python Headers -1. Open the Ubuntu Software Center -2. In the search bar enter `cmake` and select `CMake - cross-platform build system` from the list -3. Press the `install` button -4. After CMake has installed open a new terminal -5. Type `cmake --version` to confirm CMake is installed +**Ubuntu:** +```bash +sudo apt install python3-dev +``` -Or using the command line: +**Arch Linux:** +```bash +sudo pacman -S python3-dev +``` -1. Open a new terminal -2. Run `sudo snap install cmake` to install CMake from the snap store -3. After CMake has installed, close the terminal and reopen it -4. Type `cmake --version` to confirm CMake is installed +**RHEL/CentOS/Fedora:** +```bash +sudo dnf install python3-devel +# OR +sudo yum install python3-devel +``` -#### Install CMake on Arch Linux +
-1. Open a new terminal. -2. Run `sudo pacman -S cmake` to install Cmake -3. After CMake has installed, close the terminal and reopen it -4. Type `cmake --version` to confirm CMake is installed. +--- -### Linux Python headers and development libraries +## Advanced Troubleshooting -You will need to install Python to get the development libraries, if you do not already have Python installed. How you install Linux varies from operating system to operating system, but common operating system commands to install Python are listed below: -* Ubuntu: `sudo apt-get install python3` -* Arch Linux: `sudo pacman -S python3` -* Linux Distros that support `yum`: `sudo yum install python3` +**Compilation Issues:** +- **Compilation fails**: Ensure you have C compiler, CMake, and Python headers installed +- **CMake not found**: Add CMake to your system PATH +- **Permission errors**: Use `sudo` on Linux/macOS or run as Administrator on Windows +- **Python version**: Verify you're using Python 3.8+ with `python --version` -On Linux, the development headers and libaries are installed seperately from Python and can be installed using the following commands depending on your Linux distro: -* Ubuntu: `sudo apt-get install python3-dev` -* Arch Linux: `sudo pacman -S python3-dev` -* Distros supporting `yum`: `sudo yum install python3-devel` +**Getting Help:** +- Check our [FAQ](./FAQ.md) +- Search [existing issues](https://github.com/aws/aws-iot-device-sdk-python-v2/issues) +- Create a [new issue](https://github.com/aws/aws-iot-device-sdk-python-v2/issues/new/choose)