Pkgsrc documentation
From NetBSD Wiki
Like almost every open source project, pkgsrc is not documented as complete as possible. This article describes where one can find the existing documentation and some ideas to improve the situation and to finally provide the best documentation ever possible.
Contents |
Existing documentation
- See the developer FAQ in the pkgsrc guide.
Ideas and future plans
How variables should be documented
Since the pkgsrc API is largely defined in terms of variables, each such variable should have its own reference page, with the following sections:
- Name: The name of the variable
- Description:
- What is the purpose of the variable?
- How is it typically used?
- Which part of pkgsrc may set the variable? (see also pkglint's view of variables).
- system-provided fixed values
- user-settable variables with system-provided default values
- package-settable variables with system-provided default values
- ...
- At what time can the variable be used?
- as soon as its definition is loaded, or
- only at run-time, after all variables have been loaded completely.
- Caveats: What have people done wrong so far with this variable?
- Limitations: Things that would be nice but cannot be achieved using this variable.
- Bugs: Why should this variable be deprecated and replaced with something else?
- History: When did it appear, what had been before, when has it been deprecated, obsoleted and removed?
- See also: References to other variables.
How make targets should be documented
The other big part are make targets. Each make target should have the following things documented:
- Name: The name of the target
- Type:
- hook: may not have any commands associated with it, except for the file that defines the hook. There, a single command, ${DO_NADA} must be associated with it.
- package-hook: only a package itself may associate code with this target, for other file it is equivalent to a hook)
- private helper target: serves similar purposes as functions or procedures in conventional programming languages
- publicly usable target: performs a certain task, usually associated with the current package
- "read-only" targets (such as debug, help) just print some information
- modifying targets (such as extract, install) modify some things (as the name says ;))
- Description:
- What does the target do by default?
- What should it be used for?
- What should it not be used for?
- Which variables are involved in the default behavior?
- Caveats,
- Limitations,
- Bugs,
- History,
- See also
