MAKEPP_BUILTINS(1) Makepp MAKEPP_BUILTINS(1)NAMEmakepp_builtins-- Builtin commands in makepp
DESCRIPTION
A: awk, C: &cat,
chgrp,
&chmod,
chown,
&cp,
&cut, D: date, E: &echo,
&expr, F: false,
fmt, G: &grep, H: head, I: &install, L: &ln, M: m4,
&mkdir,
&mv, P: &perl,
&preprocess,
&printf, R: &rm,
rmdir, S: &sed,
&sort, T: tail,
&template,
&touch,
tr, U: &uninstall,
&uniq, Y: &yes
There is a special Shell-like possibility to call built-in commands in
a rule. The only metacharacters recognized are comment signs,
backslashes, single and double quotes. Only one command may be given
per line, and I/O redirection is not available (see "-i" and "-o" below
instead).
These commands start with "&", which is the function character in Perl
and not a valid first character in Shell. If no builtin command of
that name can be found, this is also the syntax for calling an external
script within the Perl instance performing the rule. See "run".
These commands, as well as your self defined ones and Perl scripts can
also be called as a make function, returning the standard output. The
newlines are converted to spaces, except when evaluated within a
"define" statement.
FIRST-WORDS ;= $(&cut -d' ' -f0 $(FILES))
When these commands are not indented as rule actions, they get
performed while reading the makefile. You can also access these
commands stand-alone, e.g. if you need some features not available in
the Unix counterpart, via the makeppbuiltin command.
These commands are mostly based on the GNU variant. But many options
(like --backup, --interactive or --recursive) don't really make sense
in a makefile. So, even though they'd be easy to implement in Perl,
they have been left out. Also many Unix commands offer a variety of
options that cover fairly complicated cases (e.g. sort field
specifications) while still being inherently limited. Allowing access
to Perl, which is present anyway, gives much more power here.
Lists of filenames may be empty, making it safe to call these commands
with an unchecked list. Options in their short form may be glued
together as in "-ab" instead of "-a -b". In the long form arguments
may be given either glued on with an "=" sign or separately. In the
short form they may be given either glued on directly or separately. A
few options are common to several builtins, though the short form is
sometimes hidden by a command's own option (as in "&cut -f"):
-A filename
--args-file=filename
--arguments-file=filename
Read the file and parse it as possibly quoted whitespace- and/or
newline-separated options.
-f
--force
Force the creation of the file(s) intended by the parameters, even
if a different kind of file or empty directory of that name already
exists. This must precede the "-o, --output=filename" option if it
is to have any effect on that.
-i shellcommand
--inpipe=shellcommand
Start the Shell command(s) and pipe the output into the builtin.
There may optionally be a trailing "|" character, to indicate this
is a pipe. With this option no filenames need to be given. But if
you want to perform the builtin on both files and the pipe output,
you must use "-" as a filename for the pipe output. This option is
necessary because there is no redirection syntax.
-I
--infail
If an "--inpipe" Shell command fails, that also causes the current
builtin to fail.
-o filename
--output=filename
Write the output to this file, rather than stdout. Filename may
have any of these forms:
filename
>filename
Simply write to file.
>>filename
Append to (not necessarily) existing file.
+<filename
Also open the file for input, allowing inplace editing. With
this option variant no input filenames need to be given. But
if you want to perform the builtin on more files, you must use
"-" as an input filename for this one. In fact the output gets
written to a temporary file which gets moved to filename at the
end.
|shellcommand
Pipe the builtin's output to the Shell command(s).
This option is necessary because there is no redirection syntax.
-O
--outfail
If an "--output" Shell command fails, that also causes the current
builtin to fail.
-r number
--record-size=number
Locally sets $/ for the current builtin. This splits input into
records of length number rather than line by line. If number is
zero, each input file as a whole is one record.
-s string
--separator=string
Locally sets $/ for the current builtin. This splits input on
string rather than line by line.
-S
--synclines
Generate "#line ""NO"" """FILE"""" and "#line ""NO" lines,
understood by many C-like languages.
-v
--verbose
Document the changes to the file system. This must precede other
options if it is to document their effect. If you pass this option
to makepp itself, it is as if you had given it for every single
builtin command.
There are two motivations for having builtin commands in makepp. The
first is to offer a set of utilities, which, unlike Shell commands, are
guaranteed to work the same everywhere, like "&echo -n" or "&mkdir -p",
and saving you the hassle of finding the path to &install and figuring
out its wildly varying options. In a compilation environment, it's
useful to have the "--synclines" option, which normally only "m4"
provides, on all filters.
The other is a question of efficiency. In general costly fork/execs
should be avoided where reasonably possible. On Unix emulations like
Cygwin or BS2000/Posix, this becomes a noticeable win. But, even on
Linux, when the makepp test suite was converted from external commands
to builtins, there was an overall saving of 3% user CPU usage and 15%
system CPU usage. (The tests are of course heavy on primitive actions
and hardly call the compiler.)
Consistency is also an issue, though we're not going to reform Unix.
Normally commands have various nuances of regular expressions. And
many invent sort of languages, each different of course, for doing
something (e.g. "expr", "sed" ...), or complex options for specifying
fields, delimiters, columns (e.g. "cut", "sort" ...).
Here instead, anything fancy simply gets handled by Perl, giving both
consistency across all commands, and far more power than a whole bunch
of options. Better yet, any Perlcode these commands run for you, gets
run in the package of the Makefile. So, rather than stuff Perl code
into the rule action, you can define functions and variables and use
them within the commands:
sub my_filter {
# Return true iff $_ is desirable
}
%.out: %.in Makeppfile
&grep &my_filter $(input) -o $(output)
If you use Perl functions or variables in your commands, makepp does
not recognize this as a dependency. It is generally safer to tell
makepp everything, so rules which use Perl elements should depend on
the makefile or module providing those elements, as shown in the above
example.
On the other hand ignorance may be desirable if you have a program that
mixes programmatic and configuration aspects in one file. An example
would be a WSDL file containing both a web service interface definition
and an IP address. You could preprocess this file with the &template
command to patch in the configuration, but not let makepp notice.
awk Not built in, but &sed is comparable.
&cat [option ...] filename ...
Concatenates all the files into a single one.
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -i, --inpipe=shellcommand, -I, --infail, -o,
--output=filename, -O, --outfail, -S, --synclines, -v, --verbose"
chgrp
chown
These commands are mostly not portable! They will either quietly
do nothing or fail, depending on the system. Generally only root
may perform these operations, which is why they are only available
through the &install command.
&chmod [option ...] mode filename ...
Sets mode for all given files. Mode must be an octal string.
Standard options: "-A, --args-file, --arguments-file=filename, -v,
--verbose"
&cp [option ...] sourcefile destfile
&cp [option ...] sourcefile
&cp [option ...] sourcefile ... destdir
Copy sourcefile to destfile, one sourcefile to current directory or
multiple sourcefiles to destdir with the same name.
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -v, --verbose"
-l
--link
Try to link the files. If that fails, try symbolic link, if
that is also requested, else copy.
-s
--symbolic
--symbolic-link
--symlink
Try to symbolically link the files. If that fails, copy.
See the note under &ln.
&cut [option ...] filename ...
Print selected parts of lines from each file or selected lines,
counting across all files. The output is separated by the
delimiter which defaults to TAB for fields and empty string for
characters.
Standard options: "-A, --args-file, --arguments-file=filename,
--force, -i, --inpipe=shellcommand, -I, --infail, -o,
--output=filename, -O, --outfail, -r, --record-size=number,
--separator=string, -S, --synclines, -v, --verbose"
-c list
--characters=list
Print all the characters specified by list. List may be any
Perl expression returning a list of integers. The integers can
be either positive, starting at zero to count from the
beginning, or negative to count from the end. Unlike Unix
"cut", the order you request is respected.
Unlike in Perl's slice operator where a ".." range must be
either positive or negative, &cut allows starting with a
positive and ending with a negative. But this is only
available if your expression consists only of numbers, commas
and "..". E.g. "1..-2" means everything but the first (0) and
the last (-1).
The list expression can look at the whole line in $_. Changes
to that will be ignored, however, because when this expression
is evaluated the line has already been split to Perl's
autosplit variable @::F. The numbers you return are in fact
indices to that list.
-d string
--delimiter=string
Set a new delimiter for input fields and output. Unlike Unix
"cut", this may have any length.
-E
--noescape
Treat "\" as normal literals for "-p, --printf=format".
-f list
--fields=list
Print all the groups specified by list. List is as described
under "-c, --characters=list". Note that this hides the
standard option "-f" which must be given as "--force".
-l list
--lines=list
Print all the lines specified by list. List is as described
under "-c, --characters=list" with one major difference: The
first line has number 1, there is no line 0. This is
definitely inefficient for big files, if you have a mixed
positive to negative range in your list, as it reads everything
to memory. Otherwise Perl could optimize this, but I don't
know if it does.
-m
--matching
Print only matching lines, i.e. ones which have enough
characters or fields. This implies "--only-delimited", which
is why you will miss single-field lines with "--fields=0".
-p format
--printf=format
Apply format (with \escapes) to all fields or characters.
-s
--only-delimited
Print only lines containing delimiters.
&cut -c 10-20,-5,25- $(input)
&cut -c 'grep $$_ % 3, 0..99' $(input) # 1st 100 columns not multiple of 3
&cut -d: --fields 0,4 --printf='%10s is %s\n' /etc/passwd
date
Not built in, but either of these partially does the same thing:
&expr localtime
&expr gmtime
&echo [option ...] string ...
&printf [option ...] format argument ...
&yes [option ...] string ...
Writes all strings to stdout or the given outfile. Both &echo and
&yes add a newline at the end. The strings, or for &printf the
format, may contain "\" escapes, as they are known from C or modern
Unix or Shell "echo". They are however as in Perl double-quotes,
which means some differences, like that a single trailing "\" is
not allowed. Perl has a few more interesting escapes, but the ones
you might expect to do something different are:
\cA Is a control character ^A.
\u Upcases the following letter.
\U Upcases the rest, or up to the next "\L" if found.
\xHH, \x{HHHH}
Is the character value of the given Hex code. Note that
numeric codes are not portable to EBCDIC platforms!
Unlike Unix "yes", &yes is exactly like &echo, except that it
repeats the output for as long as it can, typically until an
"--output '| command'" terminates. And, if &yes has no arguments,
it defaults to "y".
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -o, --output=filename, -O, --outfail, -v, --verbose"
-E
--noescape
Treat "\" as normal literals.
-n
--nonewline
Do not add a newline after the last string. (Not understood by
&printf.)
&expr [option ...] perlcode ...
Print the scalar value of perlcode, which may be written as one or
several arguments. Note that builtin commands are not parsed by
the Shell, so "*", "(" or ">" are not special. But string quotes
are parsed by makepp, so Perl strings must be quoted twice, unless
you want to use barewords. If the value is false, this fails.
Note that -- unlike in Unix "expr" -- Perl's index function starts
at 0 (false) and returns -1 (true) for failure.
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -o, --output=filename, -O, --outfail, -v, --verbose"
-n
--nonewline
Do not add a newline after the output.
&expr ($(VAR) - 3) * 2 < 1 && -1 || 1
&expr "$(VAR) - 3 * 2 < 1 ? 'joy' : 'sorrow'" -o $(output)
-&expr $(VAR) - 3 * 2 -o >>$(output)
false
Not very constructive and thus not built in, but &expr with no
argument or 0 is comparable.
fmt Not built in, but mentioned here since Perl provides a related
functionality. However I had problems using the "format"
declaration in a makefile. What does work is the underlying
"formline" function. E.g. to transform a csv file consisting of
names and prices to a tabular format:
sub csv2txt {
formline "\@<<<<<<<<<<<<<<< ^###########.##\n", split ',';
$_ = $^A;
$^A = '';
}
%.txt: %.csv
&sed &csv2txt $(input) -o $(output)
&grep [option ...] perlcode filename ...
&perl [option ...] perlcode filename ...
&sed [option ...] perlcode filename ...
All the files get read line by line (unless you gave a
"--separator" option), and perlcode gets evaluated for each line,
before it gets printed. &sed is similar to "perl -pe", while &grep
only outputs those lines for which perlcode returns a true value.
&perl is similar to "perl -ne", only outputting whatever you
explicitly print in the perlcode. The line content is available in
$_, which may be modified.
Of these three, only &grep will fail if it outputs nothing. Note
that there is no ignore-case option, since you would do that with
"/regexp/i".
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -i, --inpipe=shellcommand, -I, --infail, -o,
--output=filename, -O, --outfail, -r, --record-size=number, -s,
--separator=string, -S, --synclines, --verbose"
The option "--synclines" only makes sence with &perl if you use
&Mpp::Cmds::print to output $_. Only &grep has extra options:
-c
--count
Suppress normal output; instead print a count of matching
lines. With the "-v, --invert-match" option (see below), count
non-matching lines.
-l
--list
--files-with-matches
Output only the name of those files with matches. When this is
combined with "-v, --invert-match", output the name of files
with lines that don't match (a bit absurdly but compatible with
Unix -vl). When this is combined with a doubled "-vv", output
the name of files with no matches.
-v
--vice-versa
--revert-match
--invert-match
Invert the sense of matching, to select non-matching lines.
Note that this hides the standard option "-v" which must be
given as "--verbose".
-w filename
--waste-file=filename
An optional waste basket for collecting the rejected lines.
This is not only for debugging your selection code, but also
for splitting your input in two. As with the normal output,
you may modify $_ before returning false.
&sed s/foo/bar/ f1 f2 f3 -o outfile # like sed s/foo/bar/ f1 f2 f3 >outfile
&sed '$$_ = uc' f1 f2 f3 -o outfile # like tr '[:lower:]' '[:upper:]' f1 f2 f3
&grep '$$. % 3' f1 f2 f3 -o outfile # eliminate every 3rd line
&grep -c /match/i f1 f2 f3 # count the lines matching 'match' to STDOUT
Without pushing you to mass generate accessors, here's how you
could do it by simply putting a comment of RO or RW between each
type and desired variable name, all on one line. The generated
getter and optionally setter methods go into the next found public
or protected section:
# Create get and maybe set method from "type /* R[OW] */ member;".
sub cxx_accessors {
$acc ||= ''; # Candidate for 5.10.0 state
if( m!^\s*(.+?)\s*/\*\s*R([OW])\s*\*/\s*(.+?)\s*;! ) {
$acc .= "#line $.\n"; # Tell C++ where this came from
$acc .= "void set\u$3( const $1 &__tmp ) { $3 = __tmp; }"
if $2 eq 'W';
$acc .= "const $1 &get\u$3() const { return $3; }\n";
} elsif( /^\s*(?:public|protected)\s*:/ ) {
$_ .= $acc;
$acc = '';
}
}
%.cc: %.cc.in # Use &sed for I/O handling
&sed --sync-lines &cxx_accessors $(input) -o $(output)
head
tail
These are not provided, but you can achieve the same result with
&grep or "&cut --lines":
&grep 1..10 file # first ten lines
&grep 10..eof file # all lines from tenth onwards
&cut --lines -10..-1 file # last ten lines
Note that 1..10 in &grep is Perl's line number flip-flop operator,
which annoyingly starts at 1. Don't start at 0, or the flip-flop
will never become true.
&install [option ...] sourcefile destfile
&install [option ...] sourcefile ... destdir
&install --directory [option ...] directory ...
Move or rename sourcefile to destfile, or multiple sourcefiles to
destdir with the same name. This is the preferred way of
transferring build results to their final installation locations.
Every file system modification performed by &install gets logged to
the end of the file pointed to by the environment variable
$INSTALL_LOG, or, if that is not set but we are under a directory
with a RootMakeppfile(.mk), to a file of .install_log in that
directory, or else to that file in the current directory. You may
want to delete the logfile before a series of &install invocations.
Standard options: "-A, --args-file, --arguments-file=filename, -v,
--verbose"
-c
--copy
Copy the files rather than moving them. This is preferable, as
it doesn't force makepp to rebuild the file next time. But it
is not the default, for compatibility with other install
programs.
-d
--directory
In the third form form of this command create all the given
directories and any necessary parent directories.
-g group
--group=group
Change the group ownership of the destination files. The group
may be given by name or numerically.
-l
--link
Try to link the files. If that fails, copy.
--log=filename
--logfile=filename
Use filename instead of normal logfile.
-m mode
--mode=mode
Sets mode for all destination files or directories. Mode must
be an octal string.
-o owner
--owner=owner
Change the ownership of the destination files. The owner may
be given by name or numerically.
-r
--resolve
--resolve-symbolic
--resolve-symbolic-link
--resolve-symlink
-S
--symbolic
--symbolic-link
--symlink
Creates symbolic links instead of moving. These options are
passed to &ln and are described there.
-s
--strip
Calls the "strip" utility, which must be in the $PATH, on the
destination files.
&ln [option ...] sourcefile destfile
&ln [option ...] sourcefile
&ln [option ...] sourcefile ... destdir
Link sourcefile to destfile, one sourcefile to current directory or
multiple sourcefiles to destdir with the same name.
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -v, --verbose"
-r
--resolve
--resolve-symbolic
--resolve-symbolic-link
--resolve-symlink
This is what you always wanted "ln -s" to do. Create symbolic
rather than hard links, not to the strings specified, but
really to the given files.
-s
--symbolic
--symbolic-link
--symlink
Create symbolic rather than hard links.
Note: On various file or operating systems, this operation is not
supported. Or it is, e.g. by Cygwin, but not understood by native
Windows compilers, if you use one. For a makefile you can't
change, to get at least some sort of result, &ln and "&cp -l -s"
can copy the files for you instead (not directories though). To
achieve this, you need to export the following variable before
calling makepp:
export MAKEPP_LN_CP=1
&ln --resolve or --symbolic will copy the files instead of
creating a symbolic link.
export MAKEPP_LN_CP=2
&ln will copy the files instead of creating a hard link.
export MAKEPP_LN_CP=3
All invocations of &ln will copy the files instead of creating
either kind of link.
&mkdir [option ...] directory ...
Create the directories.
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -v, --verbose"
-m mode
--mode=mode
Sets mode for all created directories, irrespective of the
umask. Mode must be an octal string.
-p
--parent
Also create any necessary parent directories. Ignore directory
creation failure due to the directory already existing (even if
it was created concurrently by another process).
&mv [option ...] sourcefile destfile
&mv [option ...] sourcefile
&mv [option ...] sourcefile ... destdir
Move or rename sourcefile to destfile, one sourcefile to current
directory or multiple sourcefiles to destdir with the same name.
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -v, --verbose"
m4 Not built in, but &preprocess is, and &template is almost as
powerful.
&preprocess [option ...] variable=definition ... filename ...
This preprocesses the files exactly the same way makepp does for
makefiles. This is more powerful than &template but syntactically
not suited to files with lots of "$"-signs, like Makefiles or
scripts.
Conditional statements, as well as the statements
"include"/"_include" (which here neither build the file nor search
upwards), "perl"/"makeperl"/"perl_begin" or "sub"/"makesub", or any
statements you define within the file, are processed. Empty and
comment lines are eliminated.
But, instead of learning build rules, it will output all remaining
lines after "$(...)" expression expansion. To prevent statement
from being recognized as such, you can precede them with an empty
expression "$()". The same applies to lines you want to stay empty
or which shall retain a leading comment sign. Likewise, if a
trailing backslash is not to join a line with the next, put "$()"
after it.
A normal line gets output as is.
A line with $(MAKEEXPRESSIONS) gets expanded and output.
ifdef WANTTHIS # does not get output whether defined or not
might not get output
endif
include some files
_include some files that might not exist # or -include
$()include empty expression prevents keyword from being recognized.
# Comment lines and empty lines get swallowed.
$()# Unless they get masked with an empty expression.
$()
Empty expression prevents \$()
backslash continuation from being recognized.
might give:
A normal line gets output as is.
A line with whatever gets expanded and output.
lots of slurped in content here...
include empty expression prevents keyword from being recognized.
# Unless they get masked with an empty expression.
Empty expression prevents \
backslash continuation from being recognized.
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -o, --output=filename, -O, --outfail, -S, --synclines, -v,
--verbose"
-a
--assignment
Also treat assignments within the files as makepp would. Alas
such lines can't be masked with an empty "$()", because it is
legal to construct variable names with expressions. This
additionally recognizes the statements "define",
"export"/"unexport" and "override" (these can be masked with
"$()").
-h \\%hash
--hashref=\\%hash
This allows preallocation of the variable values, including
long ones not easily passed in a command. The passed
expression may be any Perl code that returns a hash reference.
This is merged with any other variables passed to the command,
including from another "--hashref" option.
&rm [option ...] filename ...
Delete files if you have directory write permission. This is what
Unix "rm -f" would delete, since it has a special protection for
interactive use not needed in a Makefile.
Standard options: "-A, --args-file, --arguments-file=filename, -v,
--verbose"
-f
--force
This prevents complaining about inexistent files. That is a
side effect this option has in Unix, and the only one that
makes sense here.
-m
--metainfo
In addition to the given files, this also deletes the meta
information makepp stores about them in the .makepp directory.
Thus makepp forgets all it ever knew about the given files. If
the .makepp directory becomes empty after this, it too is
deleted.
This will also delete given directories, but only if they are
empty. To facilitate this, it will delete directories last, in the
order of descending depth. So you can use "**" expressions to
delete whole hierarchies. Here's an example to be found in many
top level make files. Note that there is a "makeppclean" utility
that can do this more efficiently.
$(phony cleanold):
&rm -fm $(only-stale **/*)
$(phony clean): cleanold
&rm -f $(wildcard **/*.[ao])
$(phony distclean): clean
&rm -fm $(only-targets **/*)
rmdir
Not built in, but &rm can handle this.
&sort [option ...] filename ...
Sorts all files together in lexicographic order. This is
inefficient for rather big files, because it happens completely in
memory. It will fail if the combined size of all files exceeds the
memory you are entitled to.
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -i, --inpipe=shellcommand, -I, --infail, -o,
--output=filename, -O, --outfail, --record-size=number, -s,
--separator=string, -v, --verbose"
-c perlcode
--compare=perlcode
perlcode represents a Perl sort block, with the two sorting
candidates in $a and $b.
-n
--numeric
--numeric-sort
This sorts sorts numerically on the beginnings of records.
Leading whitespace is skipped. You can use "--transform" and
"--detransform" if the numbers are not at the beginning.
-r
--reverse
Output the results in the reverse order. Note that this hides
the standard option "-r" which must be given as
"--record-size".
-t perlcode
--transform=perlcode
-d perlcode
--detransform=perlcode
If you have a complex code, sorting gets more and more
expensive in proportion to the number of records n, because the
code gets called O(n log(n)) times. To avoid that, you can
allow Perl to concentrate on sorting, by first modifying the
strings, such that complicated search criteria extraction
happens once per record, and modifying them back, once they are
sorted.
If these options are given, the "--transform" perlcode gets
mapped to the records in $_ one after another, and can modify
them. After sorting, the "--detransform" perlcode gets mapped
to the modified records in $_ one after another, and can modify
them back. You will usually use neither or both of these
options, unless you want to output modified lines.
Turning the strings into a structure of extracted sort
criteria, which your "--compare" perlcode can pick up is known
as the Schwartzian Transform (ST). Packing everything into the
string itself, so that no "--compare" perlcode is needed,
allowing the whole sorting to happen without performing
expensive Perl code, is known as the Guttmann-Rosler Transform
(GRT). You can find tips by searching for those names on the
web.
# Expensively sort numerical expressions by value ($$ protects $ from makepp expansion)
&sort --compare 'eval( $$a ) <=> eval( $$b )' $(input) -o >>$(output)
# ST for case insensitive sorting
&sort -t '$$_ = [lc, $$_]' -c '$$a->[0] cmp $$b->[0]' -d '$$_->[1]' $(input) -o >>$(output)
# GRT using modification functions defined elsewhere in the Makeppfile
&sort -t &transform -d &detransform $(input) -o >>$(output)
-u
--uniq
--unique
After sorting, eliminate duplicates. These are either
identical lines, or if the "--compare" option is given, ones
which that perlcode reports as equivalent.
&template [option ...] macro=definition ... filename ...
This is a macro preprocessor, not quite as powerful as "m4", but
covers more than is found in many makefiles. See &preprocess for a
more powerful alternative. Any normal text goes through unchanged.
It replaces all occurrences of "@macro@", "@macro(arg1,arg2...)@"
or everything between "@@macro@@", "@@macro(arg1,arg2...)@@" and
"@@" with definition. If there are args, they replace $1 through
$9 or "${number}" in definition. One level of macro nesting is
possible in that the args in parenthesis may contain plain
"@macro@" invocations, as in "@f(@x@)@", where @x@ gets expanded
before being replaced into the body of "f".
The simple "@...@" cases are single line, but may mask a trailing
newline if the closing "@" is immediately followed by a backslash.
The multiline "@@...@@" cases must also fit on one line, but the
corresponding "@@" may be on a different line. This is useful if
you have a workaround code block in an unprocessed script, which is
to get replaced with the configured code.
In addition to passing macro definitions on the command line, you
can also put "@macro=definition@" or "@macro?=definition@" into the
file. The latter only takes effect if the macro was not defined,
presumably on the command line. You can also call "@{ Perlcode }@"
or "@@{ Perlcode }@@ ... @@" in the file. The Perl variable $ARGV
contains the name of the current input file. If you call "@macro {
Perlcode }@", then you define a new macro, the body of which is a
Perl sub. The arguments, if there are any, get passed in as @_.
@m1=some definition@\
@m2=foo $1 bar@\
@middle_of_arg=iddl@\
@m1@ @m2(m@middle_of_arg@e)@
@@m2(many lines)@@
...
@@ plain text 1 + 2 = @{ 1 + 2 }@
becomes
some definition foo middle bar
foo many lines bar plain text 1 + 2 = 3
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -i, --inpipe=shellcommand, -I, --infail, -o,
--output=filename, -O, --outfail, -S, --synclines, -v, --verbose"
-h \\%hash
--hashref=\\%hash
This allows preallocation of the macro values, including long
ones not easily passed in a command. The passed expression may
be any Perl code that returns a hash reference. This is merged
with any other macros passed to the command, including from
another "--hashref" option. A hash value may also be a code
reference, in that case the function gets called, as with
"@macro { Perlcode }@" definitions.
-s /prefix/suffix/
--simple=/prefix/suffix/
This replaces "@" before and after var with prefix and suffix
respectively. The first character is the separator and need
not be a slash.
-m /prefix/suffix/afterprefix/[aftersuffix/]
--multiline=/prefix/suffix/afterprefix/[aftersuffix/]
This replaces "@@" before and after var and at the end of the
block with prefix, suffix and afterprefix respectively. If
aftersuffix is also given, the var name must get repeated
before it. The first character is the separator and need not
be a slash. E.g. an XML-ish
--simple=|<|/>| --multiline=|<|>|</|>|
-d
--defined
Replace only instances of macros which are actually defined.
&touch [option ...] filename ...
Updates the modification and access timestamps of each file to now.
If the file doesn't exist, it gets created.
Standard options: "-A, --args-file, --arguments-file=filename, -v,
--verbose"
&uninstall [option ...] [filename ...]
Uninstall files previously installed by &install. The filenames
are logfiles written by &install. If none are given, nor an
"--inpipe" option, reads the default logfile of &install.
Standard options: "-A, --args-file, --arguments-file=filename, -i,
--inpipe=shellcommand, -I, --infail, -v, --verbose"
&uniq [option ...] filename ...
Discard all but one of successive equal lines.
Standard options: "-A, --args-file, --arguments-file=filename, -f,
--force, -i, --inpipe=shellcommand, -I, --infail, -o,
--output=filename, -O, --outfail, -r, --record-size=number, -s,
--separator=string, -S, --synclines, -v, --verbose"
-c perlcode
--compare=perlcode
This Perlcode gets the previous and current lines in $a and $b
and shall return true if it considers the two lines equal.
&uniq --compare='lc( $$a ) eq lc $$b' $(inputs) -o $(output)
tr Not built in, but &sed can handle this.
AUTHOR
Daniel Pfeiffer (occitan@esperanto.org)
perl v5.20.3 2012-02-07 MAKEPP_BUILTINS(1)
