Bug 76064

Summary: Add more information to build(7)
Product: Documentation Reporter: Gavin Atkinson <gavin.atkinson>
Component: Books & ArticlesAssignee: Tom Rhodes <trhodes>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   
Attachments:
Description Flags
build.7.diff none

Description Gavin Atkinson 2005-01-10 18:20:19 UTC 
	build(7) lacks documentation on some of the more useful
build flags and targets.

How-To-Repeat: 	n/a
Comment 1 Giorgos Keramidas freebsd_committer freebsd_triage 2005-01-11 11:23:31 UTC 
On 2005-01-10 18:10, Gavin Atkinson <gavin.atkinson@ury.york.ac.uk> wrote:
> --- src/share/man/man7/build.7	13 Aug 2004 12:59:46 -0000	1.27
> +++ src/share/man/man7/build.7	10 Jan 2005 18:09:59 -0000
[...]
>  Install the kernel and the kernel modules.
>  .It Cm reinstallkernel
>  Reinstall the kernel and the kernel modules.
> +.It Cm kernel
> +Equivalent to
> +.Cm buildkernel
> +followed by
> +.Cm installkernel

This one looks nice :-)

> +.Sh FLAGS
> +.Bl -tag -width ".Va NO_KERNELDEPEND"
> +.It Va -DNO_MAN
> +Do not build man pages.
> +.It Va -DNO_GAMES
> +Do not build games.
> +.It Va -DNO_DYNAMICROOT
> +Build
> +.Pa /bin
> +and
> +.Pa /sbin
> +statically.
> +.El
> +.Pp
> +Note that there are many other flags which can be used.
> +.Pa /usr/src/Makefile.inc1
> +lists more.
> +.Pp
> +The following flags can dramatically speed up a build,
> +but should be used with care and never after the source
> +has been updated since the last build.
> +They are mainly useful for testing changes to individual
> +files, where dependencies are known to have not changed.
> +.Bl -tag -width ".Va NO_KERNELDEPEND"
> +.It Va -DNO_CLEAN
> +Do not clean before building.
> +.It Va -DNO_KERNELDEPEND
> +Do not recreate dependency information.
> +.It Va -DNO_KERNELCONFIG
> +Do not run
> +.Xr config 8
> +to reconfigure the kernel before building.
> +.El

I'm not sure about adding a FLAGS section.  It would seem a bit
inappropriate to keep descriptions of some NO_XXX options in build(7),
others in make.conf(5) and leave some more documented only in
`src/Makefile.inc1'.

IMHO, we should document make.conf variables in make.conf(5) (i.e. the
NO_DYNAMICROOT, NO_GAMES and NO_MAN options listed above), and only
document in build(7) the following:

    -DNO_CLEANDIR run ${MAKE} clean, instead of ${MAKE} cleandir
    -DNO_CLEAN do not clean at all
    -DNO_KERNELCONFIG do not run config in ${MAKE} buildkernel
    -DNO_KERNELCLEAN do not run ${MAKE} clean in ${MAKE} buildkernel
    -DNO_KERNELDEPEND do not run ${MAKE} depend in ${MAKE} buildkernel
    -DNO_PORTSUPDATE do not update ports in ${MAKE} update
    -DNO_DOCUPDATE do not update doc in ${MAKE} update
    LOCAL_DIRS="list of dirs" to add additional dirs to the SUBDIR list
    TARGET_ARCH="arch" to crossbuild world to a different arch
Comment 2 Tom Rhodes freebsd_committer freebsd_triage 2005-02-24 03:48:10 UTC 
State Changed
From-To: open->patched

Partial patch committed, I agree with Giorgos that the 
make.conf(5) manual page is where some of these other options 
should be documented, and they are.  Everything else was 
committed.  Thanks for the submission.
Comment 3 Tom Rhodes freebsd_committer freebsd_triage 2005-02-24 03:48:10 UTC 
Responsible Changed
From-To: freebsd-doc->trhodes

Over to me, MFC reminder.
Comment 4 Tom Rhodes freebsd_committer freebsd_triage 2005-02-26 05:33:30 UTC 
State Changed
From-To: patched->closed

MFC complete, close this PR.