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.
The default application directory used by the NuttX build should be named
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:
CONFIG_APPS_DIRto be the full path to your application directory in the NuttX configuration file.
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>
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
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:
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.
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:
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.
The NuttX configuration uses
kconfig-frontends tools and the NuttX configuration file (
.config) file. For example, the NuttX
.config may have:
This will select the
apps/examples/hello in the following way:
CONFIGURED_APPS += $(APPDIR)/examples/hellolike this:
ifneq ($(CONFIG_EXAMPLES_HELLO),) CONFIGURED_APPS += $(APPDIR)/examples/hello endif
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:
Create sub-directory as: progname
In this directory there should be:
Make.defsfile that would be included by the
Kconfigfile that would be used by the configuration tool (see the file
kconfig-language.txtin the NuttX tools repository). This
Kconfigfile should be included by the
The application source code should provide the entry point:
Set the requirements in the file:
Makefile, specially the lines:
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 ..
Make.defs file should include a line like:
ifneq ($(CONFIG_PROGNAME),) CONFIGURED_APPS += progname endif
Q: Has anyone come up with a tidy way to build NuttX with board- specific pieces outside the source tree?
A: Here are three:
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
This make target is documented in the top level
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/Documentation/NuttXPortingGuide.html (Online at https://bitbucket.org/nuttx/nuttx/src/master/Documentation/NuttXPortingGuide.html#apndxconfigs under Build options). And in the
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
distclean targets (see other
Makefiles for examples), and (2) a tiny
Make.defs file that simply adds the custom build directories to the variable
CONFIGURED_APPS += my_directory1 my_directory2
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 must be able to build the sources and add the objects to the
apps/libapps.a archive. (see other
Makefiles 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
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:
MyBoard directory to
b) Add a symbolic link to
c) Configure NuttX, usually by:
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.