Feature/vendorlibraries

build/macros.mk

@@ -32,5 +32,21 @@ assert_filesize = $(call _assert_equal,"file $1",$2,$(shell echo $(call filesize
 
 assert_filebyte = $(call _assert_equal,"file $1 offset $2",$3,$(shell echo $(call filebyte,$1,$2)))
 
+# Recursive wildcard function - finds matching files in a directory tree
+target_files = $(patsubst $(SOURCE_PATH)/%,%,$(call rwildcard,$(SOURCE_PATH)/$1,$2))
+here_files = $(call wildcard,$(SOURCE_PATH)/$1$2)
+
+remove_slash = $(patsubst %/,%,$1)
+add_slash = $(patsubst %, %/,$(call remove_slash,$1))
+
+# enumerates the files across a number of directories
+# $1 the list of directories to search. Each directory is searched recursively
+# $2 the subdirectory relative to each directory to search - must end with a slash
+# $3 the wildcard to search within each directory
+# Each file is returned relative to the directory it was (recursively) searched in, prepended
+# with the name of the search directory.
+# E.g.
+# /files/libs/mylib/abc.cpp ->  libs/mylib/abc.cpp when the search is in directory /files/libs with wildcard *.cpp
+target_files_dirs = $(foreach d,$(call remove_slash,$1),$(patsubst $d/%,$(notdir $d)/%,$(call rwildcard,$d/$2,$3)))
 
 check_modular = $(if $(PLATFORM_DYNALIB_MODULES),,$(error "Platform '$(PLATFORM)' does not support dynamic modules"))

build/module.mk

@@ -5,10 +5,6 @@ include $(COMMON_BUILD)/macros.mk
 
 SOURCE_PATH ?= $(MODULE_PATH)
 
-# Recursive wildcard function - finds matching files in a directory tree
-target_files = $(patsubst $(SOURCE_PATH)/%,%,$(call rwildcard,$(SOURCE_PATH)/$1,$2))
-here_files = $(call wildcard,$(SOURCE_PATH)/$1$2)
-
 # import this module's symbols
 include $(MODULE_PATH)/import.mk
 
@@ -43,11 +39,36 @@ ifneq (,$(LOG_MODULE_CATEGORY))
 CFLAGS += -DLOG_MODULE_CATEGORY="\"$(LOG_MODULE_CATEGORY)\""
 endif
 
+# Adds the sources from the specified library directories
+# v1 libraries include all sources
+LIBCPPSRC += $(call target_files_dirs,$(MODULE_LIBSV1),,*.cpp)
+LIBCSRC += $(call target_files_dirs,$(MODULE_LIBSV1),,*.c)
+
+# v2 libraries only include sources in the "src" dir
+LIBCPPSRC += $(call target_files_dirs,$(MODULE_LIBSV2)/,src/,*.cpp)
+LIBCSRC += $(call target_files_dirs,$(MODULE_LIBSV2)/,src/,*.c)
+
+
+CPPSRC += $(LIBCPPSRC)
+CSRC += $(LIBCSRC)
+
+# add all module libraries as include directories
+INCLUDE_DIRS += $(MODULE_LIBSV1)
+
+# v2 libraries contain their sources under a "src" folder
+INCLUDE_DIRS += $(addsuffix /src,$(MODULE_LIBSV2))
+
+# $(info cppsrc $(CPPSRC))
+# $(info csrc $(CSRC))
+
+
 # Collect all object and dep files
 ALLOBJ += $(addprefix $(BUILD_PATH)/, $(CSRC:.c=.o))
 ALLOBJ += $(addprefix $(BUILD_PATH)/, $(CPPSRC:.cpp=.o))
 ALLOBJ += $(addprefix $(BUILD_PATH)/, $(patsubst $(COMMON_BUILD)/arm/%,%,$(ASRC:.S=.o)))
 
+# $(info allobj $(ALLOBJ))
+
 ALLDEPS += $(addprefix $(BUILD_PATH)/, $(CSRC:.c=.o.d))
 ALLDEPS += $(addprefix $(BUILD_PATH)/, $(CPPSRC:.cpp=.o.d))
 ALLDEPS += $(addprefix $(BUILD_PATH)/, $(patsubst $(COMMON_BUILD)/arm/%,%,$(ASRC:.S=.o.d)))
@@ -206,7 +227,6 @@ $(TARGET_BASE)$(EXECUTABLE_EXTENSION) : build_dependencies $(ALLOBJ) $(LIB_DEPS)
 	$(call echo,)
 
 
-
 # Tool invocations
 $(TARGET_BASE).a : $(ALLOBJ)
 	$(call echo,'Building target: $@')
@@ -215,31 +235,52 @@ $(TARGET_BASE).a : $(ALLOBJ)
 	$(VERBOSE)$(AR) -cr $@ $^
 	$(call echo,)
 
-# C compiler to build .o from .c in $(BUILD_DIR)
-$(BUILD_PATH)/%.o : $(SOURCE_PATH)/%.c
-	$(call echo,'Building file: $<')
+define build_C_file
+	$(call echo,'Building c file: $<')
 	$(call echo,'Invoking: ARM GCC C Compiler')
 	$(VERBOSE)$(MKDIR) $(dir $@)
 	$(VERBOSE)$(CC) $(CFLAGS) $(CONLYFLAGS) -c -o $@ $<
 	$(call echo,)
+endef
 
-# Assember to build .o from .S in $(BUILD_DIR)
-$(BUILD_PATH)/%.o : $(COMMON_BUILD)/arm/%.S
-	$(call echo,'Building file: $<')
-	$(call echo,'Invoking: ARM GCC Assembler')
+define build_CPP_file
+	$(call echo,'Building cpp file: $<')
+	$(call echo,'Invoking: ARM GCC CPP Compiler')
 	$(VERBOSE)$(MKDIR) $(dir $@)
-	$(VERBOSE)$(CC) $(ASFLAGS) -c -o $@ $<
+	$(VERBOSE)$(CC) $(CFLAGS) $(CPPFLAGS) -c -o $@ $<
 	$(call echo,)
+endef
+
+# C compiler to build .o from .c in $(BUILD_DIR)
+$(BUILD_PATH)/%.o : $(SOURCE_PATH)/%.c
+	$(build_C_file)
 
 # CPP compiler to build .o from .cpp in $(BUILD_DIR)
 # Note: Calls standard $(CC) - gcc will invoke g++ as appropriate
 $(BUILD_PATH)/%.o : $(SOURCE_PATH)/%.cpp
+	$(build_CPP_file)
+
+define build_LIB_files
+$(BUILD_PATH)/$(notdir $1)/%.o : $1/%.c
+	$$(build_C_file)
+
+$(BUILD_PATH)/$(notdir $1)/%.o : $1/%.cpp
+	$$(build_CPP_file)
+endef
+
+# define rules for each library
+# only the sources added for each library are built (so for v2 libraries only files under "src" are built.)
+$(foreach lib,$(MODULE_LIBSV1) $(MODULE_LIBSV2),$(eval $(call build_LIB_files,$(lib))))
+
+# Assember to build .o from .S in $(BUILD_DIR)
+$(BUILD_PATH)/%.o : $(COMMON_BUILD)/arm/%.S
 	$(call echo,'Building file: $<')
-	$(call echo,'Invoking: ARM GCC CPP Compiler')
+	$(call echo,'Invoking: ARM GCC Assembler')
 	$(VERBOSE)$(MKDIR) $(dir $@)
-	$(VERBOSE)$(CC) $(CFLAGS) $(CPPFLAGS) -c -o $@ $<
+	$(VERBOSE)$(CC) $(ASFLAGS) -c -o $@ $<
 	$(call echo,)
 
+
 # Other Targets
 clean: clean_deps
 	$(VERBOSE)$(RM) $(ALLOBJ) $(ALLDEPS) $(TARGET)

build/test/core.bats

@@ -26,14 +26,14 @@ load build
     [ -d $outdir ]
     [ -s $outdir/main.bin ]
     [ -s $outdir/main.elf ]
-    file_size_range $outdir/main.bin 70 85 K
+    file_size_range $outdir/main.bin 70 86 K
 }
 
 @test "repeat core main build silent outputs size" {
     cd main
     run make PLATFORM=core -s
     outdir="../build/target/main/platform-0-lto"
-    assert_equal "text data bss dec hex filename" "$(trim ${lines[0]})"
+    assert_equal "text data bss dec hex filename" "$(trim "${lines[0]}")"
     assert_equal "2" "${#lines[@]}"
 }
 

build/test/files/applibs spaces/app1/app.cpp

@@ -0,0 +1,12 @@
+#include "Particle.h"
+
+#include "lib1.h"
+#include "lib2.h"
+
+
+
+void setup()
+{
+   lib1();
+   lib2("hello");
+}

build/test/files/applibs spaces/lib1/lib1.cpp

@@ -0,0 +1,6 @@
+#include "lib1.h"
+#include "Particle.h"
+void lib1()
+{
+   Serial.println("hello from lib1");
+}

build/test/files/applibs spaces/lib1/lib1.h

@@ -0,0 +1,2 @@
+
+void lib1();

build/test/files/applibs spaces/lib2/lib2.cpp

@@ -0,0 +1,6 @@
+#include "lib2.h"
+#include "Particle.h"
+
+void lib2(const char* msg) {
+   Serial.println(msg);
+}

build/test/files/applibs spaces/lib2/lib2.h

@@ -0,0 +1 @@
+void lib2(const char* msg);

build/test/files/applibs/app/app.cpp

@@ -0,0 +1,12 @@
+#include "Particle.h"
+
+#include "lib1.h"
+#include "lib2.h"
+
+
+
+void setup()
+{
+   lib1();
+   lib2("hello");
+}

build/test/files/applibs/lib1/lib.cpp

@@ -0,0 +1,6 @@
+#include "lib1.h"
+#include "Particle.h"
+void lib1()
+{
+   Serial.println("hello from lib1");
+}

build/test/files/applibs/lib1/lib1.h

@@ -0,0 +1 @@
+#include "lib1internal/lib1.h"

build/test/files/applibs/lib1/lib1internal/lib1.h

@@ -0,0 +1,2 @@
+
+void lib1();

build/test/files/applibs/lib2/lib.cpp

@@ -0,0 +1,6 @@
+#include "lib2.h"
+#include "Particle.h"
+
+void lib2(const char* msg) {
+   Serial.println(msg);
+}

build/test/files/applibs/lib2/lib2.h

@@ -0,0 +1 @@
+void lib2(const char* msg);

build/test/files/applibs/readme.txt

@@ -0,0 +1,3 @@
+- each library deliberately includes the same named .cpp file to verify that the build keeps the objects from
+each library separate
+- each library includes private headers that are qualified with the name of the library

build/test/files/applibs_v2/app/app.cpp

@@ -0,0 +1,12 @@
+#include "Particle.h"
+
+#include "lib1.h"
+#include "lib2.h"
+
+
+
+void setup()
+{
+   lib1();
+   lib2("hello");
+}

build/test/files/applibs_v2/lib1/src/lib.cpp

@@ -0,0 +1,6 @@
+#include "lib1.h"
+#include "Particle.h"
+void lib1()
+{
+   Serial.println("hello from lib1");
+}

build/test/files/applibs_v2/lib1/src/lib1.h

@@ -0,0 +1,2 @@
+
+void lib1();

build/test/files/applibs_v2/lib2/examples/example1.cpp

@@ -0,0 +1 @@
+#error do not compile me I'm just an example. 

build/test/files/applibs_v2/lib2/src/lib.cpp

@@ -0,0 +1,6 @@
+#include "lib2.h"
+#include "Particle.h"
+
+void lib2(const char* msg) {
+   Serial.println(msg);
+}

build/test/files/applibs_v2/lib2/src/lib2.h

@@ -0,0 +1 @@
+void lib2(const char* msg);

build/test/files/applibs_v2_vendored/app/lib/lib1/src/lib.cpp

@@ -0,0 +1,6 @@
+#include "lib1.h"
+#include "Particle.h"
+void lib1()
+{
+   Serial.println("hello from lib1");
+}

build/test/files/applibs_v2_vendored/app/lib/lib1/src/lib1.h

@@ -0,0 +1,2 @@
+
+void lib1();

build/test/files/applibs_v2_vendored/app/lib/lib2/examples/example1.cpp

@@ -0,0 +1 @@
+#error do not compile me I'm just an example. 

build/test/files/applibs_v2_vendored/app/lib/lib2/src/lib.cpp

@@ -0,0 +1,6 @@
+#include "lib2.h"
+#include "Particle.h"
+
+void lib2(const char* msg) {
+   Serial.println(msg);
+}

build/test/files/applibs_v2_vendored/app/lib/lib2/src/lib2.h

@@ -0,0 +1 @@
+void lib2(const char* msg);

build/test/files/applibs_v2_vendored/app/src/app.cpp

@@ -0,0 +1,12 @@
+#include "Particle.h"
+
+#include "lib1.h"
+#include "lib2.h"
+
+
+
+void setup()
+{
+   lib1();
+   lib2("hello");
+}

build/test/libs.bats

@@ -0,0 +1,38 @@
+load build
+
+
+@test "can build a project with external libraries" {
+   cd modules/photon/user-part
+   run make $make_args PLATFORM=photon APPDIR=../build/test/files/applibs/app "APPLIBSV1=../build/test/files/applibs/lib1/ ../build/test/files/applibs/lib2/"
+    outdir=../build/test/files/applibs/app/target
+    [ -s $outdir/app.bin ]
+    file_size_range $outdir/app.bin 2 4 K 
+}
+
+
+@test "can build a project with external libraries in a directory containing spaces" {
+   skip # the make system does not support directories with spaces
+   cd modules/photon/user-part
+   run make $make_args PLATFORM=photon "APPDIR=../build/test/files/applibs spaces/app1" "\"APPLIBSV1=../build/test/files/applibs spaces/lib1/\" \"../build/test/files/applibs spaces/lib2/\""
+    outdir=../build/test/files/applibs\ spaces/app1/target
+    [ -s $outdir/app1.bin ]
+    file_size_range $outdir/app1.bin 2 4 K 
+}
+
+
+@test "can build a v1 project with external v2 libraries" {
+   cd modules/photon/user-part
+   run make $make_args PLATFORM=photon APPDIR=../build/test/files/applibs_v2/app "APPLIBSV2=../build/test/files/applibs_v2/lib1/ ../build/test/files/applibs_v2/lib2"
+    outdir=../build/test/files/applibs_v2/app/target
+    [ -s $outdir/app.bin ]
+    file_size_range $outdir/app.bin 2 4 K 
+}
+
+
+@test "can build a v2 project with vendored v2 libraries" {
+   cd modules/photon/user-part
+   run make $make_args PLATFORM=photon APPDIR=../build/test/files/applibs_v2_vendored/app/src "APPLIBSV2=../build/test/files/applibs_v2_vendored/app/lib/lib1/ ../build/test/files/applibs_v2_vendored/app/lib/lib2"
+    outdir=../build/test/files/applibs_v2_vendored/app/src/target
+    [ -s $outdir/src.bin ]
+    file_size_range $outdir/src.bin 2 4 K 
+}

build/test/runall.bash

@@ -0,0 +1,10 @@
+
+function die
+{
+   exit 1
+}
+
+bats build.bats || die
+bats core.bats || die
+bats photon.bats || die
+bats libs.bats || die

docs/build.md

@@ -85,6 +85,7 @@ When building `main` or `modules`:
 - `APPDIR`: builds the application located in $(APPDIR). The directory specified
     should be outside of the firmware repo working directory, allowing 3rd party applications to be built.
     See `USER_MAKEFILE`.
+- `APPLIBS`: directories containing external firmware libraries. See [External Libraries](#external_libs)
 - `TEST` builds the test application stored in `user/tests/$(TEST)`.
 - `USER_MAKEFILE`: when `APPDIR` is used this specifies the location of the makefile
     to include, relative to `APPDIR`. The default is `build.mk`.
@@ -356,13 +357,40 @@ To add all files in the application directory and subdirectories.
 To use a different name/location for customization makefile file other than `build.mk`, define `USER_MAKEFILE` to point to
 your custom build file. The value of `USER_MAKEFILE` is the location of your custom makefile relative to the application sources.
 
+<a name='external_libs'>
+## External Libraries
+</a>
 
-## Integrated application.cpp with firmware
+_Note that this is preliminary support for external libraries to bring some feature parity with Build. Over the coming weeks, full support for libraries will be added._
+
+External Particle libraries can be compiled and linked with firmware. To add one or more external libraries:
+
+1. download the library sources store it in a directory outside the firmware, e.g.`/particle/libs/neopixel` for the neopixel library. 
+
+2. remove the `examples` directory if it exists
+```
+cd /particle/libs/neopixel
+rm -rf firmware/examples
+``
+
+3. Rename `firmware` to be the same as the library name. 
+```
+mv firmware neopixel
+```
+This is so that includes like `#include "neopixel/neopixel.h"` will function correctly. 
+
+4. Add the APPLIBS variable to the make command which lists the directories contianing libraries to use. 
+```
+make APPDIR=/particle/apps/myapp APPLIBS=/particle/libs/neopixel
+```
+
+
+## Default application.cpp integrated with firmware
 
 In previous versions of the make system, the application code was integrated with the firmware code at `src/application.cpp`.
 This mode of building is still supported, however the location has changed to: `user/src/application.cpp`.
 
-To build the default application sources, simply run `make`
+To build the default application sources, just run `make`
 
 ```
 make