Repository: incubator-mynewt-site Updated Branches: refs/heads/master 296699c82 -> 1be654db9
Simplified installation for newt and newtmgr. Updates to vanity domain. #171 and #172 Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/76f060f3 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/76f060f3 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/76f060f3 Branch: refs/heads/master Commit: 76f060f36dfeca4ec89c31fa029615768bc3e9ef Parents: 296699c Author: aditihilbert <[email protected]> Authored: Tue Apr 18 12:11:41 2017 -0700 Committer: aditihilbert <[email protected]> Committed: Tue Apr 18 12:11:41 2017 -0700 ---------------------------------------------------------------------- docs/faq/go_env.md | 143 +++++++++++++++++++++++++++++++++++++ docs/newtmgr/install_linux.md | 71 ++++++++++++++++++ docs/newtmgr/install_mac.md | 114 +++++++++++++++++++++++++++++ 3 files changed, 328 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/76f060f3/docs/faq/go_env.md ---------------------------------------------------------------------- diff --git a/docs/faq/go_env.md b/docs/faq/go_env.md new file mode 100644 index 0000000..8771ee1 --- /dev/null +++ b/docs/faq/go_env.md @@ -0,0 +1,143 @@ +## Contributing to Newt and Newtmgr Tools +Newt and Newtmgr are written in Go (golang). This guide shows you how to install Go and setup your environment if +you would like to contribute to the newt or newtmgr tools. + +This guide shows you how to perform the following: + +1. Install Go on either Mac OS or Linux. +2. Setup the Go environment. +3. Download the newt and newtmgr source code. +4. Build the newt and newtmgr tools. +5. Update and rebuild the tools. + +Steps 2-5 apply to both Mac OS and Linux platforms. + +**Note:** You will also need to read and follow the instructions from [FAQ](/faq/answers/) to set up your git repos to submit changes. + + +### Step 1: Installing Go +The latest master branch of newt and newtmgr requires GO version 1.6 or higher. +<br> +#### Installing Go on Mac OS X + +If you do not have Homebrew installed, run the following command. You will be prompted for your sudo password. + +```no-highlight +$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +``` +You can also extract (or `git clone`) Homebrew and install it to /usr/local. + +<br> +Use brew to install Go: + +```no-highlight +$ brew install go +==> +... +... +==> *Summary* +ðº //usr/local/Cellar/go/1.8.1: 7,030 files, 281.8MB, built in 1 minute 12 seconds +``` +You can also download the Go package directly from (https://golang.org/dl/) instead of brewing it. Install it in /usr/local directory. + +<br> +#### Installing Go on Linux + +Use apt-get to install Go: +```no-highlight +$sudo apt-get update +$sudo apt-get install golang +Reading package lists... Done +Building dependency tree +Reading state information... Done + + ... + +The following NEW packages will be installed: + golang +0 upgraded, 1 newly installed, 0 to remove and 43 not upgraded. +Need to get 0 B/2,812 B of archives. +After this operation, 10.2 kB of additional disk space will be used. +Selecting previously unselected package golang. +(Reading database ... 244990 files and directories currently installed.) +Preparing to unpack .../golang_2%3a1.6.1+1ubuntu2_all.deb ... +Unpacking golang (2:1.6.1+1ubuntu2) ... +Setting up golang (2:1.6.1+1ubuntu2) ... +$ go version +go version go1.6.3 linux/amd64 +``` +<br> +###Step 2: Setting Up Your Go Environment +Go provides an environment to compile Go code, construct Go packages, and import Go code. You will use Go commands to import the **newt** repository into your local Go environment. The Go language environment dictates a specific directory structure, or workspace in Go parlance. It must contain three sibling directories with the names **src**, **pkg** and **bin**: + +* src contains Go source files organized into packages (one package per directory) +* pkg contains package objects +* bin contains executable commands. + +The **GOPATH** environment variable specifies the location of your workspace. To setup this workspace environment, create a **dev** directory and then a **go** directory under it. Set the GOPATH environment variable to this directory where you will clone the newt repository. + +```no-highlight +$ cd $HOME +$ mkdir -p dev/go +$ cd dev/go +$ export GOPATH=`pwd` +``` +<br> +Add the export GOPATH statement to the ~/.bash_profile file and source the file: + +```no-highlight +$ vi ~/.bash_profile +$ source ~/.bash_profile +``` + +<br> + + +###Step 3: Downloading the Source + +Use Go commands to retrieve the latest source from the newt repository (currently the ASF incubator directory). Check that the directories are installed. + +```no-highlight +$ go get mynewt.apache.org/newt/... +$ ls $GOPATH/src/mynewt.apache.org/newt +DISCLAIMER NOTICE newt newtvm viper +LICENSE README.md newtmgr util yaml +``` + +<br> + +### Step 4: Building the Newt and Newtmgr Tools +Perform the following commands to build the tools: +```no-highlight +$ cd $GOPATH/src/mynewt.apache.org/newt/newt +$ go install +$ ls $GOPATH/bin/ +newt newtmgr newtvm +``` + +<br> + +### Step 5: Updating and Rebuilding the Tools +Change to the directory where you initially installed the source: + +```no-highlight +$ cd $GOPATH/src/mynewt.apache.org/newt +``` +<br> +Pull the latest source from the repository (you can change to a different branch using git checkout [branch] if you need to) +```no-highlight +$ git pull +``` +<br> +Install the tools from the latest source: +```no-highlight +$ cd newt +$ go install +$ cd ../newtmgr +$ go install +$ ls $GOPATH /bin/ +newt newtmgr newtvm +``` + +This should have updated your newt and newtmgr to the latest version based on the git repository you used. + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/76f060f3/docs/newtmgr/install_linux.md ---------------------------------------------------------------------- diff --git a/docs/newtmgr/install_linux.md b/docs/newtmgr/install_linux.md new file mode 100644 index 0000000..faece9f --- /dev/null +++ b/docs/newtmgr/install_linux.md @@ -0,0 +1,71 @@ + +# Installing Newtmgr on Linux + +This page shows you how to install newtmgr from source code on Linux. + +### Install Go (golang) + +Install Go if it is not installed. The Newtmgr tool version 1.0.0 requires Go version 1.7 or later. Currently, the latest Go version that Ubuntu installs is +1.6. You can run `apt-get install golang-1.7-go` to install version 1.7. You can also download version 1.7 from [https:/ +/golang.org/dl/](https://golang.org/dl/). + +```hl_lines="1 7" +$sudo apt-get install golang-1.7-go +Reading package lists... Done + ... +Unpacking golang-1.7-go (1.7.1-2ubuntu1) ... +Setting up golang-1.7-go (1.7.1-2ubuntu1) ... +$ +$sudo ln -sf ../lib/go-1.7/bin/go /usr/bin/go +$go version +go version go1.7.1 linux/amd64 +``` +<br> + +To use go, you must set a `$GOPATH` variable in your environment. This tells +go where to put all the packages it downloads, builds and runs. + +```no-highlight +$ mkdir $HOME/dev +$ export GOPATH=$HOME/dev/Go +``` + +<br> + +Its best to add this to your `.profile` so its set automatically for your +environment. + +<br> + +### Download the newtmgr source + +You will first download the source code for newt. + +```no-highlight +go get mynewt.apache.org/newt/... +``` + +<br> + +### Building newtmgr + +Change into the directory where the newmgr tool was downloaded and +install the newtmgr tool + +```no-highlight +$cd $GOPATH/src/mynewt.apache.org/newt/newtmgr +$go install +$ls $GOPATH/bin +... newtmgr ... +``` + +<br> + +**Note:** If the `go install` command results in errors indicating some package +cannot be found, do a `go get` to download all the third-party files needed +from github.com and then run `go install` again. + +### Add to your Path + +Add your `$GOPATH/bin` directory to your path. + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/76f060f3/docs/newtmgr/install_mac.md ---------------------------------------------------------------------- diff --git a/docs/newtmgr/install_mac.md b/docs/newtmgr/install_mac.md new file mode 100644 index 0000000..5586c2b --- /dev/null +++ b/docs/newtmgr/install_mac.md @@ -0,0 +1,114 @@ +## Installing Newtmgr on Mac OS + +Newtmgr is supported on Mac OS X 64 bit platforms and has been tested on Mac OS 10.9 and higher. + +This page shows you how to install the following versions of newtmgr: + +* The latest stable release version (1.0.0) +* The latest from the master branch (unstable) + +**Note:** If you would like to contribute to the newtmgr tool, see [Setting Up Go Environment to Contribute to Newt and Newtmgr Tools](/faq/go_env). +### Adding the runtimeco/homebrew-mynewt Tap: +You should have added the runtimeco/homebrew-mynewt tap when you installed the *newt* tool. Run the following commands if you have not done so: + +```no-highlight +$brew tap runtimeco/homebrew-mynewt +$brew update +``` +<br> +### Installing the Latest Release Version of Newtmgr +Install the latest stable release version (1.0.0) of newtmgr: +```no-highlight +brew install mynewt-newtmgr +==> Installing mynewt-newtmgr from runtimeco/mynewt +==> Downloading https://github.com/runtimeco/binary-releases/raw/master/mynewt-newt-tools_1.0.0/mynewt-newtmgr-1.0.0.mavericks.bottle.tar.gz +==> Downloading from https://raw.githubusercontent.com/runtimeco/binary-releases/master/mynewt-newt-tools_1.0.0/mynewt-newtmgr-1.0.0.maveric +######################################################################## 100.0% +==> Pouring mynewt-newtmgr-1.0.0.mavericks.bottle.tar.gz +ðº /usr/local/Cellar/mynewt-newtmgr/1.0.0: 3 files, 15.2MB +``` +<br> +**Note:** This installs the newtmgr 1.0.0 binary that has been tested on Mac OS 10.9 and higher. If you are running an earlier version of Mac OS, the installation will install the latest version of Go and compile newtmgr locally. + +<br> +Check that you are using the installed version of newtmgr: +```no-highlight +$which newtmgr +/usr/local/bin/newtmgr +ls -l /usr/local/bin/newtmgr +lrwxr-xr-x 1 user staff 42 Apr 15 09:14 /usr/local/bin/newtmgr -> ../Cellar/mynewt-newtmgr/1.0.0/bin/newtmgr +``` +**Note:** If you previously built newtmgr from source and the output of `which newtmgr` shows "$GOPATH/bin/newtmgr", you will need to move "$GOPATH/bin" after "/usr/local/bin" in your $PATH. + +<br> +Get information about newtmgr: +```no-highlight +$newtmgr help +Newtmgr helps you manage remote devices running the Mynewt OS + +Usage: + newtmgr [flags] + newtmgr [command] + +Available Commands: + config Read or write a config value on a device + conn Manage newtmgr connection profiles + crash Send a crash command to a device + datetime Manage datetime on a device + echo Send data to a device and display the echoed back data + fs Access files on a device + image Manage images on a device + log Manage logs on a device + mpstats Read memory pool statistics from a device + reset Send reset request to a device + run Run test procedures on a device + stat Read statistics from a device + taskstats Read task statistics from a device + +Flags: + -c, --conn string connection profile to use + -h, --help Help for newtmgr commands + -l, --loglevel string log level to use (default "info") + -t, --trace print all bytes transmitted and received + +Use "newtmgr [command] --help" for more information about a command. +``` +<br> +#### Installing Newtmgr from the Master Branch +We recommend that you use the latest stable release version (1.0.0) of newtmgr. If you would like to use the master branch with the latest updates, you can install newtmgr from the HEAD of the master branch. + +** Notes: ** + +* The master branch may be unstable. +* This installation will install the latest version of Go on your computer, if it is not installed, and compile newtmgr locally. + +<br> +If you already installed newtgmr, unlink the current version: +```no-highlight +$brew unlink mynewt-newtmgr +``` +<br> +Install the latest unstable version of newtmgr from the master branch: +```no-highlight +$brew install --HEAD mynewt-newtmgr +==> Installing mynewt-newtmgr from runtimeco/mynewt +==> Cloning https://github.com/apache/incubator-mynewt-newt.git +Cloning into '/Users/<user>/Library/Caches/Homebrew/mynewt-newtmgr--git'... +remote: Counting objects: 623, done. +remote: Compressing objects: 100% (501/501), done. +remote: Total 623 (delta 154), reused 323 (delta 84), pack-reused 0 +Receiving objects: 100% (623/623), 1.10 MiB | 0 bytes/s, done. +Resolving deltas: 100% (154/154), done. +==> Checking out branch master +==> go install +ðº /usr/local/Cellar/mynewt-newtmgr/HEAD-409f7d3: 3 files, 15.1MB, built in 14 seconds +``` +<br> +To switch back to the stable release version (1.0.0) of newtmgr, you can run: +```no-highlight +$brew switch mynewt-newtmgr 1.0.0 +Cleaning /usr/local/Cellar/mynewt-newtmgr/1.0.0 +Cleaning /usr/local/Cellar/mynewt-newtmgr/HEAD-409f7d3 +1 links created for /usr/local/Cellar/mynewt-newtmgr/1.0.0 +``` +<br>
