Fork 0
Gregory Nutt 59bd03bb52 Update ChangeLogs 2015-04-05 09:46:39 -06:00
NxWidgets Kconfig files: If external graphics initialization is required, it depends on CONFIG_LIB_BOARDCTL and should set CONFIG_BOARDCTL_GRAPHICS 2015-03-31 16:41:48 -06:00
builtin apps/builtin: better fix for building with parallel make 2015-02-03 08:24:24 -06:00
examples Add a 'capped' boolean parameter to all drawline/drawLine functions/methods. The idea is that this will produce better joining between lines 2015-04-05 08:50:01 -06:00
graphics Add basic board support for the DK-TM4C129X Connected Development Kit. The initial commit is simply the TM4C123G Launchpad with naming changes 2014-12-16 15:29:14 -06:00
import ELF build reuires -fno-common in CFLAGS 2014-09-08 07:57:05 -06:00
include apps/netutils/netlib: Add utilities to convert to/from prefix lengths from/to 128-bit network masks. Modify the NSH IPv6 ifconfig command to show the network mask in a more standard, human readable way. 2015-02-06 10:23:15 -06:00
interpreters Add math library defines for nan functions. From Brennan Ashton. 2015-01-26 19:03:38 -06:00
modbus Suffer the consequences of moving struct timeval to its correct location 2015-02-15 15:18:35 -06:00
netutils Add some missing dependencies in Kconfig files 2015-03-29 15:52:46 -06:00
nshlib NSH initialization now calls boardctl(BOARDIOC_INIT) instead of board_app_initaliaze. Modify all configurations: Make sure that CONFIG_LIB_BOARDCTL=y appears wherever CONFIG_NSH_ARCHINIT=y appears. Remove support for CONFIG_NSH_ARCHMAC. It is not used and there are better ways to do that operation 2015-03-31 12:14:16 -06:00
platform Rename up_cxxinitialize.c to stm32_cxxinitialize.c 2015-03-23 14:14:01 -06:00
system Add Olimexino-STM32 board support from David Sidrane 2015-03-20 18:00:10 -06:00
tools Add a script to create a boot ROMFS image 2014-09-09 12:45:23 -06:00
.gitignore Add a script to create a boot ROMFS image 2014-09-09 12:45:23 -06:00
COPYING More trailing whilespace removal 2014-04-13 16:24:28 -06:00
ChangeLog.txt Update ChangeLogs 2015-04-05 09:46:39 -06:00
Kconfig Add a tiny INI file parser 2014-01-15 17:52:06 -06:00
Make.defs Removed all support for the legacy configuration mechanism from the apps/ directory 2014-03-06 12:21:14 -06:00
Makefile apps/builtin: better fix for building with parallel make 2015-02-03 08:24:24 -06:00
README.txt Removed all support for the legacy configuration mechanism from the apps/ directory 2014-03-06 12:21:14 -06:00


Application Folder


  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

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/ where x.y 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.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:


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:


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:


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 += examples/hello
  like this:

  CONFIGURED_APPS += examples/hello

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: appname

 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
      misc/tools/kconfig-language.txt).  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:

 4. Set the requirements in the file: Makefile, specially the lines:

    APPNAME    = appname
    STACKSIZE  = 768
    ASRCS      = asm source file list as a.asm b.asm ...
    CSRCS      = C source file list as foo1.c foo2.c ..

 4b. The Make.defs file should include a line like:

    ifeq ($(CONFIG_APPNAME),y)
    CONFIGURED_APPS += appname

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 four:

   1) There is a make target called 'make export'. It will build
      NuttX, then bundle all of the header files, libaries, startup
      objects, and other build components into a .zip file. You
      can can move that .zip file into any build environment you
      want. You 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/configs/README.txt and
      nuttx/Documentation/NuttxPortingGuide.html (Online at
      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 the sympolic link at apps/external that
      redirects to your application sub-directory. The apps/Makefile
      will always automatically check for the existence of an
      apps/external directory and if it exists, it will automatically
      incorporate it into the build.

      This feature of the apps/Makefile is documented only here.

      You can, for example, create a script called install.sh that
      installs a custom application, configuration, and board specific

      a) Copy 'MyBoard' directory to configs/MyBoard.
      b) Add a symbolic link to MyApplication at apps/external
      c) Configure NuttX (usually by:

         tools/configure.sh MyBoard/MyConfiguration

         or simply by copying defconfig->nuttx/.config,
         setenv.sh->nuttx/setenv.sh, and Make.defs->nuttx/Make.defs.

      Using the 'external' link makes it especially easy to add a
      'built-in' application an existing configuration.

   4) Add any link to apps/

      a) Add symbolic links apps/ to as many other directories as you
      b) Add the symbolic link to the list of candidate paths in the
         top level apps/Makefile, and
      b) Add the (relative) paths to the CONFIGURED_APPS list
         in the Make.defs file in your new directory.

      That is basically the same as my option #3 but doesn't use the
      magic 'external' link.