Add nuttx to the system framework, which is 10.1.0

2021-06-09 14:33:15 +08:00
parent 06c351e27c
commit 804bd57aa0
5000 changed files with 1488544 additions and 0 deletions
@@ -0,0 +1,239 @@
+# Application Folder
+
+## Contents
+
+- General
+- Directory Location
+- Built-In Applications
+- NuttShell (NSH) Built-In Commands
+- Synchronous Built-In Commands
+- Application Configuration File
+- Example Built-In Application
+- Building NuttX with Board-Specific Pieces Outside the Source Tree
+
+## General
+
+This folder provides various applications found in sub-directories. These
+applications are not inherently a part of NuttX but are provided to help you
+develop your own applications. The `apps/` directory is a _break away_ part of
+the configuration that you may choose to use or not.
+
+## Directory Location
+
+The default application directory used by the NuttX build should be named
+`apps/` (or `apps-x.y.z/` where `x.y.z` is the NuttX version number). This
+`apps/` directory should appear in the directory tree at the same level as the
+NuttX directory. Like:
+
+```
+ .
+ |- nuttx
+ |
+ `- apps
+```
+
+If all of the above conditions are TRUE, then NuttX will be able to find the
+application directory. If your application directory has a different name or is
+location at a different position, then you will have to inform the NuttX build
+system of that location. There are several ways to do that:
+
+1) You can define `CONFIG_APPS_DIR` to be the full path to your application
+   directory in the NuttX configuration file.
+2) You can provide the path to the application directory on the command line
+   like: `make APPDIR=<path>` or `make CONFIG_APPS_DIR=<path>`
+3) When you configure NuttX using `tools/configure.sh`, you can provide that
+   path to the application directory on the configuration command line like:
+   `./configure.sh -a <app-dir> <board-name>:<config-name>`
+
+## Built-In Applications
+
+NuttX also supports applications that can be started using a name string. In
+this case, application entry points with their requirements are gathered
+together in two files:
+
+- `builtin/builtin_proto.h` – Entry points, prototype function
+- `builtin/builtin_list.h` – Application specific information and requirements
+
+The build occurs in several phases as different build targets are executed: (1)
+context, (2) depend, and (3) default (all). Application information is collected
+during the make context build phase.
+
+To execute an application function:
+
+`exec_builtin()` is defined in the `nuttx/include/apps/builtin/builtin.h`.
+
+## NuttShell (NSH) Built-In Commands
+
+One use of builtin applications is to provide a way of invoking your custom
+application through the NuttShell (NSH) command line. NSH will support a
+seamless method invoking the applications, when the following option is enabled
+in the NuttX configuration file:
+
+```conf
+CONFIG_NSH_BUILTIN_APPS=y
+```
+
+Applications registered in the `apps/builtin/builtin_list.h` file will then be
+accessible from the NSH command line. If you type `help` at the NSH prompt, you
+will see a list of the registered commands.
+
+## Synchronous Built-In Commands
+
+By default, built-in commands started from the NSH command line will run
+asynchronously with NSH. If you want to force NSH to execute commands then wait
+for the command to execute, you can enable that feature by adding the following
+to the NuttX configuration file:
+
+```conf
+CONFIG_SCHED_WAITPID=y
+```
+
+The configuration option enables support for the `waitpid()` RTOS interface.
+When that interface is enabled, NSH will use it to wait, sleeping until the
+built-in command executes to completion.
+
+Of course, even with `CONFIG_SCHED_WAITPID=y` defined, specific commands can
+still be forced to run asynchronously by adding the ampersand (`&`) after the
+NSH command.
+
+## Application Configuration File
+
+The NuttX configuration uses `kconfig-frontends` tools and the NuttX
+configuration file (`.config`) file. For example, the NuttX `.config` may have:
+
+```conf
+CONFIG_EXAMPLES_HELLO=y
+```
+
+This will select the `apps/examples/hello` in the following way:
+
+- The top-level make will include `examples/Make.defs`
+- `examples/Make.defs` will set `CONFIGURED_APPS += $(APPDIR)/examples/hello`
+  like this:
+
+```makefile
+  ifneq ($(CONFIG_EXAMPLES_HELLO),)
+  CONFIGURED_APPS += $(APPDIR)/examples/hello
+  endif
+```
+
+## Example Built-In Application
+
+An example application skeleton can be found under the `examples/hello`
+sub-directory. This example shows how a builtin application can be added to the
+project. One must:
+
+ 1. Create sub-directory as: progname
+
+ 2. In this directory there should be:
+
+    - A `Make.defs` file that would be included by the `apps/Makefile`
+    - A `Kconfig` file that would be used by the configuration tool (see the
+      file `kconfig-language.txt` in the NuttX tools repository). This `Kconfig`
+      file should be included by the `apps/Kconfig` file
+    - A `Makefile`, and
+    - The application source code.
+
+ 3. The application source code should provide the entry point:
+
+    ```c
+    main()
+    ```
+
+ 4. Set the requirements in the file: `Makefile`, specially the lines:
+
+    ```makefile
+    PROGNAME   = progname
+    PRIORITY   = SCHED_PRIORITY_DEFAULT
+    STACKSIZE  = 768
+    ASRCS      = asm source file list as a.asm b.asm ...
+    CSRCS      = C source file list as foo1.c foo2.c ..
+    ```
+
+ 5. The `Make.defs` file should include a line like:
+
+    ```makefile
+    ifneq ($(CONFIG_PROGNAME),)
+    CONFIGURED_APPS += progname
+    endif
+    ```
+
+## Building NuttX with Board-Specific Pieces Outside the Source Tree
+
+Q: Has anyone come up with a tidy way to build NuttX with board- specific pieces
+   outside the source tree?
+
+A: Here are three:
+
+   1) There is a make target called `make export`. It will build NuttX, then
+      bundle all of the header files, libraries, startup objects, and other
+      build components into a `.zip` file. You can move that `.zip` file into
+      any build environment you want. You can even build NuttX under a DOS `CMD`
+      window.
+
+      This make target is documented in the top level `nuttx/README.txt`.
+
+   2) You can replace the entire `apps/` directory. If there is nothing in the
+      `apps/` directory that you need, you can define `CONFIG_APPS_DIR` in your
+      `.config` file so that it points to a different, custom application
+      directory.
+
+      You can copy any pieces that you like from the old apps/directory to your
+      custom apps directory as necessary.
+
+      This is documented in `NuttX/boards/README.txt` and
+      `nuttx/Documentation/NuttXPortingGuide.html` (Online at
+      https://bitbucket.org/nuttx/nuttx/src/master/Documentation/NuttXPortingGuide.html#apndxconfigs
+      under _Build options_). And in the `apps/README.txt` file.
+
+   3) If you like the random collection of stuff in the `apps/` directory but
+      just want to expand the existing components with your own, external
+      sub-directory then there is an easy way to that too: You just create a
+      symbolic link in the `apps/` directory that redirects to your application
+      sub-directory.
+
+      In order to be incorporated into the build, the directory that you link
+      under the `apps/` directory should contain (1) a `Makefile` that supports
+      the `clean` and `distclean` targets (see other `Makefile`s for examples),
+      and (2) a tiny `Make.defs` file that simply adds the custom build
+      directories to the variable `CONFIGURED_APPS` like:
+
+      ```makefile
+      CONFIGURED_APPS += my_directory1 my_directory2
+      ```
+
+      The `apps/Makefile` will always automatically check for the existence of
+      subdirectories containing a `Makefile` and a `Make.defs` file. The
+      `Makefile` will be used only to support cleaning operations. The Make.defs
+      file provides the set of directories to be built; these directories must
+      also contain a `Makefile`. That `Makefile` must be able to build the
+      sources and add the objects to the `apps/libapps.a` archive. (see other
+      `Makefile`s for examples). It should support the all, install, context,
+      and depend targets.
+
+      `apps/Makefile` does not depend on any hardcoded lists of directories.
+      Instead, it does a wildcard search to find all appropriate directories.
+      This means that to install a new application, you simply have to copy the
+      directory (or link it) into the `apps/` directory. If the new directory
+      includes a `Makefile` and `Make.defs` file, then it will automatically be
+      included in the build.
+
+      If the directory that you add also includes a `Kconfig` file, then it will
+      automatically be included in the NuttX configuration system as well.
+      `apps/Makefile` uses a tool at `apps/tools/mkkconfig.sh` that dynamically
+      builds the `apps/Kconfig` file at pre-configuration time.
+
+      You could, for example, create a script called `install.sh` that installs
+      a custom application, configuration, and board specific directory:
+
+      a) Copy `MyBoard` directory to `boards/MyBoard`.
+      b) Add a symbolic link to `MyApplication` at `apps/external`.
+      c) Configure NuttX, usually by:
+
+      ```bash
+      tools/configure.sh MyBoard:MyConfiguration
+      ```
+
+      Use of the name `apps/external` is suggested because that name is included
+      in the `.gitignore` file and will save you some nuisance when working with
+      GIT.