Re: Autotools lint tool

[David A. Wheeler]

> On Oct 2, 2019, at 9:58 PM, Gabriel Lisaca <address@hidden> wrote:
> > Sorry, I may have made my question unclear. What I meant by a "lint" tool 
> > for autoconf (and the autotools in general) is to check rather trivial 
> > things like syntax and arguments to macros to conform to what the 
> > documentation intends (e.g., number of arguments to a macro).

On Wed, 2 Oct 2019 23:05:25 -0600, Warren Young <address@hidden> wrote:
> That’s the “better diagnostics” case I brought up in my reply.  Give us a 
> case where one of the Autotools didn’t detect incorrect syntax, and someone 
> will likely add a check for that case or explain why a check can’t be written.

Typical "linters" usually don't look for *incorrect* syntax, since other tools 
already do that, and instead work to identify constructs that are likely wrong 
(even though they are syntactically correct).

That said, I completely agree that it'd be very wise to *first* create a list 
of some checks you'd like to implement, and then find the best way to implement 
them. Then you'll know what the linter will need to do. Also, although autoconf 
and automake are separate tools, they are often used together, and a linter 
needs to be prepared for that combination.

Here are some potential ideas of rules an autotools linter might check:
* Warn about non-empty macro arguments that are non-numbers and aren't 
surrounded by [...]. These are syntactically legal, but can lead to trouble, so 
my simple rule is to always surround non-numbers with [...].
* Warn about whitespace between a macro name and its following invoking '(".
* Warn about whitespace following an argument (after "," or before the closing 
")").
* Require including this line: AC_CONFIG_AUX_DIR([build-aux])
* Require including this line: AC_CONFIG_MACRO_DIR([m4])
* If there's a "Makefile.am", require that it include ACLOCAL_AMFLAGS = -I m4 
--install
* If there's a "Makefile.am", complain bitterly if it includes "SUBDIRS="; that 
suggests a recursive build, which is almost always a terrible idea that leads 
to endless trouble.

These are rules I follow and mention in 
https://www.youtube.com/watch?v=4q_inV9M_us

I would also consider this rule:
* Bitterly whine about any use of m4's changequote.  Yes, it's syntactically 
allowed, but that will totally confuse many people & tools.

I strongly urge you to implement some way to disable the next warning
from a comment *within* the code, so that if a warning is a false positive
it's still possible to end up with a clean result.
Most modern linters (like shellcheck) can do this.

> The Autotools do detect many such cases already.  For example, it’ll yell at 
> you if you name the input to Autoconf “configure.in”, its original name, 
> replaced about 10 years ago with “configure.ac”.

Which is great!  In those cases it's probably not worth implementing the same 
check in your linter (unless, of course, you worry some people will only be 
using old versions of autoconf).  Conversely, if the check can be added to the 
autotools themselves, that might be worth doing.

> I’m not sure a macro language like M4 can be reliably syntax-checked, since 
> it intermixes two or more different languages.  The higher level (M4) doesn’t 
> know the rules of the lower level language, and the lower-level language 
> (shell, in this case) can’t see the higher level, being already pre-processed.
> 
> A “lint” tool for a given pairing could be written, but it’d need to 
> understand both languages’ syntaxes and how they interact.  Tricky.

Not really. In many cases a linter needs only understand the m4 syntax, so that 
it can figure out where the arguments begin & end.  Instead of handling 
arbitrary lower-level syntax, it could simply check only certain arguments of 
certain macros to see if they meet certain rules.

A linter only needs to focus on detecting *common* mistakes and/or enforce a 
style.  Hopefully the style rules themselves exist to help avoid common 
mistakes.  As long as you only try to do that, the inability to handle 
everything is just fine.

--- David A. Wheeler