Document OSGi Makefile and improve Javadoc generation

diff --git a/osgi.mk b/osgi.mk
index cef7609717a916f901155a7cd181ed476770c908..733f20e3e9a0743c0d75f74da931806c5fdd9813 100644 (file)
--- a/osgi.mk
+++ b/osgi.mk
@@ -1,45 +1,49 @@
-
-
 #
-# GENERIC
+# Common build routines to be included in Makefiles
 #
-JVM := $(JAVA_HOME)/bin/java
-JAVADOC := $(JAVA_HOME)/bin/javadoc
-ECJ_JAR := $(A2_BASE)/org.argeo.tp.sdk/org.eclipse.jdt.core.compiler.batch.3.29.jar
-BNDLIB_JAR := $(A2_BASE)/org.argeo.tp.sdk/biz.aQute.bndlib.5.3.jar
-SLF4J_API_JAR := $(A2_BASE)/org.argeo.tp/org.slf4j.api.1.7.jar
-
-#ARGEO_MAKE = $(JVM) -cp $(ECJ_JAR):$(BNDLIB_JAR):$(SLF4J_API_JAR):$(BUILD_BASE)/bin org/argeo/build/Make
+# The following variables are found in the sdk.mk file which is generated by the configure script:
+# SDK_SRC_BASE         the base of the source code, typically the root of the cloned git repository
+# SDK_BUILD_BASE       the base of the output
+# JAVA_HOME                    the base of the JDK used to build
+A2_OUTPUT := $(SDK_BUILD_BASE)/a2
+JVM ?= $(JAVA_HOME)/bin/java
+JAVADOC ?= $(JAVA_HOME)/bin/javadoc
+
+# The following variables should be declared in the Makefile:
+# BUNDLES                      the space-separated list of bundles to be built
+# A2_CATEGORY          the a2 category the bundles will belong to
+#
+# The following variables have default values which can be overriden in the Makefile
+# DEP_CATEGORIES       the a2 categories the compilation depends on
+# JAVADOC_PACKAGES     the space-separated list of packages for which javadoc will be generated
+# A2_BASE                      the space-separated directories where already built a2 categories can be found
+DEP_CATEGORIES ?=
+JAVADOC_PACKAGES ?=
+A2_BASE ?= $(A2_OUTPUT)
+
+ECJ_JAR ?= $(A2_BASE)/org.argeo.tp.sdk/org.eclipse.jdt.core.compiler.batch.3.29.jar
+BNDLIB_JAR ?= $(A2_BASE)/org.argeo.tp.sdk/biz.aQute.bndlib.5.3.jar
+SLF4J_API_JAR ?= $(A2_BASE)/org.argeo.tp/org.slf4j.api.1.7.jar
 ARGEO_MAKE := $(JVM) -cp $(ECJ_JAR):$(BNDLIB_JAR):$(SLF4J_API_JAR) $(SDK_SRC_BASE)/sdk/argeo-build/src/org/argeo/build/Make.java
-#BND_TOOL := /usr/bin/bnd
-
-BUILD_BASE = $(SDK_BUILD_BASE)/$(shell basename $(SDK_SRC_BASE))
-
-#WORKSPACE_BNDS := $(shell cd $(SDK_SRC_BASE) && find cnf -name '*.bnd') sdk/argeo-build/argeo.bnd
-#BUILD_WORKSPACE_BNDS := $(WORKSPACE_BNDS:%=$(BUILD_BASE)/%)
+#ARGEO_MAKE = $(JVM) -cp $(ECJ_JAR):$(BNDLIB_JAR):$(SLF4J_API_JAR):$(BUILD_BASE)/bin org/argeo/build/Make
 
-#A2_JARS = $(foreach category, $(DEP_CATEGORIES), $(shell find $(A2_BASE)/$(category) -name '*.jar'))
-#A2_CLASSPATH = $(subst $(space),$(pathsep),$(strip $(A2_JARS)))
+JAVADOC_SRCS = $(foreach bundle, $(BUNDLES), $(bundle)/src)
 
-#A2_BUNDLES = $(foreach bundle, $(BUNDLES),$(A2_OUTPUT)/$(A2_CATEGORY)/$(shell basename $(bundle)).$(MAJOR).$(MINOR).jar)
+BUILD_BASE = $(SDK_BUILD_BASE)/$(shell basename $(SDK_SRC_BASE))
 
-#JAVA_SRCS = $(foreach bundle, $(BUNDLES), $(shell find $(bundle) -name '*.java'))
-#BNDS = $(foreach bundle, $(BUNDLES), $(BUILD_BASE)/$(shell basename $(bundle))/bnd.bnd)
-#ECJ_SRCS = $(foreach bundle, $(BUNDLES), $(bundle)/src[-d $(BUILD_BASE)/$(bundle)/bin])
+TARGET_BUNDLES =  $(abspath $(foreach bundle, $(BUNDLES),$(A2_OUTPUT)/$(shell dirname $(bundle))/$(A2_CATEGORY)/$(shell basename $(bundle)).$(MAJOR).$(MINOR).jar))
+TODOS = $(foreach bundle, $(BUNDLES),$(BUILD_BASE)/$(bundle)/to-build) 
 
-JAVADOC_SRCS = $(foreach bundle, $(JAVADOC_BUNDLES),$(bundle)/src)
+## Needed in order to be able to expand $$ variables
+.SECONDEXPANSION:
+.PHONY: clean-a2 osgi manifests javadoc
 
 osgi: $(BUILD_BASE)/built
 
-javadoc: $(BUILD_BASE)/java-compiled
-       $(JAVADOC) -d $(BUILD_BASE)/api --source-path $(subst $(space),$(pathsep),$(strip $(JAVADOC_SRCS))) -subpackages $(JAVADOC_PACKAGES)
-
-
-TARGET_BUNDLES :=  $(abspath $(foreach bundle, $(BUNDLES),$(A2_OUTPUT)/$(shell dirname $(bundle))/$(A2_CATEGORY)/$(shell basename $(bundle)).$(MAJOR).$(MINOR).jar))
-TODOS := $(foreach bundle, $(BUNDLES),$(BUILD_BASE)/$(bundle)/to-build) 
-
-.SECONDEXPANSION:
+javadoc: $(BUILD_BASE)/built
+       $(JAVADOC) -quiet -Xmaxwarns 1 -d $(BUILD_BASE)/api --source-path $(subst $(space),$(pathsep),$(strip $(JAVADOC_SRCS))) -subpackages $(JAVADOC_PACKAGES)
 
+# Actual build (compilation + bundle packaging)
 $(BUILD_BASE)/built : BUNDLES_TO_BUILD = $(subst $(abspath $(BUILD_BASE))/,, $(subst to-build,, $?))
 $(BUILD_BASE)/built : $(TODOS)
        $(ARGEO_MAKE) all --a2-bases $(A2_BASE) --dep-categories $(DEP_CATEGORIES) --category $(A2_CATEGORY) --bundles $(BUNDLES_TO_BUILD)
@@ -53,22 +57,6 @@ $(BUILD_BASE)/%/to-build : $$(shell find $(SDK_SRC_BASE)/% -type f -not -path 'b
        @mkdir -p $(dir $@) 
        @touch $@
 
-$(BUILD_BASE)/%/sources-modified : $$(shell find $(SDK_SRC_BASE)/$$* -name '*.java')
-       touch $@        
-
-$(BUILD_BASE)/%/java-compiled: $(BUILD_BASE)/%/sources-modified
-       $(ARGEO_MAKE) compile --a2-bases $(A2_BASE) --dep-categories $(DEP_CATEGORIES) --bundles $(BUNDLES)
-       touch $@        
-
-# Build level
-$(BUILD_BASE)/jars-built: $(BUILD_BASE)/java-compiled 
-       $(ARGEO_MAKE) bundle --category $(A2_CATEGORY) --bundles $(BUNDLES)
-       touch $@
-
-$(BUILD_BASE)/java-compiled : $(JAVA_SRCS)
-       $(ARGEO_MAKE) compile --a2-bases $(A2_BASE) --dep-categories $(DEP_CATEGORIES) --bundles $(BUNDLES)
-       touch $@
-
 clean-a2 :
        rm -rf $(TARGET_BUNDLES)
        rm -rf $(BUILD_BASE)/built
@@ -77,12 +65,15 @@ clean-a2 :
 manifests : osgi
        @mkdir -p $(foreach bundle, $(BUNDLES), $(bundle)/META-INF/);
        @$(foreach bundle, $(BUNDLES), cp -v $(BUILD_BASE)/$(bundle)/META-INF/MANIFEST.MF  $(bundle)/META-INF/MANIFEST.MF;)
-       
+
+# Local build of the builder, not used as the performance gain is negligible   
 builder: $(BUILD_BASE)/bin/org/argeo/build/Make.class
 
 $(BUILD_BASE)/bin/org/argeo/build/Make.class : $(SDK_SRC_BASE)/sdk/argeo-build/java/org/argeo/build/Make.java
        $(JVM) -jar $(ECJ_JAR) -cp $(ECJ_JAR):$(BNDLIB_JAR):$(SLF4J_API_JAR) @$(SDK_SRC_BASE)/sdk/argeo-build/ecj.args $(SDK_SRC_BASE)/sdk/argeo-build/src[-d $(BUILD_BASE)/bin]
 
+# Make variables used to replace spaces by a separator, typically in order to generate classpaths
+# for example: CLASSPATH = $(subst $(space),$(pathsep),$(strip $(JARS)))
 null  :=
 space := $(null) #
-pathsep := :
+pathsep := :
\ No newline at end of file