From 94e1a9247c5df7ea9027258e0c0e26b1aca942d1 Mon Sep 17 00:00:00 2001 From: Matias N Date: Fri, 11 Sep 2020 18:55:50 -0300 Subject: [PATCH] documentation: work on quickstart, add tabs sphinx extension --- Documentation/Pipfile | 1 + Documentation/Pipfile.lock | 28 +- Documentation/_static/custom.css | 20 ++ Documentation/conf.py | 1 + Documentation/contributing/documentation.rst | 19 ++ Documentation/quickstart/compiling.rst | 81 ++++-- Documentation/quickstart/install.rst | 270 +++++++++---------- Documentation/quickstart/quickstart.rst | 33 ++- Documentation/quickstart/running.rst | 125 +++++++-- 9 files changed, 362 insertions(+), 216 deletions(-) diff --git a/Documentation/Pipfile b/Documentation/Pipfile index de17ea3992..db5091fcac 100644 --- a/Documentation/Pipfile +++ b/Documentation/Pipfile @@ -9,6 +9,7 @@ verify_ssl = true m2r2 = "*" sphinx_rtd_theme = "*" Sphinx = "*" +sphinx-tabs = "*" [requires] python_version = "3" diff --git a/Documentation/Pipfile.lock b/Documentation/Pipfile.lock index 2b4bcf4316..1a8c18104c 100644 --- a/Documentation/Pipfile.lock +++ b/Documentation/Pipfile.lock @@ -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" } }, diff --git a/Documentation/_static/custom.css b/Documentation/_static/custom.css index c37e164662..a861bdb114 100644 --- a/Documentation/_static/custom.css +++ b/Documentation/_static/custom.css @@ -58,3 +58,23 @@ table.valign-top td { vertical-align: top !important; } +/* Make 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; +} diff --git a/Documentation/conf.py b/Documentation/conf.py index 0e9d8be48a..40cda45fd8 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -53,6 +53,7 @@ extensions = [ "m2r2", 'sphinx.ext.autosectionlabel', 'sphinx.ext.todo', + 'sphinx_tabs.tabs' ] source_suffix = [ '.rst', '.md' ] diff --git a/Documentation/contributing/documentation.rst b/Documentation/contributing/documentation.rst index 565d9ca1d4..8fde17f25c 100644 --- a/Documentation/contributing/documentation.rst +++ b/Documentation/contributing/documentation.rst @@ -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 `_ extension (see link for examples). + Tips ==== diff --git a/Documentation/quickstart/compiling.rst b/Documentation/quickstart/compiling.rst index b7439367f3..4b491ed7c0 100644 --- a/Documentation/quickstart/compiling.rst +++ b/Documentation/quickstart/compiling.rst @@ -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 ``:``. 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 ``:`` 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 : - $ # 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 `. + .. code-block:: console + + $ make clean + +It is recommended that after manually modifying the configuration you first clean +before building. ---- diff --git a/Documentation/quickstart/install.rst b/Documentation/quickstart/install.rst index 1fded37db5..71cdfa6b8c 100644 --- a/Documentation/quickstart/install.rst +++ b/Documentation/quickstart/install.rst @@ -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 `_ 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 `_ 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 `_ 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 `_. 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 `_: - -.. 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 `_ 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 `_ and Docker `container `_ +The following example shows how to install a toolchain for +ARM architecture: -Download the right flavor of the -`ARM Embedded GNU Toolchain `_ -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 `_ + and Docker `container `_ - $ 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 `_. + 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 `_ + page and distributed by the Apache mirrors. Be sure to download both the `nuttx` and `apps` tarballs. ---- diff --git a/Documentation/quickstart/quickstart.rst b/Documentation/quickstart/quickstart.rst index 5f84221dd6..734a585e6b 100644 --- a/Documentation/quickstart/quickstart.rst +++ b/Documentation/quickstart/quickstart.rst @@ -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 ```` 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 ```` and select "yes" when asked if you want to save. + #. Compile Apache NuttX .. code-block:: bash diff --git a/Documentation/quickstart/running.rst b/Documentation/quickstart/running.rst index d04a383367..4ef05ce18c 100644 --- a/Documentation/quickstart/running.rst +++ b/Documentation/quickstart/running.rst @@ -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 `_. `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 `_ connector instead, +things are a bit different. This guide assumes you have a JTAG hardware debugger like a +`Segger 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