Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MAKEPP_RULES(1)			    Makepp		       MAKEPP_RULES(1)

NAME
       makepp_rules -- How to tell makepp to build something

DESCRIPTION
       ?: &,
	 -,
	 @,  B:	:build_cache,
	 :build_check,	D: :dispatch,  E: :env,	 I: "ignore_error",
	 :include,  L: :last_chance,  M: makeperl,  N: "noecho",  P: :parser,
	 "perl",  S: :signature

       A rule is what tells makepp how to build	a file or a class of files.
       Makepp supports the same	rule syntax as other implementations of	make,
       plus some additions of its own.

       A rule has the general format

	   target_expression : dependency_expression  [	: optional arguments]
	       actions

       The list	of targets may not contain any automatic variables (except
       "$(foreach)").  The dependency list may contain only automatic
       variables referring to the target (i.e.,	"$(output)", "$(outputs)", or
       their synonyms).	 The action may	contain	any automatic variables.

       If makepp decides that the rule needs to	be executed, each line of the
       rule is executed	sequentially, and if any returns a non-zero status,
       the remainder are not executed (and makepp aborts with an error unless
       you specified the "-k" option on	the command line.)  Each action	should
       be only one line.  If an	action is too long to write conveniently on a
       single line, you	can split it into several lines	and put	a backslash to
       indicate	that the several lines should be combined into one.

       In order	to distinguish actions from the	next rule, the action should
       be indented more	than the line containing the targets and dependencies.
       Unlike other implementations of make, makepp doesn't really care	how
       much you	indent it or whether you use tab characters rather than
       spaces.	To keep	backward compatibility with traditional	make, the
       rules makepp uses to decide when	actions	end and	the next rule begins
       are somewhat complicated:

       o   The first action line must be indented more than the	line
	   containing the target.

       o   If a	line is	indented by one	tab character or 8 spaces or more,
	   then	it is considered an action line.

       o   A blank line	or a comment line with the "#" character at the	right
	   margin ends the rule, unless	the next non-blank line	is indented
	   more	than 8 spaces (or more than one	tab).

       o   If a	line is	indented as much or more than the first	action line,
	   then	it is considered an additional action line.

       There are a few special action items:

	   &

	   This	symbol shall be	followed by a command name and any number of
	   arguments.  Shell syntax is not understood fully here, only single
	   and double quotes and backslashed characters	within,	as throughout
	   makepp.  The	command	name either leads to a function	"c_name" to be
	   called with the remaining strings as	arguments.  If such a function
	   can not be found, this is identical to calling "run"	from a "perl"
	   block.

	   This	allows efficiently calling a built-in, makefile-provided or
	   external command.  The prefix "&" has been chosen because it	is the
	   function invoker in Perl, and because at the	beginning it is
	   illegal in Shell.

	       $(ROOT)/include/%.h: %.h
		   &ln $(input)	$(output)

	   noecho

	   @

	   Normally, each shell	command	is printed as it is executed.
	   However, if the first word of the action is "noecho"	(or if it
	   begins with the character "@"), then	the command is not printed.
	   For example,

	       %.o: %.cxx
		     noecho $(LIBTOOL) --mode=compile $(CC) -c $(input)

	   This	means that when	the libtool command is executed, it is not
	   printed.  (Libtool itself usually prints the	modified command that
	   it executes,	so it's	redundant to print it twice.)

	   ignore_error

	   -

	   Normally, if	the shell command returns a non-zero status, then
	   makepp aborts because the command failed.  However, some programs
	   incorrectly set the status on exit, or there	may be an error	which
	   really isn't	fatal and shouldn't abort the whole compilation.  You
	   can cause makepp to ignore the return status	by specifying
	   "ignore_error" as the first word of the command line	(or "-"	as the
	   first character).  For example,

	       $(phony distribution):
		   ignore_error	rm -r my_program-$(VERSION) # Get rid of previous junk.
		   &mkdir my_program-$(VERSION)
		   &cp $(FILES)	my_program-$(VERSION)
		   tar cf my_program-$(VERSION).tar my_program-$(VERSION)

	   This	command	makes a	directory, copies a bunch of files into	it,
	   and then puts everything into a tar file for	distribution.  It's a
	   good	idea to	clean out the previous contents	of the directory, if
	   there was anything there previously,	and that's what	the first line
	   does.  The "rm" might fail, but its return status is	ignored.

	   perl

	   makeperl

	   This	is essentially the same	as the perl statement, but it is
	   performed each time when running the	rule, not when reading the
	   makefile.  The first	variant	is plain Perl code, while the second
	   variant first passes	the statement through Make-style variable
	   expansion.

	   For the two possibilities of	putting	the braces of the body,	see
	   the explanation at "perl_perlcode" in makepp_statements.  Note that
	   the third variant explained there makes no sence here, because all
	   action lines	must be	indented.  You must signal failure in Perl
	   statements, by calling "die".

	   Per rule the	Perl statements	are currently evaluated	in a common
	   subprocess, except on Windows.  That	means they have	only read
	   access to any makefile variables.  It is also the process which
	   executes non-Perl actions.  So calling exec or exit will confuse
	   makepp.  But	this may change	in the future.	For an efficient way
	   to call Perl	scripts, see the previous item "&" or "run".

	       $(phony version):
		   noecho perl {{  # $(target) & $(VERSION) from Perl:
		     print "This is ".f_target()." $VERSION\n";
		   }}
		   echo	You can	mix this with Shell commands
		   -makeperl { print "This is $(target)	$(VERSION)\n" }

       There are several different kinds of rules, each	with different
       purposes.

   Explicit Rules
	   target1 target2: dependency1	dependency2 ...
	       actions to be performed

       This syntax specifies that in order to make either target1 or target2,
       all the files dependency1, dependency2, etc., must already have been
       made.  Then the given actions are executed by the shell to make the
       targets.

       The first explicit rule in a file is the	default	target,	and is made if
       you do not specify any targets on the command line.

       Unlike traditional make programs, makepp	usually	assumes	that one
       invocation of the action	makes all of the targets (unless there are no
       dependencies).  For example, one	invocation of yacc creates both	output
       files for this rule:

	   y.tab.c y.tab.h : parser.y
	       $(YACC) -d parser.y

       Note that other implementations of make do not have a concept of	a
       single command producing	multiple output	files, and so when you specify
       multiple	targets	they will execute the rule once	per target.  Makepp
       will revert to this behavior if it looks	like this is an	old-style
       makefile.  Specifically,	it will	execute	the rule once per target,
       instead of just once overall, if	all of the following are true:

       o   The rule action mentions the	automatic variable $@.	(The synonyms
	   "$(output)" or "$(target)" do not trigger this behavior.)

       o   The rule action does	not mention the	automatic variable
	   "$(outputs)"	(or its	synonym	"$(targets)").

       o   This	is not a pattern rule, and there is no foreach clause.

       For example,

	   all test install:
	       for subdir in $(SUBDIRS); do cd $$subdir	&& $(MAKE) $@; cd ..; done

       is a common idiom in makefiles, and makepp supports it.	(Note that you
       should never use	recursive make in any new makefiles you	write--use the
       "load_makefile" statement, or implicit makefile loading instead.)

       If you want to have the same rule executed once for each	target (e.g.,
       because the targets have	similar	commands), it's	preferable to use
       either a	pattern	rule (see below) or a "foreach"	clause.	 For example,
       if with a traditional make program you would write:

	   a b c d:
	       do_something to build $@	> $@

       in makepp, you would probably want to write it like this:

	   $(foreach) :	: foreach a b c	d
	       do_something to build $(output) > $(output)

       Phony targets

       A phony target is a target that will never actually exist in the	file
       system; it's just a way of getting makepp to build some targets and
       possibly	execute	some additional	commands.

       A typical phony target is "all",	which usually is used to cause
       everything that can be built to be built, like this:

	   all:	prog1 prog2 subdir/prog3 subdir2/libmine.a
		 @&echo	"All done!"

       If you type "makepp all", or if you put all as the first	explicit
       target in your makefile (which is typical) and just type	"makepp", then
       it will cause all the dependencies to be	built, then it will print "All
       done!".	At this	point, makepp will look	for the	file ./all and will
       discover	that it	doesn't	exist.	It will	complain loudly.

       To keep makepp from expecting the file ./all to exit, you need to tell
       it that it's a phony target.  Just put a	line like the following	in
       your makefile (it makes no difference where):

	   .PHONY: all

       An equivalent alternative which is sometimes more convenient is to use
       the "$(phony )" function, like this:

	   $(phony all): prog1 prog2 subdir/prog3 subdir2/libmine.a

       Phony targets in	one makefile can refer to phony	targets	in another
       makefile.  This is often	done with the "clean" target, like this:

	   # Top level makefile:
	   # lots of rules and stuff here
	   # ....
	   $(phony clean): subdir1/clean subdir2/clean
	       &rm -fm my_program

       Then in the subdirectories, the makefiles might read like this:

	   # Makefile in a subdirectory
	   # ...
	   $(phony clean):
	       &rm -fm $(wildcard *.o *.a)

       But nowadays you	would use the "makeppclean" command, instead of	a
       clean target.

       Wildcards

       It is safe to specify wildcards in the dependency list.	Wildcards
       match not only files that exist,	but files which	can be created given
       the rules in the	makefile.  For example,	to build a library from	all .o
       files in	a directory, you could write this:

	   libmine.a: *.o
	       &rm -f $(output)
	       ar cr $(output) $(inputs)

       This will work even if none of the ".o" files have been created yet,
       because makepp's	wildcards match	files which do not yet exist but can
       be built.  This will even pick up files whose rule is discovered	later
       (in the same makefile, or one not yet read).  In	this last point	it
       differs from the	"wildcard" function, which is limited to the known
       rules, as it must return	its result when	it is expanded.

       Makepp supports all the usual shell wildcards ("*", "?",	and "[]").  It
       also has	a wildcard "**"	which matches any number of intervening
       directories.  (This idea	was stolen from	zsh.)  For example, "**/*.c"
       matches all the .c files	in the entire source tree.  "objects/**/*.o"
       matches all the .o files	contained anywhere in the subdirectory objects
       or any of its subdirectories or any of their subdirectories.  The "**"
       wildcard	will not follow	soft links to directories at any level.	 It
       also will never return phony targets.

       Makepp's	wildcards will ignore files or directories which exist but
       cannot be read.	After all, such	files cannot be	used in	the build
       process anyway.	Putting	unreadable files in a directory	is primarily
       useful to inhibit the automatic import of the given file	from a
       repository.

       The initial assertion was that this is safe.  This is in	the sence that
       it works	whether	the files already exist, or need to be built first.
       However it is unsafe in the sence that it will still match files	that
       were built by makepp, but no longer have	a rule (e.g. you removed the
       .c file,	but the	.o file	is still there.)  To prevent this, use the
       "--rm-stale" option.

   Pattern rules
       A pattern rule is a rule	that is	applied	based on some textual pattern.
       This is used to apply the same rule to a	whole class of files.  The
       syntax is the same as GNU make's	pattern	rules:

	   %.o:	%.c
	       $(CC) -c	$(input) -o $(output)

       This says that any file in the current directory	which matches "*.c"
       can be converted	into the corresponding .o file using the given
       command.

       Note that several pattern dependencies may be supplied.	For example,
       if your xyz.o file depends on the corresponding xyz.cpp file, and also
       on a file called	moc_xyz.cflags which contains the compiler options,
       this could be expressed with:

	   %.o:	%.cpp %.cflags
	       $(CXX) `cat $(stem).cflags` -c $(inputs)	-o $(output)

       You may also have several pattern targets.  For example,

	   %.tab.h %.tab.c : %.y
	       yacc -d $(input)
	       &mv y.tab.h $(stem).tab.h
	       &mv y.tab.c $(stem).tab.c

       Ordinarily, pattern rules only look for files in	the current
       directories.  You can force them	to search in the current directory and
       all directories beneath it by setting

	   makepp_percent_subdirs := 1

       before the first	pattern	rule in	your makefile or on the	command	line
       for example.

       There is	a clear	difference between "%" and the wildcard	"*", though
       both match any string: The wildcard returns a list of files that	is
       completely used at that point.  So this depends on all .o files
       buildable here:

	   prog: *.o
	       $(LD) $(LDFLAGS)	$(inputs) -o $(output)

       This could not be achieved by replacing "*" with	"%", because the
       latter is for one-by-one	matching of input to output, producing
       internally one rule for each matched stem.

   Static pattern rules
       A static	pattern	rule is	a pattern rule that is applied only to a
       limited set of files:

	   $(SPECIAL_MODULES).o	: %.o :	%.cpp
	       $(CXX) -c $(input) -o $(output)

       This says that the pattern rule applies only to the files in
       "$(SPECIAL_MODULES).o".

       This is mostly for compatibility	with GNU make; foreach rules (see
       below) are a more powerful way of doing the same	thing.

   Foreach rules
       The above pattern rule syntax is	powerful enough	to support almost all
       builds, but occasionally	it is necessary	to do something	more
       complicated.  Makepp provides a more powerful syntax: the ":foreach"
       clause for the rule.

	   target_expression : dependency_expression : foreach file-list
	       actions

       The simplest kind of foreach rule is just a pattern rule	whose
       application is restricted to a specific list of files.  For example,
       suppose you have	a pattern rule that tells makepp how to	compile	all .c
       files.  However,	you have a list	of .c files for	which you want to do
       something different.  You could do something like this:

	   # Here's the	rule that applies to everything:
	   %.o : %.c
	       $(CC) $(CFLAGS) -c $(input) -o $(output)

	   %.o : %.c : foreach $(SPECIAL_MODULES)
	       $(CC) $(SPECIAL_CFLAGS) -c $(input) -o $(output)

       An even more powerful use of foreach rules takes	advantage of the fact
       that the	variable "$(foreach)" is set in	turn to	each file matching the
       file list and the target	and dependency expressions are evaluated.  The
       file-list may contain wildcards,	and these match	even files which don't
       exist yet but which can be built	(see "Wildcards" in makepp_rules).

       This is an unwieldy syntax but it is extremely flexible,	because	the
       "$(foreach)" variable may appear	in any way in the expression.  First,
       note that pattern rules are in fact a special case of foreach rules;
       the pattern rule

	    %.o	: %.c
	       $(CC) $(CFLAGS) -c $(input) -o $(output)

       is exactly equivalent to:

	   $(patsubst %.c, %.o,	$(foreach)) : $(foreach) : foreach *.c
	       $(CC) $(CFLAGS) -c $(input) -o $(output)

       (In fact, it's converted	to approximately that internally.)

       As an example of	how you	would use a ":foreach" clause where a pattern
       rule isn't sufficient, suppose you have some .c files which are built
       using some kind of preprocessor which takes as input files with a .k
       extension.  You want to compile those .c	files with a different set of
       compilation options than	the usual .c files which are ordinary source
       files.  You could do something like this:

	   # Rule for ordinary .c files:
	   %.o : %.c
	       $(CC) $(CFLAGS) -c $(input) -o $(output)

	   # Rule to make .c files from	.k files:
	   %.c : %.k
	       $(preprocessor) $(input)	> $(output)

	   # Special build rules for .c	files which are	made from .k files:
	   $(foreach:%.k=%.o) :	$(foreach:%.c=%.k) : foreach *.k
	       $(CC) $(SPECIAL_CFLAGS) -c $(input) -o $(output)

       (This uses the slightly more concise substitution reference syntax
       rather than calling "patsubst" explicitly.)

       Note that if all	you want to do is to change the	value of a variable
       ("CFLAGS" in this case) it's sometimes more convenient to use target-
       specific	variables.

   Legacy suffix rules
       For backward compatibility, makepp supports the old-style suffix	rules.

	   .suffix1.suffix2:
	       actions

       is equivalent to

	   %.suffix2: %.suffix1
	       actions

       but much	harder to remember.  (Which suffix comes first?)  Typically, a
       rule will appear	in a legacy makefile like this:

	   .c.o:
	       $(CC) $(CFLAGS) -c $*.c -o $*.o

       which is	exactly	equivalent to

	   %.o : %.c
	       $(CC) $(CFLAGS) -c $(input) -o $(output)

   Conflicting rules
       When there is more than one way to make a file, makepp uses a simple
       procedure to determine which rule to use.

       o   It is an error to have conflicting explicit rules for building a
	   file.

       o   Pattern rules and foreach rules with	wildcards never	override
	   explicit rules.  Thus explicit rules	can be used to specify
	   exceptions for pattern rules.  (Note	that simply using a ":foreach"
	   clause doesn't make something a pattern rule.  It must have a
	   wildcard (like "*" or "?") as part of the filename in the
	   ":foreach" clause.  If it is	just an	explicit list of files,	it is
	   treated as an explicit rule for each	of those files.)

       o   When	conflicting pattern rules come from different makefiles, rules
	   from	"nearer" makefiles override rules from "farther" makefiles.
	   "Nearer" means that the makefile is located closer to the target in
	   the directory hierarchy (i.e., the file name	of the target relative
	   to the directory the	makefile is run	from is	shorter).  If this
	   doesn't distinguish the makefiles, then the rule from the makefile
	   which is loaded latest is used.

	   This	means that you can specify a pattern rule that applies to all
	   files in your entire	directory tree in just the top-level makefile,
	   but then you	can override it	in a lower-level makefile.  For
	   example, your top-level makefile could contain:

	       %.o : %.c : foreach **/*.c
		   $(CC) $(CFLAGS) -c $(input) -o $(output)

	   and you could have a	makefile in one	of the subdirectories that
	   says:

	       %.o : %.c
		   $(CC) $(SPECIAL_CFLAGS) -c $(input) -o $(output)

       o   Pattern rules that have a shorter chain of inference	are preferred
	   over	other pattern rules.  For example, if you had the following
	   rules (based	on an example from the Linux kernel):

	       %.s: %.c
		   $(CC) -s $(input) -o	$(output)

	       %.o: %.s
		   $(AS) $(input) -o $(output)

	       %.o: %.c
		   $(CC) -c $(input) -o	$(output)

	   If we need to build "xyz.o",	we could either	build the intermediate
	   ".s"	file and then run that through the assembler using the first
	   two rules, or we could go directly to a ".o"	file using the last
	   rule.  The last rule	is preferred because there are fewer steps in
	   the chain of	inference (one instead of two).

       o   Pattern rules later in a makefile override pattern rules that are
	   earlier.  (This is backwards	from GNU make.)	 This means that you
	   should put your more	general	rules earlier, and your	more specific
	   rules later.	 For example,

	       %.o: %.c				   # General compilation rule.
		   action

	       special_%.o: special_%.c		   # Special rule for files with a
		   different action		   # "special_"	prefix.

   Rule	options
       Sometimes it is necessary to supply additional options to modify	how
       makepp executes the rule.  These	options	are specified as ":optionname
       value", either on the line containing the dependencies, or on the next
       line.

       Supplying the options on	separate lines may make	it possible for	you to
       use the same makefile with makepp and a traditional make.  For example,

	   target : dependencies
		  : signature target_newer
	       actions

       will work fine with a traditional Unix make, because it interprets the
       ": signature" line as a shell command, and a command beginning with a
       colon does nothing.

       :build_cache /path/to/build/cache
		target : dependencies
		       : build_cache /put/cache/files/over/there
		     actions

	   Specifies the path to a build cache to be used for files produced
	   by this rule.  This overrides the effect of the "build_cache"
	   statement or	the "--build-cache" command line option, if any, for
	   this	rule.  See makepp_build_cache for details about	build caches.

	   If you specify "none" instead of a path, you	disable	the build
	   cache for this particular rule.  This can be	useful to avoid
	   wasting disk	space on files that you	know aren't useful to cache,
	   either because you are very sure they will never be reused or
	   because they	are built so fast that it's not	worth caching them.

       :build_check build_check_method
		target : dependencies
		       : build_check target_newer
		     actions

	   This	tells makepp what algorithm to use to decide if	the targets
	   need	to be rebuilt.	See makepp_build_check for more	details.  This
	   overrides the effect	of the "build_check" statement or the
	   "--build-check-method" command line option, if any, for this	rule.

       :env VARIABLE ...
	   Add a dependency on the values of the named environment variables.
	   If any of them differ from the previous build, then the targets are
	   considered out of date, if the build_check method so	dictates.
	   (All	of the built-in	build check methods except for target_newer
	   respect this.)

	   VARIABLE may	be of the form "filename in PATH_VARIABLE" (in
	   quotes), in which case the targets are considered out of date if
	   the first directory from the	colon-delimited	value of PATH_VARIABLE
	   in which filename exists is different from the last build.  This
	   can be used to avoid	rebuilding the targets when PATH_VARIABLE
	   changes in an irrelevant way.

       :dispatch command ...
	   Enclose each	shell action (but not Perl actions nor Perl commands)
	   in a	"sh -c '...'" and prefix it with command, but assume that the
	   target doesn't depend on command.  This is useful if	you want to
	   send	actions	to a job queuing system, but the result	is assumed to
	   be independent of the queuing parameters, as	well as	to whether the
	   queuing system is used at all.

       :include	file_or_pattern
	   Rule	varies depending on compiler:

	       %.o : %.c
		   : include %.d : signature C
		   gcc -MD -c ...

	       %.o : %.c
		   : include %.u : signature C # IBM uses a different suffix
		   xlc -M -c ...

	       sub dependify {		   # Turn Microsoft's chatter into useful format
		   s/\$/\$\$/g;
		   s/(Note: including file: *)?(.+?)\r?\n/$1 ? "'$2' " : "'".f_output()."': "/e;
	       }
	       %.o : %.c
		   : include %.d : signature C
		   cl -showIncludes -c ... >$(stem).d
		   &sed	&dependify -o +<$(stem).d

	   Some	compilers (Intel's icc just like gcc above, or IBM's xlc) can
	   produce dependency files on the fly.	 That is, while	they compile,
	   they	write a	makefile that makepp can include.  The advantage over
	   makepp's scanner is that it is guaranteed to	be 100%	correct, where
	   we may only come close.

	   This	option harnesses that in a special way:	If the file is not
	   present, i.e. typically on the 1st build, normal scanning occurs.
	   But if the file is present, no scanning occurs (which is why	we
	   specify a smart signature above -- not scanning falls back to the
	   dumb	default	of timestamp and size).	 Instead it includes the file,
	   before executing the	rule.  After successfully executing the	rule,
	   it forgets whatever it read the first time, given that the file
	   might have been outdated.  Instead it reads the file	again, if it
	   changed, for	having up-to-date build	info.

	   WARNING: This is inherently unreliable.  The	dependency file	gets
	   produced by the very	rule for which it is a dependency.  On the
	   other hand, the compiler knows about	all it's internal sub-
	   includes, which makepp usually ignores.  This is a reliability
	   advantage only for the case where a compiler	patch fixes only the
	   sub-includes.  The price is that makepp ends	up looking at many
	   more	files, which takes time.

	   There is a catch when you remove an "#include" statement and	the
	   corresponding file: It will still be	mentioned in the dependency
	   file	from the last time, when it was	needed.	 In such a case	you
	   must	edit the dependency file to remove the dependency which	is no
	   longer fulfillable.

	   This	feature	can not	be used	with a build cache because fetching a
	   file	from there requires knowing everything about the file.	But a
	   dependency file depends on those files makepp learns	about by
	   reading it.	Such a circular	dependency is not normally possible in
	   a reliable build system.  This is an	exception because after
	   rebuilding and rereading a dependency file everything is correct
	   again.

	   If you build	in your	repositories, makepp will pick up the
	   dependency file from	the 1st	repository which contains one.	This
	   is unlike other files, where	it takes the 1st with the expected
	   signature.  This is better than for build caches, where for lack of
	   signature, it can't even find the file.

       :last_chance
	   Enable an open-ended	rule, such as

	       %.foo foo%.bar: :last_chance
		   &echo $@ -o $@
		   &cp $(outputs)

	   Because a rule such as this could generate an essentially infinite
	   number of targets, a	target of this rule will not match a
	   $(wildcard) function	or pattern rule	unless something else has
	   already instanced the rule by referencing the target	specifically.
	   Furthermore,	if "--rm-stale"	is specified, then a target left over
	   from	a previous makepp run will appear stale	if the only way	to
	   build it is via a last_chance rule that hasn't been instanced for
	   the target yet, which is a desirable	behavior because the build
	   will	fail more consistently when it erroneously relies on a
	   wildcard to match targets from a previous run.

	   The ":last_chance" option is	intended to call attention to the
	   special behavior of the rule	with respect to	matching wildcards.

       :parser parser
	   This	tells makepp how to parse the command for detecting (include)
	   files.  Usually, makepp guesses how to do this based	on the words
	   in the command itself (see makepp_scanning for details).  However,
	   if makepp guesses wrongly, you may want to explicitly indicate the
	   parser, like	this:

	       %.o: %.abc
		   : parser c_compilation
		   action here

	   This	causes makepp to perform the same parsing and scanning that it
	   does	for C/C++ build	commands, even if it doesn't recognize the
	   action as a C compilation.

	   The default parser depends on the command.  If you do not specify a
	   ":parser" option, then the first word of each command is examined.
	   For example for a compile or	link command, makepp will use the
	   "c_compilation" parser; or if the command looks like	the Gnu
	   variant, "gcc_compilation".	If no parser is	found it uses the
	   "none" parser.  For more details on this, or	if you want to write
	   your	own parser or change makepp's default parsers, see
	   makepp_scanning.

	   Note	that this applies to every command in the rule,	which may not
	   be what you want:

	       %.o: %.c	: parser c-compilation
		   @echo 'Building $(output)'
		   @funny_cc ...

	   This	will also interpret "echo" as a	compiler and deduce its
	   argument 'Building mymodule.o' as an	implicit dependency.  This
	   will	lead to	the complaint that it doesn't know how to build	such a
	   file.  In this case you would be better off with "register_parser".
	   There you find an explanation how parser can	be given either	as a
	   classname or	as a function name.

       :signature signature_method
	       target :	dependencies
		      :	signature md5
		   actions

	   This	tells makepp what algorithm to use to determine	if the
	   dependencies	have changed.  See makepp_signatures for more details.
	   Signature methods which are included	with the makepp	distribution
	   are are "plain", "md5", "C" or "c_compilation_md5", and
	   "shared_object".  This overrides any	signature method specified
	   with	the "-m" or "--signature-method" command line options, or with
	   the "signature" statement.

   Special characters
       Makepp can support filenames that have special characters in them like
       a colon or a space.  Suppose, for example, you want to create a file
       called "a:thing"	from the file "b:thing".  You can't write the rule
       this way:

	   a:thing : b:thing	   # This is a syntax error
	       &cat $(input) -o	$(output)

       because makepp won't know which colons separate targets from
       dependencies and	which are part of the filenames.  Instead, simply
       enclose the name	in quotes, like	this:

	   "a:thing" : "b:thing"
	       &cat $(input) -o	$(output)

       Now the rule is unambiguous.

       Makepp's	quoting	syntax is quite	similar	to the shell's.	 You can, for
       example,	use single quotes instead of double quotes, or you can escape
       special characters with a backslash:

	   a\:thing : 'b:thing'
	       &cat $(input) -o	$(output)

       Suppose,	for example, that your filename	is "'"!;\$".  Now why you'd
       want such a filename I don't know, but here are several ways you	could
       specify it to makepp (and the shell):

	   \''"!;\$$'
	   "'\"!;\\$$"

       Pay attention as	to when	makepp strips quotes and when the shell	does.
       Makepp looks at quotes only in the following cases:

       o   in the "ifeq" family	of tests

       o   before and after the	rule colon

       o   in a	makepp builtin command

       o   in a	function that pertains to files

       Unlike the shell, makepp	doesn't	expand quotes while assigning them to
       a variable.  Thus the following rules are identical:

	   FILE	= 'name	with spaces'
	   x :=	$(print	$(FILE))       # just to check that quotes are still there
	   $(FILE):		       # quotes	around single file stripped by makepp
	       &echo hello -o$(FILE)   # quotes	around single file stripped by makepp
	       echo there >>$(FILE)    # quotes	around single file stripped by Shell
	   'name with spaces':
	       &echo hello -o'name with	spaces'
	       echo there >>'$(output)'	# quotes were stripped above, add them again

       Note that (unlike the Shell) variables beginning	with "$" are expanded
       even inside single quotes.  Dollar signs	cannot be protected by quotes
       or backslashes.	To get a literal dollar	sign, use a double dollar
       sign, e.g.,

	   $(phony all):
	       @&echo This is a	dollar sign: $$
	       @for val	in a b c d; do echo $$val; done

       Generally, you should be	able to	deal with just about any special
       character by quoting it in some way.  This includes spaces, control
       characters, etc.	 However, be aware that	at present, makepp's comment
       stripping is somewhat simplistic, and any "#" characters	preceded by
       whitespace will be interpreted as comments no matter how	they are
       quoted.

       When a target or	dependency name	is put into an automatic variable like
       "$(output)", then the quotes and	any backslashes	are stripped.  This
       means that if you want to reference the filename	in the actions,	you
       will probably have to quote it again, like this:

	   "a file name	with spaces":
	       echo "Special contents" > "$@"

       If you don't put	the quotes around $@, then the shell will see the
       command

	   echo	"Special contents" > a file name with spaces

       which writes the	string "Special	contents file name with	spaces"	to the
       file called a.  This is probably	not what you want.

AUTHOR
       Gary Holt (holt-makepp@gholt.net)

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 83:
	   You can't have =items (as at	line 88) unless	the first thing	after
	   the =over is	an =item

perl v5.32.1			  2012-02-07		       MAKEPP_RULES(1)

NAME | DESCRIPTION | AUTHOR | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=makepp_rules&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help