NAME

DESCRIPTION

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:

-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"

&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"

    &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:

&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"

    &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:

    &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

    # 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"

&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"

&mkdir [option ...] directory ...

Create the directories.

Standard options: "-A, --args-file, --arguments-file=filename, -f, --force, -v, --verbose"

&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"

&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"

    $(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"

&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"

&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"

    &uniq --compare='lc( $$a ) eq lc $$b' $(inputs) -o $(output)

tr

Not built in, but &sed can handle this.

AUTHOR