The eMake subbuild feature is designed to help speed up component builds through intelligent build avoidance. Currently, the subbuild feature’s scope includes the following use case:
Makefile: ------------- .PHONY: a b all: a b @echo all a b: $(MAKE) -C $@
a/Makefile ------------- all: a.lib @echo a
a.lib: @touch $@
b/Makefile ------------- all: ../a/a.lib @echo b
Explanation : If something from ‘
a ’ changes, and you are building from ‘
b ’, the only way to pick up the new
a.lib is to build from the top level directory. With subbuilds, you know
b ’s dependencies so you can build those dependencies directly without having to build everything from the top level directory.
The subbuild database must be built beforehand to make the dependency list available without having to parse any Makefiles that are not in the current directory.
The following sections describe how to use subbuilds. Refer to Subbuild limitations for additional information.
Subbuild database generation
The following command runs your build as normal and also generates a subbuild database with the name
emake --emake-gen-subbuild-db=1 --emake-root=<path> --emake-subbuild-db=emake.subbuild.db
path > is the eMake root directory setting.
--emake-root is required for cluster builds.
--emake-subbuild-db is optional. If it is missing, the default
emake.subbuild.db name is used.
Run a Build Using Subbuild
The following command runs a build with subbuild information:
--emake-subbuild-db=<file> to run a build with subbuild information. When you invoke eMake with the
--emake-subbuild-db option, it uses the dependencies extracted from the makefile and the subbuild database to determine which build components are prerequisites of the desired current make, then rebuilds those components before proceeding as normal.
When you specify
--emake-subbuild-db=<file>, do not specify
--emake-gen-subbuild-db, otherwise eMake regenerates the database.
There is no incremental building of the database. Each time you change something in a makefile in your build, you must rebuild the database by doing a full build.
The database is not currently optimized for size. This might result in an extremely large database for very large builds.
Subbuilds do not provide additional gains in non-recursive make builds.
Because of the manner in which subbuilds are currently scheduled, there is interleaving output for the “Entering directory…” and “Leaving directory…” messages.
For example: If a subbuild database was built for the following build:
Makefile: ------------- .PHONY: a b all: a b a b: $(MAKE) -C $@
a/Makefile ---------------- all: a.lib a.lib: echo aaa > $@
b/Makefile: ---------------- all: ../a/a.lib echo b
When you proceed to build just ‘
b ’ (maybe with “
emake -C b ”) and
a/a.lib is missing, you receive “entering directory a” after “entering directory b”, even though ‘
a ’ is supposed to be built before ‘
make: Entering directory 'b' make -C a make: Entering directory 'a' echo aaa > a.lib make: Leaving directory 'a' echo b b make: Leaving directory 'b'
Information applying to local builds only
Rules to build a sub-directory’s output files must not overlap. For example: The rule to build
sub1/foo.omust appear in
sub1/Makefileonly and not
sub2/Makefile. Default suffix rules can cause eMake to find a way to build
sub1/foo.owhile trying to build
sub2. In this situation, adding “
sub2/Makefilecan resolve the issue.
Subbuilds require that the build be componentized to some degree.
Subbuilds require that you have practiced “good hygiene” in your build tree—there must be explicit dependencies mentioned in the component makefiles.
For example: If a build has two components,
foo produces a library
bar uses that library, the rule might be written to produce
bar.exe such as this in
bar.exe: $(BAR_OBJS) link $(BAR_OBJS) -l $(OUTDIR)/foo/foo.dll
For subbuilds to work (in local mode), it must be modified as in the following:
bar.exe: $(BAR_OBJS) $(OUTDIR)/foo/foo.dll link $(BAR_OBJS) -l $(OUTDIR)/foo/foo.dll
Note that it is explicitly stated that
foo.dll. Also note that it is NOT required to have a rule to build
There cannot be ANY rule at all to build
bar/Makefile, explicit or implicit, otherwise you will get the wrong information for building
foo/foo.dll in the subbuilds database. The subbuilds database currently allows updates to existing entries while building the database.