diff options
Diffstat (limited to 'apps')
-rw-r--r-- | apps/README.txt | 132 |
1 files changed, 93 insertions, 39 deletions
diff --git a/apps/README.txt b/apps/README.txt index af3d07304..f6d888adc 100644 --- a/apps/README.txt +++ b/apps/README.txt @@ -1,70 +1,124 @@ Application Folder ================== -This folder provides various applications found in sub-directories. - -Application entry points with their requirements are gathered together in -in two files: - - - namedapp/namedapp_proto.h Entry points, prototype function - - namedapp/namedapp_list.h Application specific information and requirements +Contents +-------- + + General + Directory Location + Named Applications + Named Startup main() function + NuttShell (NSH) Built-In Commands + Application Configuration File + Example Named Application + +General +------- +This folder provides various applications found in sub-directories. These +applications are not inherently a part of NuttX but are provided you help +you develop your own applications. The apps/ directory is a "break away" +part of the configuration that you may chose 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/ +directoy 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> + +Named Applications +------------------ +NuttX also supports applications that can be started using a name string. +In this case, zpplication entry points with their requirements are gathered +together in two files: + + - namedapp/namedapp_proto.h Entry points, prototype function + - namedapp/namedapp_list.h Application specific information and requirements The build occurs in several phases as different build targets are executed: -(1) contex, (2) depend, and (3) default (all). Application information is +(1) context, (2) depend, and (3) default (all). Application information is collected during the make context build phase. To execute an application function: - exec_namedapp() is defined in the nuttx/include/apps/apps.h - -NuttShell provides transparent method of invoking the command, when the -following option is enabled: + exec_namedapp() is defined in the nuttx/include/apps/apps.h - CONFIG_NSH_BUILTIN_APPS=y +NuttShell (NSH) Built-In Commands +--------------------------------- +One use of named 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: -in the NuttX configuration. + CONFIG_NSH_BUILTIN_APPS=y +Application Configuration File +------------------------------ A special configuration file is used to configure which applications -are to be included in the build. This file is configs/<board>/<configuration>/appconfig. -The existence of the appconfig file in the board configuration directory -is sufficient to enable building of applications. +are to be included in the build. The source for this file is +configs/<board>/<configuration>/appconfig. The existence of the appconfig +file in the board configuration directory is sufficient to enable building +of applications. The appconfig file is copied into the apps/ directory as .config when NuttX is configured. .config is included in the toplevel apps/Makefile. As a minimum, this configuration file must define files to add to the CONFIGURED_APPS list like: - CONFIGURED_APPS += hello poweroff jvm - -The form of each entry is <dir>=<dependency> when: - - <dir> is the name of a subdirectory in the apps directory, and + CONFIGURED_APPS += vsn/hello vsn/poweroff vsn/jvm - <dependency> is a make dependency. This will be "touch"-ed each time - that the sub-directory is rebuilt. +Named Start-Up main() function +------------------------------ +A named application can even be used as the main, start-up entry point +into your embedded software. When the user defines this option in +the NuttX configuration file: -When the user defines an option: - CONFIG_BUILTIN_APP_START=<application name> - -that application shall be invoked immediately after system starts. -Note that application name must be provided in ".." as: "hello", + CONFIG_BUILTIN_APP_START=<application name> + +that application shall be invoked immediately after system starts +*instead* of the normal, default "user_start" entry point. +Note that <application name> must be provided as: "hello", will call: - int hello_main(int argc, char *argv[]) -Application skeleton can be found under the hello sub-directory, -which shows how an application can be added to the project. One must -define: + int hello_main(int argc, char *argv[]) + +Example Named Application +------------------------- +An example application skeleton can be found under the vsn/hello +sub-directory. This example shows how a named application can be added +to the project. One must define: 1. create sub-directory as: appname 2. provide entry point: appname_main() 3. set the requirements in the file: Makefile, specially the lines: - APPNAME = appname - 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 .. - 4. add application in the apps/Makefile + APPNAME = appname + 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 .. + + 4. add application in the apps/.config + |