.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MAKEPPINFO 1" .TH MAKEPPINFO 1 "2014-09-11" "perl v5.20.0" "Makepp" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" makeppinfo \-\- What makepp knows about files .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fB?:\fR\ \-?,\ \&\fBA:\fR\ \-A, \-\-args\-file, \-\-arguments\-file,\ \&\fBD:\fR\ \-d, \-\-dates, \-\-decode\-dates,\ \&\fBF:\fR\ \-f, \-\-force,\ \&\fBH:\fR\ \-h, \-\-help,\ \&\fBK:\fR\ \-k, \-\-keylist, \-\-keys,\ \&\fBM:\fR\ \f(CW$MAKEPPINFOFLAGS\fR,\ \&\fBQ:\fR\ \-q, \-\-quiet,\ \&\fBT:\fR\ \-t, \-\-traverse,\ \&\fBU:\fR\ \-u, \-\-unremembered,\ \&\fBV:\fR\ \-V, \-\-version .PP \&\fBmakeppinfo\fR \fIoption\fR [file ...] .PP \&\fBmppi\fR \fIoption\fR [file ...] .PP Makepp remembers detailed information about the files it scanned and/or built. For the built files it remembers everything that was relevant, which includes their dependencies. This information is stored in the \fI.makepp\fR subdirectory along the file it pertains to. It has the form of key-value pairs. In some cases the value will again be a list of associated pairs, typically the signature and the file. .PP If both \f(CW\*(C`ENV_DEPS\*(C'\fR and \f(CW\*(C`ENV_VALS\*(C'\fR get displayed, they are merged into a two column table. .PP If both \f(CW\*(C`DEP_SIGS\*(C'\fR and \f(CW\*(C`SORTED_DEPS\*(C'\fR get displayed, they are merged into a two column table (in this order which gives a better layout). Each dependency has a \f(CW\*(C`SIGNATURE\*(C'\fR which is only \f(CW\*(C`timestamp,size\*(C'\fR, used only to check if the file must be rescanned. For dangling symlinks, instead of the linkee's signature, the link's own signature is determined in this way, and a \f(CW0\fR prepended to mark this special case. The interesting information is stored in some other key, for the built in signatures as follows: .IP "\(bu" 4 \&\f(CW\*(C`C_MD5_SUM\*(C'\fR for \f(CW\*(C`C\*(C'\fR or \f(CW\*(C`c_compilation_md5\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`MD5_SUM\*(C'\fR for \f(CW\*(C`md5\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`SHARED_OBJECT\*(C'\fR for \f(CW\*(C`shared_object\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`V_MD5_SUM\*(C'\fR for \f(CW\*(C`verilog_synthesis_md5\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`XML_MD5_SUM\*(C'\fR for \f(CW\*(C`xml\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`XML_SPACE_MD5_SUM\*(C'\fR for \f(CW\*(C`xml_space\*(C'\fR .PP These signature lists are the most frequent reason for rebuilding a file, so you might like to check, whether the signature stored for a dependency matches the current \f(CW\*(C`BUILD_SIGNATURE\*(C'\fR of that file. If the signatures and everything else matches, that is the basis for getting a file from (one of) your repositories or build cache if it is found there. The details depend on the applicable build check method. .PP You will encounter two kinds of signatures: simple ones consist of two comma separated numbers, which are the timestamp in file system format (seconds since 1970) and the size. For some files makepp will additionally have the relevant smart signature which is a base64 encoded (letters, digits, slash and plus) \s-1MD5\s0 sum of the plain or digested file contents. .PP This command is partially a makepp debug tool. The list of keys varies depending on which scanner, build check and signature was used. To fully understand the output, you may need to look at the source code. That said, there is also some generally interesting information to be gotten. .PP Valid options are: .IP "\-A \fIfilename\fR" 4 .IX Item "-A filename" .PD 0 .IP "\-\-args\-file=\fIfilename\fR" 4 .IX Item "--args-file=filename" .IP "\-\-arguments\-file=\fIfilename\fR" 4 .IX Item "--arguments-file=filename" .PD Read the file and parse it as possibly quoted whitespace\- and/or newline-separated options. .IP "\-d" 4 .IX Item "-d" .PD 0 .IP "\-\-dates" 4 .IX Item "--dates" .IP "\-\-decode\-dates" 4 .IX Item "--decode-dates" .PD In the simple signatures prepend the 1st number, the raw date-time, with its human readable form in parentheses. .IP "\-f" 4 .IX Item "-f" .PD 0 .IP "\-\-force" 4 .IX Item "--force" .PD Display info even when it is invalid because of inexistent or modified file. In this case the key \f(CW\*(C`SIGNATURE\*(C'\fR is replaced by \f(CW\*(C`invalidated_SIGNATURE\*(C'\fR and the value indicates in parentheses that the file was deleted or what signature the file now has. .IP "\-?" 4 .PD 0 .IP "\-h" 4 .IX Item "-h" .IP "\-\-help" 4 .IX Item "--help" .PD Print out a brief summary of the options. .IP "\-k \fIlist\fR" 4 .IX Item "-k list" .PD 0 .IP "\-\-keys=\fIlist\fR" 4 .IX Item "--keys=list" .IP "\-\-keylist=\fIlist\fR" 4 .IX Item "--keylist=list" .PD The \fIlist\fR specifies one or more space separated Shell style patterns (with [xyz], ?, *, {a,bc,def}). Remember to protect these from your Shell by quoting. These are matched against the keys. Each pattern may be preceded with an exclamation mark (\f(CW\*(C`!\*(C'\fR) or a caret (\f(CW\*(C`^\*(C'\fR) to exclude the matched keys from those selected before instead of adding them to the selection. If the first pattern starts with an exclamation mark, it operates on all keys. .Sp .Vb 1 \& \-\-keys=\*(AqCOMMAND CWD\*(Aq # How was this built and where (relative to file). .Ve .Sp If you want only filenames (useful with \f(CW\*(C`\-t|\-\-traverse\*(C'\fR) select an inexistent key like \*(L"none\*(R". .IP "\-q" 4 .IX Item "-q" .PD 0 .IP "\-\-quiet" 4 .IX Item "--quiet" .PD Don't list file and key names. Repeat to also omit warnings. .IP "\-t" 4 .IX Item "-t" .PD 0 .IP "\-\-traverse" 4 .IX Item "--traverse" .PD Also output the same information for each file in \s-1SORTED_DEPS \s0(recursively if repeated). .IP "\-u" 4 .IX Item "-u" .PD 0 .IP "\-\-unremembered" 4 .IX Item "--unremembered" .PD Traverse dependencies of the given files, but instead of showing their info, from all the involved directories list only those files not remembered for these targets. The idea here is to help you spot no longer needed files. Somewhat surprisingly this will include the Makefiles from those directories, because these are mostly not a dependency. .Sp Giving this option twice will also go to far away directories which are not output relatively, like \fI/usr/include\fR. .IP "\-V" 4 .IX Item "-V" .PD 0 .IP "\-\-version" 4 .IX Item "--version" .PD Print out the version number. .SH "EXAMPLES" .IX Header "EXAMPLES" .SS "General" .IX Subsection "General" Each build check method documents how to see what they base their decision on. Finding the paths of the dependencies is the same in all cases, so it is shown here. If you build to a different directory, finding the path of the inputs requires a translation relative to \s-1CWD. E\s0.g. either short or long form: .PP .Vb 8 \& makeppinfo \-\-keys=\*(AqCWD SORTED_DEPS\*(Aq obj/b.o \& mppi \-k\*(AqCWD SORTED_DEPS\*(Aq obj/b.o \& obj/b.o: \& CWD=../src \& SORTED_DEPS= \& b.c \& inc/b.h \& /usr/bin/gcc .Ve .PP \&\s-1CWD\s0 is the directory relative to file, from where it was built. That directory is the one from where all relative paths in \s-1SORTED_DEPS\s0 start. This means that under the same directory we have inputs \fIsrc/b.c\fR and \&\fIsrc/inc/b.h\fR and an output \fIobj/b.o\fR. From the viewpoint of \fIb.o\fR, the inputs are \fI../src/b.c\fR and \fI../src/inc/b.h\fR. It does not matter that we gave a relative path for \fIb.o\fR, the information shown would be the same, had we first changed to \fIobj\fR. .SS "The reason for a rebuild" .IX Subsection "The reason for a rebuild" In some cases makepp may be repeatedly rebuilding a seemingly up to date file. If \f(CW\*(C`makepplog\*(C'\fR does not help here, this command gives you the exact state of affairs: .PP .Vb 2 \& makeppinfo \-\-traverse somefile \& mppi \-t somefile .Ve .PP When this reproducibly happens, issue this command before and after, and compare the outputs. The things that differ are the reason of the rebuild. .SS "Proving Consistency" .IX Subsection "Proving Consistency" Sometimes you will change your Makefiles and wonder if they still do the same thing. Here's a command that tells you exactly how makepp built \fIsomefile\fR: .PP .Vb 2 \& makeppinfo \-\-traverse \-\-traverse \-\-keys=\*(AqCWD COMMAND\*(Aq somefile \& mppi \-ttk\*(AqCWD SORTED_DEPS\*(Aq somefile .Ve .PP This will recursively traverse over all dependencies of \fIsomefile\fR and tell you in which directory it issued which command. By running this after the old and after the new build and comparing the outputs, you can see what changed. .PP The same works for testing a new version of makepp, though some older versions would handle whitespace in command continuation lines differently, and there was a bug in sort order, which can make the files come out in a different order. If this is the case for you, let the Shell assemble the sorted arguments: .PP .Vb 2 \& makeppinfo \-\-keys=\*(AqCWD COMMAND\*(Aq \`makeppinfo \-\-traverse \-\-traverse \-\-keys=none somefile|tr \-d :|sort\` \& mppi \-k\*(AqCWD SORTED_DEPS\*(Aq \`mppi \-ttknone somefile|tr \-d :|sort\` .Ve .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" Makeppinfo looks at the following environment variable: .ie n .IP "$MAKEPPINFOFLAGS" 4 .el .IP "\f(CW$MAKEPPINFOFLAGS\fR" 4 .IX Item "$MAKEPPINFOFLAGS" Any flags in this environment variable are interpreted as command line options before any explicit options. Quotes are interpreted like in makefiles. .SH "AUTHOR" .IX Header "AUTHOR" Daniel Pfeiffer (occitan@esperanto.org)