=head1 NAME
makepp -- Command line syntax for makepp
=for vc $Id: makepp_command.pod,v 1.59 2012/10/14 15:16:04 pfeiffer Exp $
=head1 DESCRIPTION
=for genindex '[-$][-?\w]+' makepp_command.pod
B<?:>E<nbsp>L<-?|/_>,E<nbsp>
B<A:>E<nbsp>L<-A|/a_filename>,
L<--args-file|/a_filename>,
L<--arguments-file|/a_filename>,
L<--assume-new|/w_filename>,
L<--assume-old|/o_filename>,E<nbsp>
B<B:>E<nbsp>L<-b|/b_directory>,
L<--build-cache|/b_directory>,
L<--build-check|/build_check_method>,
L<--build-check-method|/build_check_method>,E<nbsp>
B<C:>E<nbsp>L<-C|/c_directory>,
L<-c|/c>,E<nbsp>
B<D:>E<nbsp>L<--defer-include|/defer_include>,
L<--directory|/c_directory>,
L<--do-build|/dont_build_filename>,
L<--dont-build|/dont_build_filename>,
L<--dont-read|/dont_read_filename>,
L<--do-read|/dont_read_filename>,
L<--dry-run|/n>,
L<--dump-makefile|/dump_makefile_filename>,
L<--dump-makeppfile|/dump_makefile_filename>,E<nbsp>
B<E:>E<nbsp>L<-e|/e>,
L<--environment-overrides|/e>,
L<--env-overrides|/e>,E<nbsp>
B<F:>E<nbsp>L<-F|/f_makeppfile>,
L<-f|/f_makefile>,
L<--file|/f_makefile>,
L<--final-rules-only|/final_rules_only>,
L<--force-copy-from-bc|/force_copy_from_bc>,
L<--force-rescan|/force_rescan>,E<nbsp>
B<G:>E<nbsp>L<--gullible|/gullible>,E<nbsp>
B<H:>E<nbsp>L<-h|/_>,
L<--help|/_>,
L<--hybrid|/hybrid>,
L<--hybrid-recursion|/hybrid>,
L<--hybrid-recursive-make|/hybrid>,E<nbsp>
B<I:>E<nbsp>L<-I|/i_directory>,
L<--implicit-load-makeppfile-only|/implicit_load_makeppfile_only>,
L<--include|/i_directory>,
L<--include-dir|/i_directory>,
L<--in-sandbox|/sandbox_directory>,
L<--inside-sandbox|/sandbox_directory>,E<nbsp>
B<J:>E<nbsp>L<-j|/j_n>,
L<--jobs|/j_n>,
L<--just-print|/n>,E<nbsp>
B<K:>E<nbsp>L<-k|/k>,
L<--keep-going|/k>,E<nbsp>
B<L:>E<nbsp>L<--last-chance-rules|/last_chance_rules>,
L<--load-makefile|/load_makefile_makefile>,
L<--load-makeppfile|/load_makefile_makefile>,
L<--log|/log_logfilename>,
L<--log-file|/log_logfilename>,E<nbsp>
B<M:>E<nbsp>L<-m|/m_method>,
L<--makefile|/f_makefile>,
L<$MAKEFLAGS|/_makeflags>,
L<$MAKEPP_CASE_SENSITIVE_FILENAMES|/_makepp_case_sensitive_filenames>,
L<--makeppfile|/f_makeppfile>,
L<$MAKEPPFLAGS|/_makeppflags>,
L<--md5-bc|/md5_bc>,
L<--md5-check-bc|/md5_bc>,E<nbsp>
B<N:>E<nbsp>L<-n|/n>,
L<--new-file|/w_filename>,
L<--no-builtin-rules|/r>,
L<--no-cache-scaninfos|/no_cache_scaninfos>,
L<--no-implicit-load|/no_implicit_load>,
L<--no-log|/no_log>,
L<--no-path-executable-dependencies|/no_path_exe_dep>,
L<--no-path-exe-dep|/no_path_exe_dep>,
L<--no-populate-bc|/no_populate_bc>,
L<--no-print-directory|/no_print_directory>,
L<--no-remake-makefiles|/no_remake_makefiles>,
L<--no-warn|/no_warn>,E<nbsp>
B<O:>E<nbsp>L<-o|/o_filename>,
L<--old-file|/o_filename>,
L<--out-of-sandbox|/out_of_sandbox_filename>,
L<--override-signature|/override_signature_method>,
L<--override-signature-method|/override_signature_method>,E<nbsp>
B<P:>E<nbsp>L<--populate-bc-only|/populate_bc_only>,
L<--profile|/profile>,E<nbsp>
B<Q:>E<nbsp>L<--quiet|/s>,E<nbsp>
B<R:>E<nbsp>L<-R|/r_directory>,
L<-r|/r>,
L<--recon|/n>,
L<--remove-stale|/rm_stale>,
L<--remove-stale-files|/rm_stale>,
L<--repository|/r_directory>,
L<--rm-stale|/rm_stale>,
L<--root-dir|/c>,
L<--root-directory|/c>,E<nbsp>
B<S:>E<nbsp>L<-s|/s>,
L<--sandbox|/sandbox_directory>,
L<--sandbox-warn|/sandbox_warn>,
L<--sandbox-warning|/sandbox_warn>,
L<--signature|/m_method>,
L<--signature-method|/m_method>,
L<--silent|/s>,
L<--stop|/stop>,
L<--stop-after-loading|/stop>,
L<--stop-on-race|/stop_race>,
L<--stop-race|/stop_race>,
L<--symlink-in-rep-as-file|/symlink_in_rep_as_file>,
L<--symlink-in-repository-as-file|/symlink_in_rep_as_file>,E<nbsp>
B<T:>E<nbsp>L<--traditional|/traditional>,
L<--traditional-recursion|/traditional>,
L<--traditional-recursive-make|/traditional>,E<nbsp>
B<V:>E<nbsp>L<-V|/v>,
L<-v|/v>,
L<--verbose|/v>,
L<--version|/v>,
L<--virtual-sandbox|/virtual_sandbox>,E<nbsp>
B<W:>E<nbsp>L<-W|/w_filename>,
L<--what-if|/w_filename>
B<makepp> S<[ I<option> ... ]> S<[ I<VAR=value> ]> S<[ I<target> ... ]>
B<mpp> S<[ I<option> ... ]> S<[ I<VAR=value> ]> S<[ I<target> ... ]>
Makepp supports most of the command line options and syntax that other makes
support. The hyphens between the words are always optional, and can also be
replaced by an underscore. You specify a list of targets to build on the
command line. If you do not specify any targets, the first explicit target in
the makefile is built.
You can assign variables on the command line which will override any
assignment or environment variable in every Makefile loaded, e.g.,
makepp CFLAGS=-O2
Valid options are most of the standard make options, plus a few new ones:
=over 4
=item -A I<filename>
=item --args-file=I<filename>
=item --arguments-file=I<filename>
Read the file and parse it as possibly quoted whitespace- and/or newline-separated options.
=item -b I<directory>
=item --build-cache=I<directory>
Specifies the path to a build cache. See L<makepp_build_cache> for details.
The build cache must already exist; see L<makepp_build_cache/How to manage a
build cache> for how to make it in the first place. Build caches defined on
the command line may be overridden by a
L<build_cache|makepp_statements/build_cache_path_to_build_cache> statement in
a makefile or a L<:build_cache|makepp_rules/build_cache_path_to_build_cache>
rule modifier . If you work with several different builds, it may be useful
to set the environment variable C<MAKEPPFLAGS> to contain
C<--buil>C<d-cache=/path/to/build/cache> so that all of your builds will take
advantage of the build cache by default.
=item --build-check=I<method>
=item --build-check-method=I<method>
The name of a build check method to use to decide whether files need to
be rebuilt. Possible values are C<target_newer>, C<exact_match>, See L<makepp_build_check> for information on build check
methods.
=item -C I<directory>
=item --directory=I<directory>
Cd to the given directory before loading the makefile and trying to build the
targets. This is similar to specifying a directory with C<-F>, except that
subsequent C<-C>, C<-f>, C<-F>, C<-I> and C<-R> options are interpreted
relative to the new directory, rather than the old one.
=item -c
=item --root-dir
=item --root-directory
Cd up to the directory containing a RootMakeppfile.
=item --defer-include
Workaround for include statement before the rule that builds the include file.
This happens by pretending the include statements come last in the makefile.
That way the include statement is performable, but variable overrides or
modifications may still fail, in which case you should set the problematic
ones on the command line (whereas gmake ignores any variable setting from the
include file that might influence how that file itself gets built).
=item --dont-build=I<filename>
=item --do-build=I<filename>
Do not build the specified file, or, if it is a directory, everything
thereunder, even though makepp thinks it should -- or do build, overriding the
opposite specification from a higher directory. This is useful if you built a
specific file by hand using different compilation options. Without this
option, if you compile a module by hand and then run makepp to compile the
rest of the program, makepp will also recompile the module you compiled by
hand, because makepp cannot guarantee that the build is correct if any of the
files were not built under its control. With this option, you tell makepp
that you really know what you are doing in the case of this particular file
and you promise that it's ok not to rebuild it.
For example,
% cc -g -DSPECIAL_DEBUG -c x.c -o x.o # Special compilation by hand
% makepp
cc -g -O2 -c x.c -o x.o # Makepp just overrode your compilation here!
cc x.o y.o -o my_program # Relinks.
% cc -g -DSPECIAL_DEBUG -c x.c -o x.o # Do it again.
% makepp --dont-build x.o # Tell makepp not to rebuild x.o even if it wants to.
cc x.o y.o -o my_program # Now it relinks without recompiling.
If you want special compilation options for just one module, it's often
easier to edit the makefile than to compile by hand as in this example;
see L<makepp_variables/Target-specific assignments> for an easy way of
doing this.
If you put a F<RootMakeppfile(.mk)> at the root of your build system, that
directory and everything under it defaults to C<--do-build>, while the overall
root of your file system defaults to C<--dont-build>. That way, everything
inside your build system is built (if necessary) but nothing outside is
attempted. If, in this scenario, you want external parts to always be built
as needed, you must explicitly pick them up with C<load_makefile> statements in
one of the makefiles within your tree.
You may have one F<RootMakeppfile(.mk)> each, in separate build trees, and
they will be loaded if one tree has dependencies in another one. But you are
not allowed to have F<RootMakeppfile(.mk)> in nested directories, avoiding
funny effects that tend to arise when you accidentally call C<makepp
--repository> again in a subdirectory. These effects include duplicate rules
through duplicate sources, or eternal build cache reimports because cached
files have the right signatures but the wrong relative pathes.
Override C<--dont-build> for the specified file or directory. If you have a
F<RootMakeppfile(.mk)> at the root of your build system, but you want makepp
to build something outside of your build system just this once, you must
explicitly mark it as C<--do-build>. If you specify C<--do-build> for a file
or directory under a F<RootMakeppfile(.mk)>, without C<--dont-build> for a higher
directory, then the root (and all else under it) of your build system defaults
to C<--dont-build>.
To resolve conflicts between C<--dont-build> and C<--do-build>, the one
with the most specific path takes precedence regardless of order.
If the same path is specified with both C<--dont-build> and C<--do-build>,
then the rightmost one wins.
The options C<--dont-build> and C<--do-build> can be dangerous if you give the
wrong hints to makepp, since you are asking makepp not to do checks it needs,
to guarantee a correct build. But since they allow greatly reducing the
number of checks, they can speed up your builds dramatically, as explained in
L<potentially unsafe speedup methods|makepp_speedup/Potentially Unsafe Methods>.
=item --dont-read=I<filename>
=item --do-read=I<filename>
Do not read the specified file, or, if it is a directory, everything
thereunder -- or do read, overriding the opposite specification from a higher
directory. Generate an error rather than read files marked for
C<--dont-read>. See L<--sandbox|/sandbox_directory>. The filesystem
root always defaults to readable.
=item --dump-makefile=I<filename>
=item --dump-makeppfile=I<filename>
Dump the raw contents of the makefileZ<>(s) for the current directory
(as determined by the position of this option relative to any C<-C> options)
to F<filename>.
Include files are interpolated, comments are stripped out and C<ifdef>'s
are resolved.
C<# line "file"> markers are inserted as necessary.
The final value of any non-reference scalars in the makefile's package are
printed following the makefile.
This is useful for debugging, but (currently) you won't necessarily be able
use the dump file as an equivalent makefile, for example because it contains
both the include statement and the interpolated file.
=item -e
=item --env-overrides
=item --environment-overrides
Causes variables from the environment to override definitions in the
makefile. By default, assignments within the makefile override variable
values which are imported from the environment.
=item -F I<Makeppfile>
=item --makeppfile=I<Makeppfile>
Loads the specified Makefile or, if you specify a directory, the F<Makefile>
therein, instead of the one in the current directory -- any target specified
to the right of this option is interpreted relative to the directory
containing the Makefile. For the details of the directory case and
F<RootMakeppfile> see the explanation at the next option.
This option can be useful if you execute makepp from unpredictable
directories. For example, if you compile from within emacs and you have
sources scattered all over your directory tree, the current working directory
for the compilation command will be the directory the last source file you
edited was in, which may or may not be the top level directory for your
compilation. However, you can specify your compilation command as
makepp -F /your/source/dir/top
and this will work no matter what your current directory is.
Because this option doesn't affect the directory relative to which subsequent
C<-C>, C<-f>, C<-F>, C<-I> and C<-R> options are specified, you can make
targets relative to the current directory like this:
makepp -F /foo/bar -C . mytarget
=item -f I<Makefile>
=item --file=I<Makefile>
=item --makefile=I<Makefile>
Loads the specified Makefile or, if you specify a directory, the F<Makefile>
therein, instead of the one in the current directory. If you do not specify
the C<-f> option or the C<-F> option, makepp looks first for a file in the
current directory (or the directory specified by the rightmost C<-C> option,
if any) called, then F<RootMakeppfile.mk>, F<Makeppfile>, then
F<Makeppfile.mk>, then F<makefile>, then F<Makefile>. Multiple C<-F> and
C<-f> options may be specified.
The first two (F<RootMakeppfile>) are special (whether given explicitly or
found implicitly). There must be at most one of those two in any given build
tree on which makepp is to operate. But there may be several if you build
several disjoint trees in one go. Those two are looked for not only in the
aforementioned directory, but also upwards from there. If one is found, it is
loaded before any other.
=item --final-rules-only
Ignore the dependencies and implicit targets of the rule unless the target is
phony.
=item --force-copy-from-bc
When using build caches, always copy files in and out of the cache, even if
the source and target are on the same filesystem. This is mainly useful for
testing (emulating) the case in which they are not.
=item --force-rescan
Don't use cached scanner results from previous runs.
=item --gullible
Believe that the rules create what they declare, rather than checking. This
is faster, but doesn't catch bugs in rules.
=item -?
=item -h
=item --help
Print out a brief summary of the options.
=item --hybrid
=item --hybrid-recursion
=item --hybrid-recursive-make
This option is present to allow makepp to work with old makefiles that use
recursive make extensively, especially multiply into the same dir. By
default, recursive make is implemented by a subprocess that communicates with
the parent process; the build is actually done by the parent process. This
allows some of makepp's nice features like repositories to work with recursive
make invocations. However, this technique will not work if you load more than
one makefile from the same directory. In that case this option says to fall
back to starting another independent instance of makepp. If this fails, try
C<--traditional-recursive-make>.
If you do use this option, you will get log files in the each directory the
fall back occurred in. To get rid of only them use C<makeppclean --logs
--recurse> or C<mppc -lr>.
=item -I I<directory>
=item --include=I<directory>
=item --include-dir=I<directory>
Search the given directory for included makefiles.
=item --implicit-load-makeppfile-only
If implicit loading of makefiles is enabled, then automatically load only a
file called F<RootMakeppfile>, F<RootMakeppfile.mk>, F<Makeppfile>, or
F<Makeppfile.mk>, and B<not> F<makefile> or F<Makefile>. This is useful if
makepp has dependencies that are generated by some other flavor of make, and
makepp can't read that flavor's makefiles in general. (You want to avoid this
situation if possible, but it tends to arise while you're in the process of
porting a legacy build system to makepp.) This has no effect if implicit
loading is disabled.
=item -j I<n>
=item --jobs=I<n>
Interprets the argument I<n> as the number of shell commands that can be
executed in parallel. By default, makepp does not execute commands in
parallel.
Unlike some other versions of make, when jobs are executed in parallel, makepp
directs their output to a file and only displays the output when the commands
have finished. This prevents output from several different commands from
being mixed together on the display, but it does mean that you might have to
wait a little longer to see the output, and stderr messages will usually
appear before stdout stuff, differing from terminal output.
Native Windows Perls (i.e. Strawberry and ActiveState), because they do not
support the Unix fork/exec paradigm, do not allow this option (Cygwin works
fine!). As a partial replacement, you can use the
L<--sandbox|/sandbox_directory> option there, though this is far less
comfortable.
=item -k
=item --keep-going
Build as many files as safely possible, even if some commands have errors. By
default, makepp stops when it encounters the first error, even if there are
other files that need to be built that don't depend on the erroneous file.
=item --last-chance-rules
Activate limited special handling for pattern rules with '%' only on the
target side. This is needed because normally, unlike traditional makes,
makepp instantiates all rules with all available files from the bottom up,
allowing it to find all creatable dependencies.
=item --load-makefile=I<Makefile>
=item --load-makeppfile=I<Makefile>
Loads the specified makefile I<before> any other makefiles, except for
F<RootMakeppfile>, or F<RootMakeppfile.mk> above it, but do not consider this
option for the purposes of determining the default target. If no other
makefile is specified, then one is sought using the usual rules. If the
specified makefile is the same makefile that is found using the usual rules,
then this option has no effect.
=item --log=I<logfilename>
=item --log-file=I<logfilename>
Changes the name of the log file to the indicated name. By default, the log
file is called F<.makepp/log>. This file is readable with L<makepplog,
mppl|makepplog>.
=item -m I<method>
=item --signature=I<method>
=item --signature-method=I<method>
Specifies the default signature method to use for rules which do not have the
C<:signature> modifier in makefiles which do not have a C<signature>
statement. Does not override the choice made by command parsers, e.g. C/C++
compilers. Possible values are C<md5>, C<C> or C<c_compilation_md5>, C<xml>
and C<xml-space>. For more details, see L<makepp_signatures>.
=item --md5-bc
=item --md5-check-bc
When importing from a build cache, reject cached targets unless the MD5_SUM
is present and matches the imported target.
When populating a build cache, calculate and store the MD5_SUM in the build
info if it isn't there already.
This is slower and leads to more rebuilds, but it guarantees that imported
targets and build info files correspond exactly.
=item -n
=item --dry-run
=item --just-print
=item --recon
Print out commands without actually executing them -- unreliably where
commands depend on previous results. This allows you to see what makepp will
do, without actually changing any files.
More precisely, makepp executes all recursive make commands as normal (but
hopefully you're not using recursive make anywhere!). Other commands are
simply printed without being executed. Even commands which are prefixed with
C<@> or C<noecho> are printed after the C<@> or C<noecho> is stripped off.
However commands prefixed with C<+> should be executed, but currently are not.
B<Warning:> The commands that makepp executes with C<-n> are not
necessarily the same thing it will do without C<-n>. File signatures do
not change at all with C<-n>, which means that makepp cannot perform
exactly the same build tests that it does when the signatures are
changing. This will occasionally make a difference if you are using MD5
signatures (which is the default for compilation commands) or if you
have shell commands that might or might not change the date.
For example, suppose that you generate a F<.h> file via some sort of
preprocessor. This can happen in a lot of different ways. For concreteness,
suppose you automatically generate a list of prototypes for functions defined
in each C module (see L<http://cproto.sourceforge.net/> for how the C<cproto>
application works or L<http://www.lemoda.net/c/cfunctions/> for the similar
cfunctions).
prototypes.h : *.c
cproto $(CPPFLAGS) $(inputs) > $(output)
Then each F<.c> file will include F<prototypes.h>. The purpose of this is to
maintain the forward declarations for all functions automatically, so if you
change a function's signature or add a new function, you don't ever have to
put in forward or extern declarations anywhere. You don't even have to
declare the dependency of your .o files on this one -- makepp will see the
include statement and automatically see if it needs to (re)run cproto.
Now suppose you change just one F<.c> file. What happens when you run makepp
with C<-n> in this case is that it realizes that F<prototypes.h> needs to be
remade. In all probability, remaking F<prototypes.h> won't affect its
signature--the file contents will probably be identical because no function
arguments have been changed--so most of the time, nothing that depends on
F<prototypes.h> actually has to be recompiled. But makepp doesn't know that
unless it's actually allowed to execute the commands. So it assumes that
anything that depends on F<prototypes.h> will also have to be recompiled.
Thus in this example, changing one F<.c> file will cause S<C<makepp -n>> to
think that every single F<.c> file needs to be recompiled, even though most
likely the regular makepp command will actually not run all those commands.
This situation isn't all that common, and can only occur if (a) you use
a signature method that depends on file contents rather than date, as
the default compilation signature method does, or (b) if you have shell
commands that don't always change the date. E.g., with a traditional
implementation of make that only looks at dates instead of file
signatures, sometimes people will write commands like this:
prototypes.h : $(wildcard *.c) # Hacked technique not necessary for makepp
cproto $(CPPFLAGS) $(inputs) > junk.h
if cmp -s junk.h prototypes.h; then \
rm junk.h; \
else \
mv junk.h prototypes.h; \
fi
Thus if rerunning cproto on all the files produces exactly the same file
contents, the file date is not updated. This will have exactly the same
problem as the above example with S<C<makepp -n>>: it is not known
whether the date on F<prototypes.h> changes unless the command is
actually run, so S<C<makepp -n>> cannot possibly be 100% accurate.
(Note that using the traditional S<C<make -n>> will also have exactly
the same problem on this example.)
S<C<makepp -n>> should always print out more commands than a regular
invocation of makepp, not fewer. If it prints out fewer commands, it means
that makepp does not know about some dependency; some file is changing that it
is not expecting to change on the basis of what it knows about what files each
rule affects. This means that your makefile has a bug.
=item --no-cache-scaninfos
Do not record the results of scanning, forcing it to be reperformed next time
makepp runs.
=item --no-implicit-load
Don't automatically load makefiles from directories referenced (see
L<makepp_build_algorithm/Implicit loading>). By default, makepp automatically
loads a makefile from any directory that contains a dependency of some target
it needs to build, and from any directory that is scanned by a wildcard.
Sometimes, however, this causes a problem, since makefiles need to be loaded
with different command line variables or options, and if they are implicitly
loaded before they are explicitly loaded by a recursive make invocation or the
C<load_makefile> statement, makepp aborts with an error. You can also turn
off makefile loading on a directory-by-directory basis by using the
C<no_implicit_load> statement in one of your makefiles.
=item --no-log
Don't bother writing a detailed description of what was done to the log file.
By default, makepp writes out an explanation of every file that it tried to
build, and why it built it or did not build it, to a file called
F<.makepp/log>, readable with L<makepplog, mppl|makepplog>. This can be
extremely valuable for debugging a makefile--makepp tells you what it thought
all of the dependencies were, and which one(s) it thought changed. However,
it does take some extra CPU time, and you might not want to bother.
=item --no-path-exe-dep
=item --no-path-executable-dependencies
Do not add implicit dependencies on executables picked up from the command
search path. If this option is specified, then makepp assumes that any
executable whose behavior might change with a new version will be specified
with a name containing a slash.
This is useful for programs such as grep and diff, which always do basically
the same thing even if their implementation changes, though you're better off
using the L<builtin commands|makepp_builtins> for grep. You may also need
this for repositories on NFS clusters, where the same commands might not have
the same timestamp everywhere, causing unnecessary rebuilds depending what
machine somebody works on.
=item --no-populate-bc
Don't populate the build cache, but still import from it when possible.
This is useful when the environment might cause targets to be generated
differently, but makepp doesn't know about such dependencies.
It's also useful to avoid thrashing the build cache with a huge number
of concurrent writers that might interfere with one another.
=item --no-print-directory
Turn off the entering or leaving directory messages.
=item --no-remake-makefiles
Ordinarily, makepp loads each makefile in, then looks to see whether
there is a rule that specifies how to update the makefile. If there is,
and the makefile needs to be rebuilt, the command is executed, and the
makefile is reread. This often causes problems with makefiles produced
for the standard Unix make utility, because (in my experience) often the
make rules for updating makefiles are inaccurate--they frequently omit
targets which are modified. This can cause makepp to remake a lot of
files unnecessarily. You can often solve this problem by simply
preventing makepp from updating the makefile automatically (but you have
to remember to update it by hand).
=item --no-warn
Don't print any warning messages to stderr, only to log file. Most warning
messages are about constructs that you might see in legacy makefiles that
makepp considers dangerous, but a few of them concern possible errors in your
makefile.
=item -o I<filename>
=item --assume-old=I<filename>
=item --old-file=I<filename>
Pretends that the specified file has not changed, even if it has. Any
targets that depend on this file will not be rebuilt because of this
file, though they might be rebuilt if some other dependency has also
changed. The file itself might or might not be rebuilt, depending on
whether it is out of date with respect to its dependencies. (To prevent
that, use C<--dont-build>.)
=item --override-signature=I<method>
=item --override-signature-method=I<method>
Same as C<--signature-method>, but even overrides the choice made by command
parsers.
=item --out-of-sandbox=I<filename>
Generate an error rather than write files outside the "sandbox". Like
--dont-build, more specific paths override less specific paths. The
filesystem root defaults to out-of-sandbox if there are any C<--sandbox>
options.
The purpose of the sandbox is to enable multiple concurrent makepp processes
to safely operate on disjoint parts of the filesystem. In order for this to
work reliably, concurrent sandboxes must not overlap, and each process must
mark the sandbox of every other concurrent makepp process for
L<--dont-read|/dont_read_filename>. See L<partitioning into
sandboxes|makepp_sandboxes>.
=item --populate-bc-only
Don't import for the build cache. This is useful when you want to
donate targets to the cache, but you don't want to rely on the contents
of the cache (e.g. for mission-critical builds).
=item --profile
Output raw timestamps before and after each action.
=item -R I<directory>
=item --repository=I<directory>
Specify the given directory as a repository (see L<makepp_repositories> for
details). Repositories are added in the order specified on the command line,
so the first one you specify has precedence. All files in the directory (and
all its subdirectories) are automatically linked to the current directory (and
subdirectories) if they are needed.
If you just specify a directory after C<-R>, its contents are linked into the
current directory. You can link its contents into any arbitrary place in the
file system by specifying the location before an equals sign, e.g, S<C<-R
subdir1/subdir2=/users/joe/joes_nifty_library>>.
=item -r
=item --no-builtin-rules
Don't load the default rule sets. If this option is not specified, and
the variable C<makepp_no_builtin> is not defined in the makefile, then a
set of rules for compiling C, C++, and Fortran code is loaded for each
directory.
=item --rm-stale X<--rm-stale>
=item --remove-stale
=item --remove-stale-files
Ignore stale files rather then treating them as new source files, removing
them if necessary in order to prevent them from being read by a build command.
This is not the default because it deletes things, but it is often required
in order for incremental building to work properly.
For example, assume that there is an F<x.c> file that looks like this:
#include "x.h"
int main() { return X; }
Consider this makefile:
$(phony default): x
x.h:
&echo "#define X 1" -o $@
At some point, you change the makefile to look like this:
CFLAGS := -Idir
$(phony default): x
dir/x.h:
&mkdir -p $(dir $@)
&echo "#define X 2" -o $@
Now if you build from clean, F<x> exits with status 2, but if you build
while the old F<./x.h> file still exists and you don't specify C<--rm-stale>,
then F<x> exits with status 1, because the include directive picks up the
stale generated header file.
If you build with C<--rm-stale>, then F<./x.h> is removed, and the result
is the same as that of a clean build, which is almost always a good thing.
Note that if you build in a repository, you have to give this option there
first, because the importing makepp doesn't know what might be stale in the
repository.
=item -s
=item --quiet
=item --silent
Don't echo commands and don't print informational messages like "Scanning" or
"Loading makefile".
=item --sandbox=I<directory>
=item --in-sandbox=I<directory>
=item --inside-sandbox=I<directory>
Restrain this instance of makepp to a subtree of a normally bigger build tree.
See L<partitioning into sandboxes|makepp_sandboxes>.
=item --sandbox-warn
=item --sandbox-warning
Downgrade violations of "in-sandbox" and "dont-read" to warnings instead of
errors. See L<partitioning into sandboxes|makepp_sandboxes>.
=item --stop
=item --stop-after-loading
After loading the top level Makeppfile, and any others explicitly or
implicitly (through dependencies from other directories) loaded from there,
makepp will stop itself (go to sleep). This happens before it analyzes
anything else. It will tell you the command needed to wake it up again. If
you do it in a Shell, you get the prompt and can then fore- or background it.
If you do it within an IDE, it'll just sleep, and you can awaken it from
another Shell.
The intention is that you can start makepp this way before you're finished
editing some files. Depending on your project structure and size, this can
allow makepp to get a headstart of many seconds worth of work by the time
you're done.
If you use C<prebuild> or C<$(make)> it will stop when it gets to that point,
so it might not be so useful. Nor will it consider regeneration of
Makeppfiles, but this is not expected to happen frequently.
=item --stop-race
=item --stop-on-race
Exit in error rather than only warning about a sandbox access collision that
could be fixed.
=item --symlink-in-rep-as-file
=item --symlink-in-repository-as-file
If a repository contains a symbolic link, then by default that symbolic link
is imported as a link, which is to say that the target of the imported link
need not be identical to the target of the symbolic link in the repository.
If the C<--symlink-in-repository-as-file> option is specified, then the
symbolic link is imported as its target file, which is to say that the imported
link points to the same target file as the symbolic link in the repository.
This is useful if the symbolic link in the repository was intended to have
the build-time semantics of a copy.
=item --traditional
=item --traditional-recursion
=item --traditional-recursive-make
This option is present to allow makepp to work with old makefiles that use
recursive make extensively, especially with varying options. By default,
recursive make is implemented by a subprocess that communicates with the
parent process; the build is actually done by the parent process. This allows
some of makepp's nice features like repositories to work with recursive make
invocations. However, this technique will not work if you use different
command line options on different invocations of recursive make. Before you
use this, try C<--hybrid-recursive-make>.
C<--traditional-recursive-make> option makes makepp do recursive makes the
same way as the traditional make, allowing more makefiles to work, but then
repositories and parallel builds do not work properly. This option is rarely
needed any more, and makepp will tell you if it runs into a construct that
requires it.
If you do use this option, you will get log files piling up in the various
directories this changes to. To get rid of only them use C<makeppclean
--logs --recurse> or C<mppc -lr>.
=item -v
=item --verbose
Verbose mode. Explains what it is trying to build, and why each file is
being built. This can be useful if you think a file is being rebuilt
too often.
This option actually takes what would be written to the log file and displays
it on the screen. It's usually easier to run makepp and then look at the
output of L<makepplog>, which allows various selections and some rewriting.
=item -V
=item --version
Print out the version number.
=item --virtual-sandbox
Don't rewrite build infos of files that were not created by this makepp process.
See L<partitioning into sandboxes|makepp_sandboxes>.
=item -W I<filename>
=item --assume-new=I<filename>
=item --new-file=I<filename>
=item --what-if=I<filename>
Pretends the specified file has changed, so that any targets that depend
on that file will be rebuilt. The file itself is not necessarily
changed (it might or might not be rebuilt, depending on whether it is up
to date with respect to its dependencies), but everything that depends
on it thinks that it has changed. This can be useful for debugging a
makefile.
=back
=head1 ENVIRONMENT
Makepp searches upwards for a file called F<.makepprc> when starting and again
after every C<-C> or C<-c> option. Each time it finds such a file, but only
once per file, it will read the file and parse it as possibly quoted options
on one or several lines. Unlike the option C<-A>, the options will be parsed
relative to the directory where the file resides.
Makepp looks at the following environment variables:
=over 4
=item $MAKEFLAGS
Any flags in this environment variable are interpreted as command line options
before any explicit options. All command line arguments are put into this variable
Note that the traditional make also uses this
variable, so if you have to use both make and makepp, you might want to
consider using C<MAKEPPFLAGS>.
=item $MAKEPPFLAGS
Same as C<MAKEFLAGS> as far as makepp is concerned. If this variable is
not blank, then C<MAKEFLAGS> is ignored. Sometimes this is useful
instead of C<MAKEFLAGS> if you have to use both make and makepp, and you
need to keep the options separate.
=item $MAKEPP_CASE_SENSITIVE_FILENAMES
Makepp will attempt to determine whether its default directory is case
sensitive by creating a file and then accessing it with a different
case. Usually this works fine, as long as all the files you're
accessing are on the same file system as your default directory, so you
should rarely need to use this option.
If this variable is present in the environment, its value (C<0> or empty
string for false, anything else for true) will override makepp's choice. This
variable is mostly useful on Windows, if you want to override makepp's default
setting. If you don't treat filenames as case sensitive, then makepp converts
all filenames to lowercase, which causes occasional difficulties. (E.g.,
emacs may will open several buffers to the same file.)
Makepp does not currently support a build across several file systems well,
if one is case sensitive and the other case insensitive.
=back