Change the way modules are built so that object paths are relative and use vpath for locating sources (so source paths are also shorter).

Add some basic documentation for the build system files while we're at it.

3 files changed, 107 insertions, 22 deletions

diff --git a/makefiles/README.txt b/makefiles/README.txt
new file mode 100644
index 000000000..8b84e4c40
--- /dev/null
+++ b/makefiles/README.txt
@@ -0,0 +1,71 @@
+PX4 Build System
+================
+
+The files in this directory implement the PX4 runtime firmware build system
+and configuration for the standard PX4 boards and software, in conjunction
+with Makefile in the parent directory.
+
+../Makefile
+
+	Top-level makefile for the PX4 build system. This makefile supports
+	building NuttX archives, as well as supervising the building of all
+	of the defined PX4 firmware configurations.
+
+	Try 'make help' in the parent directory for documentation.
+
+firmware.mk
+
+	Manages the build for one specific firmware configuration. 
+	See the comments at the top of this file for detailed documentation.
+
+	Builds modules, builtin command lists and the ROMFS (if configured).
+
+	This is the makefile directly used by external build systems; it can
+	be configured to compile modules both inside and outside the PX4
+	source tree. When used in this mode, at least BOARD, MODULES and 
+	CONFIG_FILE must be set.
+
+module.mk
+
+	Called by firmware.mk to build individual modules.
+	See the comments at the top of this file for detailed documentation.
+
+	Not normally used other than by firmware.mk.
+
+nuttx.mk
+
+	Called by ../Makefile to build or download the NuttX archives.
+
+upload.mk
+
+	Called by ../Makefile to upload files to a target board. Can be used
+	by external build systems as well.
+
+setup.mk
+
+	Provides common path and tool definitions. Implements host system-specific
+	compatibility hacks.
+
+board_<boardname>.mk
+
+	Board-specific configuration for <boardname>. Typically sets CONFIG_ARCH
+	and then includes the toolchain definition for the board.
+
+config_<boardname>_<configname>.mk
+
+	Parameters for a specific configuration on a specific board.
+	The board name is derived from the filename.  Sets MODULES to select
+	source modules to be included in the configuration, may also set
+	ROMFS_ROOT to build a ROMFS and BUILTIN_COMMANDS to include non-module
+	commands (e.g. from NuttX)
+
+toolchain_<toolchainname>.mk
+
+	Provides macros used to compile and link source files.
+	Accepts EXTRADEFINES to add additional pre-processor symbol definitions,
+	EXTRACFLAGS, EXTRACXXFLAGS, EXTRAAFLAGS and EXTRALDFLAGS to pass
+	additional flags to the C compiler, C++ compiler, assembler and linker
+	respectively.
+
+	Defines the COMPILE, COMPILEXX, ASSEMBLE, PRELINK, ARCHIVE and LINK
+	macros that are used elsewhere in the build system.
diff --git a/makefiles/firmware.mk b/makefiles/firmware.mk
index b63aa28d7..e6a45a4e8 100644
--- a/makefiles/firmware.mk
+++ b/makefiles/firmware.mk
@@ -223,12 +223,15 @@ MODULE_OBJS		:= $(foreach path,$(dir $(MODULE_MKFILES)),$(WORK_DIR)$(path)module
 .PHONY: $(MODULE_OBJS)
 $(MODULE_OBJS):		relpath = $(patsubst $(WORK_DIR)%,%,$@)
 $(MODULE_OBJS):		mkfile = $(patsubst %module.pre.o,%module.mk,$(relpath))
+$(MODULE_OBJS):		workdir = $(@D)
 $(MODULE_OBJS):		$(GLOBAL_DEPS) $(NUTTX_CONFIG_HEADER)
+	$(Q) $(MKDIR) -p $(workdir)
 	$(Q) $(MAKE) -r -f $(PX4_MK_DIR)module.mk \
-		MODULE_WORK_DIR=$(dir $@) \
+		-C $(workdir) \
+		MODULE_WORK_DIR=$(workdir) \
 		MODULE_OBJ=$@ \
 		MODULE_MK=$(mkfile) \
-		MODULE_NAME=$(lastword $(subst /, ,$(@D))) \
+		MODULE_NAME=$(lastword $(subst /, ,$(workdir))) \
 		module
 
 # make a list of phony clean targets for modules
diff --git a/makefiles/module.mk b/makefiles/module.mk
index 0fe6f0ffe..db6f4e15e 100644
--- a/makefiles/module.mk
+++ b/makefiles/module.mk
@@ -39,6 +39,10 @@
 # symbols, as the global namespace is shared between all modules. Normally an 
 # module will just export one or more <command>_main functions.
 #
+# IMPORTANT NOTE:
+#
+# This makefile assumes it is being invoked in the module's output directory.
+#
 
 #
 # Variables that can be set by the module's module.mk:
@@ -179,26 +183,30 @@ CXXFLAGS	+= -fvisibility=$(DEFAULT_VISIBILITY) -include $(PX4_INCLUDE_DIR)visibi
 #
 module:			$(MODULE_OBJ) $(MODULE_COMMAND_FILES)
 
+##
+## Locate sources (allows relative source paths in module.mk)
+##
+#define SRC_SEARCH
+#	$(abspath $(firstword $(wildcard $1) $(wildcard $(MODULE_SRC)/$1) MISSING_$1))
+#endef
 #
-# Locate sources (allows relative source paths in module.mk)
+#ABS_SRCS		?= $(foreach src,$(SRCS),$(call SRC_SEARCH,$(src)))
+#MISSING_SRCS		:= $(subst MISSING_,,$(filter MISSING_%,$(ABS_SRCS)))
+#ifneq ($(MISSING_SRCS),)
+#$(error $(MODULE_MK): missing in SRCS: $(MISSING_SRCS))
+#endif
+#ifeq ($(ABS_SRCS),)
+#$(error $(MODULE_MK): nothing to compile in SRCS)
+#endif
 #
-define SRC_SEARCH
-	$(abspath $(firstword $(wildcard $1) $(wildcard $(MODULE_SRC)/$1) MISSING_$1))
-endef
+##
+## Object files we will generate from sources
+##
+#OBJS			:= $(foreach src,$(ABS_SRCS),$(MODULE_WORK_DIR)$(src).o)
 
-ABS_SRCS		?= $(foreach src,$(SRCS),$(call SRC_SEARCH,$(src)))
-MISSING_SRCS		:= $(subst MISSING_,,$(filter MISSING_%,$(ABS_SRCS)))
-ifneq ($(MISSING_SRCS),)
-$(error $(MODULE_MK): missing in SRCS: $(MISSING_SRCS))
-endif
-ifeq ($(ABS_SRCS),)
-$(error $(MODULE_MK): nothing to compile in SRCS)
-endif
-
-#
-# Object files we will generate from sources
-#
-OBJS			:= $(foreach src,$(ABS_SRCS),$(MODULE_WORK_DIR)$(src).o)
+OBJS		 = $(addsuffix .o,$(SRCS))
+$(info SRCS $(SRCS))
+$(info OBJS $(OBJS))
 
 #
 # SRCS -> OBJS rules
@@ -206,13 +214,16 @@ OBJS			:= $(foreach src,$(ABS_SRCS),$(MODULE_WORK_DIR)$(src).o)
 
 $(OBJS):		$(GLOBAL_DEPS)
 
-$(filter %.c.o,$(OBJS)): $(MODULE_WORK_DIR)%.c.o: %.c $(GLOBAL_DEPS)
+vpath %.c $(MODULE_SRC)
+$(filter %.c.o,$(OBJS)): %.c.o: %.c $(GLOBAL_DEPS)
 	$(call COMPILE,$<,$@)
 
-$(filter %.cpp.o,$(OBJS)): $(MODULE_WORK_DIR)%.cpp.o: %.cpp $(GLOBAL_DEPS)
+vpath %.cpp $(MODULE_SRC)
+$(filter %.cpp.o,$(OBJS)): %.cpp.o: %.cpp $(GLOBAL_DEPS)
 	$(call COMPILEXX,$<,$@)
 
-$(filter %.S.o,$(OBJS)): $(MODULE_WORK_DIR)%.S.o: %.S $(GLOBAL_DEPS)
+vpath %.S $(MODULE_SRC)
+$(filter %.S.o,$(OBJS)): %.S.o: %.S $(GLOBAL_DEPS)
 	$(call ASSEMBLE,$<,$@)
 
 #