Skip to content

Commit b819a27

Browse files
TwistedTwiglegTwistedTwigleg
authored
Readme install instructions update (#245)
Commit log: * Updated README to use prerequisites and follow the same format as the other V2 SDKs * Fix typo * Moved prerequisites to documents folder, adjusted code for running CRT repo from SDK * Split the installation into seperate categories
1 parent 9c24718 commit b819a27

File tree

2 files changed

+295
-22
lines changed

2 files changed

+295
-22
lines changed

‎README.md

Lines changed: 51 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -21,37 +21,66 @@ to JS by the [awscrt](https://github.com/awslabs/aws-crt-nodejs) package.
2121

2222

2323
## Installation
24-
### Check for minimum Requirements
25-
* The AWS IoT Device SDK for JavaScript requires Node v10.0 or later.
26-
```
27-
node -v
28-
```
2924

30-
### Install the required libraries using apt
31-
```
32-
sudo apt-get install cmake
33-
sudo apt-get install libssl-dev
34-
```
25+
### Minimum Requirements
3526

36-
### Install the required libraries using yum
37-
```
38-
sudo yum install cmake
39-
sudo yum install openssl-devel
40-
```
27+
For use with Node, the following are required:
28+
* Node v10.0+
29+
* Run `node -v` to check Node version.
30+
* CMake 3.1+
31+
* `libssl-dev` or `openssl-dev` (on Linux)
4132

42-
### Install the AWS Common Runtime
43-
```
44-
npm install aws-crt
45-
```
33+
[Step-by-step instructions](./documents/PREREQUISITES.md)
4634

47-
### Install the AWS IoT Device SDK
48-
```
35+
### Build SDK in existing project with NPM
36+
``` sh
37+
# Navigate to the Javascript project you want to add the
38+
# Javascript V2 SDK to.
39+
cd <your javascript project here>
40+
# Install the V2 SDK.
4941
npm install aws-iot-device-sdk-v2
42+
# Now you can use the Javascript V2 SDK in your project.
5043
```
5144

52-
### Build from source
45+
### Build the V2 SDK from source
46+
47+
``` sh
48+
# Create a workspace directory to hold all the SDK files.
49+
mkdir sdk-workspace
50+
cd sdk-workspace
51+
# Clone the repository to access the samples.
52+
git clone --recursive https://github.com/aws/aws-iot-device-sdk-js-v2.git
53+
# Ensure all submodules are properly updated.
54+
cd aws-iot-device-sdk-js-v2
55+
git submodule update --init --recursive
56+
# Install the SDK.
57+
npm install
58+
# Then you can run the samples following the instructions in the samples README.
5359
```
60+
61+
### Build the V2 SDK and CRT from source
62+
63+
``` sh
64+
# Create a workspace directory to hold all the SDK files.
65+
mkdir sdk-workspace
66+
cd sdk-workspace
67+
# Clone the CRT repository.
68+
# (Use the latest version of the CRT here instead of "v1.12.4").
69+
git clone --branch v1.12.4 --recurse-submodules https://github.com/awslabs/aws-crt-nodejs.git
70+
# Ensure all submodules are properly updated.
71+
cd aws-crt-nodejs
72+
git submodule update --init --recursive
73+
cd ..
74+
# Clone the SDK repository.
75+
git clone --recursive https://github.com/aws/aws-iot-device-sdk-js-v2.git
76+
# Ensure all submodules are properly updated.
77+
cd aws-iot-device-sdk-js-v2
78+
git submodule update --init --recursive
79+
# Install the CRT.
80+
npm install ../aws-crt-nodejs
81+
# Install the SDK.
5482
npm install
83+
# Then you can run the samples following the instructions in the samples README.
5584
```
5685

5786
## Samples

‎documents/PREREQUISITES.md

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# PREREQUISITES
2+
3+
## Node v10.0+
4+
5+
You will need to install NodeJS in orderto run the SDK on Windows, MacOS, and Linux. You can find installers for NodeJS on the NodeJS website's download page: [NodeJS Download](https://nodejs.org/en/download/). Just download the installer for your platform and follow the prompts to install.
6+
7+
You can also install NodeJS using Linux package managers if you are on Linux or using `brew` if you are on MacOS. Instructions for both are listed further below.
8+
9+
Once installed, you can check which version of Node you have installed using
10+
``` sh
11+
node -v
12+
```
13+
14+
## C++ 11 Compiler
15+
16+
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:
17+
18+
* Clang: 3.9 or higher
19+
* GCC: 4.8 or higher
20+
* MSVC: 2015 or higher
21+
22+
Listed below are ways to install C++ 11 compilers on [Windows](#windows-c-compilers), [MacOS](#macos-c-compiler), and [Linux](#linux-c-compilers).
23+
24+
## CMake 3.1+
25+
26+
You will also need CMake to build the SDK. The minimum required version is CMake 3.1.
27+
28+
Below are the instructions to install CMake in a non-platform specific way:
29+
30+
1. Download CMake3.1+ for your platform: https://cmake.org/download/
31+
2. Run the Cmake Installer. Make sure you add CMake into **PATH**.
32+
3. Restart the command prompt / terminal.
33+
34+
Listed below are also instructions to install CMake on [Windows](#windows-cmake), [MacOS](#macos-cmake), and [Linux](#linux-cmake).
35+
36+
## Windows Instructions
37+
38+
### Windows Node v10.0+
39+
40+
The official NodeJS website provides a installer for Windows NodeJS on [their download page](https://nodejs.org/en/download/). Just download the installer for Windows and follow the prompts to install.
41+
42+
### Windows C++ Compilers
43+
44+
#### MinGW-w64
45+
46+
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.
47+
48+
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).
49+
50+
1. Download and run the MSYS2 installer from the [MSYS2 website](https://www.msys2.org/).
51+
2. Follow the install instructions on the [MSYS2 website](https://www.msys2.org/).
52+
* Make sure to follow the instructions on the website for updating the database and base packages!
53+
* Installing MinGW-w64 may be part of these instructions. If so, install MinGW-w64 using the instructions there.
54+
3. If MinGW-w64 was not part of the install instructions for MSYS2, run `pacman -S --needed base-devel mingw-w64-x85_64-toolchain`.
55+
4. Next you need to add MinGW to your windows `PATH` environment variables so you can run it from the terminal.
56+
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.
57+
6. Once the Windows Settings window is open, search for `Edit environment variables for your account`.
58+
7. Select the `Path` variable in the `User variables` property and press the `Edit` button.
59+
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.
60+
9. Once you have added the path to the `Path` variable in the `User variables` property, select `OK` and save.
61+
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.
62+
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.
63+
64+
#### MSVC
65+
66+
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.
67+
68+
Install Visual Studio with MSVC
69+
1. Download **Visual Studio Installer** https://visualstudio.microsoft.com/downloads/
70+
2. Run the installer, check the **Desktop development with C++** workload and select Install.
71+
3. Verify your MSVC installation
72+
* In Windows Start up Menu, try open "Developer Command Prompt for VS".
73+
* In the opened terminal/console window, type `cl.exe` and it *should* output the compiler version.
74+
* You can also find the compiler version by opening Visual Studio by selecting `help` and then `about`.
75+
76+
If using MSVC, you will need to use the Developer Command Prompt instead of the standard terminal when compiling the SDK and samples.
77+
78+
### Windows CMake
79+
80+
#### MinGW-w64
81+
82+
If you installed MinGW-w64 via `MSYS32` in the steps above, you can easily install CMake using the following:
83+
84+
1. Run `pacman -S mingw-w64-x86_64-cmake`.
85+
2. You will also need to install a build tool. You can install `ninja` or `make`.
86+
3. To install `ninja` run `pacman -S mingw-w64-x86_64-ninja`.
87+
4. To install `make` run `pacman -S mingw-w64-x86_64-make`.
88+
5. Run `cmake --version` to check that CMake is properly installed.
89+
90+
#### Manual Install
91+
92+
You can also install CMake manually by following the install instructions on the CMake website:
93+
94+
1. Download CMake3.1+ for Windows: https://cmake.org/download/
95+
2. Run the Cmake Installer.
96+
4. Next you need to add CMake to your windows `PATH` environment variables so you can run it from the terminal.
97+
* 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`.
98+
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.
99+
6. Once the Windows Settings window is open, search for `Edit environment variables for your account`.
100+
7. Select the `Path` variable in the `User variables` property and press the `Edit` button.
101+
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.
102+
9. Once you have added the path to the `Path` variable in the `User variables` property, select `OK` and save.
103+
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.
104+
11. Run `cmake --version` to check that CMake is properly installed.
105+
106+
107+
## MacOS Instructions
108+
109+
### MacOS Node v10.0+
110+
111+
The official NodeJS website provides a installer for MacOS NodeJS on [their download page](https://nodejs.org/en/download/). Just download the installer for MacOS and follow the prompts to install.
112+
113+
You can also install NodeJS on MacOS using `brew` with the following command:
114+
115+
``` sh
116+
brew install node
117+
```
118+
119+
### MacOS C++ Compiler
120+
121+
#### XCode Command Line Tools using `brew`
122+
123+
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`.
124+
125+
[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:
126+
127+
1. Open a new terminal and input the following command:
128+
``` sh
129+
bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
130+
```
131+
2. If XCode Command Line Tools are not installed, the `brew` install process will ask if you want to install. Type `y` to install.
132+
3. Wait for `brew` to install the XCode Command Line Tools. This make take some time.
133+
4. Once `brew` is finished, confirm the XCode Command Line Tools have installed by opening a new terminal and inputting `clang --version`.
134+
135+
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.
136+
137+
##### XCode Command Line Tools using installer
138+
139+
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:
140+
141+
1. Go to [developer.apple.com/downloads](https://developer.apple.com/download/all/).
142+
2. Input your AppleID to access the developer downloads.
143+
3. From the presented list, scroll until you find `Command Line Tools for Xcode <version>`.
144+
4. Select `view more details` and then select `Additionals Tools for Xcode <version>.dmg`.
145+
5. Once downloaded, double click the `.dmg` and follow the installer instructions.
146+
6. Confirm XCode Command Line Tools have installed by opening a new terminal and inputting `clang --version`.
147+
148+
### MacOS CMake
149+
#### CMake using `brew`
150+
151+
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:
152+
153+
1. Confirm you have `brew` installed:
154+
``` sh
155+
brew --version
156+
```
157+
2. Install CMake by running `brew install cmake`.
158+
3. Close any console/terminal windows you have open. This is to refresh the console/terminal so it uses the latest changes.
159+
4. Confirm CMake is installed by running `cmake --version`.
160+
161+
#### Manual Install
162+
163+
You can also install CMake manually by following the install instructions on the CMake website:
164+
165+
1. Go to [cmake.org/install](https://cmake.org/install/).
166+
2. Follow the install instructions for MacOS on the website page.
167+
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.
168+
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:
169+
``` sh
170+
sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install
171+
```
172+
5. This will create the symlinks so you can run CMake from the terminal.
173+
6. Close any console/terminal windows you have open. This is to refresh the console/terminal so it uses the latest changes.
174+
175+
## Linux
176+
177+
### Linux Node v10.0+
178+
179+
The official NodeJS website provides a installer for Linux NodeJS on [their download page](https://nodejs.org/en/download/). Just download the installer for Linux and follow the prompts to install.
180+
181+
You can also install NodeJS on Linux using the package manager for the Linux operating system on [many Linux operating systems](https://nodejs.org/en/download/package-manager/). Below are the instructions for Ubuntu and Arch Linux:
182+
183+
* Ubuntu: `sudo apt install nodejs`
184+
* Arch Linux: `sudo pacman -S nodejs`
185+
186+
### Linux C++ Compilers
187+
188+
Many Linux operating systems have C++ compilers installed by default, so you might already `clang` or `gcc` preinstalled.
189+
To test, try running the following in a new terminal:
190+
191+
``` sh
192+
clang --version
193+
```
194+
``` sh
195+
gcc --version
196+
```
197+
198+
If these commands fail, then please follow the instructions below for installing a C++ compiler on your Linux operating system.
199+
200+
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.
201+
202+
#### Install GCC or Clang on Ubuntu
203+
204+
1. Open a new terminal
205+
2. (optional) Run `sudo apt-get update` to get latest package updates.
206+
3. (optional) Run `sudo apt-get upgrade` to install latest package updates.
207+
4. Run `sudo apt-get install build-essential` to install GCC or `sudo apt-get install clang` to install Clang.
208+
5. Once the install is finished, close the terminal and reopen it.
209+
6. Confirm GCC is installed by running `gcc --version` or Clang is installed by running `clang --version`.
210+
211+
#### Install GCC or Clang on Arch Linux
212+
213+
1. Open a new terminal.
214+
2. Run `sudo pacman -S gcc` to install GCC or `sudo pacman -S clang` to install Clang.
215+
3. Once the install is finished, close the terminal and reopen it.
216+
4. Confirm Clang is installed by running `gcc --version`.
217+
218+
### Linux CMake
219+
220+
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.
221+
222+
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.
223+
224+
#### Install CMake on Ubuntu
225+
226+
1. Open the Ubuntu Software Center
227+
2. In the search bar enter `cmake` and select `CMake - cross-platform build system` from the list
228+
3. Press the `install` button
229+
4. After CMake has installed open a new terminal
230+
5. Type `cmake --version` to confirm CMake is installed
231+
232+
Or using the command line:
233+
234+
1. Open a new terminal
235+
2. Run `sudo snap install cmake` to install CMake from the snap store
236+
3. After CMake has installed, close the terminal and reopen it
237+
4. Type `cmake --version` to confirm CMake is installed
238+
239+
#### Install CMake on Arch Linux
240+
241+
1. Open a new terminal.
242+
2. Run `sudo pacman -S cmake` to install Cmake
243+
3. After CMake has installed, close the terminal and reopen it
244+
4. Type `cmake --version` to confirm CMake is installed.

0 commit comments

Comments
 (0)