662580 - makefiles: add debug macros and 'help' documentation targets

Status: RESOLVED WONTFIX

(Firefox Build System :: General, defect)

Description

[Joey Armstrong [:joey]]

Attachment: Make debug macros and a skeleton help hierarchy

Add help targets to begin documenting makefile elements.
Add trace macros [triggered on demand] to aide in debugging

Comment 1

[Joey Armstrong [:joey]]

Comment on attachment 537831 [details] [diff] [review]
Make debug macros and a skeleton help hierarchy

non-invasive help targets that can be used to document makefile elements

Comment 2

[Benjamin Smedberg]

Comment on attachment 537831 [details] [diff] [review]
Make debug macros and a skeleton help hierarchy

Is this supposed to be documentation of the meaning of makefile variables, or their values? We already have rules to dump the values of the most important variables at the end of rules.mk. But in general, I think it's kinda weird/overkill to use makefiles to document the system, instead of a README file or our standard doc website. We have previously tried to document the various variable meanings on MDC, and I think I'd prefer to keep it there instead of moving all that in-tree. Then "make help" could just be 
help:
    echo "See https://developer.mozilla.org/en/How_Mozilla%27s_build_system_works for details about the Mozilla build system."

Also, it seems really complex to use make to provide these docs, instead of writing a README.build file.

Ted should probably make the final decision on this, though, since he's the module owner.

Comment 3

[Joey Armstrong [:joey]]

Attachment: Make debug macros and a skeleton help hierarchy

Same basic set of files included with the earlier patch.
Removed a few stray files that were checked in.
Renamed a few files to match the *.mk convention.

Comment 4

[Joey Armstrong [:joey]]

(In reply to comment #2)
> Comment on attachment 537831 [details] [diff] [review] [review]
> Make debug macros and a skeleton help hierarchy
> 
> Is this supposed to be documentation of the meaning of makefile variables,
> or their values? We already have rules to dump the values of the most
> important variables at the end of rules.mk. But in general, I think it's
> kinda weird/overkill to use makefiles to document the system, instead of a
> README file or our standard doc website. We have previously tried to
> document the various variable meanings on MDC, and I think I'd prefer to
> keep it there instead of moving all that in-tree. Then "make help" could
> just be 
> help:
>     echo "See
> https://developer.mozilla.org/en/How_Mozilla%27s_build_system_works for
> details about the Mozilla build system."
> 
> Also, it seems really complex to use make to provide these docs, instead of
> writing a README.build file.
> 
> Ted should probably make the final decision on this, though, since he's the
> module owner.

Ok I'll check on the wiki writeup.

The intent was to provide help directly within the sandbox w/o having to search for content offline.  Grep can be used for specifics:

  % cd obj--ff-dbg/db
  % gmake help.variables | grep FOOBAR


The structure would also allow documenting macro values { possibly derived }:

[phantasm:db] gmake help.variables.OS_ARCH
===========================================================================
Topic: help.variables.OS_ARCH
===========================================================================
AIX
ANDROID
BSD_OS
BeOS
DGUX
Darwin
DragonFly
FreeBSD

Comment 5

[Joey Armstrong [:joey]]

Preferred answer is to maintain text in MDC/wiki rather than generating content from the sandbox.  This will allow the community to be involved with maintaining documentation if they choose to.