diff --git a/Documentation/guides/customapps.rst b/Documentation/guides/customapps.rst new file mode 100644 index 0000000000..5ae2ca6d46 --- /dev/null +++ b/Documentation/guides/customapps.rst @@ -0,0 +1,346 @@ +================== +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 + + 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 : + + 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. diff --git a/Documentation/guides/customboards.rst b/Documentation/guides/customboards.rst new file mode 100644 index 0000000000..fcd4301f32 --- /dev/null +++ b/Documentation/guides/customboards.rst @@ -0,0 +1,71 @@ +==================== +Custom Boards How-To +==================== + +As explained in :doc:`../quickstart/configuring`, supported boards (also known +as "in-tree" boards) are configured using a standard syntax: + + .. code-block:: console + + $ cd nuttx + $ ./tools/configure.sh -l board-name:config-name + Copy files + Select CONFIG_HOST_LINUX=y + Refreshing... + +Sometimes it is not appropriate, or not wanted, to add a new or custom board to +the Nuttx boards tree itself. If so, the board can be defined out-of-tree in a +custom directory and still be built easily. + +------------------ +Add a Custom Board +------------------ + +The same set of files as provided for in-tree boards is required (i.e. configs, +Kconfig, scripts, etc.) but these can be placed in a directory of your choice. + +In this example, the files are assumed to exist in: + ``../nuttx/CustomBoards/MyCustomBoardName`` + + .. code-block:: console + + $pwd + /home/nuttx/nuttx + $ ls -1 ../CustomBoards/MyCustomBoardName + configs + helpers + include + Kconfig + scripts + $ ls ../CustomBoards/MyCustomBoardName/configs + nsh + MyCustomConfig + $ + + +To build the custom board, the syntax is slightly different to in-tree boards and configs: + + .. code-block:: console + + $ .tools/configure -l ../CustomBoards/MyCustomBoardName/MyCustomConfig + Copy files + Select CONFIG_HOST_LINUX=y + Refreshing... + +Kconfig Settings +---------------- + +Once the board is configured, to ensure subsequent builds run correctly, there +are two Kconfig settings that need to be set. These are: + +:menuselection:`Board Selection --> Custom Board Configuration --> Custom Board Name` + +:menuselection:`Board Selection --> Custom Board Configuration --> Relative custom board directory` + +They should be set to suit your board name and directory location. + +.. Note:: + If you subsequently run a ``make distclean`` operation, then these settings will be lost. + They should be added back before building, and/or before running ``make menuconfig``. + + diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst index 6fff019a87..6b4c332e3c 100644 --- a/Documentation/guides/index.rst +++ b/Documentation/guides/index.rst @@ -12,3 +12,5 @@ Guides tasktrace.rst cpp_cmake.rst pysimcoder.rst + customboards.rst + customapps.rst