NAME

       makepp_faq -- Frequently asked questions about makepp

DESCRIPTION

       Here you may find installation instructions and some points which are not obvious from the
       rest of the documentation.  This shows stumbling blocks, whereas howto type questions will
       be found in the cookbook.

   Getting Started
       Where to download?

       Makepp is hosted on SourceForge and can be downloaded as a source code tarball or as
       installation package for Debian .deb based Linuxes or .rpm based Linuxes from
       http://sourceforge.net/projects/makepp/files/

       Like tons of Perl software, makepp can also be downloaded from CPAN by clicking the
       Download link on http://search.cpan.org/dist/makepp/

       Makepp is part of Debian GNU/Linux unstable and testing.  This means you can install it
       directly via "apt-get install makepp" or by choosing it from your preferred package tool
       like synaptic.

       Makepp is part of archlinux and of Gentoo Linux.  Note that distro-specific suffixes like
       2.0-1 or 2.0-r1 is not the release candidate 1, but the final released version 2.0.

       Can I try it without installing?

       Yes, if you want to try makepp on your own makefiles, either put the directory where you
       unpacked it into your path, or else run it explicitly like this, with an absolute or
       relative path to makepp:

           perl /where/you/unpacked/it/makepp

       How to choose perl version?

       You must have Perl 5.8 or newer somewhere on your system.  By default all uninstalled
       scripts will use the "perl" in your path.  But you can run them with an explicit instance
       of perl.  The test runner and installation will run everything with this same instance.

           /path/to/perl /where/you/unpacked/it/makepp

       In case some script doesn't properly recognize which "perl" it is being run with, you can
       help it by telling it the path to the same instance of perl via the "PERL" variable:

           PERL=/path/to/perl /path/to/perl /where/you/unpacked/it/makepp

       This can also be an instance to be searched in your path, if it doesn't contain a
       directory separator:

           PERL=perl5.16.2 perl5.16.2 /where/you/unpacked/it/makepp

       How to install?

       There are two ways to install, which lead to the same result:

       configure (alias config.pl)
           This allows for traditional style installation:

               ./configure && make test && make install

           The only difference between these two is that "configure" is not a Perl script, so you
           can't say "perl configure", whereas you can use all the above variants like "perl
           config.pl".  Valid options are:

           -b, --bindir=/path/to/installation/bin
               Where the binaries go (default: prefix/bin).  Makepp's binaries are just Perl
               scripts so they are architecture independent.  If you give this option, but no
               "--prefix", it will strip /bin to deduce a prefix for the other default values.

           -d, --datadir=/path/to/installation/share/makepp
               Where to install makepp's library files (default: prefix/share/makepp).

           -f, --findbin=relative/path/to/datadir/from/bindir
               Where to find libraries relative to executables, or 'none' (the default) to find
               them in datadir.

           -h, --htmldir=/path/to/installation/share/html
               Where the HTML documentation goes (default: prefix/doc/makepp if prefix/doc
               exists, else datadir/html), or 'none' if you do not want it installed.

           -m, --mandir=/path/to/man
               Where the manual pages should reside (default: prefix/share/man if it exists, else
               prefix/man), or 'none' if you do not want them installed.

           --makefile=/path/to/Makefile
               Specify location where you can write the Makefile (default: .).  Unlike the other
               options, which are remembered for the following install step, this file is created
               immediately.

           -p, --prefix=/path/to/installation
               Specify location where you want to install everything (default: /usr/local).  All
               other paths are by default relative to this one.

           -V
           --version
               Print out the version number.

           If you want to do a mockup installation to some destdir for packaging your own
           distribution, you can give an extra parameter to the last command:

               make DESTDIR=/temporary/destdir install

       install.pl
           This is the backend that performs the actual installation.  You can call it directly:

               ./install.pl bindir datadir mandir htmldir findbin destdir

           The parameters are optional and correspond to the options from the previous section.
           You are prompted for those you don't supply, except for the last one, which is not
           normally needed.

       Makefile.PL
           The customary file Makefile.PL is currently only present for technical reasons.  It
           will not help you to install.  Therefore, alas, you can't use tools like "cpanm" to
           install in one go.

       On some systems whichever "perl" you end up calling may be a symbolic link to some precise
       version "perl5.m.n".  In this case perl sees only that one, and will thus use it to
       install against.  If you don't want that, use the "PERL" variable as described above.  If
       you install with the second variant, i.e. just the name of the executable without slashes,
       the installed scripts will always search for that one via "/usr/bin/env".  This makes them
       a tiny bit slower to start, for a greater flexibility.

       Why does installation say permission denied?

       If you want to install to a system directory like /usr, /usr/local or /opt, you can only
       do that if you run the installation as user root.  On many Unices you can run a command as
       root, by prepending "sudo" to it, and depending on the system entering the either the root
       password, or yours, as prompted for.

       This is not necessary for the preparatory "configure" or "config.pl" step which only
       writes a Makefile in the current directory.

   Build Questions
       What are unimportant targets?

       Makepp remembers the dependencies of every file.  If any of them need to be rebuilt, that
       will be done before rescanning.  But if the build failed, yet the scan succeeds, because
       the file isn't even needed anymore, then at the end the failure will be reported as
       unimportant.  (The build should not be attempted, instead letting the rescan do those
       builds it finds to be necessary, but that happens in a different place, so this would be
       difficult.)

       Why does it run this rule 3 times?

       GNU make has no makepp style multi target rules.  Instead it interprets this as a shortcut
       for three separate rules:

           a b c:
               echo $@
               touch a b c

       However, it doesn't check why a file is there.  If a file exists (and is newer than any
       dependencies) it is happy.  Whichever of the three files gets built first, provides the
       other two, so this behaves somewhat like a multitarget rule -- but can cause race
       conditions in parallel builds.

       A similar rule might have been:

           a b c:
               touch $@

       Gmake indeed runs this one once per required file.  Without knowing what the command does
       (it might be a script which internally creates some files), the two cases can't easily be
       told apart by makepp.

       So as a special compatibility fallback, if a multi target rule action mentions only old
       style $@ and neither new style "$(output)" nor "$(target)" nor their plural forms, it is
       treated as separate rules.  This however means running it repeatedly, as makepp ignores
       randomly appearing files for which it has no metadata.

       Why does it complain that a created file is phony?

       If you have a command that continues working asynchronously, after it came back with a
       success return code, makepp will notice the promised file as missing and complain.  This
       can also typically happen on some network file systems, which may physically write only
       several seconds later.

       If you cannot evite such an unsatisfactory situation, you can ask makepp to be sloppy
       about this check with the "--gullible" option.  But then the next command which depends on
       the produced file might still fail.

       Why does it recreate files unnecessarily?

       I have observed this on NFS, where due to file attribute caching the timestamp of the
       produced file was not yet the one the it finally had.  On the next run makepp noticed the
       difference and considered the file unduly modified.  This got resolved with a mount option
       of "acregmin=0", making attributes visible immediately.

       This can also happen with repositories, e.g. if someone else has built in the repository
       with "umask 066" or using a compiler that bars others from reading the produced file.
       This will also happen if either the repository or your build tree shares a common path
       prefix with some dependencies (e.g. /opt/repository and /opt/sometool, in which case
       makepp will remember the path once as relative, and once as absolute, looking like changed
       dependencies.

       Does the C source file or the object file depend on headers?

       It depends on your viewpoint.  If a prototype in a header changes, the programmer may have
       to adapt the source code.  So from that viewpoint there is a dependency.

       But for the build this is completely irrelevant.  Here the outputs depend on the inputs.
       If a header file changes this may affect the object file (e.g. addition of parameters with
       default values, which the programmer may ignore, but not the compiler).  So from makepp's
       viewpoint only the produced object file depends on the headers, i.e. must be rebuilt when
       these change.

   Miscellaneous
       Why does makepp selectively detect dependencies?

       In this rule why does makepp make output depend on input1, but not on input2?

           output:
               zcat <input1 >output
               zcat input2 >>output

       There are three levels to scanning.  The first is the lexer, which tries to understand the
       Shell part of the execution.  I.e. which commands get called and what I/O redirections
       take place.  This notices input1 and output (even if it had not been declared a target of
       this rule).

       The next step are the command parsers.  Makepp has a few for typical compilation commands.
       These check the command line options to understand what the command will do.  In the
       process they pick up dependencies like libraries ("cc -llib"), include paths ("cc -Idir")
       and input files.  The task of a "zcat" parser would be to know that "-S" takes an
       argument, but all other non option words are filenames (optionally suffixed by .gz), and
       that "--" ends options.  Alas there is no such parser, no more than for hundreds of other
       commands.

       The third step for some languages is the scanning of input files, to detect includes as
       further dependencies.  This does not apply to this example.

       How can I debug makepp?

       You can put "$(print )" around a suspicious expression.  This returns the unchanged
       expression, while printing it as a side effect.

       You can dump the current directory's (multiply after "-C" if you want) makefile with the
       "--dump-makefile=file" option, to see how makepp sees it.

       Makepp writes a log of everything it does and why.  You can look at that with makepplog,
       mppl or makeppgraph, mppg.  You can make it more verbose by setting the environment
       variable "MAKEPP_DEBUG".

       Makepp records all it knows about a file, for reuse on the next run.  Though it takes some
       understanding of makepp's internals, dumping it with makeppinfo, mppi for one or more
       files, usually gives a clue what is wrong.  "MAKEPP_DEBUG" additionally provides the
       "RULE_SOURCE".

       If you are feeling adventurous, use makepp from cvs.  This includes extra modules that
       hook into "perl -d" to better display makepp's internals.

       Is it safe to use?

       Yes, it will do exactly what your makefiles say (which many programmers find hard to
       understand, since rule based inference is very different from most programming paradigms).

       And no, if you don't trust the makefiles you got, definitely not!  A makefile is a funny
       kind of script, the purpose of which is to run commands that are expected to modify your
       file system.  Makepp has no means of checking what harm they will do.

       Worse, there are execute always syntaxes, which are performed even with "--dry-run" (which
       does not run the rules, but evaluates everything else).  That might be something like
       this:

           bad_boy := $(shell rm *)

   External tools
       Can I use cc -M or gcc -MM?

       The short answer is yes.  The long answer is that they have the advantage of knowing the
       effect of even the last weird compiler option, and sub-includes hidden in some compiler
       internal directory, where makepp only comes pretty close.  The disadvantage is that they
       have no idea of the build rules, so they can not reliably depend on yet to-be-built files,
       which includes files to be fetched from a repository.  And they are not extensible to
       other languages, as makepp's scanner is.  Usually you are at least as well off, not
       resorting to these tools.

       Nonetheless, some compilers can produce this as a by-product.  If you'd rather use this
       see :include.

       Can I use CCache, Compilercache or cachecc1?

       The short answer is yes.  The long answer is that these programs need to repeat the work
       makepp does, to get a reliable fingerprint of files.  With traditional makes this even
       comes too late, because those miss many situations calling for a recompilation.  With
       makepp it is just easier to use the built in build cache, which has the added advantage
       that it can handle all kinds of files.

       Note that ccache direct mode has a bug https://bugzilla.samba.org/show_bug.cgi?id=8728
       that will ignore change in include pathes.  This makes t/makeppreplay.test fail with
       "wrong file: out".  Export "CCACHE_NODIRECT=1" to avoid that.

AUTHOR

       Daniel Pfeiffer (occitan@esperanto.org)