Custom Application Directories

Warning

Migrated from: https://cwiki.apache.org/confluence/display/NUTTX/Custom+Application+Directories

Most people use the generic apps/ directory with NuttX. That is convenient and well-documented. However, it should always be remembered that NuttX is a stand-alone, general-purpose OS and has no dependency on that “canned” application directory.

This page shows how to create your own, custom application directory from scratch.

Creating the Custom Application Directory

Below is a simple example of the minimum custom application directory. It contains only three files: Makefile, Kconfig, and hello.c.

Makefile

The custom application directory must include a Makefile that supports all of the make targets expected by the NuttX build system and must generate an archive called libapps.a in the top-level of the custom directory structure. The minimal required targets for the Makefile look like this:

APPDIR = ${shell pwd}

-include $(TOPDIR)/Make.defs

# files

CSRCS = hello.c
COBJS = hello.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

Kconfig

A Kconfig file must be included, but it need not contain any meaningful configuration options. This file is where you can add application-specific configuration settings if desired. The minimal Kconfig might look like:

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

hello.c

Your custom application must compile at least one source file to generate the required libapps.a archive. One of these source files must include the main() entry point to the application. That main function (or similarly named entry point) is called after OS initialization completes.

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.

Below is a small “Hello, World!” example, where custom_main() is the application entry point:

#include <stdio.h>

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

Building with the Custom Application Directory

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

CONFIG_APPS_DIR="../custom-apps"
CONFIG_USER_ENTRYPOINT="custom_main"

Note

You can only access the ../custom-apps/Kconfig file if CONFIG_APPS_DIR is set to ../custom-apps before running make menuconfig. If you start with an existing configuration, you may face a “chicken-and-egg” situation. One workaround is to manually edit the .config file before running make menuconfig.

Alternatively, if you use the tools/configure.sh script, you can specify the custom-apps directory from the command line:

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

Afterward, just build NuttX as you normally would. When you run the program that was built with your custom application directory, you should see:

Hello, World!!