Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update newt_linux.rst #416

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update newt_linux.rst #416

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 37 additions & 102 deletions docs/install/newt_linux.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,108 +1,40 @@
Installing Newt on Linux
------------------------

You can install the latest release (1.5.0) of the newt tool from a Debian binary package (amd64). You can also download
You can install the latest release (1.8.0) of the newt tool by downloading and installing a binary executable (amd64). You can also download
and build the latest release version of newt from source.

This page shows you how to:

1. Set up your computer to download Debian binary packages from the JuulLabs-OSS APT repository.
1. Install the latest release version of newt by manually downloading and installing the binary executable.

**Note:** The key for signing the repository has changed. If you set up your computer before release 1.1.0, you will
need to download and import the public key again.
2. Download, build, and install the latest release version of newt from source.

2. Install the latest release version of newt from a Debian binary package. You can use apt-get to install the package
or manually download and install the Debian binary package.

3. Download, build, and install the latest release version of newt from source.

If you are installing on an amd64 platform, we recommend that you install from the binary package.
If you are installing on an amd64 platform, we recommend that you install the binary executable.

See :doc:`prev_releases` to install an earlier version of newt.

**Note:** We have tested the newt tool binary and apt-get install from the JuulLabs-OSS APT repository for Ubuntu version
1704. Earlier Ubuntu versions (for example: Ubuntu 14) may have incompatibility with the repository. You can manually
download and install the Debian binary package.

**Note:** See :doc:`../../misc/go_env` if you want to:

- Use the newt tool with the latest updates from the master branch. The master branch may be unstable and we recommend
that you use the latest stable release version.
- Contribute to the newt tool.

Setting Up Your Computer to use apt-get to Install the Package
Installing the Latest Release of Newt
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The newt Debian packages are stored in a private APT repository on **https://github.com/JuulLabs-OSS/debian-mynewt**.
To use apt-get, you must set up the following on your computer to retrieve packages from the repository:

**Note**: You only need to perform this setup once on your computer. However, if you previously downloaded and imported
the public key for the JuulLabs-OSS APT repository, you will need to perform step 2 again as the key has changed.

1. Download the public key for the JuulLabs-OSS APT repository and import the key into the apt keychain.
2. Add the repository for the binary and source packages to the apt source list.

Download the public key for the JuulLabs-OSS apt repo (**Note:** There is a ``-`` after ``apt-key add``):

.. code-block:: console

$ wget -qO - https://raw.githubusercontent.com/JuulLabs-OSS/debian-mynewt/master/mynewt.gpg.key | sudo apt-key add -

Add the repository for the binary and source packages to the ``mynewt.list`` apt source list file:

.. code-block:: console

$ sudo tee /etc/apt/sources.list.d/mynewt.list <<EOF
deb https://raw.githubusercontent.com/JuulLabs-OSS/debian-mynewt/master latest main
EOF

**Note:** Previously the repository lived under ``runtimeco/debian-mynewt``, and although
updating should remain working, if it stops pulling in the latest releases, please try updating
``/etc/apt/sources.list.d/mynewt.list`` and substitute ``runtimeco`` by ``JuulLabs-OSS``.

Update the available packages:

.. code-block:: console

$ sudo apt-get update

**Note:** If you are not using Ubuntu version 1704, you may see the following errors. We have provided instructions on
how to manually download and install the binary package.

.. code-block:: console
#. Download and unpack the newt binary executable.

W: Failed to fetch https://raw.githubusercontent.com/JuulLabs-OSS/debian-mynewt/master/dists/latest/main/source/Sources HttpError404

Installing the Latest Release of Newt from a Binary Package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can use either apt-get to install the package, or manually download and install the Debian binary package.

Method 1: Using apt-get to Upgrade or to Install
==============================================================================================

Run the following commands to upgrade or install the latest version of newt:

.. code-block:: console

$ sudo apt-get update
$ sudo apt-get install newt

**Note:** If you encounter build errors (such as missing ``sys/mman.h``), please make sure you have a 32-bit glibc:

.. code-block:: console

$ sudo apt-get install gcc-multilib
.. code-block:: console

Method 2: Downloading and Installing the Debian Package Manually
==============================================================================================
$ wget -P /tmp https://downloads.apache.org/mynewt/apache-mynewt-1.8.0/apache-mynewt-newt-bin-linux-1.8.0.tgz
$ tar -xzf /tmp/apache-mynewt-newt-bin-linux-1.8.0.tgz

Download and install the package manually.
#. Move the executable to /usr/bin or a directory in your PATH:

.. code-block:: console
.. code-block:: console

$ wget https://raw.githubusercontent.com/JuulLabs-OSS/binary-releases/master/mynewt-newt-tools_1.5.0/newt_1.5.0-1_amd64.deb
$ sudo dpkg -i newt_1.5.0-1_amd64.deb
$ mv /tmp/apache-mynewt-newt-bin-linux-1.8.0/newt /usr/bin

See `Checking the Installed Version of Newt`_ to verify that you are using the installed version of newt.

Expand All @@ -116,16 +48,16 @@ source.

.. code-block:: console

$ wget -P /tmp https://github.com/apache/mynewt-newt/archive/mynewt_1_5_0_tag.tar.gz
$ tar -xzf /tmp/mynewt_1_5_0_tag.tar.gz
$ wget -P /tmp https://github.com/apache/mynewt-newt/archive/mynewt_1_8_0_tag.tar.gz
$ tar -xzf /tmp/mynewt_1_8_0_tag.tar.gz

#. Run the build.sh to build the newt tool.

.. code-block:: console

$ cd mynewt-newt-mynewt_1_5_0_tag
$ cd mynewt-newt-mynewt_1_8_0_tag
$ ./build.sh
$ rm /tmp/mynewt_1_5_0_tag.tar.gz
$ rm /tmp/mynewt_1_8_0_tag.tar.gz

#. You should see the ``newt/newt`` executable. Move the executable to a bin directory in your PATH:

Expand All @@ -152,61 +84,64 @@ Checking the Installed Version of Newt
$ which newt
/usr/bin/newt
$ newt version
Apache Newt version: 1.5.0
Apache Newt version: 1.8.0

2. Get information about newt:

.. code-block:: console

$ newt
Newt allows you to create your own embedded application based on the Mynewt
operating system. Newt provides both build and package management in a single
tool, which allows you to compose an embedded application, and set of
projects, and then build the necessary artifacts from those projects. For more
information on the Mynewt operating system, please visit
https://mynewt.apache.org/.

Please use the newt help command, and specify the name of the command you want
Newt allows you to create your own embedded application based on the Mynewt
operating system. Newt provides both build and package management in a single
tool, which allows you to compose an embedded application, and set of
projects, and then build the necessary artifacts from those projects. For more
information on the Mynewt operating system, please visit
https://mynewt.apache.org/.
Please use the newt help command, and specify the name of the command you want
help for, for help on how to use a specific command

Usage:
newt [flags]
newt [command]

Examples:
newt
newt help [<command-name>]
For help on <command-name>. If not specified, print this message.

Available Commands:
apropos Search manual page names and descriptions
build Build one or more targets
clean Delete build artifacts for one or more targets
create-image Add image header to target binary
debug Open debugger session to target
docs Project documentation generation commands
help Help about any command
info Show project info
install Install project dependencies
load Load built target to board
man Browse the man-page for given argument
man-build Build man pages
mfg Manufacturing flash image commands
new Create a new project
pkg Create and manage packages in the current workspace
resign-image Re-sign an image.
resign-image Obsolete
run build/create-image/download/debug <target>
size Size of target components
sync Synchronize project dependencies
target Commands to create, delete, configure, and query targets
test Executes unit tests for one or more packages
upgrade Upgrade project dependencies
vals Display valid values for the specified element type(s)
version Display the Newt version number

Flags:
--escape Apply Windows escapes to shell commands
-h, --help Help for newt commands
-j, --jobs int Number of concurrent build jobs (default 4)
-j, --jobs int Number of concurrent build jobs (default 8)
-l, --loglevel string Log level (default "WARN")
-o, --outfile string Filename to tee output to
-q, --quiet Be quiet; only display error output
-s, --silent Be silent; don't output anything
-v, --verbose Enable verbose output when executing commands

Use "newt [command] --help" for more information about a command.