Skip to content

docs: install: Update install instructions #602

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

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: install: Update install instructions #602

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7f24319
docs: install: Update install instructions for Linux
Slawek-skrawek Jul 22, 2025
dae11e3
docs: install: Update install instructions for Windows
Slawek-skrawek Jul 22, 2025
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
141 changes: 17 additions & 124 deletions docs/install/newt_linux.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,149 +1,40 @@
Installing Newt on Linux
------------------------

You can install the latest release (1.9.0) of the newt tool from a Debian binary package (amd64). You can also download
and build the latest release version of newt from source.
You can install the latest release of the newt tool from https://mynewt.apache.org/download or download latest sources
directly from GitHub https://github.com/apache/mynewt-newt and build your binary localy.

This page shows you how to:

1. Set up your computer to download Debian binary packages from the JuulLabs-OSS APT repository.

**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. 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.

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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

Method 2: Downloading and Installing the Debian Package Manually
==============================================================================================

Download and install the package manually.

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

$ wget https://raw.githubusercontent.com/JuulLabs-OSS/binary-releases/master/mynewt-newt-tools_1.9.0/newt_1.9.0-1_amd64.deb
$ sudo dpkg -i newt_1.9.0-1_amd64.deb
$ git clone https://github.com/apache/mynewt-newt.git

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

Installing the Latest Release of Newt from a Source Package
Installing Newt from Sources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you are running Linux on a different architecture, you can build and install the latest release version of newt from
source.

The newt tool is written in Go (https://golang.org/). In order to build Apache Mynewt, you must have Go 1.12 or later
installed on your system. Please visit the Golang website for more information on installing Go (https://golang.org/).

#. Download and unpack the newt source:

.. code-block:: console

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

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

.. code-block:: console

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

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

- If you previously built newt from the master branch, you can move the binary to your $GOPATH/bin directory.

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

$ mv newt/newt $GOPATH/bin
$ mkdir ~/bin
$ mv ./newt/newt ~/bin/.
$ export PATH=$PATH:~/bin

- If you are installing newt for the first time and do not have a Go workspace set up, you can move the binary to
/usr/bin or a directory in your PATH:
#. To make newt visible in every new terminal add the export to ~/.bashrc

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

$ mv newt/newt /usr/bin
$ echo 'export PATH=$PATH:~/bin' >> ~/.bashrc

Checking the Installed Version of Newt
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -155,7 +46,7 @@ Checking the Installed Version of Newt
$ which newt
/usr/bin/newt
$ newt version
Apache Newt version: 1.9.0
Apache Newt 1.13.0 / c6bf556 / 2024-11-15_06:58

2. Get information about newt:

Expand Down Expand Up @@ -185,6 +76,7 @@ Checking the Installed Version of Newt
apropos Search manual page names and descriptions
build Build one or more targets
clean Delete build artifacts for one or more targets
completion Generate the autocompletion script for the specified shell
create-image Add image header to target binary
debug Open debugger session to target
docs Project documentation generation commands
Expand Down Expand Up @@ -212,6 +104,7 @@ Checking the Installed Version of Newt
-l, --loglevel string Log level (default "WARN")
-o, --outfile string Filename to tee output to
-q, --quiet Be quiet; only display error output
--shallow int Use shallow clone for git repositories up to specified number of commits
-s, --silent Be silent; don't output anything
-v, --verbose Enable verbose output when executing commands

Expand Down
31 changes: 17 additions & 14 deletions docs/install/newt_windows.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ This guide shows you how to perform the following:

1. Install MSYS2/MinGW.
2. Install Git.
3. Install latest release (1.8.0) of newt from binary.
3. Install latest release of newt from binary.
4. Install go for building newt from source.
5. Install latest release of newt from source.

Expand Down Expand Up @@ -93,7 +93,7 @@ You can install the latest release of newt from binary. It has been tested on Wi

1. Start a MinGW terminal.

2. Download the newt binary tar file `apache-mynewt-newt-bin-windows-1.8.0.tgz <https://www.apache.org/dyn/closer.lua/mynewt/apache-mynewt-1.8.0/apache-mynewt-newt-bin-windows-1.8.0.tgz>`__.
2. Download the latest newt binary tar file for Windows from https://mynewt.apache.org/download.

3. Extract the file:

Expand All @@ -102,13 +102,13 @@ You can install the latest release of newt from binary. It has been tested on Wi

.. code-block:: console

$ tar -xzf apache-mynewt-newt-bin-windows-1.8.0.tgz -C $GOPATH/bin --strip-components=1 apache-mynewt-newt-bin-windows-1.8.0/newt.exe
$ tar -xzf apache-mynewt-newt-bin-windows-x.x.x.tgz -C $GOPATH/bin --strip-components=1 apache-mynewt-newt-bin-windows-x.x.x/newt.exe

- If you are installing newt for the first time and do not have a Go workspace setup, you can extract into /usr/bin directory:

.. code-block:: console

$ tar -xzf apache-mynewt-newt-bin-windows-1.8.0.tgz -C /usr/bin --strip-components=1 apache-mynewt-newt-bin-windows-1.8.0/newt.exe
$ tar -xzf apache-mynewt-newt-bin-windows-x.x.x.tgz -C /usr/bin --strip-components=1 apache-mynewt-newt-bin-windows-x.x.x/newt.exe

4. Verify the installed version of newt. See `Checking the Installed Version`_.

Expand Down Expand Up @@ -136,20 +136,19 @@ source.

1. Start a MinGw terminal.

2. Download and unpack the newt source:
2. Download and unpack the newt source (get version number from https://mynewt.apache.org/download):

.. code-block:: console

$ 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
$ wget -P /tmp https://github.com/apache/mynewt-newt/archive/mynewt_x_x_x_tag.tar.gz
$ tar -xzf /tmp/mynewt_x_x_x_tag.tar.gz

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

.. code-block:: console

$ cd mynewt-newt-mynewt_1_8_0_tag
$ cd mynewt-newt
$ MSYS=winsymlinks:nativestrict ./build.sh
$ rm /tmp/mynewt_1_8_0_tag.tar.gz

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

Expand All @@ -173,14 +172,16 @@ Checking the Installed Version

.. code-block:: console

$ which newt
/usr/bin/newt
$ newt version
Apache Newt 1.8.0 / ab96a8a-dirty / 2020-03-18_23:25
Apache Newt 1.13.0 / c6bf556 / 2024-11-15_06:58

2. Get information about newt:

.. code-block:: console

$ newt help
$ 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
Expand All @@ -204,6 +205,7 @@ Checking the Installed Version
apropos Search manual page names and descriptions
build Build one or more targets
clean Delete build artifacts for one or more targets
completion Generate the autocompletion script for the specified shell
create-image Add image header to target binary
debug Open debugger session to target
docs Project documentation generation commands
Expand All @@ -225,13 +227,14 @@ Checking the Installed Version
version Display the Newt version number

Flags:
--escape Apply Windows escapes to shell commands (default true)
--escape Apply Windows escapes to shell commands
-h, --help Help for newt commands
-j, --jobs int Number of concurrent build jobs (default 8)
-j, --jobs int Number of concurrent build jobs (default 4)
-l, --loglevel string Log level (default "WARN")
-o, --outfile string Filename to tee output to
-q, --quiet Be quiet; only display error output
--shallow int Use shallow clone for git repositories up to specified number of commits
-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.
Use "newt [command] --help" for more information about a command.
Loading