WIP

Author: lvanasse

Documentation/guides/building_nuttx_with_app_out_of_src_tree.rst

@@ -0,0 +1,53 @@
+========================================================
+Building NuttX with Applications 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 four approaches:
+
+1. Make export
+--------------
+
+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. Replace the apps/ Directory
+------------------------------
+
+You can replace the entire ``apps/`` directory. It is not a critical part of the
+OS. The ``apps/`` is simply provided for you to help with your application
+development. It should not dictate anything that you do.
+
+To use a different ``apps`` directory, simply execute ``make menuconfig`` in the
+top-level ``nuttx/`` directory and redefine ``CONFIG_APPS_DIR`` in your
+``.config`` file so that it points to a different, custom application directory.
+Note that ``CONFIG_APPS_DIR`` is a relative path from the top-level
+``nuttx/`` 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``, in the "NuttX Porting Guide" and "Build options,"
+and in the ``apps/README.txt`` file.
+
+3. Extend the apps/ Directory
+-----------------------------
+
+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 do that too: Create a symbolic link in the
+``apps/`` directory that redirects to your application sub-directory (or copy
+your code into a sub-directory of ``apps/``).
+
+Makefile and Make.defs
+^^^^^^^^^^^^^^^^^^^^^^
+
+In order to be incorporated into the build, the directory that you link under
+the ``apps

Documentation/guides/index.rst

@@ -59,4 +59,5 @@ Guides
   port.rst
   updating_release_system_elf.rst
   partially_linked_elf.rst
-  fully_linked_elf.rst
+  fully_linked_elf.rst
+  building_nuttx_with_app_out_of_src_tree.rst