incubator-nuttx/Documentation/guides/customapps.rst

==================
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.

  #. Replace the apps/ directory completely
  #. Extend the apps/ directory to include a new custom directory
  #. 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:

    .. code-block:: console

      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:

    .. code-block:: console

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

or

    .. code-block:: console

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

    .. code-block:: console

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

:menuselection:`CONFIG_APPS_DIR="../CustomApps"`

:menuselection:`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:
  
      .. code-block:: console  

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

  or

      .. code-block:: console  

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

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

  .. code-block:: console

    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:

  .. code-block:: console

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

2.3 Makefile
------------

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

  .. code-block:: console

    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:

  .. code-block:: console

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

  .. code-block:: console

    #
    # 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.

:menuselection:`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.1 Create Custom Apps directory and a Symbolic Link
----------------------------------------------------

Create a directory for the custom apps in a location of your choosing. Then create A
symbolic link in the main nuttx/apps directory.

This example assumes this has been placed below the top Nuttx folder, alongside the
default ``apps`` directory, i.e. ``nuttx/CustomApps``

  .. code-block:: console

    $ pwd
    /home/nuttx
    $ ls -1
    apps
    CustomBoards
    nuttx
    $ mkdir CustomApps
    $ ls -1
    apps
    CustomApps
    CustomBoards
    nuttx
    $ cd apps
    $ ln -s ../CustomApps CustomApps

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.