> From: Paul Smith <psm...@gnu.org> > Date: Sat, 26 Aug 2023 12:48:05 -0400 > > I added a new appendix to the GNU make manual for troubleshooting help; > I haven't pushed it yet. See below. Comments welcome.
Thanks, this sounds very useful. Some comments below. > If you have problems with GNU Make, first consider the type of > problem you are having. Problems will generally be in one of these > categories: > > * A syntax or other error was reported when 'make' attempted to parse > your makefiles. > > * A command that 'make' invoked failed (exited with a non-0 exit > code). > > * The command that 'make' invoked was not the one you expected. > > * 'make' was not able to find a rule to build a target. > > * 'make' rebuilds a target that you didn't think was out of date. > > * Or, 'make' did not rebuild a target that you expected it to build. This checklist is very useful, but to make it even more useful, it lacks two things: . an example of error message that indicates each kind of problem . a cross-reference to where the details are It is possible that just a cross-reference could be enough, since you already have an example of an error message there, but I still suggest to maybe include it here: the appendix is large, and describes very different problems, so being able to quickly go to the relevant part is invaluable IME. > C.2 Errors Reported by Commands > =============================== > > If GNU Make parses the makefiles correctly and runs a command to rebuild > a target, it expects that command to exit with an error code of '0' (for > success). Any other exit code will be reported by 'make' as a failure > and will generate an error message with this form: > > make: *** [Makefile:10: target] Error 2 > > All the information you need to find that command are given: the name > of the makefile (here 'Makefile') and line number (here '10') of the > command make invoked, the target (here 'target') that make was trying to > build, and finally the exit code of the command (here '2'). I would suggest to add here a short description of how to interpret these exit codes. The codes 2 and -1 are very frequent, so maybe explain them right here. For the other, I would tell the reader to look in the documentation of the failed command. > If the makefile doesn't provide a rule for this target, you can add > one. If there is a rule which you intended 'make' to use to build this > target and it wasn't used, the most common reasons for this are: > > * The target was misspelled. You should consider following the _DRY_ > principle (Don't Repeat Yourself) by assigning file names (targets > and prerequisites) to makefile variables and using those variables > rather than retyping the file names. > > * The target is in a different directory. 'make' considers the > targets 'target' and 'dir/target' (for example) to be different > targets. If you are using rules that create targets outside of the > current working directory, be sure you correctly prefix them with > their directories everywhere that they appear in the makefile. > > * A pattern rule didn't match because one of its prerequisites cannot > be built. Pattern rules will only be used when *all* prerequisites > can be satisfied: either they exist already or 'make' can find a > way to build them. If any prerequisite cannot be created, then the > pattern does not match and 'make' will continue looking for another > matching pattern. If no matching pattern can be found, then 'make' > will fail. I would add one more item: a pattern rule has an error. It might be included in the first item above, but it is not obvious, and pattern rules are sometimes tricky to write. > To troubleshoot these issues (*note Strategies for Troubleshooting: > Troubleshooting Strategies.), remove the '@' prefix in your recipe when > 'make' does rebuild the target so you can see what command is being > invoked. Removing @ is not always enough. Many makefiles nowadays need you to say "make V=1" to override the default verbosity level. I suggest to mention that. > Remove '@' prefixes > ------------------- > > If your makefile is using the '@' prefix in recipes to prevent 'make' > from echoing the commands it invokes (*note Recipe Echoing: Echoing.), > the first thing you should do is remove this token so that you can see > the full command line that 'make' is running. This will help you > understand what your recipe is actually doing. And here. Thanks!
