Skip to content

Commit 3b0f898

Browse files
lvanasselvanasse
committed
Doc: improve and add documentations for the guide section of the wiki
* Improve the building nuttx with app out of source tree * Add new guide pages * Building uclibc++ * Custom app directories * Debugging ELF loadable modules * Multiple NSH sessions * NSH network link management * RAM & ROM disks * Reading CAN messages * Remove device drivers with NSH
1 parent 197e372 commit 3b0f898

12 files changed

+1000
-14
lines changed

‎Documentation/guides/building_nuttx_with_app_out_of_src_tree.rst‎

Lines changed: 167 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,15 @@
22
Building NuttX with Applications Outside the Source Tree
33
========================================================
44

5-
Q:
6-
Has anyone come up with a tidy way to build NuttX with board-specific pieces
7-
outside the source tree?
5+
.. warning::
6+
Migrated from:
7+
https://cwiki.apache.org/confluence/display/NUTTX/Building+NuttX+with+Applications+Outside+of+the+Source+Tree
88

9-
A:
10-
Here are four approaches:
9+
Q: Has anyone come up with a tidy way to build NuttX with board-specific pieces outside the source tree?
10+
========================================================================================================
11+
12+
A: Here are four approaches:
13+
============================
1114

1215
1. Make export
1316
--------------
@@ -17,9 +20,11 @@ all of the header files, libraries, startup objects, and other build components
1720
into a ``.zip`` file. You can move that ``.zip`` file into any build environment
1821
you want. You can even build NuttX under a DOS CMD window.
1922

20-
This make target is documented in the top-level ``nuttx/README.txt``.
23+
This ``make target`` is documented in the top-level
24+
:doc:`Legacy README </introduction/resources>`. Search for ``Build Targets``
25+
2126

22-
2. Replace the apps/ Directory
27+
1. Replace the apps/ Directory
2328
------------------------------
2429

2530
You can replace the entire ``apps/`` directory. It is not a critical part of the
@@ -29,15 +34,15 @@ development. It should not dictate anything that you do.
2934
To use a different ``apps`` directory, simply execute ``make menuconfig`` in the
3035
top-level ``nuttx/`` directory and redefine ``CONFIG_APPS_DIR`` in your
3136
``.config`` file so that it points to a different, custom application directory.
32-
Note that ``CONFIG_APPS_DIR`` is a relative path from the top-level
37+
Note that ``CONFIG_APPS_DIR`` is a `relative` path from the top-level
3338
``nuttx/`` directory.
3439

3540
You can copy any pieces that you like from the old ``apps/`` directory to your
36-
custom ``apps`` directory as necessary. This is documented in
37-
``nuttx/boards/README.txt``, in the "NuttX Porting Guide" and "Build options,"
38-
and in the ``apps/README.txt`` file.
41+
custom ``apps`` directory as necessary. This is documented in
42+
the `NuttX Porting Guide <https://cwiki.apache.org/confluence/display/NUTTX/Porting+Guide>`_
43+
and in the `apps/README.md <https://github.com/apache/nuttx-apps/blob/master/README.md>`_ file.
3944

40-
3. Extend the apps/ Directory
45+
1. Extend the apps/ Directory
4146
-----------------------------
4247

4348
If you like the random collection of stuff in the ``apps/`` directory but just
@@ -46,8 +51,157 @@ then there is an easy way to do that too: Create a symbolic link in the
4651
``apps/`` directory that redirects to your application sub-directory (or copy
4752
your code into a sub-directory of ``apps/``).
4853

54+
.. image:: image/custom_app_dir_through_extension.png
55+
4956
Makefile and Make.defs
5057
^^^^^^^^^^^^^^^^^^^^^^
5158

5259
In order to be incorporated into the build, the directory that you link under
53-
the ``apps
60+
the ``apps/`` directory should contain:
61+
62+
1. A ``Makefile`` that supports the ``clean`` and ``distclean`` targets (see
63+
other Makefiles for examples).
64+
2. A tiny ``Make.defs`` make file fragment that simply adds the build
65+
directories to the variable ``CONFIGURED_APPS`` like:
66+
67+
.. code-block:: shell
68+
69+
CONFIGURED_APPS += my_directory1 my_directory2
70+
71+
Automatic Sub-directory Inclusion
72+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
73+
74+
The ``apps/Makefile`` will always automatically check for the existence of
75+
sub-directories containing a ``Makefile`` and a ``Make.defs`` file. The
76+
``Makefile`` will be used only to support cleaning operations. The
77+
``Make.defs`` file provides the set of relative paths to directories to be
78+
built; these directories must also contain a ``Makefile``. That ``Makefile`` can
79+
build the sources and add the object files to the ``apps/libapps.a`` archive
80+
(see other Makefiles for examples). It should support the ``all``, ``install``,
81+
``context``, and ``depend`` targets.
82+
83+
``apps/Makefile`` does not depend on any hard-coded lists of directories.
84+
Instead, it does a wildcard search to find all appropriate directories. This
85+
means that to install a new application, you simply have to copy the directory
86+
(or link it) into the ``apps/`` directory. If the new directory includes a
87+
``Makefile`` and a ``Make.defs`` file, then it will be automatically discovered
88+
and included in the build at ``make`` time.
89+
90+
Kconfig
91+
^^^^^^^
92+
93+
If the directory that you add also includes a ``Kconfig`` file, then it will be
94+
automatically included in the NuttX configuration system as well.
95+
``apps/Makefile`` uses a tool at ``apps/tools/mkkconfig.sh`` that dynamically
96+
builds the ``apps/Kconfig`` file at pre-configuration time.
97+
98+
.. note::
99+
100+
The native Windows build will use a corresponding tool called
101+
``apps/tools/mkconfig.bat``.
102+
103+
Install script
104+
^^^^^^^^^^^^^^
105+
106+
You could, for example, create a script called ``install.sh`` that installs a
107+
custom application, configuration, and board-specific directory:
108+
109+
1. Copy ``MyBoard`` directory to ``boards/MyBoard``.
110+
2. Add a symbolic link to ``MyApplication`` at ``apps/external``
111+
3. Configure NuttX:
112+
113+
.. code-block:: shell
114+
115+
tools/configure.sh MyBoard:MyConfiguration
116+
117+
Special ``apps/external`` Directory
118+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
119+
120+
Use of the name ``apps/external`` is suggested because that name is included in
121+
the ``.gitignore`` file and will save you some nuisance when working with GIT.
122+
123+
4. Contain the apps/ Directory
124+
------------------------------
125+
126+
A simple, minimally invasive approach would be to contain the ``apps/`` GIT
127+
clone within your custom application directory. In this case, ``apps/`` would
128+
appear as a directory under your custom application directory instead of your
129+
application directories being inserted as sub-directories of ``apps/``. It may
130+
even be implemented as a sub-module of your custom application directory.
131+
132+
.. image:: image/custom_app_dir_through_containment.png
133+
134+
Kconfig and Makefile
135+
^^^^^^^^^^^^^^^^^^^^
136+
137+
There are only a few minimal requirements of your custom application directory.
138+
It needs to have only its own ``Makefile`` and ``Kconfig`` file. That
139+
``Kconfig`` would need to include the ``apps/Kconfig``. The ``Makefile`` would
140+
similarly need to invoke the ``apps/Makefile`` for all of the relevant build
141+
targets. For example, the ``clean`` target:
142+
143+
.. code-block:: shell
144+
145+
$(MAKE) -c apps clean TOPDIR=$(TOPDIR)
146+
147+
Library Issues
148+
^^^^^^^^^^^^^^
149+
150+
The contained directory will create and install a static library called
151+
``libapps($LIBEXT)`` in the ``nuttx/staging`` directory. Your custom logic must
152+
also appear in the ``nuttx/staging`` directory. Here are two ways that you might
153+
do that:
154+
155+
1. **Merge with ``libapps($LIBEXT)``.**
156+
The custom application directory's ``Makefile`` could create and install the
157+
final ``libapps($LIBEXT)`` in the ``nuttx/staging`` directory.
158+
``<custom-dir>/apps/libapps($LIBEXT)`` could merge its custom object files
159+
with ``<custom-dir>/libapps($LIBEXT)`` and then re-install the library at
160+
``nuttx/staging``.
161+
2. **Use the EXTRA_LIBS Feature.**
162+
The build system supports two special make-related variables called
163+
``EXTRA_LIBS`` and ``EXTRA_LIBPATHS``. These may be defined in your
164+
board-specific ``Make.defs`` file. ``EXTRA_LIBS`` provides the name of your
165+
custom library. If you create ``<custom-dir>/libcustom.a``, then the value
166+
of ``EXTRA_LIBS`` would be ``-lcustom`` and the value of ``EXTRA_LIBPATHS``
167+
would be ``-L <custom-dir>`` (assuming the GNU ld linker).
168+
169+
Relative Effort and Benefits
170+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
171+
172+
The contained ``apps/`` directory approach requires some more effort than the
173+
extended ``apps/`` approach, but has the advantage that there will be no strange
174+
behavior due to issues with ``.gitignore`` and, hence, a cleaner user
175+
experience.
176+
177+
Out-of-tree Builds
178+
^^^^^^^^^^^^^^^^^^
179+
180+
This configuration also has the possibility of supporting out-of-tree builds
181+
using ``fusefs``. Suppose, for example, that you have a project directory with
182+
the contained ``apps/`` directory and, say, three platform build directories.
183+
Using ``fusefs``, you can overlay one of the platform build directories on top
184+
of the project directory. Then all files generated by the build will be written
185+
into the overlaid platform build directory. When the ``fusefs`` is torn down,
186+
the project directory will still be clean, and the build result will still be in
187+
the platform build directory. This can then be repeated for the other two
188+
platform build directories.
189+
190+
In this case, you would probably also want to contain the ``nuttx/`` directory
191+
in the project directory as well so that the entire system is built out-of-tree.
192+
193+
Hooking External Applications into the Configuration System
194+
-----------------------------------------------------------
195+
196+
Suppose you have opted to extend the ``apps/`` directory with your custom
197+
external application directories and would also like to support configuration
198+
variables in your external application. No problem! Thanks to Sebastien Lorquet,
199+
any external application that you install into the ``apps/`` (whether via a
200+
symbolic link or via a directory copy) `will` be included in the NuttX
201+
configuration system.
202+
203+
The top-level ``Kconfig`` file in the ``apps/`` directory is automatically
204+
generated based on the contents of each ``apps/`` sub-directory. If your
205+
installed sub-directory contains ``Kconfig``, ``Makefile``, and ``Make.defs``
206+
files, then it will be incorporated into the NuttX configuration system when the
207+
top-level ``Kconfig`` file is generated.

‎Documentation/guides/building_uclibcpp.rst‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
=================
2+
Building uClibc++
3+
=================
4+
5+
.. warning::
6+
Migrated from:
7+
https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=139629550
8+
and is probably outdated
9+
10+
A version of `uClibc++ <http://cxx.uclibc.org/>`_ has been ported to NuttX and is available in the NuttX
11+
uClibc++ GIT repository at `Bitbucket.org <https://bitbucket.org/nuttx/uclibc/>`_ . This version of uClibc++ was
12+
adapted for NuttX by the RGMP team.
13+
14+
This custom version of uClibc++ resides in the NuttX repository at:
15+
16+
https://bitbucket.org/nuttx/uclibc/
17+
18+
rather than in the main NuttX source tree, due to licensing issues: NuttX is
19+
licensed under the permissive, modified BSD License; uClibc++, on the other
20+
hand, is licensed under the stricter GNU LGPL Version 3 license.
21+
22+
General build instructions are available in the uClibc++ `README.txt <https://bitbucket.org/nuttx/uclibc/src/master/README.txt>`_
23+
file. Those instructions are not repeated here. This page documents specific
24+
issues encountered when building this NuttX version of uClibc++ and how they
25+
are resolved.
26+
27+
Undefined Reference to ``_impure_ptr``
28+
======================================
29+
30+
**Problem**
31+
32+
When building uClibc++, you may encounter an undefined reference to
33+
``_impure_ptr`` similar to:
34+
35+
.. code-block:: none
36+
37+
LD: nuttx
38+
.../arm-none-eabi/lib/armv7e-m\libsupc++.a(vterminate.o): In function
39+
`__gnu_cxx::__verbose_terminate_handler()`:
40+
vterminate.cc:(.text._ZN9__gnu_cxx27__verbose_terminate_handlerEv+0xfc):
41+
undefined reference to `_impure_ptr'
42+
43+
**Solution**
44+
45+
A definitive, elegant solution is not known, but the following workaround has
46+
proven to work:
47+
48+
1. Locate the directory where you can find ``libsupc++``:
49+
50+
.. code-block:: console
51+
52+
arm-none-eabi-gcc -mcpu=cortex-m4 -mthumb -print-file-name=libsupc++.a
53+
54+
2. Go to that directory and save a copy of ``vterminate.o`` (in case you need
55+
it later):
56+
57+
.. code-block:: console
58+
59+
cd <the-directory-containing-libsupc++.a>
60+
arm-none-eabi-ar.exe -x libsupc++.a vterminate.o
61+
62+
3. Remove ``vterminate.o`` from the library. At build time, the uClibc++
63+
package will provide a usable replacement:
64+
65+
.. code-block:: console
66+
67+
arm-none-eabi-ar.exe -d libsupc++.a vterminate.o
68+
69+
4. At this point, NuttX should link with no problem. If you ever want to
70+
restore the original ``vterminate.o`` to ``libsupc++.a``, you can do so
71+
by running:
72+
73+
.. code-block:: console
74+
75+
arm-none-eabi-ar.exe rcs libsupc++.a vterminate.o
76+
77+
After removing ``vterminate.o`` from the standard library, the
78+
uClibc++-provided ``vterminate.o`` becomes the active implementation and
79+
prevents references to ``_impure_ptr`` from arising during linkage.
80+
81+
.. note::
82+
Always exercise caution when modifying toolchain libraries. This
83+
workaround is known to be effective but it replaces standard library
84+
objects, which may have side effects in other toolchain usage scenarios.

0 commit comments

Comments
 (0)