1 # -*- mode: makefile -*-
3 # Copyright (c) 2012, Joyent, Inc. All rights reserved.
5 # Makefile.targ: common targets.
7 # NOTE: This makefile comes from the "eng" repo. It's designed to be dropped
8 # into other repos as-is without requiring any modifications. If you find
9 # yourself changing this file, you should instead update the original copy in
10 # eng.git and then update your repo to use the new version.
12 # This Makefile defines several useful targets and rules. You can use it by
13 # including it from a Makefile that specifies some of the variables below.
15 # Targets defined in this Makefile:
17 # check Checks JavaScript files for lint and style
18 # Checks bash scripts for syntax
19 # Checks SMF manifests for validity against the SMF DTD
21 # clean Removes built files
23 # docs Builds restdown documentation in docs/
25 # prepush Depends on "check" and "test"
27 # test Does nothing (you should override this)
29 # xref Generates cscope (source cross-reference index)
31 # For details on what these targets are supposed to do, see the Joyent
34 # To make use of these targets, you'll need to set some of these variables. Any
35 # variables left unset will simply not be used.
37 # BASH_FILES Bash scripts to check for syntax
38 # (paths relative to top-level Makefile)
40 # CLEAN_FILES Files to remove as part of the "clean" target. Note
41 # that files generated by targets in this Makefile are
42 # automatically included in CLEAN_FILES. These include
43 # restdown-generated HTML and JSON files.
45 # DOC_FILES Restdown (documentation source) files. These are
46 # assumed to be contained in "docs/", and must NOT
47 # contain the "docs/" prefix.
49 # JSL_CONF_NODE Specify JavaScriptLint configuration files
50 # JSL_CONF_WEB (paths relative to top-level Makefile)
52 # Node.js and Web configuration files are separate
53 # because you'll usually want different global variable
54 # configurations. If no file is specified, none is given
55 # to jsl, which causes it to use a default configuration,
56 # which probably isn't what you want.
58 # JSL_FILES_NODE JavaScript files to check with Node config file.
59 # JSL_FILES_WEB JavaScript files to check with Web config file.
61 # You can also override these variables:
63 # BASH Path to bash (default: bash)
65 # CSCOPE_DIRS Directories to search for source files for the cscope
66 # index. (default: ".")
68 # JSL Path to JavaScriptLint (default: "jsl")
70 # JSL_FLAGS_NODE Additional flags to pass through to JSL
74 # JSSTYLE Path to jsstyle (default: jsstyle)
76 # JSSTYLE_FLAGS Additional flags to pass through to jsstyle
80 # Defaults for the various tools we use.
83 BASHSTYLE ?= tools/bashstyle
93 JSL_FLAGS ?= --nologo --nosummary
95 ifeq ($(shell uname -s),SunOS)
103 # Defaults for other fixed values.
106 DISTCLEAN_FILES += $(BUILD)
107 DOC_BUILD = $(BUILD)/docs/public
110 # Configure JSL_FLAGS_{NODE,WEB} based on JSL_CONF_{NODE,WEB}.
112 ifneq ($(origin JSL_CONF_NODE), undefined)
113 JSL_FLAGS_NODE += --conf=$(JSL_CONF_NODE)
116 ifneq ($(origin JSL_CONF_WEB), undefined)
117 JSL_FLAGS_WEB += --conf=$(JSL_CONF_WEB)
121 # Targets. For descriptions on what these are supposed to do, see the
122 # Joyent Engineering Guide.
126 # Instruct make to keep around temporary files. We have rules below that
127 # automatically update git submodules as needed, but they employ a deps/*/.git
128 # temporary file. Without this directive, make tries to remove these .git
129 # directories after the build has completed.
131 .SECONDARY: $($(wildcard deps/*):%=%/.git)
134 # This rule enables other rules that use files from a git submodule to have
135 # those files depend on deps/module/.git and have "make" automatically check
136 # out the submodule as needed.
139 git submodule update --init deps/$*
142 # These recipes make heavy use of dynamically-created phony targets. The parent
143 # Makefile defines a list of input files like BASH_FILES. We then say that each
144 # of these files depends on a fake target called filename.bashchk, and then we
145 # define a pattern rule for those targets that runs bash in check-syntax-only
146 # mode. This mechanism has the nice properties that if you specify zero files,
147 # the rule becomes a noop (unlike a single rule to check all bash files, which
148 # would invoke bash with zero files), and you can check individual files from
149 # the command line with "make filename.bashchk".
152 check-bash: $(BASH_FILES:%=%.bashchk) $(BASH_FILES:%=%.bashstyle)
160 .PHONY: check-jsl check-jsl-node check-jsl-web
161 check-jsl: check-jsl-node check-jsl-web
163 check-jsl-node: $(JSL_FILES_NODE:%=%.jslnodechk)
165 check-jsl-web: $(JSL_FILES_WEB:%=%.jslwebchk)
167 %.jslnodechk: % $(JSL_EXEC)
168 $(JSL) $(JSL_FLAGS) $(JSL_FLAGS_NODE) $<
170 %.jslwebchk: % $(JSL_EXEC)
171 $(JSL) $(JSL_FLAGS) $(JSL_FLAGS_WEB) $<
173 .PHONY: check-jsstyle
174 check-jsstyle: $(JSSTYLE_FILES:%=%.jsstylechk)
176 %.jsstylechk: % $(JSSTYLE_EXEC)
177 $(JSSTYLE) $(JSSTYLE_FLAGS) $<
180 check: check-jsl check-jsstyle check-bash
185 -$(RMTREE) $(CLEAN_FILES)
189 -$(RMTREE) $(DISTCLEAN_FILES)
191 CSCOPE_FILES = cscope.in.out cscope.out cscope.po.out
192 CLEAN_FILES += $(CSCOPE_FILES)
200 find $(CSCOPE_DIRS) -name '*.c' -o -name '*.h' -o -name '*.cc' \
201 -o -name '*.js' -o -name '*.s' -o -name '*.cpp' > $@
204 # The "docs" target is complicated because we do several things here:
206 # (1) Use restdown to build HTML and JSON files from each of DOC_FILES.
208 # (2) Copy these files into $(DOC_BUILD) (build/docs/public), which
209 # functions as a complete copy of the documentation that could be
210 # mirrored or served over HTTP.
212 # (3) Then copy any directories and media from docs/media into
213 # $(DOC_BUILD)/media. This allows projects to include their own media,
214 # including files that will override same-named files provided by
217 # Step (3) is the surprisingly complex part: in order to do this, we need to
218 # identify the subdirectories in docs/media, recreate them in
219 # $(DOC_BUILD)/media, then do the same with the files.
221 DOC_MEDIA_DIRS := $(shell find docs/media -type d 2>/dev/null | grep -v "^docs/media$$")
222 DOC_MEDIA_DIRS := $(DOC_MEDIA_DIRS:docs/media/%=%)
223 DOC_MEDIA_DIRS_BUILD := $(DOC_MEDIA_DIRS:%=$(DOC_BUILD)/media/%)
225 DOC_MEDIA_FILES := $(shell find docs/media -type f 2>/dev/null)
226 DOC_MEDIA_FILES := $(DOC_MEDIA_FILES:docs/media/%=%)
227 DOC_MEDIA_FILES_BUILD := $(DOC_MEDIA_FILES:%=$(DOC_BUILD)/media/%)
230 # Like the other targets, "docs" just depends on the final files we want to
231 # create in $(DOC_BUILD), leveraging other targets and recipes to define how
236 $(DOC_FILES:%.restdown=$(DOC_BUILD)/%.html) \
237 $(DOC_FILES:%.restdown=$(DOC_BUILD)/%.json) \
238 $(DOC_MEDIA_FILES_BUILD)
241 # We keep the intermediate files so that the next build can see whether the
242 # files in DOC_BUILD are up to date.
245 $(DOC_FILES:%.restdown=docs/%.html) \
246 $(DOC_FILES:%.restdown=docs/%json)
249 # We do clean those intermediate files, as well as all of DOC_BUILD.
253 $(DOC_FILES:%.restdown=docs/%.html) \
254 $(DOC_FILES:%.restdown=docs/%.json)
257 # Before installing the files, we must make sure the directories exist. The |
258 # syntax tells make that the dependency need only exist, not be up to date.
259 # Otherwise, it might try to rebuild spuriously because the directory itself
260 # appears out of date.
262 $(DOC_MEDIA_FILES_BUILD): | $(DOC_MEDIA_DIRS_BUILD)
264 $(DOC_BUILD)/%: docs/% | $(DOC_BUILD)
267 docs/%.json docs/%.html: docs/%.restdown | $(DOC_BUILD) $(RESTDOWN_EXEC)
268 $(RESTDOWN) $(RESTDOWN_FLAGS) -m $(DOC_BUILD) $<
273 $(DOC_MEDIA_DIRS_BUILD):
277 # The default "test" target does nothing. This should usually be overridden by
278 # the parent Makefile. It's included here so we can define "prepush" without
279 # requiring the repo to define "test".