How to get help with pkgsrc / pkgsrc documentation

[Roland Illig <rillig%NetBSD.org@localhost>]

Hi,

in the last months, the documentation of the pkgsrc infrastructure has 
improved quite a lot. It's just that many people don't know that this 
has happended. Therefore I'm writing this informational mail.

= Tracking down pkgsrc error messages =

Many of the error messages that come from the pkgsrc infrastructure 
contain the file name that produced the error message, together with 
some keywords. Example:

ERROR: [check-wrkref.mk] CHECK_WRKREF must be one of \
       { no tools work objwrkdir }

When you see such an error message and you don't know what it means, you 
can try two things: First, try the pkgsrc help system:

$ make help
usage: /usr/bin/make help topic=<topic>

        <topic> may be a variable name or a make target,
        for example CONFIGURE_DIRS or patch. For convenience,
        you don't need to use uppercase letters when typing
        variable names.


Now, looking at the ERROR: message above, the most useful keyword to 
look for is CHECK_WRKREF. Let's try that:

$ make help topic=check_wrkref

This command lists all the documentation comments in the infrastructure 
where the word CHECK_WRKREF is likely to be defined. The output often 
follows certain conventions, which have not yet been documented and may 
therefore be hard to understand by uninitiated users.

In many cases, the documentation that you get with "make help" is taken 
directly from a file on the infrastructure. You can look at the $Id$ 
line to see which file it is. At the beginning of that file, you will 
find the same text that is shown here.

= Structure of the documentation comments =

This text usually begins with some paragraphs explaining what the 
mentioned file does.

Then, the section on "User-settable variables" lists those variables 
that may be set in the mk.conf file, as described in the pkgsrc 
guide[1]. If you are just _using_ pkgsrc, and not creating your own 
packages, you should not need to read anything after that section.

Then follow the "Package-settable variables", which are interesting to 
package maintainers and may be set in the package anywhere before the 
last line, which is (or at least should be) the one including 
"../../mk/bsd.pkg.mk".

The last (optional) thing is the list of "Variables defined by this 
file". These variables may be used in the package after the file has 
been included. Note that there are two kinds of variables: Some may be 
used in preprocessing directives of make(1), and some may not. This 
distinction is not yet documented.

= Conclusion =

I hope that using the methods described in this mail, you will more 
easily find the relevant pkgsrc documentation and save some time.

Roland

= References =

[1] http://www.netbsd.org/Documentation/pkgsrc/configuring.html