Custom Apps How-to

NuttX comes with a large number of Apps but, most likely, you will want to add your own.

There are various different options for this depending on your requirements.

  1. Replace the apps/ directory completely

  2. Extend the apps/ directory to include a new custom directory

  3. Include an additional custom directory outside of the main source trees

The following sections explain these 3 methods using a CustomHello.c app and the directory CustomApps as an example.

Tip

If you make errors while setting this up and the build fails, it is most likely you’ll need to run make clean and possibly even make distclean before rebuilding to ensure it works correctly.

1. Replace The Apps/ Directory Completely

The CustomApps directory need only to contain the minimum three files:

  • Makefile

  • Kconfig

  • CustomHello.c

1.1 Makefile

The custom application directory must include a Makefile to make all of the targets expected by the NuttX build and must generate an archive called libapps.a in the top-level of the custom directory structure.

The Makefile has just those minimum required targets:

APPDIR = ${shell pwd}

-include $(TOPDIR)/Make.defs

# files

CSRCS = CustomHello.c
COBJS = CustomHello.o

ROOTDEPPATH = --dep-path .

# Build targets

all: libapps.a
.PHONY: dirlinks context preconfig depend clean clean_context distclean
.PRECIOUS: libapps$(LIBEXT)

# Compile C Files

$(COBJS): %$(OBJEXT): %.c
$(call COMPILE, $<, $@)

# Add object files to the apps archive

libapps.a: $(COBJS)
  $(call ARCHIVE, libapps.a, $(COBJS))

# Create directory links

dirlinks:

# Setup any special pre-build context

context:

# Setup any special pre-configuration context

preconfig:

# Make the dependency file, Make.deps

depend: Makefile $(CSRCS)
  $(Q) $(MKDEP) $(ROOTDEPPATH) "$(CC)" -- $(CFLAGS) -- $(SRCS) > Make.dep

# Clean the results of the last build

clean:
  $(call CLEAN)

# Remove the build context and directory links

clean_context:

# Restore the directory to its original state

distclean: clean clean_context
  $(call DELFILE, Make.dep)

# Include dependencies

-include Make.dep

1.2 Kconfig

A Kconfig file must be included but need not be populated with any meaningful options. This is a place where you can add settings to generate customized builds of your custom application and/or choose which of your apps to include.

In the minimum case, Kconfig is only:

# For a description of the syntax of this configuration file,
# see the file kconfig-language.txt in the NuttX tools repository.
#

or

# For a description of the syntax of this configuration file,
# see the file kconfig-language.txt in the NuttX tools repository.
#

1.3 CustomHello.c

The custom application must actually compile some source files in order to generate the required libapps.a archive. One of these source files must include the main() entry point to the application.

The function of this main() entry point simply to bring-up the full application. It is called at the completion of OS initialization.

What this application initialization entry point does, how it interacts with the rest of your application, and where the rest of you application code is located is of no concern to the OS.

Only this one entry point is needed.

For this “Hello, Custom World!” application custom_hello() is the application entry point:

#include <stdio.h>

int custom_hello(int argc, char *argv[])
{
  printf("Hello, Custom World!!\n");
  return 0;
}

1.4 Building with the CustomApps Directory

In order to build with the new custom configuration, you will need the following in your configuration:

CONFIG_APPS_DIR=”../CustomApps”

CONFIG_USER_ENTRYPOINT=”custom_hello”

Note that you can only access the ../CustomApps/Kconfig configuration file if CONFIG_APPS_DIR is set to ../CustomApps BEFORE make menuconfig is executed

This can be done by

  • hand-editing the .config file before running make menuconfig, which is rarely a good idea

  • Using kconfig-tweak --set-str CONFIG_APPS_DIR ../CustomApps

  • select the CustomApps directory as a command line option at the time the board is configured:

    ./tools/configure.sh -a ../CustomApps <board>:<config>

    or

    .tools/configure.sh -l ../CustomBoards/MyCustomBoardName/MyCustomConfig

Then build as you normally would. When you execute the custom_hello app you should see:

Hello, Custom World!!

2. Extend the apps/ directory to include a new custom directory

The collection of apps provided in nuttx-apps can be useful, and this method simply extends the directory structure to include your own directory structure.

The existing /apps makefile automatically checks for the existence of sub-directories that contain a Makefile and Make.defs file. This example assumes there is likely to be more than one custom app, and includes a Kconfig for the app itself. Inclusion of a Kconfig allows custom App options to be included in the NuttX configuration system, but is optional.

2.1 Custom Apps Directory

Simply create a new directory under the existing apps directory with a name of your choice. This example uses the directory name CustomApps.

2.2 Make.defs

Create this file in the CustomApps directory, with the following line added:

include $(wildcard $(APPDIR)/CustomApps/*/Make.defs)

2.3 Makefile

Create a Makefile in the CustomApps directory, with the following lines added:

MENUDESC = "Custom Apps"

include $(APPDIR)/Directory.mk

2.4 CustomHello App

Create a sub-directory under the CustomApps directory called CustomHello.

The same CustomHello.c file as described above should be created here.

2.5 CustomHello Makefile

Create a Makefile in the CustomApps/CustomHello directory with the following lines:

include $(APPDIR)/Make.defs

# Custom Hello built-in application info

PROGNAME = $(CONFIG_CUSTOM_APPS_CUSTOM_HELLO_PROGNAME)
PRIORITY = $(CONFIG_CUSTOM_APPS_CUSTOM_HELLO_PRIORITY)
STACKSIZE = $(CONFIG_CUSTOM_APPS_CUSTOM_HELLO_STACKSIZE)
MODULE = $(CONFIG_CUSTOM_APPS_CUSTOM_HELLO)

# Custom Hello

MAINSRC = CustomHello.c

include $(APPDIR)/Application.mk

2.6 CustomHello Kconfig

Create a Kconfig file in the CustomApps/CustomHello directory, with the following lines. For the purposes of this example, the Kconfig will only cover our single application):

#
# For a description of the syntax of this configuration file,
# see the file kconfig-language.txt in the NuttX tools repository.
#

config CUSTOM_APPS_CUSTOM_HELLO
        tristate "Custom Hello App"
        default n
        ---help---
                Enable the Custom Hello App

if CUSTOM_APPS_CUSTOM_HELLO

config CUSTOM_APPS_CUSTOM_HELLO_PROGNAME
        string "Program name"
        default "custom_hello"
        ---help---
                This is the name of the program that will be used when the NSH ELF
                program is installed.

config CUSTOM_APPS_CUSTOM_HELLO_PRIORITY
        int "Custom Hello task priority"
        default 100

config CUSTOM_APPS_CUSTOM_HELLO_STACKSIZE
        int "Custom Hello stack size"
        default DEFAULT_TASK_STACKSIZE

endif

2.7 Build and Run

Once these files have been created, run a make clean (you may need to run make distclean followed by make menuconfig. If successful there will be new Kconfig entries.

Application Configuraration ‣ Custom Apps ‣ Custom Hello App

Select the Custom Hello App and run the usual build process. If successful you can run the newly included custom_hello app.

3. Include an Additional Custom Cirectory Outside of the Main Source Trees

Thia is similar to the previous approach, but places the CustomApps directory outside of the default trees.

3.2 Make.defs etc.

Follow all the steps as in sections 2.2 to 2.7 above, creating the exact same files but placing then in the new CustomApps directory location created as described here.