[NaCl SDK] Simplify the auto-generated Makefiles for examples.

This change removed a lot of the boiler-plate from the
example Makefiles.  In my view we could go step further
and have common.mk do all the work for us, but this is
a step in the right direction for having short, easy
to read/modify/clone Makefiles.

This change removed whitespace and comments from the
generated files, and also tried to avoid project specific
names where possible (just SOURCES not hello_world_SOURCES).

BUG=
R=binji@chromium.org, noelallen@chromium.org

Review URL: https://codereview.chromium.org/17354002

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@208219 0039d316-1c4b-4281-b951-d872f2087c98

7 files changed, 168 insertions, 142 deletions

diff --git a/native_client_sdk/src/README b/native_client_sdk/src/README
index c85406f..f3ce40c 100644
--- a/native_client_sdk/src/README
+++ b/native_client_sdk/src/README
@@ -1,4 +1,5 @@
-Welcome to the Native Client SDK.
+Welcome to the Native Client SDK
+================================
 
 Native Client Tools Bundle
 Version: ${VERSION}
@@ -10,6 +11,7 @@ Please refer to the online documentation here:
   http://code.google.com/chrome/nativeclient
 
 OTHER DEVELOPMENT
+-----------------
 
 If you want to contribute to the Native Client SDK itself, please read the
 online documentation on contributing code to Chromium here:
@@ -17,6 +19,7 @@ online documentation on contributing code to Chromium here:
   http://www.chromium.org/developers/contributing-code
 
 KNOWN ISSUES
+------------
 
 Please refer to the online documentation here:
 
diff --git a/native_client_sdk/src/README.Makefiles b/native_client_sdk/src/README.Makefiles
new file mode 100644
index 0000000..1179395
--- /dev/null
+++ b/native_client_sdk/src/README.Makefiles
@@ -0,0 +1,95 @@
+Build System for Native Client SDK examples
+===========================================
+
+The examples and libraries that ship with the Native Client SDK use a
+build system based on GNU Make.
+
+Each example or library is contained in its own directory along with a
+Makefile.  The Makefiles are capable of building Native Client
+applications and libraries using any of the available toolchains as well
+as building host applications with the host's toolchain. In order to
+keep the top-level Makefiles simple, most of actual build rules are
+specified in as set of shared rules files in the $NACL_SDK_ROOT/tools
+directory.
+
+This document describes some of the variables and macros used by in the
+build system.  For more details please see the .mk files in the tools
+folder.
+
+Using the build system for new projects
+--------------------------------------
+
+It is perfectly possible to use the included build system for projects
+outside of the Native Client SDK.  A good starting point for doing this
+would be to copy the Makefile from the hello_world example.  In most
+simple cases the only changes needed are to update the SOURCES and
+TARGET variables.
+
+User Variables
+--------------
+
+TARGET
+  This variable holds the name of your project.  Normally this is the
+  basename of the library or executable which is the final target.
+
+SOURCES
+  The list of sources to be built.  In most cases this list is passed to
+  the compile and link macros.
+
+VALID_TOOLCHAINS
+  This variable can be used to control which toolchains are supported by
+  the project.  Valid entries for this list are: newlib, glibc, pnacl,
+  linux, mac, win.  The default value is: "newlib glibc pnacl".
+
+NACL_SDK_ROOT
+  Optionally force the build system to use a certain location for the
+  Native Client SDK. If not set within the Makefile the $NACL_SDK_ROOT
+  environment variable will by used. It is an error if this variable is
+  neither set within the Makefile nor in the environment.
+
+Macros / Rules
+--------------
+
+The following macros can be used in the Makefiles to generate the rules
+for building the various kinds types of target.  These are designed to
+be used via the 'call' macro.  e.g.  $(call COMPILE_RULE,$(SOURCES))
+
+COMPILE_RULE
+  This rule is used to build object files from a list of sources.
+
+SO_RULE
+  Used to build shared objects from a list of sources.
+
+LIB_RULE
+  Used to build static libraries from a list of sources.
+
+NMF_RULE
+  Used to build nmf metadata file from a native client executable (or
+  set of executables). This is needed in order to run the executable in
+  chrome.
+
+HTML_RULE
+  Used to build both html and nmf files from a native client executable
+  (or set of executables) which will allow the executable to be run
+  in chrome.
+
+For more information on how to use these rules in your Makefile see
+the shared Makefiles in the tools folders:
+
+common.mk
+  Top level shared rules file that include the toolchain specific
+  rules.
+
+nacl_gcc.mk
+  Rules for building using the gcc-based NaCl toolchains.
+
+nacl_llvm.mk
+  Rules for building using the llvm-based PNaCl toolchains.
+
+host_gcc.mk
+  Rules for building using the linux/mac host gcc toolchain.
+
+host_vc.mk
+  Rules for building using the windows Visual Studio toolchain.
+
+.. vim: ft=rst tw=72
diff --git a/native_client_sdk/src/build_tools/build_sdk.py b/native_client_sdk/src/build_tools/build_sdk.py
index 26cefcf..a54a8af 100755
--- a/native_client_sdk/src/build_tools/build_sdk.py
+++ b/native_client_sdk/src/build_tools/build_sdk.py
@@ -154,12 +154,16 @@ def BuildStepMakePepperDirs(pepperdir, subdirs):
   for subdir in subdirs:
     buildbot_common.MakeDir(os.path.join(pepperdir, subdir))
 
+TEXT_FILES = [
+  'AUTHORS',
+  'COPYING',
+  'LICENSE',
+  'README.Makefiles',
+]
 
 def BuildStepCopyTextFiles(pepperdir, pepper_ver, revision):
   buildbot_common.BuildStep('Add Text Files')
-  files = ['AUTHORS', 'COPYING', 'LICENSE']
-  files = [os.path.join(SDK_SRC_DIR, filename) for filename in files]
-  oshelpers.Copy(['-v'] + files + [pepperdir])
+  InstallFiles(SDK_SRC_DIR, pepperdir, TEXT_FILES)
 
   # Replace a few placeholders in README
   readme_text = open(os.path.join(SDK_SRC_DIR, 'README')).read()
diff --git a/native_client_sdk/src/build_tools/library.mk b/native_client_sdk/src/build_tools/library.mk
index 2ee3490..1d44b33 100644
--- a/native_client_sdk/src/build_tools/library.mk
+++ b/native_client_sdk/src/build_tools/library.mk
@@ -1,78 +1,37 @@
-# Copyright (c) 2012 The Chromium Authors. All rights reserved.
+# Copyright (c) 2013 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
-
-#
-# GNU Make based build file.  For details on GNU Make see:
-#   http://www.gnu.org/software/make/manual/make.html
-#
-#
-
-# Default configuration
-#
-# By default we will build a Debug configuration using the GCC newlib toolchain
-# to override this, specify TOOLCHAIN=newlib|glibc or CONFIG=Debug|Release on
-# the make command-line or in this file prior to including common.mk.  The
-# toolchain we use by default will be the first valid one listed
-VALID_TOOLCHAINS:={{' '.join(tools)}}
-
-
-[[# Only one target is allowed in a library project]]
 [[target = targets[0] ]]
-[[name = target['NAME'] ]]
 [[flags = ' '.join(target.get('CCFLAGS', []))]]
 [[flags += ' '.join(target.get('CXXFLAGS', []))]]
 
-#
-# Get pepper directory for toolchain and includes.
-#
-# If NACL_SDK_ROOT is not set, then assume it can be found relative to
-# to this Makefile.
-#
-NACL_SDK_ROOT?=$(abspath $(CURDIR)/../..)
-EXTRA_INC_PATHS={{' '.join(target.get('INCLUDES', []))}}
+# GNU Makefile based on shared rules provided by the Native Client SDK.
+# See README.Makefiles for more details.
 
-include $(NACL_SDK_ROOT)/tools/common.mk
+VALID_TOOLCHAINS := {{' '.join(tools)}}
+NACL_SDK_ROOT ?= $(abspath $(CURDIR)/../..)
+[[if 'INCLUDES' in target:]]
+EXTRA_INC_PATHS={{' '.join(target['INCLUDES'])}}
+[[]]
 
-#
-# Target Name
-#
-# The base name of the final library, also the name of the NMF file containing
-# the mapping between architecture and actual NEXE.
-#
-TARGET={{name}}
+include $(NACL_SDK_ROOT)/tools/common.mk
 
-#
-# List of sources to compile
-#
-SOURCES= \
+TARGET = {{target['NAME']}}
+CFLAGS = {{flags}}
+SOURCES = \
 [[for source in sorted(target['SOURCES']):]]
   {{source}} \
 [[]]
 
+all: install
 
-
-#
-# Use the compile macro for each source.
+# Build rules generated by macros from common.mk:
 #
-$(foreach src,$(SOURCES),$(eval $(call COMPILE_RULE,$(src),{{flags}})))
-
-#
-# Use the lib macro for this target on the list of sources.
-#
-$(eval $(call LIB_RULE,{{name}},$(SOURCES)))
+$(foreach src,$(SOURCES),$(eval $(call COMPILE_RULE,$(src),$(CFLAGS))))
+$(eval $(call LIB_RULE,$(TARGET),$(SOURCES)))
 
 [[if target['TYPE'] != 'static-lib':]]
 ifeq ($(TOOLCHAIN),glibc)
-#
-# When building with GLIBC, also build a shared object version of the
-# library.
-#
-$(eval $(call SO_RULE,{{name}},$(SOURCES)))
+$(eval $(call SO_RULE,$(TARGET),$(SOURCES)))
 endif
 [[]]
-
-#
-# Install the resulting libraries in the SDK library directory.
-#
-all: install
diff --git a/native_client_sdk/src/build_tools/sdk_files.list b/native_client_sdk/src/build_tools/sdk_files.list
index 65c19bd..510a432 100644
--- a/native_client_sdk/src/build_tools/sdk_files.list
+++ b/native_client_sdk/src/build_tools/sdk_files.list
@@ -643,6 +643,7 @@ lib/pnacl/Release/libsdk_util.a
 LICENSE
 NOTICE
 README
+README.Makefiles
 src/error_handling/error_handling.c
 [win]src/error_handling/make.bat
 src/error_handling/Makefile
diff --git a/native_client_sdk/src/build_tools/template.mk b/native_client_sdk/src/build_tools/template.mk
index 19583ea..4d76ec5 100644
--- a/native_client_sdk/src/build_tools/template.mk
+++ b/native_client_sdk/src/build_tools/template.mk
@@ -1,105 +1,68 @@
-# Copyright (c) 2012 The Chromium Authors. All rights reserved.
+# Copyright (c) 2013 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
-#
-# GNU Make based build file.  For details on GNU Make see:
-#   http://www.gnu.org/software/make/manual/make.html
-#
-
-
-#
-# Default configuration
-#
-# By default we will build a Debug configuration using the GCC newlib toolchain
-# to override this, specify TOOLCHAIN=newlib|glibc or CONFIG=Debug|Release on
-# the make command-line or in this file prior to including common.mk.  The
-# toolchain we use by default will be the first valid one listed
-VALID_TOOLCHAINS:={{' '.join(tools)}}
+# GNU Makefile based on shared rules provided by the Native Client SDK.
+# See README.Makefiles for more details.
 
+VALID_TOOLCHAINS := {{' '.join(tools)}}
 {{pre}}
-#
-# Get pepper directory for toolchain and includes.
-#
-# If NACL_SDK_ROOT is not set, then assume it can be found relative to
-# to this Makefile.
-#
-NACL_SDK_ROOT?=$(abspath $(CURDIR)/{{rel_sdk}})
+NACL_SDK_ROOT ?= $(abspath $(CURDIR)/{{rel_sdk}})
 include $(NACL_SDK_ROOT)/tools/common.mk
 
-
-#
-# Target Name
-#
-# The base name of the final NEXE, also the name of the NMF file containing
-# the mapping between architecture and actual NEXE.
-#
-TARGET={{targets[0]['NAME']}}
-
-#
-# List of sources to compile
-#
+TARGET = {{targets[0]['NAME']}}
+[[if targets[0].get('DEPS'):]]
+DEPS = {{' '.join(targets[0].get('DEPS', []))}}
+LIBS = $(DEPS) {{' '.join(targets[0].get('LIBS'))}}
+[[else:]]
+LIBS = {{' '.join(targets[0].get('LIBS'))}}
+[[]]
 [[for target in targets:]]
-{{target['NAME']}}_SOURCES= \
-[[  for source in sorted(target['SOURCES']):]]
-[[    if not source.endswith('.h'):]]
-  {{source}} \
+[[  source_list = (s for s in sorted(target['SOURCES']) if not s.endswith('.h'))]]
+[[  source_list = ' \\\n  '.join(source_list)]]
+[[  sources = target['NAME'] + '_SOURCES']]
+[[  cflags = target['NAME'] + '_CFLAGS']]
+[[  flags = ' '.join(target.get('CCFLAGS', []))]]
+[[  flags += ' '.join(target.get('CXXFLAGS', []))]]
+[[  if len(targets) == 1:]]
+[[    sources = 'SOURCES']]
+[[    cflags = 'CFLAGS']]
 [[  ]]
-
+[[  if flags:]]
+{{cflags}} = {{flags}}
+[[  ]]
+{{sources}} = {{source_list}}
 [[]]
 
+# Build rules generated by macros from common.mk:
 
-#
-# List of libraries to link against.  Unlike some tools, the GCC and LLVM
-# based tools require libraries to be specified in the correct order.  The
-# order should be symbol reference followed by symbol definition, with direct
-# sources to the link (object files) are left most.  In this case:
-#    hello_world -> ppapi_main -> ppapi_cpp -> ppapi -> pthread -> libc
-# Notice that libc is implied and come last through standard compiler/link
-# switches.
-#
-# We break this list down into two parts, the set we need to rebuild (DEPS)
-# and the set we do not.  This example does not have a any additional library
-# dependencies.
-#
-DEPS={{' '.join(targets[0].get('DEPS', []))}}
-LIBS=$(DEPS) {{' '.join(targets[0].get('LIBS'))}}
-
-
-#
-# Use the library dependency macro for each dependency
-#
+[[if targets[0].get('DEPS'):]]
 $(foreach dep,$(DEPS),$(eval $(call DEPEND_RULE,$(dep))))
-
-#
-# Use the compile macro for each source.
-#
-[[for target in targets:]]
-[[  name = target['NAME'] ]]
-[[  flags = ' '.join(target.get('CCFLAGS', []))]]
-[[  flags += ' '.join(target.get('CXXFLAGS', []))]]
-$(foreach src,$({{name}}_SOURCES),$(eval $(call COMPILE_RULE,$(src),{{flags}})))
+[[if len(targets) > 1:]]
+[[  for target in targets:]]
+[[    name = target['NAME'] ]]
+$(foreach src,$({{name}}_SOURCES),$(eval $(call COMPILE_RULE,$(src),$({{name}}_CFLAGS))))
+[[else:]]
+$(foreach src,$(SOURCES),$(eval $(call COMPILE_RULE,$(src),$(CFLAGS))))
 [[]]
 
-#
-# Use the link macro for this target on the list of sources.
-#
 [[for target in targets:]]
+[[  sources = target['NAME'] + '_SOURCES']]
 [[  name = target['NAME'] ]]
+[[  if len(targets) == 1:]]
+[[    sources = 'SOURCES']]
+[[    name = '$(TARGET)']]
 [[  if target['TYPE'] == 'so':]]
-$(eval $(call SO_RULE,{{name}},$({{name}}_SOURCES)))
+$(eval $(call SO_RULE,{{name}},$({{sources}})))
 [[  elif target['TYPE'] == 'so-standalone':]]
-$(eval $(call SO_RULE,{{name}},$({{name}}_SOURCES),,,1))
+$(eval $(call SO_RULE,{{name}},$({{sources}}),,,1))
 [[  else:]]
 ifeq ($(CONFIG),Release)
-$(eval $(call LINK_RULE,{{name}}_unstripped,$({{name}}_SOURCES),$(LIBS),$(DEPS)))
+$(eval $(call LINK_RULE,{{name}}_unstripped,$({{sources}}),$(LIBS),$(DEPS)))
 $(eval $(call STRIP_RULE,{{name}},{{name}}_unstripped))
 else
-$(eval $(call LINK_RULE,{{name}},$({{name}}_SOURCES),$(LIBS),$(DEPS)))
+$(eval $(call LINK_RULE,{{name}},$({{sources}}),$(LIBS),$(DEPS)))
 endif
 [[]]
 
-#
-# Specify the NMF to be created with no additional arguments.
-#
 $(eval $(call NMF_RULE,$(TARGET),)){{post}}
diff --git a/native_client_sdk/src/tools/nacl_gcc.mk b/native_client_sdk/src/tools/nacl_gcc.mk
index 89ef16b..108039d 100644
--- a/native_client_sdk/src/tools/nacl_gcc.mk
+++ b/native_client_sdk/src/tools/nacl_gcc.mk
@@ -373,10 +373,11 @@ ifeq ($(CONFIG),Debug)
 NMF_FLAGS += --debug-libs
 endif
 
+EXECUTABLES=$(foreach arch,$(ARCH_SUFFIXES),$(OUTDIR)/$(1)$(arch)) $(GLIBC_SO_LIST)
 
 define NMF_RULE
 all: $(OUTDIR)/$(1).nmf
-$(OUTDIR)/$(1).nmf: $(foreach arch,$(ARCH_SUFFIXES),$(OUTDIR)/$(1)$(arch)) $(GLIBC_SO_LIST)
+$(OUTDIR)/$(1).nmf: $(EXECUTABLES)
 	$(call LOG,CREATE_NMF,$$@,$(NMF) $(NMF_FLAGS) -o $$@ $$^ $(GLIBC_PATHS) -s $(OUTDIR) $(2) $(GLIBC_REMAP))
 endef
 
@@ -387,6 +388,6 @@ CREATE_HTML := python $(NACL_SDK_ROOT)/tools/create_html.py
 
 define HTML_RULE
 all: $(OUTDIR)/$(1).html
-$(OUTDIR)/$(1).html: $(foreach arch,$(ARCH_SUFFIXES),$(OUTDIR)/$(1)$(arch)) $(GLIBC_SO_LIST)
+$(OUTDIR)/$(1).html: $(EXECUTABLES)
 	$(call LOG,CREATE_HTML,$$@,$(CREATE_HTML) -o $$@ $$^)
 endef