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 2026/10/22 02:23:09 UTC
(nuttx) 02/02: Documentation: Say that the arch sets the ELF and module flags.
This is an automated email from the ASF dual-hosted git repository.
xiaoxiang781216 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit a46119d43726b69bb91805af45ec94c5024c95d2
Author: Marco Casaroli <ma...@gmail.com>
AuthorDate: Tue Oct 20 23:33:23 2026 +0200
Documentation: Say that the arch sets the ELF and module flags.
The notes of the elf, posix_spawn, module and sotest examples told the
board to set CELFFLAGS, LDELFFLAGS, CMODULEFLAGS and LDMODULEFLAGS
with "=", with the entry point main and with linker scripts that do
not exist. The arch Toolchain.defs sets these flags. Say that a board
can add an option with "+=", and that it must not set them again.
Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: Marco Casaroli <ma...@gmail.com>
---
Documentation/applications/examples/elf/index.rst | 37 +++++++---------------
.../applications/examples/module/index.rst | 36 ++++++---------------
.../applications/examples/posix_spawn/index.rst | 37 +++++++---------------
.../applications/examples/sotest/index.rst | 36 ++++++---------------
4 files changed, 42 insertions(+), 104 deletions(-)
diff --git a/Documentation/applications/examples/elf/index.rst b/Documentation/applications/examples/elf/index.rst
index 1988fd5a8b0..65707789bd4 100644
--- a/Documentation/applications/examples/elf/index.rst
+++ b/Documentation/applications/examples/elf/index.rst
@@ -27,41 +27,26 @@ Configuration options:
**Notes**:
-1. ``CFLAGS`` should be provided in ``CELFFLAGS``. RAM and FLASH memory regions may
- require long allcs. For ARM, this might be::
-
- CELFFLAGS = $(CFLAGS) -mlong-calls
-
- Similarly for C++ flags which must be provided in ``CXXELFFLAGS``.
-
-2. Your top-level ``nuttx/Make.defs`` file must also include an appropriate
- definition, ``LDELFFLAGS``, to generate a relocatable ELF object. With GNU LD,
- this should include ``-r`` and ``-e main`` (or ``_main`` on some platforms).::
-
- LDELFFLAGS = -r -e main
-
- If you use GCC to link, you make also need to include ``-nostdlib``.
-
-3. ELF size: The ELF files in this example are, be default, quite large because
+1. The arch ``Toolchain.defs`` sets ``CELFFLAGS``, ``CXXELFFLAGS`` and
+ ``LDELFFLAGS``. For example, on ARM they contain ``-mlong-calls``, the entry
+ point ``_start`` and the linker script ``libs/libc/elf/gnu-elf.ld``. A board
+ ``scripts/Make.defs`` can add an option with ``+=``, for example
+ ``LDELFFLAGS += -melf32lriscv``. Do not set these variables again with
+ ``=``: the board then loses the options that the arch adds for the
+ configuration, for example ``crt0.o`` and the PIC and FDPIC options.
+
+2. ELF size: The ELF files in this example are, be default, quite large because
they include a lot of build garbage. You can greatly reduce the size of the
ELF binaries are using the ``objcopy --strip-unneeded`` command to remove
un-necessary information from the ELF files.
-4. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
+3. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
That is because the Cygwin GCC does not generate ELF file but rather some
Windows-native binary format.
If you really want to do this, you can create a NuttX x86 buildroot toolchain
and use that be build the ELF executables for the ROMFS file system.
-5. Linker scripts. You might also want to use a linker scripts to combine
- sections better. An example linker script is at
- ``nuttx/binfmt/elf/gnu-elf.ld``. That example might have to be tuned for
- your particular linker output to position additional sections correctly. The
- GNU LD ``LDELFFLAGS`` then might be::
-
- LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/elf/gnu-elf.ld
-
-6. When generating the ``romfs.img`` for external filesystem the image (``romfs.img``)
+4. When generating the ``romfs.img`` for external filesystem the image (``romfs.img``)
needs to be manually copied to the start of the configured ``CONFIG_EXAMPLES_ELF_DEVPATH``
using ``openocd`` or your preferred programmer.
diff --git a/Documentation/applications/examples/module/index.rst b/Documentation/applications/examples/module/index.rst
index e75a3e86580..04115a12a88 100644
--- a/Documentation/applications/examples/module/index.rst
+++ b/Documentation/applications/examples/module/index.rst
@@ -20,43 +20,27 @@ configuration options:
**Notes**:
-1. ``CFLAGS`` should be provided in ``CMODULEFLAGS``. RAM and FLASH memory regions
- may require long allcs. For ARM, this might be::
-
- CMODULEFLAGS = $(CFLAGS) -mlong-calls
-
- Similarly for C++ flags which must be provided in ``CXXMODULEFLAGS``.
-
-2. Your top-level ``nuttx/Make.defs`` file must also include an appropriate
- definition, LDMODULEFLAGS, to generate a relocatable ELF object. With GNU LD,
- this should include ``-r`` and ``-e <entry point>``.::
-
- LDMODULEFLAGS = -r -e module_initialize
-
- If you use GCC to link, you make also need to include ``-nostdlib``.
-
-3. This example also requires ``genromfs``. ``genromfs`` can be build as part of the
+1. The arch ``Toolchain.defs`` sets ``CMODULEFLAGS`` and ``LDMODULEFLAGS``. For
+ example, on ARM they contain ``-mlong-calls``, ``-r`` and the linker script
+ ``libs/libc/elf/gnu-elf.ld``. A board ``scripts/Make.defs`` can add an option
+ with ``+=``, for example ``LDMODULEFLAGS += -melf32lriscv``. Do not set these
+ variables again with ``=``: the board then loses the options that the arch
+ adds for the configuration, for example the FDPIC options.
+
+2. This example also requires ``genromfs``. ``genromfs`` can be build as part of the
nuttx toolchain. Or can built from the ``genromfs`` sources that can be found
in the NuttX tools repository (``genromfs-0.5.2.tar.gz``). In any event, the
PATH variable must include the path to the ``genromfs`` executable.
-4. ELF size: The ELF files in this example are, be default, quite large because
+3. ELF size: The ELF files in this example are, be default, quite large because
they include a lot of build garbage. You can greatly reduce the size of the
ELF binaries are using the ``objcopy --strip-unneeded`` command to remove
un-necessary information from the ELF files.
-5. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
+4. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
That is because the Cygwin GCC does not generate ELF file but rather some
Windows-native binary format.
If you really want to do this, you can create a NuttX x86 ``buildroot``
toolchain and use that be build the ELF executables for the ROMFS file
system.
-
-6. Linker scripts. You might also want to use a linker scripts to combine
- sections better. An example linker script is at
- ``nuttx/libc/elf/gnu-elf.ld``. That example might have to be tuned for your
- particular linker output to position additional sections correctly. The GNU
- LD ``LDMODULEFLAGS`` then might be::
-
- LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/elf/gnu-elf.ld
diff --git a/Documentation/applications/examples/posix_spawn/index.rst b/Documentation/applications/examples/posix_spawn/index.rst
index f9872edcdbe..e4f83cb3c77 100644
--- a/Documentation/applications/examples/posix_spawn/index.rst
+++ b/Documentation/applications/examples/posix_spawn/index.rst
@@ -32,42 +32,27 @@ Test-specific configuration options:
**Notes**:
-1. ``CFLAGS`` should be provided in ``CELFFLAGS``. RAM and FLASH memory regions may
- require long allcs. For ARM, this might be::
-
- CELFFLAGS = $(CFLAGS) -mlong-calls
-
- Similarly for C++ flags which must be provided in ``CXXELFFLAGS``.
-
-2. Your top-level ``nuttx/Make.defs`` file must also include an appropriate
- definition, ``LDELFFLAGS``, to generate a relocatable ELF object. With GNU LD,
- this should include ``-r`` and ``-e main`` (or ``_main`` on some platforms).::
-
- LDELFFLAGS = -r -e main
-
- If you use GCC to link, you make also need to include ``-nostdlib``.
-
-3. This example also requires ``genromfs``. ``genromfs`` can be build as part of the
+1. The arch ``Toolchain.defs`` sets ``CELFFLAGS``, ``CXXELFFLAGS`` and
+ ``LDELFFLAGS``. For example, on ARM they contain ``-mlong-calls``, the entry
+ point ``_start`` and the linker script ``libs/libc/elf/gnu-elf.ld``. A board
+ ``scripts/Make.defs`` can add an option with ``+=``, for example
+ ``LDELFFLAGS += -melf32lriscv``. Do not set these variables again with
+ ``=``: the board then loses the options that the arch adds for the
+ configuration, for example ``crt0.o`` and the PIC and FDPIC options.
+
+2. This example also requires ``genromfs``. ``genromfs`` can be build as part of the
nuttx toolchain. Or can built from the ``genromfs`` sources that can be found
in the NuttX tools repository (``genromfs-0.5.2.tar.gz``). In any event, the
``PATH`` variable must include the path to the ``genromfs`` executable.
-4. ELF size: The ELF files in this example are, be default, quite large because
+3. ELF size: The ELF files in this example are, be default, quite large because
they include a lot of build garbage. You can greatly reduce the size of the
ELF binaries are using the ``objcopy --strip-unneeded`` command to remove
un-necessary information from the ELF files.
-5. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
+4. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
That is because the Cygwin GCC does not generate ELF file but rather some
Windows-native binary format.
If you really want to do this, you can create a NuttX x86 buildroot toolchain
and use that be build the ELF executables for the ROMFS file system.
-
-6. Linker scripts. You might also want to use a linker scripts to combine
- sections better. An example linker script is at
- ``nuttx/binfmt/elf/gnu-elf.ld``. That example might have to be tuned for
- your particular linker output to position additional sections correctly. The
- GNU LD ``LDELFFLAGS`` then might be::
-
- LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/elf/gnu-elf.ld
diff --git a/Documentation/applications/examples/sotest/index.rst b/Documentation/applications/examples/sotest/index.rst
index 1049591d7ab..980f98541d0 100644
--- a/Documentation/applications/examples/sotest/index.rst
+++ b/Documentation/applications/examples/sotest/index.rst
@@ -19,42 +19,26 @@ system. At run time, the shared library is installed and exercised. Requires
**Notes**:
-1. ``CFLAGS`` should be provided in ``CMODULEFLAGS``. RAM and FLASH memory regions
- may require long allcs. For ARM, this might be::
-
- CMODULEFLAGS = $(CFLAGS) -mlong-calls
-
- Similarly for C++ flags which must be provided in ``CXXMODULEFLAGS``.
-
-2. Your top-level ``nuttx/Make.defs`` file must also include an appropriate
- definition, ``LDMODULEFLAGS``, to generate a relocatable ELF object. With GNU
- LD, this should include ``-r`` and ``-e <entry point>``.::
-
- LDMODULEFLAGS = -r -e module_initialize
-
- If you use GCC to link, you make also need to include ``-nostdlib``.
-
-3. This example also requires ``genromfs``. ``genromfs`` can be built as part of the
+1. The arch ``Toolchain.defs`` sets ``CMODULEFLAGS`` and ``LDMODULEFLAGS``. For
+ example, on ARM they contain ``-mlong-calls``, ``-r`` and the linker script
+ ``libs/libc/elf/gnu-elf.ld``. A board ``scripts/Make.defs`` can add an option
+ with ``+=``, for example ``LDMODULEFLAGS += -melf32lriscv``. Do not set these
+ variables again with ``=``: the board then loses the options that the arch
+ adds for the configuration, for example the FDPIC options.
+
+2. This example also requires ``genromfs``. ``genromfs`` can be built as part of the
nuttx toolchain. Or can built from the ``genromfs`` sources that can be found
in the NuttX tools repository (``genromfs-0.5.2.tar.gz``). In any event, the
``PATH`` variable must include the path to the ``genromfs`` executable.
-4. ELF size: The ELF files in this example are, be default, quite large because
+3. ELF size: The ELF files in this example are, be default, quite large because
they include a lot of build garbage. You can greatly reduce the size of the
ELF binaries are using the ``objcopy --strip-unneeded`` command to remove
un-necessary information from the ELF files.
-5. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
+4. Simulator. You cannot use this example with the NuttX simulator on Cygwin.
That is because the Cygwin GCC does not generate ELF file but rather some
Windows-native binary format.
If you really want to do this, you can create a NuttX x86 buildroot toolchain
and use that to build the ELF executables for the ROMFS file system.
-
-6. Linker scripts. You might also want to use a linker script to combine
- sections better. An example linker script is at
- ``nuttx/libc/elf/gnu-elf.ld``. That example might have to be tuned for your
- particular linker output to position additional sections correctly. The GNU
- LD ``LDMODULEFLAGS`` then might be::
-
- LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/elf/gnu-elf.ld