Repository: incubator-mynewt-site Updated Branches: refs/heads/develop 6f5c8273b -> d7a35b7b2
1) Reorganized and updated the Contributing to Newt and Newtmgr Tools section to reflect the separate newtmgr git repo. 2) Added a note to indicate this is the setup to use if a user running on the Linux platform wants the latest updates from master. 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/1db5d8d0 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/1db5d8d0 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/1db5d8d0 Branch: refs/heads/develop Commit: 1db5d8d0cfa4ccb64f6973ece7ab3bf306844dc1 Parents: 6f5c827 Author: cwanda <wa...@happycity.com> Authored: Sun Apr 23 16:21:19 2017 -0700 Committer: cwanda <wa...@happycity.com> Committed: Sun Apr 23 16:21:19 2017 -0700 ---------------------------------------------------------------------- docs/faq/go_env.md | 147 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 103 insertions(+), 44 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/1db5d8d0/docs/faq/go_env.md ---------------------------------------------------------------------- diff --git a/docs/faq/go_env.md b/docs/faq/go_env.md index 8771ee1..a757420 100644 --- a/docs/faq/go_env.md +++ b/docs/faq/go_env.md @@ -1,22 +1,22 @@ -## 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. +## Contributing to Newt or Newtmgr Tools +Newt and Newtmgr are written in Go (golang). This guide shows you how to install Go and setup your environment to update and build the tools if you want to: + +* Contribute to newt or newtmgr features or fix bugs. +* Build the tools with latest updates from the master branch on a Linux platform. This guide shows you how to perform the following: -1. Install Go on either Mac OS or Linux. +1. Install Go on either Mac OS X or Linux. (Tasks that are specific to each platform are called out.) 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. +3. Download the source, build, and install the newt or newtmgr tools. +4. Update and rebuild the tools. -**Note:** You will also need to read and follow the instructions from [FAQ](/faq/answers/) to set up your git repos to submit changes. +**Note:** You will also need to read and follow the instructions from the [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. +The latest master branch of newt and newtmgr requires GO version 1.6 or higher. You can skip this step and proceed to Step 2 if you already have Go version 1.6 or higher installed. + <br> #### Installing Go on Mac OS X @@ -68,13 +68,16 @@ 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**: + +This section describes the Go environment and how to setup a Go workspace. If you already have a Go workspace for your other Go projects, you can skip this step and proceed to Step 3. + +Go provides an environment to compile Go code, construct Go packages, and import Go code. You will use Go commands to import the newt or newtmgr package 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. +* bin contains the Go application executables that Go builds and installs. -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. +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 and newtmgr repositories. ```no-highlight $ cd $HOME @@ -83,61 +86,117 @@ $ cd dev/go $ export GOPATH=`pwd` ``` <br> -Add the export GOPATH statement to the ~/.bash_profile file and source the file: - +Add the following export statements to your ~/.bash_profile file and source the file: ```no-highlight -$ vi ~/.bash_profile -$ source ~/.bash_profile +export GOPATH=$HOME/dev/go +export PATH=$GOPATH/bin:$PATH ``` +<br> + +###Step 3: Downloading the Source and Installing the Tools +Newt and newtmgr are individual Go packages and have their own git repositories. You can download the source and install one or both tools. + +We use the `go get` command to download the source, build, and install the binary in the **$GOPATH/bin** directory. <br> +####Downloading and Installing the Newt Tool +The newt Go package is **mynewt.apache.org/newt/newt** and is stored in the [Apache Mynewt newt tool repository mirrored on github](https://github.com/apache/incubator-mynewt-newt). -###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. +Download the newt package source and install the tool: ```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 +$cd $GOPATH +$go get mynewt.apache.org/newt/newt +$cd $GOPATH/src/mynewt.apache.org/newt +$ls +DISCLAIMER RELEASE_NOTES.md util +INSTALLING.md build.sh viper +LICENSE newt yaml +NOTICE newtmgr +README.md newtvm +$git status +On branch master +Your branch is up-to-date with 'origin/master'. + +nothing to commit, working directory clean ``` +<br> +**Note:** The source code under the **newtmgr** directory is no longer used or updated. The current **newtmgr** source has its own Git repository. <br> +Check that the newt binary is installed and you are using the one from ** $GOPATH/bin**: -### 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 +$ls $GOPATH/bin/newt +~/dev/go/bin/newt +$which newt +~/dev/go/bin/newt +$newt version +Apache Newt (incubating) version: 1.0.0-dev ``` - <br> +####Downloading and Installing the Newtmgr Tool +The newtmgr Go package is **mynewt.apache.org/newtmgr/newtmgr**. It is stored in the [Apache Mynewt newtmgr tool repository mirrored on github](https://github.com/apache/incubator-mynewt-newtmgr). -### Step 5: Updating and Rebuilding the Tools -Change to the directory where you initially installed the source: +Download the newtmgr package and install the tool: ```no-highlight -$ cd $GOPATH/src/mynewt.apache.org/newt +$cd $GOPATH +$go get mynewt.apache.org/newtmgr/newtmgr +$cd $GOPATH/src/mynewt.apache.org/newtmgr +$ls +DISCLAIMER NOTICE newtmgr +LICENSE README.md nmxact +$git status +On branch master +Your branch is up-to-date with 'origin/master'. + +nothing to commit, working directory clean ``` <br> -Pull the latest source from the repository (you can change to a different branch using git checkout [branch] if you need to) +Check that the newtmgr binary is installed and you are using the one from **$GOPATH/bin**: + ```no-highlight -$ git pull +$ls $GOPATH/bin/newtmgr +~/dev/go/bin/newtmgr +$which newt +~/dev/go/bin/newtmgr ``` <br> -Install the tools from the latest source: +### Step 4: Updating and Rebuilding the Tools: +This section shows you how to rebuild the newt and newtmgr tools with the latest updates from the master branch or after you have made changes in your branch. + +Here is the general procedure to rebuild either the newt or newtmgr tool. The only difference is the directory where you will be executing the commands from. You will need to repeat the procedure to rebuild both tools. + +1. Change to the directory where the local Git repository for the tool is installed. +2. Pull the latest changes from the master branch. If you made changes you will need to rebase with **origin master** (See [FAQ](/faq/answers/)). +3. Build and install the tool. + +<br> +Change to the directory where the source for the tool is installed. + +For the **newt** tool: ```no-highlight -$ cd newt -$ go install -$ cd ../newtmgr -$ go install -$ ls $GOPATH /bin/ -newt newtmgr newtvm +$cd $GOPATH/src/mynewt.apache.org/newt/newt ``` -This should have updated your newt and newtmgr to the latest version based on the git repository you used. +For the **newtmgr** tool: +```no-highlight +$cd $GOPATH/src/mynewt.apache.org/newtmgr/newtmgr +``` +<br> +After you change to the specific tool directory, get the latest updates from the master branch. If you made changes and need to rebase with the origin, add the `--rebase origin master` arguments to the `git pull` command: +```no-highlight +$git pull +``` + +<br> +Build and install the tool. The updated binary will be installed in the **$GOPATH/bin** directory: + +```no-highlight +$go install +``` +You can run the `ls -l` command to check the modification time for the binary to ensure the new version is installed.
