mirror of
https://github.com/apache/nuttx-apps.git
synced 2026-08-01 20:29:00 +00:00
Rename README and README.txt to README.md
This commit is contained in:
Maciej Wójcik
Brennan Ashton
parent
a01be75a44
commit
51e6645f71
53 changed files with 0 additions and 0 deletions
223
README.md
Normal file
223
README.md
Normal file
|
|
@ -0,0 +1,223 @@
|
|||
Application Folder
|
||||
==================
|
||||
|
||||
Contents
|
||||
--------
|
||||
|
||||
General
|
||||
Directory Location
|
||||
Built-In Applications
|
||||
NuttShell (NSH) Built-In Commands
|
||||
Synchronous Built-In Commands
|
||||
Application Configuration File
|
||||
Example Built-In Application
|
||||
Building NuttX with Board-Specific Pieces Outside the Source Tree
|
||||
|
||||
General
|
||||
-------
|
||||
This folder provides various applications found in sub-directories. These
|
||||
applications are not inherently a part of NuttX but are provided to help
|
||||
you develop your own applications. The apps/ directory is a "break away"
|
||||
part of the configuration that you may choose to use or not.
|
||||
|
||||
Directory Location
|
||||
------------------
|
||||
The default application directory used by the NuttX build should be named
|
||||
apps/ (or apps-x.y.z/ where x.y.z is the NuttX version number). This apps/
|
||||
directory 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>
|
||||
|
||||
Built-In Applications
|
||||
---------------------
|
||||
NuttX also supports applications that can be started using a name string.
|
||||
In this case, application entry points with their requirements are gathered
|
||||
together in two files:
|
||||
|
||||
- builtin/builtin_proto.h Entry points, prototype function
|
||||
- builtin/builtin_list.h Application specific information and requirements
|
||||
|
||||
The build occurs in several phases as different build targets are executed:
|
||||
(1) context, (2) depend, and (3) default (all). Application information is
|
||||
collected during the make context build phase.
|
||||
|
||||
To execute an application function:
|
||||
|
||||
exec_builtin() is defined in the nuttx/include/apps/builtin/builtin.h
|
||||
|
||||
NuttShell (NSH) Built-In Commands
|
||||
---------------------------------
|
||||
One use of builtin 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:
|
||||
|
||||
CONFIG_NSH_BUILTIN_APPS=y
|
||||
|
||||
Applications registered in the apps/builtin/builtin_list.h file will then
|
||||
be accessible from the NSH command line. If you type 'help' at the NSH
|
||||
prompt, you will see a list of the registered commands.
|
||||
|
||||
Synchronous Built-In Commands
|
||||
-----------------------------
|
||||
By default, built-in commands started from the NSH command line will run
|
||||
asynchronously with NSH. If you want to force NSH to execute commands
|
||||
then wait for the command to execute, you can enable that feature by
|
||||
adding the following to the NuttX configuration file:
|
||||
|
||||
CONFIG_SCHED_WAITPID=y
|
||||
|
||||
The configuration option enables support for the waitpid() RTOS interface.
|
||||
When that interface is enabled, NSH will use it to wait, sleeping until
|
||||
the built-in command executes to completion.
|
||||
|
||||
Of course, even with CONFIG_SCHED_WAITPID=y defined, specific commands
|
||||
can still be forced to run asynchronously by adding the ampersand (&)
|
||||
after the NSH command.
|
||||
|
||||
Application Configuration File
|
||||
------------------------------
|
||||
The NuttX configuration uses kconfig-frontends tools and the NuttX
|
||||
configuration file (.config) file. For example, the NuttX .config
|
||||
may have:
|
||||
|
||||
CONFIG_EXAMPLES_HELLO=y
|
||||
|
||||
This will select the apps/examples/hello in the following way:
|
||||
|
||||
- The top-level make will include examples/Make.defs
|
||||
- examples/Make.defs will set CONFIGURED_APPS += $(APPDIR)/examples/hello
|
||||
like this:
|
||||
|
||||
ifneq ($(CONFIG_EXAMPLES_HELLO),)
|
||||
CONFIGURED_APPS += $(APPDIR)/examples/hello
|
||||
endif
|
||||
|
||||
Example Built-In Application
|
||||
----------------------------
|
||||
An example application skeleton can be found under the examples/hello
|
||||
sub-directory. This example shows how a builtin application can be added
|
||||
to the project. One must:
|
||||
|
||||
1. Create sub-directory as: progname
|
||||
|
||||
2. In this directory there should be:
|
||||
|
||||
- A Make.defs file that would be included by the apps/Makefile
|
||||
- A Kconfig file that would be used by the configuration tool (see the
|
||||
file kconfig-language.txt in the NuttX tools repository). This
|
||||
Kconfig file should be included by the apps/Kconfig file
|
||||
- A Makefile, and
|
||||
- The application source code.
|
||||
|
||||
3. The application source code should provide the entry point:
|
||||
main()
|
||||
|
||||
4. Set the requirements in the file: Makefile, specially the lines:
|
||||
|
||||
PROGNAME = progname
|
||||
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 ..
|
||||
|
||||
4b. The Make.defs file should include a line like:
|
||||
|
||||
ifneq ($(CONFIG_PROGNAME),)
|
||||
CONFIGURED_APPS += progname
|
||||
endif
|
||||
|
||||
Building NuttX with Board-Specific Pieces Outside the Source Tree
|
||||
-----------------------------------------------------------------
|
||||
|
||||
Q: Has anyone come up with a tidy way to build NuttX with board-
|
||||
specific pieces outside the source tree?
|
||||
A: Here are three:
|
||||
|
||||
1) There is a make target called 'make export'. It will build
|
||||
NuttX, then bundle all of the header files, libraries, startup
|
||||
objects, and other build components into a .zip file. You
|
||||
can move that .zip file into any build environment you
|
||||
want. You can even build NuttX under a DOS CMD window.
|
||||
|
||||
This make target is documented in the top level nuttx/README.txt.
|
||||
|
||||
2) You can replace the entire apps/ directory. If there is
|
||||
nothing in the apps/ directory that you need, you can define
|
||||
CONFIG_APPS_DIR in your .config file so that it points to a
|
||||
different, custom application directory.
|
||||
|
||||
You can copy any pieces that you like from the old apps/directory
|
||||
to your custom apps directory as necessary.
|
||||
|
||||
This is documented in NuttX/boards/README.txt and
|
||||
nuttx/Documentation/NuttxPortingGuide.html (Online at
|
||||
https://bitbucket.org/nuttx/nuttx/src/master/Documentation/NuttxPortingGuide.html#apndxconfigs
|
||||
under Build options). And in the apps/README.txt file.
|
||||
|
||||
3) If you like the random collection of stuff in the apps/ directory
|
||||
but just want to expand the existing components with your own,
|
||||
external sub-directory then there is an easy way to that too:
|
||||
You just create a symbolic link in the apps/ directory that
|
||||
redirects to your application sub-directory.
|
||||
|
||||
In order to be incorporated into the build, the directory that
|
||||
you link under the apps/ directory should contain (1) a Makefile
|
||||
that supports the clean and distclean targets (see other Makefiles
|
||||
for examples), and (2) a tiny Make.defs file that simply adds the
|
||||
custom build directories to the variable CONFIGURED_APPS like:
|
||||
|
||||
CONFIGURED_APPS += my_directory1 my_directory2
|
||||
|
||||
The apps/Makefile will always automatically check for the
|
||||
existence of subdirectories containing a Makefile and a Make.defs
|
||||
file. The Makefile will be used only to support cleaning operations.
|
||||
The Make.defs file provides the set of directories to be built; these
|
||||
directories must also contain a Makefile. That Makefile must be able
|
||||
to build the sources and add the objects to the apps/libapps.a archive.
|
||||
(see other Makefiles for examples). It should support the all,
|
||||
install, context, and depend targets.
|
||||
|
||||
apps/Makefile does not depend on any hardcoded lists of directories.
|
||||
Instead, it does a wildcard search to find all appropriate
|
||||
directories. This means that to install a new application, you
|
||||
simply have to copy the directory (or link it) into the apps/
|
||||
directory. If the new directory includes a Makefile and Make.defs
|
||||
file, then it will automatically be included in the build.
|
||||
|
||||
If the directory that you add also includes a Kconfig file, then it
|
||||
will automatically be included in the NuttX configuration system as
|
||||
well. apps/Makefile uses a tool at apps/tools/mkkconfig.sh that
|
||||
dynamically builds the apps/Kconfig file at pre-configuration time.
|
||||
|
||||
You could, for example, create a script called install.sh that
|
||||
installs a custom application, configuration, and board specific
|
||||
directory:
|
||||
|
||||
a) Copy 'MyBoard' directory to boards/MyBoard.
|
||||
b) Add a symbolic link to MyApplication at apps/external
|
||||
c) Configure NuttX (usually by:
|
||||
|
||||
tools/configure.sh MyBoard:MyConfiguration
|
||||
|
||||
Use of the name ''apps/external'' is suggested because that name
|
||||
is included in the .gitignore file and will save you some nuisance
|
||||
when working with GIT.
|
||||
Loading…
Add table
Add a link
Reference in a new issue