Skip to content

Commit 7cb3272

Browse files
TwistedTwiglegTwistedTwigleg
authored
Readme install instructions update (#316)
* Updated README build from source section, as well as updating the prerequisites to use latest install instructions from C++ repo
1 parent 53a75c3 commit 7cb3272

File tree

2 files changed

+199
-72
lines changed

2 files changed

+199
-72
lines changed

‎PREREQUISITES.md

Lines changed: 193 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
## Python 3.6 of higher
44

5+
How you install Python varies from platform to platform. Below are the instructions for Windows, MacOS, and Linux:
6+
57
* On Windows:
68
* Download the Python installer from the official Python website: [Python Website](https://www.python.org/downloads/windows/)
79
* On MacOS:
@@ -12,112 +14,144 @@
1214
* Arch Linux: `sudo pacman -S python3`
1315
* Linux Distros that support `yum`: `sudo yum install python3`
1416

15-
# Installation Issues
17+
## Installation Issues
1618

1719
`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:
1820

21+
* C++ 11 or higher
22+
* Clang 3.9+ or GCC 4.8+ or MSVC 2015+
1923
* CMake 3.1+
2024
* Python headers and development libraries
21-
* You may also need to install a C/C++ compiler to compile the C code
2225

23-
Steps to install these dependencies per platform are listed below.
26+
Steps to install these dependencies are below, as well as per platform instructions for [Windows](#windows-instructions), [MacOS](#macos-instructions), and [Linux](#linux-instructions).
27+
28+
## C++ 11 Compiler
29+
30+
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:
31+
32+
* Clang: 3.9 or higher
33+
* GCC: 4.8 or higher
34+
* MSVC: 2015 or higher
2435

36+
Listed below are ways to install C++ 11 compilers on [Windows](#windows-c-compilers), [MacOS](#macos-c-compiler), and [Linux](#linux-c-compilers).
2537

26-
## Cmake 3.1+
27-
### Cmake 3.1+ on Windows
38+
## CMake 3.1+
39+
40+
You will also need CMake to build the SDK. The minimum required version is CMake 3.1.
41+
42+
Below are the instructions to install CMake in a non-platform specific way:
2843

2944
1. Download CMake3.1+ for your platform: https://cmake.org/download/
3045
2. Run the Cmake Installer. Make sure you add CMake into **PATH**.
3146
3. Restart the command prompt / terminal.
3247

33-
### Cmake 3.1+ on Mac
48+
Listed below are also instructions to install CMake on [Windows](#windows-cmake), [MacOS](#macos-cmake), and [Linux](#linux-cmake).
3449

35-
You can install CMake easily using `brew` and it is the recommended workflow for most usecases. [Brew](https://brew.sh/) is a command line package manager that makes it easy to install packages and software dependencies.
50+
## Python headers and development libraries
3651

37-
1. Open a new terminal and input the following command:
38-
``` sh
39-
bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
40-
```
41-
2. If XCode Command Line Tools are not installed, the `brew` install process will ask if you want to install. Type `y` to install.
42-
3. Wait for `brew` to install the XCode Command Line Tools. This make take some time.
43-
4. Once `brew` is finished, confirm the XCode Command Line Tools have installed by opening a new terminal and inputting `clang --version`.
52+
For Windows and MacOS, the development headers and libraries should be installed automatically.
4453

45-
Once `brew` is installed, you can install CMake using these steps:
46-
1. Install CMake by running `brew install cmake`.
47-
2. Once the install is finished, close the terminal and reopen it.
48-
3. Confirm CMake is installed by running `cmake --version`.
54+
On Linux, the development headers and libaries are installed seperately and can be installed using the following commands depending on your Linux distro:
55+
* Ubuntu: `sudo apt-get install python3-dev`
56+
* Arch Linux: `sudo pacman -S python3-dev`
57+
* Distros supporting `yum`: `sudo yum install python3-devel`
4958

50-
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)
51-
and install XCode Command Line Tools though the installer. You can find steps to install the XCode Command Line tools here: [Install XCode Command Line Tools](#macos-xcode-command-line-tools)
59+
## Windows Instructions
5260

53-
#### CMake using official precompiled download
61+
### Windows C++ Compilers
5462

55-
You can also install CMake using a precompiled binary using the following steps:
63+
#### MinGW-w64
5664

57-
1. Go to [cmake.org/install](https://cmake.org/install/).
58-
2. Follow the install instructions for MacOS on the website page.
59-
3. Once CMake is installed and added to the path, confirm it's working by running `cmake --version`.
65+
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.
6066

61-
### Cmake 3.1 on Linux
67+
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).
6268

63-
#### Install CMake on Ubuntu
69+
1. Download and run the MSYS2 installer from the [MSYS2 website](https://www.msys2.org/).
70+
2. Follow the install instructions on the [MSYS2 website](https://www.msys2.org/).
71+
* Make sure to follow the instructions on the website for updating the database and base packages!
72+
* Installing MinGW-w64 may be part of these instructions. If so, install MinGW-w64 using the instructions there.
73+
3. If MinGW-w64 was not part of the install instructions for MSYS2, run `pacman -S --needed base-devel mingw-w64-x85_64-toolchain`.
74+
4. Next you need to add MinGW to your windows `PATH` environment variables so you can run it from the terminal.
75+
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.
76+
6. Once the Windows Settings window is open, search for `Edit environment variables for your account`.
77+
7. Select the `Path` variable in the `User variables` property and press the `Edit` button.
78+
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.
79+
9. Once you have added the path to the `Path` variable in the `User variables` property, select `OK` and save.
80+
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.
81+
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.
6482

65-
1. Open the Ubuntu Software Center
66-
2. In the search bar enter `cmake` and select `CMake - cross-platform build system` from the list
67-
3. Press the `install` button
68-
4. After CMake has installed open a new terminal
69-
5. Type `cmake --version` to confirm CMake is installed
83+
#### MSVC
7084

71-
Or using the command line:
85+
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.
7286

73-
1. Open a new terminal
74-
2. Run `sudo snap install cmake` to install CMake from the snap store
75-
3. After CMake has installed, close the terminal and reopen it
76-
4. Type `cmake --version` to confirm CMake is installed
87+
Install Visual Studio with MSVC
88+
1. Download **Visual Studio Installer** https://visualstudio.microsoft.com/downloads/
89+
2. Run the installer, check the **Desktop development with C++** workload and select Install.
90+
3. Verify your MSVC installation
91+
* In Windows Start up Menu, try open "Developer Command Prompt for VS".
92+
* In the opened terminal/console window, type `cl.exe` and it *should* output the compiler version.
93+
* You can also find the compiler version by opening Visual Studio by selecting `help` and then `about`.
7794

78-
#### Install CMake on Arch Linux
95+
If using MSVC, you will need to use the Developer Command Prompt instead of the standard terminal when compiling the SDK and samples.
7996

80-
1. Open a new terminal.
81-
2. Run `sudo pacman -S cmake` to install Cmake
82-
3. After CMake has installed, close the terminal and reopen it
83-
4. Type `cmake --version` to confirm CMake is installed.
97+
### Windows CMake
8498

99+
#### MinGW-w64
85100

86-
## Python headers and libraries
101+
If you installed MinGW-w64 via `MSYS32` in the steps above, you can easily install CMake using the following:
87102

88-
For Windows and MacOS, the development headers and libraries should be installed automatically.
103+
1. Run `pacman -S mingw-w64-x86_64-cmake`.
104+
2. You will also need to install a build tool. You can install `ninja` or `make`.
105+
3. To install `ninja` run `pacman -S mingw-w64-x86_64-ninja`.
106+
4. To install `make` run `pacman -S mingw-w64-x86_64-make`.
107+
5. Run `cmake --version` to check that CMake is properly installed.
89108

90-
On Linux, the development headers and libaries are installed seperately and can be installed using the following commands depending on your Linux distro:
91-
* Ubuntu: `sudo apt-get install python3-dev`
92-
* Arch Linux: `sudo pacman -S python3-dev`
93-
* Distros supporting `yum`: `sudo yum install python3-devel`
109+
#### Manual Install
94110

111+
You can also install CMake manually by following the install instructions on the CMake website:
95112

96-
## C/C++ Compiler
113+
1. Download CMake3.1+ for Windows: https://cmake.org/download/
114+
2. Run the Cmake Installer.
115+
4. Next you need to add CMake to your windows `PATH` environment variables so you can run it from the terminal.
116+
* 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`.
117+
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.
118+
6. Once the Windows Settings window is open, search for `Edit environment variables for your account`.
119+
7. Select the `Path` variable in the `User variables` property and press the `Edit` button.
120+
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.
121+
9. Once you have added the path to the `Path` variable in the `User variables` property, select `OK` and save.
122+
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.
123+
11. Run `cmake --version` to check that CMake is properly installed.
97124

98-
First, check if you need to install a C/C++ compiler by running one of the following commands:
125+
### Windows Python headers and development libraries
99126

100-
``` sh
101-
g++ --version
102-
```
127+
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/)
103128

104-
``` sh
105-
clang --version
106-
```
129+
The development headers and libraries should be installed automatically when you install Python.
107130

108-
If you get a message with a version number, then you already have a C/C++ compiler and do not need to install anything else.
109131

110-
### Windows
132+
## MacOS Instructions
111133

112-
You can compile C and C++ code through MSVC. To install Visual Studio with MSVC, follow these steps:
113-
1. Download **Visual Studio Installer** https://visualstudio.microsoft.com/downloads/
114-
2. Run the installer, check the **Desktop development with C++** workload and select Install.
115-
3. Verify your MSVC installation
116-
* In Windows Start up Menu, try open "Developer Command Prompt for VS"
134+
### MacOS C++ Compiler
135+
136+
#### XCode Command Line Tools using `brew`
137+
138+
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`.
139+
140+
[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:
141+
142+
1. Open a new terminal and input the following command:
143+
``` sh
144+
bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
145+
```
146+
2. If XCode Command Line Tools are not installed, the `brew` install process will ask if you want to install. Type `y` to install.
147+
3. Wait for `brew` to install the XCode Command Line Tools. This make take some time.
148+
4. Once `brew` is finished, confirm the XCode Command Line Tools have installed by opening a new terminal and inputting `clang --version`.
149+
150+
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.
117151

118-
### MacOS (XCode Command Line Tools)
152+
##### XCode Command Line Tools using installer
119153

120-
To compile C/C++ code on MacOS, you will need to install the Command Line Tools using the following steps:
154+
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:
121155

122156
1. Go to [developer.apple.com/downloads](https://developer.apple.com/download/all/).
123157
2. Input your AppleID to access the developer downloads.
@@ -126,10 +160,61 @@ To compile C/C++ code on MacOS, you will need to install the Command Line Tools
126160
5. Once downloaded, double click the `.dmg` and follow the installer instructions.
127161
6. Confirm XCode Command Line Tools have installed by opening a new terminal and inputting `clang --version`.
128162

129-
### Linux
130-
#### Install GCC or Clang on Ubuntu
163+
### MacOS CMake
164+
#### CMake using `brew`
165+
166+
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:
167+
168+
1. Confirm you have `brew` installed:
169+
``` sh
170+
brew --version
171+
```
172+
2. Install CMake by running `brew install cmake`.
173+
3. Close any console/terminal windows you have open. This is to refresh the console/terminal so it uses the latest changes.
174+
4. Confirm CMake is installed by running `cmake --version`.
175+
176+
#### Manual Install
177+
178+
You can also install CMake manually by following the install instructions on the CMake website:
179+
180+
1. Go to [cmake.org/install](https://cmake.org/install/).
181+
2. Follow the install instructions for MacOS on the website page.
182+
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.
183+
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:
184+
``` sh
185+
sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install
186+
```
187+
5. This will create the symlinks so you can run CMake from the terminal.
188+
6. Close any console/terminal windows you have open. This is to refresh the console/terminal so it uses the latest changes.
189+
190+
### MacOS Python headers and development libraries
191+
192+
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:
193+
* Using `brew` (steps to [install `brew`](##cmake-31-on-mac)): `brew install python`.
194+
* Download the Python installer from the official Python website: [Python Website](https://www.python.org/downloads/macos/)
131195

132-
To compile C/C++ code on Ubuntu Linux, you will need to follow these steps:
196+
The development headers and libraries should be installed automatically when you install Python.
197+
198+
199+
## Linux instructions
200+
201+
### Linux C++ Compilers
202+
203+
Many Linux operating systems have C++ compilers installed by default, so you might already `clang` or `gcc` preinstalled.
204+
To test, try running the following in a new terminal:
205+
206+
``` sh
207+
clang --version
208+
```
209+
``` sh
210+
gcc --version
211+
```
212+
213+
If these commands fail, then please follow the instructions below for installing a C++ compiler on your Linux operating system.
214+
215+
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.
216+
217+
#### Install GCC or Clang on Ubuntu
133218

134219
1. Open a new terminal
135220
2. (optional) Run `sudo apt-get update` to get latest package updates.
@@ -140,9 +225,47 @@ To compile C/C++ code on Ubuntu Linux, you will need to follow these steps:
140225

141226
#### Install GCC or Clang on Arch Linux
142227

143-
To compile C/C++ code on Arch Linux, you will need to follow these steps:
144-
145228
1. Open a new terminal.
146229
2. Run `sudo pacman -S gcc` to install GCC or `sudo pacman -S clang` to install Clang.
147230
3. Once the install is finished, close the terminal and reopen it.
148231
4. Confirm Clang is installed by running `gcc --version`.
232+
233+
### Linux CMake
234+
235+
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.
236+
237+
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.
238+
239+
#### Install CMake on Ubuntu
240+
241+
1. Open the Ubuntu Software Center
242+
2. In the search bar enter `cmake` and select `CMake - cross-platform build system` from the list
243+
3. Press the `install` button
244+
4. After CMake has installed open a new terminal
245+
5. Type `cmake --version` to confirm CMake is installed
246+
247+
Or using the command line:
248+
249+
1. Open a new terminal
250+
2. Run `sudo snap install cmake` to install CMake from the snap store
251+
3. After CMake has installed, close the terminal and reopen it
252+
4. Type `cmake --version` to confirm CMake is installed
253+
254+
#### Install CMake on Arch Linux
255+
256+
1. Open a new terminal.
257+
2. Run `sudo pacman -S cmake` to install Cmake
258+
3. After CMake has installed, close the terminal and reopen it
259+
4. Type `cmake --version` to confirm CMake is installed.
260+
261+
### Linux Python headers and development libraries
262+
263+
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:
264+
* Ubuntu: `sudo apt-get install python3`
265+
* Arch Linux: `sudo pacman -S python3`
266+
* Linux Distros that support `yum`: `sudo yum install python3`
267+
268+
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:
269+
* Ubuntu: `sudo apt-get install python3-dev`
270+
* Arch Linux: `sudo pacman -S python3-dev`
271+
* Distros supporting `yum`: `sudo yum install python3-devel`

0 commit comments

Comments
 (0)