documentation: work on quickstart, add tabs sphinx extension
This commit is contained in:
Matias N
Adam Feuer
parent
c1878406b5
commit
94e1a9247c
@ -9,6 +9,7 @@ verify_ssl = true
|
||||
m2r2 = "*"
|
||||
sphinx_rtd_theme = "*"
|
||||
Sphinx = "*"
|
||||
sphinx-tabs = "*"
|
||||
|
||||
[requires]
|
||||
python_version = "3"
|
||||
|
||||
28
Documentation/Pipfile.lock
generated
28
Documentation/Pipfile.lock
generated
@ -1,7 +1,7 @@
|
||||
{
|
||||
"_meta": {
|
||||
"hash": {
|
||||
"sha256": "0f506aecc0f6e03287fd75ac128cf2d561b32ce607fd0559eab0a95641181d8c"
|
||||
"sha256": "947fcd26ed23c573b22e756acb18187f74ed08821f8274f42643d782d9f6636c"
|
||||
},
|
||||
"pipfile-spec": 6,
|
||||
"requires": {
|
||||
@ -28,6 +28,7 @@
|
||||
"sha256:1aac2ae2d0d8ea368fa90906567f5c08463d98ade155c0c4bfedd6a0f7160e38",
|
||||
"sha256:d670ea0b10f8b723672d3a6abeb87b565b244da220d76b4dba1b66269ec152d4"
|
||||
],
|
||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
|
||||
"version": "==2.8.0"
|
||||
},
|
||||
"certifi": {
|
||||
@ -49,6 +50,7 @@
|
||||
"sha256:0c5b78adfbf7762415433f5515cd5c9e762339e23369dbe8000d84a4bf4ab3af",
|
||||
"sha256:c2de3a60e9e7d07be26b7f2b00ca0309c207e06c100f9cc2a94931fc75a478fc"
|
||||
],
|
||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
|
||||
"version": "==0.16"
|
||||
},
|
||||
"idna": {
|
||||
@ -56,6 +58,7 @@
|
||||
"sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6",
|
||||
"sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"
|
||||
],
|
||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
|
||||
"version": "==2.10"
|
||||
},
|
||||
"imagesize": {
|
||||
@ -63,6 +66,7 @@
|
||||
"sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
|
||||
"sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"
|
||||
],
|
||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
|
||||
"version": "==1.2.0"
|
||||
},
|
||||
"jinja2": {
|
||||
@ -70,6 +74,7 @@
|
||||
"sha256:89aab215427ef59c34ad58735269eb58b1a5808103067f7bb9d5836c651b3bb0",
|
||||
"sha256:f0a4641d3cf955324a89c04f3d94663aa4d638abe8f733ecd3582848e1c37035"
|
||||
],
|
||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
|
||||
"version": "==2.11.2"
|
||||
},
|
||||
"m2r2": {
|
||||
@ -116,6 +121,7 @@
|
||||
"sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7",
|
||||
"sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be"
|
||||
],
|
||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
|
||||
"version": "==1.1.1"
|
||||
},
|
||||
"mistune": {
|
||||
@ -130,6 +136,7 @@
|
||||
"sha256:4357f74f47b9c12db93624a82154e9b120fa8293699949152b22065d556079f8",
|
||||
"sha256:998416ba6962ae7fbd6596850b80e17859a5753ba17c32284f67bfff33784181"
|
||||
],
|
||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
|
||||
"version": "==20.4"
|
||||
},
|
||||
"pygments": {
|
||||
@ -137,6 +144,7 @@
|
||||
"sha256:647344a061c249a3b74e230c739f434d7ea4d8b1d5f3721bc0f3558049b38f44",
|
||||
"sha256:ff7a40b4860b727ab48fad6360eb351cc1b33cbf9b15a0f689ca5353e9463324"
|
||||
],
|
||||
"markers": "python_version >= '3.5'",
|
||||
"version": "==2.6.1"
|
||||
},
|
||||
"pyparsing": {
|
||||
@ -144,6 +152,7 @@
|
||||
"sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
|
||||
"sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
|
||||
],
|
||||
"markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
|
||||
"version": "==2.4.7"
|
||||
},
|
||||
"pytz": {
|
||||
@ -158,6 +167,7 @@
|
||||
"sha256:b3559a131db72c33ee969480840fff4bb6dd111de7dd27c8ee1f820f4f00231b",
|
||||
"sha256:fe75cc94a9443b9246fc7049224f75604b113c36acb93f87b80ed42c44cbb898"
|
||||
],
|
||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
|
||||
"version": "==2.24.0"
|
||||
},
|
||||
"six": {
|
||||
@ -165,6 +175,7 @@
|
||||
"sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259",
|
||||
"sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced"
|
||||
],
|
||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
|
||||
"version": "==1.15.0"
|
||||
},
|
||||
"snowballstemmer": {
|
||||
@ -190,11 +201,20 @@
|
||||
"index": "pypi",
|
||||
"version": "==0.5.0"
|
||||
},
|
||||
"sphinx-tabs": {
|
||||
"hashes": [
|
||||
"sha256:537857f91f1b371f7b45eb8ac83001618b3e3178c78df073d2cc4558a8e66ef5",
|
||||
"sha256:54132c8a57aa19bba6e17fe26eb94ea9df531708ff3f509b119313b32d0d5aff"
|
||||
],
|
||||
"index": "pypi",
|
||||
"version": "==1.3.0"
|
||||
},
|
||||
"sphinxcontrib-applehelp": {
|
||||
"hashes": [
|
||||
"sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
|
||||
"sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"
|
||||
],
|
||||
"markers": "python_version >= '3.5'",
|
||||
"version": "==1.0.2"
|
||||
},
|
||||
"sphinxcontrib-devhelp": {
|
||||
@ -202,6 +222,7 @@
|
||||
"sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e",
|
||||
"sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"
|
||||
],
|
||||
"markers": "python_version >= '3.5'",
|
||||
"version": "==1.0.2"
|
||||
},
|
||||
"sphinxcontrib-htmlhelp": {
|
||||
@ -209,6 +230,7 @@
|
||||
"sha256:3c0bc24a2c41e340ac37c85ced6dafc879ab485c095b1d65d2461ac2f7cca86f",
|
||||
"sha256:e8f5bb7e31b2dbb25b9cc435c8ab7a79787ebf7f906155729338f3156d93659b"
|
||||
],
|
||||
"markers": "python_version >= '3.5'",
|
||||
"version": "==1.0.3"
|
||||
},
|
||||
"sphinxcontrib-jsmath": {
|
||||
@ -216,6 +238,7 @@
|
||||
"sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
|
||||
"sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
|
||||
],
|
||||
"markers": "python_version >= '3.5'",
|
||||
"version": "==1.0.1"
|
||||
},
|
||||
"sphinxcontrib-qthelp": {
|
||||
@ -223,6 +246,7 @@
|
||||
"sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
|
||||
"sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"
|
||||
],
|
||||
"markers": "python_version >= '3.5'",
|
||||
"version": "==1.0.3"
|
||||
},
|
||||
"sphinxcontrib-serializinghtml": {
|
||||
@ -230,6 +254,7 @@
|
||||
"sha256:eaa0eccc86e982a9b939b2b82d12cc5d013385ba5eadcc7e4fed23f4405f77bc",
|
||||
"sha256:f242a81d423f59617a8e5cf16f5d4d74e28ee9a66f9e5b637a18082991db5a9a"
|
||||
],
|
||||
"markers": "python_version >= '3.5'",
|
||||
"version": "==1.1.4"
|
||||
},
|
||||
"urllib3": {
|
||||
@ -237,6 +262,7 @@
|
||||
"sha256:91056c15fa70756691db97756772bb1eb9678fa585d9184f24534b100dc60f4a",
|
||||
"sha256:e7983572181f5e1522d9c98453462384ee92a0be7fac5f1413a1e35c56cc0461"
|
||||
],
|
||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' and python_version < '4'",
|
||||
"version": "==1.25.10"
|
||||
}
|
||||
},
|
||||
|
||||
@ -58,3 +58,23 @@ table.valign-top td {
|
||||
vertical-align: top !important;
|
||||
}
|
||||
|
||||
/* Make <kbd> elements look nice */
|
||||
|
||||
kbd {
|
||||
margin: 0px 0.1em;
|
||||
padding: 0.1em 0.6em;
|
||||
border-radius: 3px;
|
||||
border: 1px solid rgb(204, 204, 204);
|
||||
color: rgb(51, 51, 51);
|
||||
line-height: 1.4;
|
||||
font-family: Arial,Helvetica,sans-serif;
|
||||
font-size: 10px;
|
||||
display: inline-block;
|
||||
box-shadow: 0px 1px 0px rgba(0,0,0,0.2), inset 0px 0px 0px 2px #ffffff;
|
||||
background-color: rgb(247, 247, 247);
|
||||
-moz-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
|
||||
-webkit-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
|
||||
-moz-border-radius: 3px;
|
||||
-webkit-border-radius: 3px;
|
||||
text-shadow: 0 1px 0 #fff;
|
||||
}
|
||||
|
||||
@ -53,6 +53,7 @@ extensions = [
|
||||
"m2r2",
|
||||
'sphinx.ext.autosectionlabel',
|
||||
'sphinx.ext.todo',
|
||||
'sphinx_tabs.tabs'
|
||||
]
|
||||
|
||||
source_suffix = [ '.rst', '.md' ]
|
||||
|
||||
@ -145,6 +145,25 @@ In case you need to leave a TODO note in the documentation to point that somethi
|
||||
which is available via the ``sphinx.ext.todo`` extension. This will let the reader of the documentation also know that the documentation
|
||||
is not yet finished somewhere and may further motivate a contribution.
|
||||
|
||||
User Indications
|
||||
----------------
|
||||
|
||||
To indicate a keypress, menu action or GUI button selection, use the following:
|
||||
|
||||
.. code-block:: RST
|
||||
|
||||
Go into menu :menuselection:`File --> Save As`, click :guilabel:`&OK` or press :kbd:`Enter`.
|
||||
|
||||
which would render as:
|
||||
|
||||
Go into menu :menuselection:`File --> Save As`, click :guilabel:`&OK` or press :kbd:`Enter`.
|
||||
|
||||
Tabbed examples
|
||||
---------------
|
||||
|
||||
To indicate different instructions/examples for different scenarios (for example, different Operating
|
||||
Systems) use the `tabs <https://github.com/executablebooks/sphinx-tabs>`_ extension (see link for examples).
|
||||
|
||||
Tips
|
||||
====
|
||||
|
||||
|
||||
@ -1,57 +1,82 @@
|
||||
.. include:: /substitutions.rst
|
||||
.. _compiling:
|
||||
|
||||
=========
|
||||
Compiling
|
||||
=========
|
||||
|
||||
Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
|
||||
into an executable binary file that can be run on the embedded board.
|
||||
Now that we've installed Apache NuttX prerequisites and downloaded the source code,
|
||||
we are ready to compile the source code into an executable binary file that can
|
||||
be run on the embedded board.
|
||||
|
||||
#. List Possible Apache NuttX Base Configurations
|
||||
Initialize Configuration
|
||||
========================
|
||||
|
||||
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.
|
||||
The first step is to initialize NuttX configuration for a given board, based from
|
||||
a pre-existing configuration. To list all supported configurations you can do:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ cd nuttx
|
||||
$ ./tools/configure.sh -L | less
|
||||
|
||||
The output is in the format ``<board name>:<board configuration>``. You will see that
|
||||
generally all boards support the ``nsh`` configuration which is a good sarting point
|
||||
since it enables booting into the interactive command line
|
||||
:doc:`/components/nsh/index`.
|
||||
|
||||
#. Initialize Configuration
|
||||
To choose a configuration you pass the ``<board name>:<board configuration>`` option
|
||||
to ``configure.sh`` and indicate your host platform, such as:
|
||||
|
||||
Pick one of the board:application base configuration pairs from the list, and feed it to the
|
||||
configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
|
||||
possible, this guide doesn't cover them yet.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ cd nuttx
|
||||
$ # this is the basic layout of the command:
|
||||
$ # ./tools/configure.sh -l <board-name>:<config-dir>
|
||||
$ # for example:
|
||||
$ ./tools/configure.sh -l sama5d2-xult:nsh
|
||||
$ ./tools/configure.sh -l stm32f4discovery:nsh
|
||||
|
||||
The ``-l`` tells use that we're on Linux (macOS and Windows builds are
|
||||
possible). Use the ``-h`` argument to see all available options.
|
||||
|
||||
#. Customize Your Configuration (Optional)
|
||||
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.
|
||||
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.
|
||||
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
|
||||
.. code-block:: console
|
||||
|
||||
$ make menuconfig
|
||||
$ cd nuttx/
|
||||
$ make menuconfig
|
||||
|
||||
.. todo::
|
||||
Explain some useful options.
|
||||
|
||||
#. Compile NuttX
|
||||
Build NuttX
|
||||
===========
|
||||
|
||||
.. code-block:: bash
|
||||
We can now build NuttX. To do so, you can simply run:
|
||||
|
||||
$ make clean; make
|
||||
.. code-block:: console
|
||||
|
||||
#. Install the Executable Program on Your Board
|
||||
$ cd nuttx/
|
||||
$ make make
|
||||
|
||||
The build will complete by generating the binary outputs
|
||||
inside `nuttx` directory. Typically this includes the `nuttx`
|
||||
ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
|
||||
file that can be flashed to the board.
|
||||
|
||||
To clean the build, you can do:
|
||||
|
||||
This step is a bit more complicated, depending on your board. It's covered in the section
|
||||
:ref:`Running Apache NuttX <running>`.
|
||||
.. code-block:: console
|
||||
|
||||
$ make clean
|
||||
|
||||
It is recommended that after manually modifying the configuration you first clean
|
||||
before building.
|
||||
|
||||
----
|
||||
|
||||
|
||||
@ -11,183 +11,153 @@ version, you may need to change some of the commands.
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Install prerequisites for building using Linux
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.. tabs::
|
||||
|
||||
#. Install system packages
|
||||
.. tab:: Linux
|
||||
|
||||
#. Install system packages
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo apt install \
|
||||
bison flex gettext texinfo libncurses5-dev libncursesw5-dev \
|
||||
gperf automake libtool pkg-config build-essential gperf \
|
||||
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
|
||||
|
||||
#. Give yourself access to the serial console device
|
||||
#. Give yourself access to the serial console device
|
||||
|
||||
This is done by adding your Linux user to the ``dialout`` group:
|
||||
This is done by adding your Linux user to the ``dialout`` group:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo usermod -a -G dialout $USER
|
||||
$ # now get a login shell that knows we're in the dialout group:
|
||||
$ su - $USER
|
||||
|
||||
.. tab:: macOS
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo usermod -a -G dialout $USER
|
||||
$ # now get a login shell that knows we're in the dialout group:
|
||||
$ su - $USER
|
||||
$ brew tap discoteq/discoteq
|
||||
$ brew install flock
|
||||
$ brew install x86_64-elf-gcc # Used by simulator
|
||||
$ brew install u-boot-tools # Some platform integrate with u-boot
|
||||
|
||||
Install prerequisites for building and using Apache NuttX (macOS)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.. tab:: Windows / WSL
|
||||
|
||||
.. code-block:: bash
|
||||
If you are are building Apache NuttX on windows and using WSL follow
|
||||
that installation guide for Linux. This has been verified against the
|
||||
Ubunutu 18.04 version.
|
||||
|
||||
$ brew tap discoteq/discoteq
|
||||
$ brew install flock
|
||||
$ brew install x86_64-elf-gcc # Used by simulator
|
||||
$ brew install u-boot-tools # Some platform integrate with u-boot
|
||||
There may be complications interacting with
|
||||
programming tools over USB. Recently support for USBIP was added to WSL 2
|
||||
which has been used with the STM32 platform, but it is not trivial to configure:
|
||||
https://github.com/rpasek/usbip-wsl2-instructions
|
||||
|
||||
Install prerequisites for building and using Apache NuttX (Windows -- WSL)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.. tab:: Windows/Cygwin
|
||||
|
||||
If you are are building Apache NuttX on windows and using WSL follow
|
||||
that installation guide for Linux. This has been verified against the
|
||||
Ubunutu 18.04 version.
|
||||
Download and install `Cygwin <https://www.cygwin.com/>`_ using the minimal
|
||||
installation in addition to these packages::
|
||||
|
||||
There may be complications interacting with
|
||||
programming tools over USB. Recently support for USBIP was added to WSL 2
|
||||
which has been used with the STM32 platform, but it is not trivial to configure:
|
||||
https://github.com/rpasek/usbip-wsl2-instructions
|
||||
|
||||
Install prerequisites for building and using Apache NuttX (Windows -- Cygwin)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Download and install `Cygwin <https://www.cygwin.com/>`_ using the minimal
|
||||
installation in addition to these packages::
|
||||
|
||||
make bison libmpc-devel
|
||||
gcc-core byacc automake-1.15
|
||||
gcc-g++ gperf libncurses-devel
|
||||
flex gdb libmpfr-devel
|
||||
git unzip zlib-devel
|
||||
|
||||
Install Required Tools (All Platforms)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
There are a collection of required tools that need to be built to build most Apache NuttX configurations:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ mkdir buildtools
|
||||
$ export NUTTXTOOLS=`pwd`/buildtools
|
||||
$ export NUTTXTOOLS_PATH=$NUTTXTOOLS/bin:$NUTTXTOOLS/usr/bin
|
||||
$ git clone https://bitbucket.org/nuttx/tools.git tools
|
||||
|
||||
*NOTE:* You will need to add ``NUTTXTOOLS_PATH`` to your environment ``PATH``
|
||||
|
||||
#. Install gperf tool
|
||||
|
||||
This required to build ``kconfig-frontends``.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd tools/
|
||||
$ wget http://ftp.gnu.org/pub/gnu/gperf/gperf-3.1.tar.gz
|
||||
$ tar zxf gperf-3.1.tar.gz
|
||||
$ cd gperf-3.1
|
||||
$ ./configure --prefix=$NUTTXTOOLS
|
||||
$ make
|
||||
$ make install
|
||||
|
||||
#. Install kconfig-frontends tool
|
||||
|
||||
This is necessary to run the ``./nuttx/tools/configure.sh`` script as well as using the ncurses-based menuconfig system.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd tools/
|
||||
$ cd kconfig-frontends
|
||||
$ # on MacOS do the following:
|
||||
$ patch < ../kconfig-macos.diff -p 1
|
||||
$ ./configure --prefix=$NUTTXTOOLS --enable-mconf --disable-shared --enable-static --disable-gconf --disable-qconf --disable-nconf
|
||||
$ # on Linux do the following:
|
||||
$ ./configure --prefix=$NUTTXTOOLS --enable-mconf --disable-gconf --disable-qconf
|
||||
$ touch aclocal.m4 Makefile.in
|
||||
$ make
|
||||
$ make install
|
||||
|
||||
#. Install gen-romfs (optional)
|
||||
|
||||
|
||||
This is required if you want to build ROM-based file systems.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd tools/
|
||||
$ tar zxf genromfs-0.5.2.tar.gz
|
||||
$ cd genromfs-0.5.2
|
||||
$ make install PREFIX=$NUTTXTOOLS
|
||||
|
||||
Get Source Code (Stable)
|
||||
------------------------
|
||||
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.
|
||||
|
||||
|
||||
Get Source Code (Development)
|
||||
------------------------------
|
||||
Apache NuttX is `actively developed on GitHub <https://github.com/apache/incubator-nuttx/>`_. If you want
|
||||
to use it, modify it or help develop it, you'll need the source code.
|
||||
|
||||
You can either clone the public repositories:
|
||||
|
||||
.. 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
|
||||
|
||||
Or, download the `tarball <https://github.com/apache/incubator-nuttx/tarball/master>`_:
|
||||
|
||||
.. 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).
|
||||
|
||||
Later if we want to make modifications (for instance, to improve NuttX and save them in our own branch,
|
||||
or submit them back to the project), we can do that easily using git to track our changes and submit them
|
||||
upstream to the NuttX project.
|
||||
make bison libmpc-devel
|
||||
gcc-core byacc automake-1.15
|
||||
gcc-g++ gperf libncurses-devel
|
||||
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.
|
||||
|
||||
Install a Cross-Compiler Toolchain
|
||||
----------------------------------
|
||||
|
||||
With Apache 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.
|
||||
To build Apache NuttX you need the appropriate toolchain
|
||||
according to your target platform. Some Operating Systems
|
||||
such as Linux distribute toolchains for various architectures.
|
||||
This is usually an easy choice however you should be aware
|
||||
that in some cases the version offered by your OS may have
|
||||
problems and it may better to use a widely used build from
|
||||
another source.
|
||||
|
||||
There are hints on how to get the latest tool chains for most supported 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>`_
|
||||
The following example shows how to install a toolchain for
|
||||
ARM architecture:
|
||||
|
||||
Download the right flavor of the
|
||||
`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.
|
||||
.. tabs::
|
||||
|
||||
Unpack it into ``/opt/gcc`` and add the bin directory to your path. For instance:
|
||||
.. code-tab:: console Ubuntu (deb)
|
||||
|
||||
$ apt install gcc-arm-none-eabi binutils-arm-none-eabi
|
||||
|
||||
.. tab:: From arm.com
|
||||
|
||||
First, create a directory to hold the toolchain:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ usermod -a -G users $USER
|
||||
$ # get a login shell that knows we're in this group:
|
||||
$ su - $USER
|
||||
$ sudo mkdir /opt/gcc
|
||||
$ sudo chgrp -R users /opt/gcc
|
||||
$ sudo chmod -R u+rw /opt/gcc
|
||||
$ cd /opt/gcc
|
||||
|
||||
Download and extract toolchain:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ HOST_PLATFORM=x86_64-linux # use "mac" for macOS.
|
||||
$ # For windows there is a zip instead (gcc-arm-none-eabi-9-2019-q4-major-win32.zip)
|
||||
$ wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2
|
||||
$ tar xf gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2
|
||||
|
||||
Add the toolchain to your `PATH`:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ echo "export PATH=/opt/gcc/gcc-arm-none-eabi-9-2019-q4-major/bin:$PATH" >> ~/.bashrc
|
||||
|
||||
You can edit your shell's rc files if you don't use bash.
|
||||
|
||||
.. code-block:: console
|
||||
.. tip::
|
||||
There are hints on how to get the latest tool chains for most supported
|
||||
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>`_
|
||||
|
||||
$ usermod -a -G users $USER
|
||||
$ # get a login shell that knows we're in this group:
|
||||
$ su - $USER
|
||||
$ sudo mkdir /opt/gcc
|
||||
$ sudo chgrp -R users /opt/gcc
|
||||
$ sudo chmod -R u+rw /opt/gcc
|
||||
$ cd /opt/gcc
|
||||
$ HOST_PLATFORM=x86_64-linux # use "mac" for macOS.
|
||||
$ # For windows there is a zip instead (gcc-arm-none-eabi-9-2019-q4-major-win32.zip)
|
||||
$ curl -L -o gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2 https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2
|
||||
$ tar xf gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2
|
||||
$ # add the toolchain bin/ dir to your path...
|
||||
$ # you can edit your shell's rc files if you don't use bash
|
||||
$ echo "export PATH=/opt/gcc/gcc-arm-none-eabi-9-2019-q4-major/bin:$PATH" >> ~/.bashrc
|
||||
Get Source Code
|
||||
---------------
|
||||
|
||||
Now that all required tools are installed, you need to download NuttX source-code.
|
||||
|
||||
.. 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:
|
||||
|
||||
.. 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
|
||||
|
||||
The development source code is also available as a compressed archive, should you need it:
|
||||
|
||||
.. 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.
|
||||
|
||||
----
|
||||
|
||||
|
||||
@ -52,25 +52,22 @@ computer, you're using an ARM microcontroller on your embedded board, and you're
|
||||
|
||||
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
|
||||
|
||||
On Ubuntu 20.04 LTS and later, you can do:
|
||||
$ apt install kconfig-frontends
|
||||
|
||||
.. code-block:: console
|
||||
.. code-tab:: console MacOS, Ubuntu 18.04 LTS and earlier
|
||||
|
||||
$ apt install kconfig-frontends
|
||||
|
||||
On MacOS, and Ubuntu 18.04 LTS and earlier, you need to install manually:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ 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
|
||||
$ 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
|
||||
|
||||
@ -106,8 +103,8 @@ computer, you're using an ARM microcontroller on your embedded board, and you're
|
||||
|
||||
$ make menuconfig
|
||||
|
||||
Use your arrows to navigate the menu and ``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.
|
||||
|
||||
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
|
||||
|
||||
@ -1,13 +1,110 @@
|
||||
.. include:: /substitutions.rst
|
||||
.. _running:
|
||||
|
||||
=======
|
||||
Running
|
||||
=======
|
||||
|
||||
Embedded boards have different ways to get your program onto them and get them running. This guide assumes your board
|
||||
has a JTAG connector, and you have a JTAG hardware debugger like a
|
||||
`Segger J-Link <https://www.segger.com/products/debug-probes/j-link/>`_. `JTAG <https://en.wikipedia.org/wiki/JTAG>`_
|
||||
is a set of standards that let you attach a hardware device to your embedded board, and then remotely control the CPU.
|
||||
In order to finally run NuttX on your board, you first have to flash the NuttX
|
||||
binary. As an easy start, it is recommended that you choose a well supported board
|
||||
which also integrates the debugger/programmer in the board itself exposed via USB
|
||||
connector.
|
||||
|
||||
A good choice is a Nucleo or Discovery board from ST Microelectronics,
|
||||
as there is a wide choice of suported boards for the STM32 architecture in NuttX.
|
||||
Also, these boards expose an UART port over the USB connection which allows you
|
||||
to interact with NuttX via the interactive console without any extra hardware.
|
||||
For the purposes of this guide, we will use the Nucleo F103RB board.
|
||||
|
||||
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
|
||||
of programmers and target microcontrollers.
|
||||
|
||||
To install the stable version of openocd you can do:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ apt install openocd
|
||||
|
||||
.. todo:: add instructions for other platforms
|
||||
|
||||
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:
|
||||
|
||||
.. 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
|
||||
|
||||
$ cd nuttx/
|
||||
$ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg -c 'init' \
|
||||
-c 'program nuttx/nuttx.bin verify reset' -c 'shutdown'
|
||||
|
||||
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:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. code-tab:: console picocom (CLI)
|
||||
|
||||
$ picocom -b 115200 /dev/ttyUSB0
|
||||
|
||||
.. code-tab:: console gtkterm (GUI)
|
||||
|
||||
$ gtkterm -s 115200 -p /dev/ttyUSB0
|
||||
|
||||
|
||||
Debugging
|
||||
=========
|
||||
|
||||
Using ``openocd`` you can also debug NuttX. To do so, first run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg
|
||||
|
||||
which will start a GDB server. Then, start ``gdb`` as:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd nuttx/
|
||||
$ gdb-multiarch nuttx/nuttx
|
||||
|
||||
Inside ``gdb`` console, connect to the ``openocd`` server with:
|
||||
|
||||
.. code-block::
|
||||
|
||||
(gdb) target extended-remote :3333
|
||||
|
||||
You can debug using standard ``gdb`` commands.
|
||||
|
||||
Advanced Debugging with JTAG
|
||||
----------------------------
|
||||
|
||||
If your board does not have an embedded programmer and uses
|
||||
`JTAG <https://en.wikipedia.org/wiki/JTAG>`_ connector instead,
|
||||
things are a bit different. This guide assumes you have a JTAG hardware debugger like a
|
||||
`Segger J-Link <https://www.segger.com/products/debug-probes/j-link/>`_.
|
||||
JTAG is a set of standards that let you
|
||||
attach a hardware device to your embedded board, and then remotely control the CPU.
|
||||
You can load code, start, stop, step through the program, and examine variables and memory.
|
||||
|
||||
#. Attach the Debugger Cables
|
||||
@ -18,28 +115,19 @@ You can load code, start, stop, step through the program, and examine variables
|
||||
communicate with to load code and start, stop, and step the embedded board's CPU. Your command line may be
|
||||
different from this one.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ JLinkGDBServer -device ATSAMA5D27 -if JTAG -speed 1000 -JTAGConf -1,-1
|
||||
|
||||
#. Launch the GNU Debugger
|
||||
|
||||
In another terminal window, launch the GDB for your platform. In the case of this guide, this came with the
|
||||
In another terminal window, launch the GDB. In the case of this guide, this came with the
|
||||
ARM Embedded GNU Toolchain we downloaded in the Install step.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
$ arm-none-eabi-gdb
|
||||
|
||||
#. Connect to the board's serial console
|
||||
|
||||
Usually you connect a USB-to-serial adapter to the board's serial console so you can see debug logging or
|
||||
execute Apache NuttX Shell (nsh) commands. You can access the serial console from Linux with the ``picocom`` terminal
|
||||
program. From another terminal, do this:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ picocom -b 115200 /dev/ttyUSB0
|
||||
$ cd nuttx/
|
||||
$ gdb-multiarch nuttx/nuttx
|
||||
|
||||
#. Set gdb to talk with the J-Link
|
||||
|
||||
@ -66,7 +154,6 @@ You can load code, start, stop, step through the program, and examine variables
|
||||
|
||||
::
|
||||
|
||||
(gdb) file nuttx
|
||||
(gdb) load nuttx
|
||||
`/home/adamf/src/nuttx-sama5d36-xplained/nuttx/nuttx' has changed; re-reading symbols.
|
||||
Loading section .text, size 0x9eae4 lma 0x20008000
|
||||
|
||||
Loading…
Reference in New Issue
Block a user