1Makefile::Parser(3) User Contributed Perl Documentation Makefile::Parser(3)
2
6 Makefile::Parser - A simple parser for Makefiles
7
9 This document describes Makefile::Parser 0.211 released on March 16,
10 2008.
11
13 use Makefile::Parser;
14 $parser = Makefile::Parser->new;
16 # equivalent to ->parse('Makefile');
18 $parser->parse or
19 die Makefile::Parser->error;
20 # get last value assigned to the specified variable 'CC':
22 print $parser->var('CC');
23 # get all the variable names defined in the Makefile:
25 @vars = $parser->vars;
26 print join(' ', sort @vars);
27 @roots = $parser->roots; # Get all the "root targets"
29 print $roots[0]->name;
30 @tars = $parser->targets; # Get all the targets
32 $tar = join("\n", $tars[0]->commands);
33 # get the default target, say, the first target
35 # defined in Makefile:
36 $tar = $parser->target;
37 $tar = $parser->target('install');
39 # get the name of the target, say, 'install' here:
40 print $tar->name;
41 # get the dependencies for the target 'install':
43 @depends = $tar->depends;
44 # access the shell command used to build the current target.
46 @cmds = $tar->commands;
47 # parse another file using the same Parser object:
49 $parser->parse('Makefile.old') or
50 die Makefile::Parser->error;
51 # get the target who is specified by variable EXE_FILE
53 $tar = $parser->target($parser->var('EXE_FILE'));
54
56 This is a simple parser for Makefiles. At this very early stage, the
57 parser only supports a limited set of features, so it may not recognize
58 most of the advanced features provided by certain make tools like GNU
59 make. Its initial purpose is to provide basic support for another
60 module named Makefile::GraphViz, which is aimed to render the building
61 process specified by a Makefile using the amazing GraphViz library. The
62 Make module is not satisfactory for this purpose, so I decided to build
63 one of my own.
64 WARNING!!! This stuff is highly experimental and is currently at pre-
66 alpha stage, so production use is strongly discouraged. Right now it's
67 just a toy for parsing trivial makefiles.
68 IMPORTANT!!! If you're looking for something more serious for parsing
70 GNU makefiles, please see Makefile::Parser::GmakeDB instead. The
71 GmakeDB parser has passed 51% of GNU make's official test suite as of
72 this writing.
73 If you're looking for something that can parse makefiles losslessly,
75 take a look at the Makefile::DOM module which may fit your needs.
76 SYNTAX SUPPORTED
78 The current parser implementation has been trying to support a common
79 feature set of both MS NMAKE and GNU make. In the future, different
80 formats of Makefiles will be handled by individual subclasses such as
81 Makefile::Parser::Gmake.
82 Variable Definition
84 MIN_T_FILES = $(PAT_COVER_FILES) t\optest.t t\my_perl.exe.t t\types.cod.t \
85 t\catln.t t\exe2hex.t t\hex2bin.t t\bin2hex.t t\bin2asm.t t\ndisasmi.t \
86 t\Idu.t t\pat_tree.t t\state_mac.t t\Idu-Util.t t\cidu.t \
87 t\opname.t t\error.t t\operand.t t\01disasm.t t\02disasm.t t\03disasm.t \
88 t\disasm_cover.t t\ndisasm.t
89 T_FILES = t\main.cod.t t\bin2hex.exe.t t\hex2bin.exe.t $(MIN_T_FILES)
90 DIRFILESEP = ^\
91 "Simply expanded" variables' definition sytax in GUN make is also
93 supported:
94 FOO := blah blah blah
96 which is considered invalid in Win32 NMake. "Recursively expanded"
98 variables are currently treated as "simply expanded" variables.
99 Variable redefinition can be handled as well:
101 CC = cl
103 %.obj : %.c
105 $(CC) /nologo /c $<
106 CC = gcc
108 %.o : %.c
110 $(CC) -c $<
111 Variable expansion sytax
113 ${abc}
115 is accepted, whereas Win32 NMAKE will complain about it.
117 Currently, environment variables defined in the command-line are
119 not imported.
120 I have no idea what default value should be assigned to built-in
122 variables like $(MAKE) and $(CC). Currently they will be left
123 untouched if they're not set explicitly in the Makefile.
124 Due to the current implementation, expansion of unrecognized built-
126 in varaibles and variables not previously defined by Makefile will
127 NOT be performed. This behavior is different from any practial make
128 tools, but is reasonable at this early stage of this parser.
129 Explicit Rules
131 $(CIDU_DLL) : C\idu.obj C\idu.def
132 link /dll /nologo /debug /out:$@ /def:C\idu.def C\idu.obj
133 $(CIDU_LIB) : $(CIDU_DLL)
135 C\idu.obj : C\idu.c C\idu.h
137 cd C
138 cl /nologo /c /I . idu.c
139 cd ..
140 smoke : all pat_cover t\pat_cover.t \
142 t/pat_cover.ast.ast
143 perl util\run-smoke.pl . smoke.html
144 perl txt2html.pl t\*.t t\*.ast
145 clean:
147 copy t\pat_cover.ast.ast.html ..\ /Y
148 $(RM_F) encoding.html encoding.pod state_mac.xml encoding.ast \
149 pat_tree.ast state_mac.ast \
150 main.cod pat_cover.pod pat_cover.html types.cod \
151 hex2bin.exe hex2bin.obj
152 Specital variable $@ will be expanded using its value in the
154 context.
155 Implicit Rules
157 Pattern Rules
158 %.obj : %.asm
159 masm /t $<;
160 %.exe : %.obj
162 link /BATCH /NOLOGO $<;
163 The special varaibles $< and $* will be expanded according to
165 the context.
166 Old-Fashioned Suffix Rules
168 Currently only double-suffix rules are supported:
169 .SUFFIXES: .obj .asm .exe
171 .asm.obj :
173 masm /t $<
174 .obj.exe :
176 link /nologo $<
177 At this moment, .SUFFIXES is a no-op. So any suffix-like things
179 will be treated as suffixes, excluding the following example:
180 .c.o: foo.h
182 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $<
183 In suffix rules, no prerequisites are allowed according to most
185 make tools.
186 Substitution References
188 objects = foo.o bar.o baz.o
189 sources = $(objects:.o=.c) # foo.c bar.c baz.c
190 Functions
192 Currently the following GNU make makefile builtin functions are
193 supported:
194 " $(subst from,to,text) "
196 " $(patsubst pattern,replacement,text) "
197 " $(strip string) "
198 " $(findstring find,text) "
199 " $(filter pattern...,text) "
200 " $(filter-out pattern...,text) "
201 " $(sort list) "
202 " $(word n,text) "
203 " $(words text) "
204 " $(wordlist s,e,text) "
205 " $(firstword names...) "
206 " $(lastword names...) "
207 " $(dir names...) "
208 " $(notdir names...) "
209 " $(suffix names...) "
210 " $(basename names...) "
211 " $(addsuffix suffix,names...) "
212 " $(addprefix prefix,names...) "
213 " $(join list1,list2) "
214 " $(wildcard pattern...) "
215 " $(realpath names...) "
216 " $(abspath names...) "
217 " $(if condition,then-part[,else-part]) "
218 " $(or condition1[,condition2[,condition3...]]) "
219 " $(and condition1[,condition2[,condition3...]]) "
220 " $(foreach var,list,text) "
221 " $(error argument...) "
222 " $(warning argument...) "
223 " $(info argument...) "
224 " $(shell cmd...) "
225 Please consult the GNU make Manual for details and also take a look
227 at the following file for some use cases:
228 <http://svn.openfoundry.org/mdom/branches/gmake/t/gmake/sanity/func-refs.t>
230 Commands after ';'
232 all : ; echo 'hello, world!'
233 Specital variable $@ will be expanded using its value in the
235 context.
236 For the list of features which will be added very soon, take a look at
238 the "TODO" section.
239
241 This class provides the main interface to the Makefile parser.
242 METHODS
244 "$obj = Makefile::Parser->new()"
245 It's the constructor for the Parser class. You may provide the path
246 of your Makefile as the argument which . It is worth mentioning
247 that the constructor will not call ->parse method internally, so
248 please remember calling ->parse after you construct the parser
249 object.
250 "$obj->parse()"
252 "$obj->parse($Makefile_name)"
253 "$obj->parse($Makefile_name, { var => value, ... })"
254 This method parse the specified Makefile (default to 'Makefile').
255 When an error occurs during the parsing procedure, "parse" will
257 return undef. Otherwise, a reference to Parser object itself is
258 returned. It is recommended to check the return value every time
259 you call this method. The detailed error info can be obtained by
260 calling the "error" method.
261 You can also pass a hash reference to specify initial variables and
263 their values. Note that these variables are treated as "defaults"
264 so assignments in the makefile have higher priority.
265 "$obj->error()"
267 It returns the error info set by the most recent failing operation,
268 such as a parsing failure.
269 "$obj->var($variable_name)"
271 The var method returns the value of the given variable. Since the
272 value of variables can be reset multiple times in the Makefile, so
273 what you get is always the last value set to the variable. It's
274 worth noting that variable reassignment can be handled
275 appropriately during parsing since the whole parsing process is a
276 one-pass operation compared to the multiple-pass strategy used by
277 the CPAN module Make.
278 "@vars = $obj->vars"
280 This will return all the variables defined in the Makefile. The
281 order may be quite different from the order they appear in the
282 Makefile.
283 "$obj->target($target_name)"
285 This method returns a Makefile::Target object with the name
286 specified. It will returns undef if the rules for the given target
287 is not described in the Makefile. It is worth noting that only
288 targets with a definition body will be considered as a target here.
289 When $target_name is omitted, this method will return the default
291 target, say, the first target defined in Makefile, to the user.
292 This can be handy if you try to build a make tool on top of this
293 module.
294 It is important not to send something like "$(MY_LIB)" as the
296 target name. Only raw values are acceptable. If you really want to
297 do something like this, please use the following code:
298 my $tar = $parser->target($parser->var('MY_LIB'));
300 but this code will break if you have reassigned values to variable
302 MY_LIB in your Makefile.
303 "@targets = $obj->targets()"
305 This returns all the targets in Makefile. The order can be
306 completely different from the order they appear in Makefile. So the
307 following code will not work if you want to get the default target
308 (the first target):
309 @tars = $parser->targets;
311 print $tars[0];
312 Please use the following syntax instead:
314 print $parser->target;
316 The type of the returned list is an array of Makefile::Target
318 objects.
319 "@roots = $obj->roots()"
321 The "roots" method returns the "root targets" in Makefile. The
322 targets which there're no other targets depends on are called the
323 root targets. For example, install, uninstall, and veryclean are
324 all root targets in the Makefile generated by the
325 ExtUtils::MakeMaker module. On the other hand, clean and test are
326 not, which may be somewhat counterintuitive. That's because
327 there're some other targets depend on clean, test, or both.
328 The type of the returned list is an array of Makefile::Target
330 objects.
331 PACKAGE VARIABLES
333 $Makefile::Parser::Strict
334 When this variable is set to true, the parser will sense syntax
335 errors and semantic errors in the Makefile. Default off.
336 $Makefile::Parser::Debug
338 When this variable is set to true, the parser will enter Debug
339 Mode. This variable is not supposed to be used directly by the
340 user.
341
343 post_parse
344 Iterate the Makefile AST to apply implicit rules in the following
345 form:
346 %.o : %.c
348 $(CC) -c $<
349 solve_imp($depend)
351 Solve implicit rules as many as possible using one target name that
352 appears in other target's dependency list.
353
355 This class overloads the "" operator so its instances can be
356 automatically converted to strings using their names.
357 METHODS
359 "$class->new($target_name, $colon_type)"
360 This is the constructor for class Makefile::Target. The first
361 argument is the target name which can't be a Makefile variable, the
362 second one is a single colon or a double colon which is used by the
363 rule definition in Makefile.
364 This method is usually called internally by the Makefile::Parser
366 class. It doesn't make much sense to me if the user has a need to
367 call it manually.
368 "$obj->name()"
370 It will return the name of the current Target object.
371 "@prereqs = $obj->prereqs()"
373 You can get the list of prerequisites (or dependencies) for the
374 current target. If no dependency is specified in the Makefile for
375 the target, an empty list will be returned.
376 "@prereqs = $obj->depends()"
378 Alias to the "prereqs" method. This method is only preserved for
379 the sake of backward-compatibility. Please use "prereqs" instead.
380 "$obj->commands()"
382 This method returns a list of shell commands used to build the
383 current target. If no shell commands is given in the Makefile, an
384 empty array will be returned.
385
387 For the very latest version of this module, check out the source from
388 <http://svn.openfoundry.org/makefileparser/branches/gmake-db>. There is
389 anonymous access to all.
390
392 The following syntax will be implemented soon:
393 · Add support the remaining GNU make makefile builtin functions:
395 "origin", "value", "call", "flavor", and "eval".
397 · Add support for recursively-expanded variables.
399 · Implement rules with multiple targets
401 · Serious support for "Recursively expanded" variables in GUN make
403 · Comments that span multiple lines via trailing backslash
405 · Lines that don't contain just comments
407 · Literal "#" escaped by a leading backslash
409 · The include directive
411 · Look for 'GNUmakefile' and 'makefile' automatically
413 · MAKEFILES Variable
415 · MAKEFILE_LIST Variable
417 · .VARIABLES Variable
419
421 Please feel free to report bugs or send your wish-list to
422 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Makefile-Parser>.
423
425 plmake, makesimple, Makefile::Parser::GmakeDB, Makefile::GraphViz,
426 Make.
427
429 Agent Zhang, "<agentzh@yahoo.cn>"
430
432 Copyright (c) 2005-2008 by Agent Zhang (agentzh).
433 This library is free software; you can redistribute it and/or modify it
435 under the same terms as Perl itself.
436perl v5.10.1 2008-03-16 Makefile::Parser(3)