build

my $handle = build($objinfo);

Starts building the specified object. When build() returns, the object may not have been built yet; build() returns a handle (see MakeEvent.pm for details) which you can wait on if you want to wait until the build is actually done. The usual idiom is

wait_for main::build($objinfo);

If you do this, of course, you make it harder for makepp to build targets in parallel because the makepp process will not spawn any other build requests until this one is done.

When any targets are built, the global variable $n_files_changed is updated.

parse_command_line

parse_command_line(@ARGV, \%environment_hash);

Parses and executes the given command line. Loads whatever makefiles are necessary and builds the appropriate targets, or at least starts off the build. (It doesn't wait until the build is finished.) Returns a list of build handles.

The environment must be provided as a reference to a hash. Any rules which are executed have the environment set to this value before the shell is invoked.

This parser only accepts options which are valid during recursive makes or from the load_makefile command. There are other options which are handled by the mainline makepp code which are not accepted here.

parse_command_line assumes that the current directory is the proper directory for executing the command.

::log

::log KEY => {object | array of objects | string} ...
  if $log_level;

The list of available KEYs is present in makepplog. If you pass an non-key str if will later be output verbatim. The objects must have a method `name'.

This log overrides logarithm (which is not needed by makepp). Because of this, and because it is not exported, it must always be invoked as ::log.

The log format contains a few control chars, denoted here as ^A, ^B ...

The first line is special, the invocation preceded by "logversion^A" as explained at @obsolete_msg in makepplog.

A leading ^B is stripped, but tells makepplog to outdent, and a leading ^C to indent. After that a line with no ^A is considered plain text. Else it is split on the ^A`s. There must be a ^A at the line end, which allows having multine fields between ^A`s. If the resulting fields contain ^B`s they are lists of simple fields, else just one simple field.

The first field is a message key. The others work as follows. If the simple fields contain ^C`s they are ref definitions of up to 4 fields:

ref[^Cname[^Cdir-ref[^Cdir-name]]]

The refs are numbers (hex on HP/UX with 64bit pointers) and the names are to be remembered by makepplog for these numbers. If a dir-name is present, that is remembered for dir-ref, else it has been given earlier. If a dir-ref is given, that is prependended to name with a slash and remembered for ref. Else if only name is given that is remembered for ref as is. If ref is alone, it has been given earlier. Makepplog will output the remembered name for refs between quotes.

The fields may also be plain strings if they contain no known ref. Due to the required terminator, the strings may contain newlines, which will get displayed as \n. For keys that start with N_, all fields are treated as plain numbers, even if they happen to coincide with a ref.

flush_log

Flush the log file and standard file handles. This is useful for making sure that output of a perl action is not lost before the action's process terminates with POSIX::_exit.

print_error

print_error "message", ...;

Prints an error message, with the program name prefixed. For any arg which is a reference, $arg->name is printed.

If any filename is printed, it should have be quoted as in `filename' or `filename:lineno:' at BOL, so that IDEs can parse it.