MAKEPP_FAQ(1)

🌸 MAKEPP_FAQ(1) 🌸 — the makepp FAQ, but make it a vibe check

📛 NAME 📛

makepp_faq -- Frequently asked questions about makepp

💬 DESCRIPTION 💬

Okay so here you'll find installation instructions and some points that are not obvious from the rest of the docs. This is the stumbling blocks zone, bestie. Howto-type questions? Those live in the cookbook. 💅

🚀 Getting Started 🚀

🌈 Where to download? 🌈

Makepp is hosted on SourceForge and can be downloaded as a source code tarball or as an 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. (iykyk 😭)

🧚 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 avoid 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? 💀

ok bestie so you got a sketchy-looking expression and you're like 👀? Wrap it in $(print ). That's it. It hands the expression back to you completely unchanged, it just prints it on the side so you can see what it actually turned into. Sneaky little x-ray. 🩻

Want to see the whole makefile the way makepp sees it? Dump it with the --dump-makefile=file option. Heads up though — it dumps the current directory's makefile, so if you're poking around somewhere else you gotta multiply that after -C. 🗂️

Makepp is also a lil diary keeper — it writes a log of everything it does and why. Read it with makepplog, mppl, or makeppgraph, mppg. Want it louder and messier? Set the environment variable MAKEPP_DEBUG. 💅

And makepp remembers everything it knows about a file, so it can reuse that on the next run. Dumping it takes a little understanding of makepp's internals, but makeppinfo, mppi for one or more files, usually gives you a clue about what's wrong. MAKEPP_DEBUG also gives you the RULE_SOURCE. 🔍

Feeling adventurous? 🧚 Use makepp from cvs — that version includes extra modules that hook into perl -d so makepp's internals display all pretty.

---

Is it safe to use? 💀

Yes — it does exactly what your makefiles say. Which, ngl, a lot of programmers find hard to understand, because rule-based inference is very different from most programming paradigms.

And no — if you don't trust the makefiles you got, then definitely not! A makefile is a funny kind of script, and the whole point of it 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 that get performed even with --dry-run (which does not run the rules, but evaluates everything else). It might look something like this:

bad_boy := $(shell rm *)

🚨 bestie. read that again. --dry-run is not a safety bubble for stuff like this.

---

External tools 🛠️

Can I use cc -M or gcc -MM?

Short answer: yes. Long answer: they do have a glow-up — they know the effect of even the last weird compiler option, and of sub-includes hidden in some compiler internal directory, where makepp only comes pretty close. ✨

But the downside is they have no idea of the build rules, so they can't reliably depend on yet to-be-built files — and that includes files to be fetched from a repository. Also they're not extensible to other languages, whereas makepp's scanner is. Usually you're at least as well off not resorting to these tools. 💁‍♀️

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

Can I use CCache, Compilercache or cachecc1?

Short answer: yes. Long answer: these programs have to repeat the work makepp does, just 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's just easier to use the built in build cache — which has the added advantage that it can handle all kinds of files. 👑

🐛 PSA: 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)

---

and that's a wrap, bestie 🫶 this page is from perl v5.32.0, dated 2021-01-06, and it's the MAKEPP_FAQ(1) manpage — so if you're quoting me, quote the source too, periodt. 💖