You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by xi...@apache.org on 2020/12/06 03:43:47 UTC
[incubator-nuttx] branch master updated (e37001f -> 1e7c13d)
This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git.
from e37001f net/setsockopt/IP_MULTICAST_TTL: add handles of different prototypes
new 9c83b40 Documentation: re-enable prev, next buttons
new 1e7c13d Documentation: merge quickstart with the rest of "getting started"
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
Documentation/conf.py | 6 +-
Documentation/quickstart/compiling.rst | 8 +-
Documentation/quickstart/configuring.rst | 18 ++---
Documentation/quickstart/index.rst | 12 +--
Documentation/quickstart/install.rst | 115 ++++++++++++++++------------
Documentation/quickstart/quickstart.rst | 124 -------------------------------
Documentation/quickstart/running.rst | 56 ++++++++------
7 files changed, 119 insertions(+), 220 deletions(-)
delete mode 100644 Documentation/quickstart/quickstart.rst
[incubator-nuttx] 01/02: Documentation: re-enable prev, next buttons
Posted by xi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 9c83b407b409a1e11e4adceb3efc5e59c539f328
Author: Matias N <ma...@protobits.dev>
AuthorDate: Sat Dec 5 23:24:16 2020 -0300
Documentation: re-enable prev, next buttons
---
Documentation/conf.py | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 668e764..b1780a0 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -93,9 +93,9 @@ html_theme = 'sphinx_rtd_theme'
html_show_sphinx = False
-html_theme_options = {
- 'prev_next_buttons_location': None
-}
+#html_theme_options = {
+# 'prev_next_buttons_location': None
+#}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
[incubator-nuttx] 02/02: Documentation: merge quickstart with the
rest of "getting started"
Posted by xi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit 1e7c13dba3bc7a3cc468e3154ea23a29c77c7184
Author: Matias N <ma...@protobits.dev>
AuthorDate: Sat Dec 5 23:24:34 2020 -0300
Documentation: merge quickstart with the rest of "getting started"
---
Documentation/quickstart/compiling.rst | 8 +-
Documentation/quickstart/configuring.rst | 18 ++---
Documentation/quickstart/index.rst | 12 +--
Documentation/quickstart/install.rst | 115 ++++++++++++++++------------
Documentation/quickstart/quickstart.rst | 124 -------------------------------
Documentation/quickstart/running.rst | 56 ++++++++------
6 files changed, 116 insertions(+), 217 deletions(-)
diff --git a/Documentation/quickstart/compiling.rst b/Documentation/quickstart/compiling.rst
index b2c5fd6..c2a2ae4 100644
--- a/Documentation/quickstart/compiling.rst
+++ b/Documentation/quickstart/compiling.rst
@@ -66,8 +66,10 @@ To clean the build, you can do:
.. code-block:: console
$ make clean
+
+.. tip::
-----
-
-Next up is :ref:`running`.
+ To increase build speed (or of any other target such as ``clean``), you can
+ pass the ``-jN`` flag to ``make``, where ``N`` is the number of parallel jobs
+ to start (usually, the number of processors on your machine).
diff --git a/Documentation/quickstart/configuring.rst b/Documentation/quickstart/configuring.rst
index 0213d41..3edd030 100644
--- a/Documentation/quickstart/configuring.rst
+++ b/Documentation/quickstart/configuring.rst
@@ -4,9 +4,9 @@
Configuring
===========
-Apache NuttX is a very configurable operating system. Nearly all features can be configured in or
-out of the system. This makes it possible to compile a build tailored for your hardware and
-application.
+Apache NuttX is a very configurable: nearly all features can be configured in or
+out of the system. This makes it possible to compile a build tailored for your
+hardware and application.
The Apache NuttX configuration system uses Linux's
`kconfig system <https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt>`_ which
@@ -14,9 +14,9 @@ includes various frontends that allow you to modify configuration easily. Usuall
frontend is used, which is a console based menu system (more info `here <https://en.wikipedia.org/wiki/Menuconfig>`_).
As previously explained in :doc:`compiling`, the first step is to load a premade configuration for
-your board. Then, you can modify this configuration to your liking.
-
-In this example, we will show how you modify the default configuration of the ``sim`` build.
+your board. Then, you can modify this configuration to your liking. In this example, we will show
+how you modify the default configuration of the ``sim`` build, a build of NuttX which runs on your own
+computer.
#. Initialize Board Configuration
@@ -103,7 +103,7 @@ If you know exactly which configuration symbol you want to change, you can use t
This is also useful to script configuration changes that you perform often:
-.. code-block:: console
+.. code-block:: bash
#!/bin/bash
@@ -121,7 +121,3 @@ This is also useful to script configuration changes that you perform often:
kconfig-tweak --disable CONFIG_DEBUG_NOOPT
kconfig-tweak --disable CONFIG_SYSLOG_TIMESTAMP
make oldconfig
-
-----
-
-Next up is :ref:`debugging`.
diff --git a/Documentation/quickstart/index.rst b/Documentation/quickstart/index.rst
index e922ddc..24da718 100644
--- a/Documentation/quickstart/index.rst
+++ b/Documentation/quickstart/index.rst
@@ -2,20 +2,12 @@
Getting Started
===============
-This section describes how to get started with NuttX. :ref:`quickstart/quickstart:Quickstart` is for
-experienced embedded developers, and quickly outlines the basic of getting NuttX configured and
-compiled. Use this if you are experienced with FreeRTOS, Zephyr, or a similar RTOS.
-
-The remaining sections are detailed instructions aimed at beginners for getting the necessary
-compilers and other tools installed, then compiling NuttX and running on your hardware. There are sections
-on configuring NuttX with more features than just the minimum, and a section on debugging. For reference
-there is also a description of the code organization and some details about what happens when running ``make``
-to build NuttX.
+This guide will explain how to get started with NuttX. The following sections will go through each
+required step:
.. toctree::
:maxdepth: 1
- quickstart.rst
install.rst
compiling.rst
running.rst
diff --git a/Documentation/quickstart/install.rst b/Documentation/quickstart/install.rst
index c80b14d..e56cd2f 100644
--- a/Documentation/quickstart/install.rst
+++ b/Documentation/quickstart/install.rst
@@ -1,41 +1,35 @@
.. include:: /substitutions.rst
.. _install:
+==========
Installing
==========
-To start developing on Apache NuttX, we need to get the source code, configure it, compile it, and get it uploaded onto an
-embedded computing board. These instructions are for `Ubuntu <https://ubuntu.com/>`_ Linux and macOS Catalina. If you're using a different
-version, you may need to change some of the commands.
+The first step to get started with NuttX is to install a series of required tools, a toolchain for the architecture
+you will be working with and, finally, download NuttX source code itself.
Prerequisites
--------------
-
-.. tabs::
+=============
- .. tab:: Linux
+First, install the following set of system dependencies according to your Operating System:
- #. Install system packages
-
- .. code-block:: console
-
- $ sudo apt install \
- bison flex gettext texinfo libncurses5-dev libncursesw5-dev \
- gperf automake libtool pkg-config build-essential gperf genromfs \
- libgmp-dev libmpc-dev libmpfr-dev libisl-dev binutils-dev libelf-dev \
- libexpat-dev gcc-multilib g++-multilib picocom u-boot-tools util-linux
+.. tabs::
- #. Give yourself access to the serial console device
+ .. tab:: Linux (debian based)
- This is done by adding your Linux user to the ``dialout`` group:
+ Run the following command to install packages:
- .. code-block:: console
+ .. code-block:: console
- $ sudo usermod -a -G dialout $USER
- $ # now get a login shell that knows we're in the dialout group:
- $ su - $USER
+ $ sudo apt install \
+ bison flex gettext texinfo libncurses5-dev libncursesw5-dev \
+ gperf automake libtool pkg-config build-essential gperf genromfs \
+ libgmp-dev libmpc-dev libmpfr-dev libisl-dev binutils-dev libelf-dev \
+ libexpat-dev gcc-multilib g++-multilib picocom u-boot-tools util-linux
.. tab:: macOS
+
+ Run the following command to install packages:
.. code-block:: console
@@ -64,11 +58,30 @@ Prerequisites
flex gdb libmpfr-devel
git unzip zlib-devel
-To complete the installation of prerequisites, you need to install `kconfig-frontends`
-as instructed in the :doc:`quickstart` guide.
+KConfig frontend
+----------------
+
+NuttX configuration system uses `KConfig <https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt>`_ which is exposed via a series of interactive menu-based *frontends*, part of the ``kconfig-frontends`` package. Depending on your OS you may use a precompiled package or you will have to build it from source:
+
+ .. tabs::
+
+ .. code-tab:: console Ubuntu 20.04 LTS and later
+
+ $ apt install kconfig-frontends
+
+ .. code-tab:: console MacOS, Ubuntu 18.04 LTS and earlier
-Install a Cross-Compiler Toolchain
-----------------------------------
+ $ cd tools/kconfig-frontends
+ $ # on MacOS do the following:
+ $ patch < ../kconfig-macos.diff -p 1
+ $ ./configure --enable-mconf --disable-shared --enable-static --disable-gconf --disable-qconf --disable-nconf
+ $ # on Linux do the following:
+ $ ./configure --enable-mconf --disable-nconf --disable-gconf --disable-qconf
+ $ make
+ $ make install
+
+Toolchain
+=========
To build Apache NuttX you need the appropriate toolchain
according to your target platform. Some Operating Systems
@@ -123,20 +136,19 @@ ARM architecture:
architectures in the Apache NuttX CI helper
`script <https://github.com/apache/incubator-nuttx-testing/blob/master/cibuild.sh>`_
and Docker `container <https://github.com/apache/incubator-nuttx-testing/blob/master/docker/linux/Dockerfile>`_
+
+.. todo::
+ Required toolchain should be part of each arch documentation (see `relevant issue <https://github.com/apache/incubator-nuttx/issues/2409>`_).
-Get Source Code
----------------
+Download NuttX
+==============
-Now that all required tools are installed, you need to download NuttX source-code.
+Apache NuttX is actively developed on GitHub. There are two main repositories, `nuttx <https://github.com/apache/incubator-nuttx>`_ and `apps <https://github.com/apache/incubator-nuttx-apps>`_, where the latter is technically optional (but recommended for complete set of features). If you intend to contribute changes, you need the absolute latest version or you simply prefer to work using git, you should clone these repositories (recommended). Otherwise you can choose to download any `st [...]
.. tabs::
- .. tab:: Development (Git)
-
- Apache NuttX is `actively developed on GitHub <https://github.com/apache/incubator-nuttx/>`_.
- If you intend to contribute changes or you simply need the absolute latest version,
- you should clone the Git repositories:
-
+ .. tab:: Clone git repositories
+
.. code-block:: console
$ mkdir nuttx
@@ -148,15 +160,26 @@ Now that all required tools are installed, you need to download NuttX source-cod
.. code-block:: console
- $ curl -OL https://github.com/apache/incubator-nuttx/tarball/master
- $ curl -OL https://github.com/apache/incubator-nuttx-apps/tarball/master
- # optionally, zipball is also available (for Windows users).
-
- .. tab:: Stable Release
-
- Apache NuttX releases are published on the project `Downloads <https://nuttx.apache.org/download/>`_
- page and distributed by the Apache mirrors. Be sure to download both the `nuttx` and `apps` tarballs.
-
-----
+ $ mkdir nuttx
+ $ cd nuttx
+ $ wget https://github.com/apache/incubator-nuttx/tarball/master -O nuttx.tar.gz
+ $ wget https://github.com/apache/incubator-nuttx-apps/tarball/master -O apps.tar.gz
+ $ tar zxf nuttx.tar.gz
+ $ tar zxf apps.tar.gz
+
+ There are also ``.zip`` archives available (useful for Windows users): just replace ``tarball`` with
+ ``zipball``.
+
+ .. tab:: Download stable release
+
+ Go to `releases <https://nuttx.apache.org/download/>`_ and choose a version to download. The following
+ example uses version 9.1.0:
-Next up is :ref:`compiling`.
+ .. code-block:: console
+
+ $ mkdir nuttx
+ $ cd nuttx
+ $ wget https://downloads.apache.org/incubator/nuttx/9.1.0/apache-nuttx-9.1.0-incubating.tar.gz -O nuttx.tar.gz
+ $ wget https://downloads.apache.org/incubator/nuttx/9.1.0/apache-nuttx-apps-9.1.0-incubating.tar.gz -O apps.tar.gz
+ $ tar zxf nuttx.tar.gz
+ $ tar zxf apps.tar.gz
diff --git a/Documentation/quickstart/quickstart.rst b/Documentation/quickstart/quickstart.rst
deleted file mode 100644
index 3b5301a..0000000
--- a/Documentation/quickstart/quickstart.rst
+++ /dev/null
@@ -1,124 +0,0 @@
-.. include:: /substitutions.rst
-.. _quickstart:
-
-Quickstart
-==========
-
-Here's the quick version of getting started with NuttX. This is a bare-bones outline for experienced developers– if it's
-going too quickly, dive into the following sections. This Quickstart guide assumes you're on a Linux
-computer, you're using an ARM microcontroller on your embedded board, and you're familiar with using the command line.
-
-#. Install a Cross-Compiler Toolchain
-
- With NuttX, you compile the operating system and your application on your desktop or laptop computer, then install the
- binary file on your embedded computer. This guide assumes your computer is an
- `ARM <https://en.wikipedia.org/wiki/ARM_architecture>`_ CPU. If it isn't, you'll need a different tool chain.
-
- You can download a toolchain from
- `ARM Embedded GNU Toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
- for your embedded processor's CPU. You can also use a toolchain shipped with your OS for the `none-eabi` target, such as `gcc-arm-none-eabi` in Linux.
-
- In the following example, we download ``gcc-arm-none-eabi`` version 9.0 and unpack it into ``/opt/gcc``:
-
- .. code-block:: console
-
- $ sudo mkdir /opt/gcc
- $ sudo chgrp -R users /opt/gcc
- $ cd /opt/gcc
- $ wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-x86_64-linux.tar.bz2
- $ tar xf gcc-arm-none-eabi-9-2019-q4-major-x86_64-linux.tar.bz2
-
- Then, add the toolchain ``bin/`` directory to your path:
-
- .. code-block:: console
-
- $ echo "export PATH=/opt/gcc/gcc-arm-none-eabi-9-2019-q4-major/bin:$PATH" >> ~/.bashrc
-
- If you are using any other shell, the procedure is similar by editing the corresponding rc file.
-
-#. Download Apache NuttX
-
- The next step is to download NuttX main repository along the application repository. The latter is technically optional in a very minimal configurations but should be included in normal configuration since it includes the NuttX shell.
-
- .. code-block:: console
-
- $ mkdir nuttx
- $ cd nuttx
- $ git clone https://github.com/apache/incubator-nuttx.git nuttx
- $ git clone https://github.com/apache/incubator-nuttx-apps apps
- $ git clone https://bitbucket.org/nuttx/tools.git tools
-
-#. Install the ``kconfig-frontends`` package
-
- NuttX is configured using ``kconfig`` system via an interactive menu system (``menuconfig``). It also includes the ``kconfig-tweak`` utility that can be used to quickly change debug settings without going into the menu system.
-
- .. tabs::
-
- .. code-tab:: console Ubuntu 20.04 LTS and later
-
- $ apt install kconfig-frontends
-
- .. code-tab:: console MacOS, Ubuntu 18.04 LTS and earlier
-
- $ cd tools/kconfig-frontends
- $ # on MacOS do the following:
- $ patch < ../kconfig-macos.diff -p 1
- $ ./configure --enable-mconf --disable-shared --enable-static --disable-gconf --disable-qconf --disable-nconf
- $ # on Linux do the following:
- $ ./configure --enable-mconf --disable-nconf --disable-gconf --disable-qconf
- $ make
- $ make install
-
-#. List Possible Apache NuttX Base Configurations
-
- Find your hardware and a good starting application in the list of base configurations. In the application list,
- ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
-
- .. code-block:: bash
-
- $ cd nuttx
- $ ./tools/configure.sh -L | less
-
-#. Initialize Configuration
-
- Pick one of the board:application base configuration pairs from the list, and feed it to
- the configuration script. The ``-l`` tells us that we're on Linux. macOS and Windows builds
- are possible, this guide doesn't cover them yet.
-
- .. code-block:: bash
-
- $ cd nuttx
- $ ./tools/configure.sh -l <board-name>:<config-dir>
- # for instance:
- $ ./tools/configure.sh -l sama5d27-xult:nsh
-
-#. Customize Your Configuration (Optional)
-
- This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
- any of the options now, but knowing how to do this will come in handy later.
-
- There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
-
- .. code-block:: bash
-
- $ make menuconfig
-
- Use your arrows to navigate the menu and :kbd:`Enter` key to enable/disable options. To exit and save your configuration, go back to the main menu, choose ``<Exit>`` and select "yes" when asked if you want to save.
-
-#. Compile Apache NuttX
-
- .. code-block:: bash
-
- $ make
-
-#. Install the Executable Program on Your Board
-
- This step is a bit more complicated, depending on your board. It's covered in the section
- :ref:`Running Apache NuttX <running>`.
-
-----
-
-.. rubric:: More Details
-
-If you want more details, start at :ref:`install`.
-
diff --git a/Documentation/quickstart/running.rst b/Documentation/quickstart/running.rst
index 6ad48e5..dd07a6e 100644
--- a/Documentation/quickstart/running.rst
+++ b/Documentation/quickstart/running.rst
@@ -20,32 +20,33 @@ Flashing
========
There are various tools you can use to flash the NuttX binary to your Nucleo
-board. One common option is to use `openocd` which supports a large number
+board. One common option is to use ``openocd`` which supports a large number
of programmers and target microcontrollers.
-To install the stable version of openocd you can do:
+You should note that ``openocd`` project has not made stable releases for long
+time and support for newer hardware will probably be only available in the
+latest Git version, so it is actually recommended to install latest development
+version.
-.. code-block:: console
+.. tabs::
- $ apt install openocd
+ .. code-tab:: console Install stable version (Ubuntu)
-.. todo:: add instructions for other platforms
+ $ apt install openocd
-You should note that openocd project has not made stable releases for long
-time and support for newer hardware will probably be only available in the
-latest Git version. To install it you should:
+ .. tab:: Install latest version from source
-.. code-block:: console
-
- $ git clone git://git.code.sf.net/p/openocd/code openocd
- $ cd openocd
- $ ./bootstrap
- $ ./configure --prefix=install/
- $ make install
-
-The resulting installation will be under ``openocd/install``. You can add
-``openocd/install/bin`` to your ``PATH``.
+ .. code-block:: console
+
+ $ git clone git://git.code.sf.net/p/openocd/code openocd
+ $ cd openocd
+ $ ./bootstrap
+ $ ./configure --prefix=install/
+ $ make install
+ The resulting installation will be under ``openocd/install``. You can add
+ ``openocd/install/bin`` to your ``PATH``.
+
Now, to flash the binary to your board, connect the USB cable and do:
.. code-block:: console
@@ -59,7 +60,8 @@ Access NuttShell
Once you flash your board, it will reset and offer a prompt over the serial
console. With the Nucleo board, you can simply open the terminal program
-of your choice where you will see the ``nsh>`` prompt:
+of your choice where you will see the ``nsh>`` prompt (press :kbd:`enter`
+if you don't see anything):
.. tabs::
@@ -70,7 +72,15 @@ of your choice where you will see the ``nsh>`` prompt:
.. code-tab:: console gtkterm (GUI)
$ gtkterm -s 115200 -p /dev/ttyUSB0
-
-----
-
-Next up is :ref:`configuring`.
+
+.. tip::
+
+ You may have to add yourself to the ``dialout`` group on Linux to have permission
+ to access serial ports:
+
+ .. code-block:: console
+
+ $ gpasswd -a <user> dialout
+
+ Where ``<user>`` is your username. You will need to log out from your desktop
+ for the change to have effect.