In the 15.0 tree (also in main / CURRENT) the top-level Makefile.inc1 in src (https://cgit.freebsd.org/src/tree/Makefile.inc1?h=releng/15.0) says this on lines 4 and 481 respectively: ``` # -DNO_CLEAN do not clean at all .info The src.conf WITHOUT_CLEAN option can now be used instead of NO_CLEAN. ``` But the documentation for `src.conf` (https://man.freebsd.org/cgi/man.cgi?query=src.conf&apropos=0&sektion=0&manpath=FreeBSD+15.0-RELEASE&arch=default&format=html) only mentions a `WITH_CLEAN`, and the `UPDATING` file says (since 20240729) that no-clean is the default these days. The documentation ought to be consistent; I think that means that the Makefile.inc1 should not mention NO_CLEAN or WITHOUT_CLEAN, but possibly add a line in the documentation section at the top saying "WITH_CLEAN=yes clean the object directory before starting".
You can still set -DNO_CLEAN, and it will still have the same effect as always (will not clean before doing the build, independent of what the default is), and some developers still use it so it should be documented. E.g. if WITH_CLEAN is set in src.conf -DNO_CLEAN on the command line would have the desired effect. Summary of clean build settings: - no-clean builds are the default - as a general rule no-clean builds should be functional. We have a hack to fix up cases where dependencies fail (tools/build/depend-cleanup.sh) as well as a heavier-weight mechanism to trigger a full clean build when necessary (e.g. across compiler updates). If a no-clean build fails it's a bug that should be fixed using one of those two mechanisms - WITH_CLEAN can be set in src.conf to override the no-clean default - -DNOCLEAN and -DNO_CLEAN are accepted on the command line for backwards compatibility and will perform a clean build, overriding a WITH_CLEAN setting
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=a6afa194f382e4f81277fdc7e81e229d3c8caf5f commit a6afa194f382e4f81277fdc7e81e229d3c8caf5f Author: Ed Maste <emaste@FreeBSD.org> AuthorDate: 2026-01-02 20:16:00 +0000 Commit: Ed Maste <emaste@FreeBSD.org> CommitDate: 2026-01-02 20:16:00 +0000 Makefile.inc1: Indicate that no-clean builds are on by default PR: 292130 Makefile.inc1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Thanks Ed, that clarifies a little, but that wasn't the confusing bit for me. Let me try again: - if you set `NO_CLEAN`, then line 481 will print an info message - the info message says you can use `WITHOUT_CLEAN` - but `WITHOUT_CLEAN` is not, as far as I can tell, a knob you can set in `src.conf` The documentation for `src.conf` says that `WITH_CLEAN` is a knob, which has the opposite meaning. I think that we ought to also remove the informational message: when `NO_CLEAN` is on, even as the default, there's no need to explain anything additional.
> Thanks Ed, that clarifies a little, but that wasn't the confusing bit for me. Yeah, I didn't think this was sufficient and so didn't close the PR, just a realization that at the very least the description of NO_CLEAN in Makefile.inc1 should indicate that by default it doesn't do anything / isn't needed. I'm trying to find a good way to handle this. I wanted to remove NO_CLEAN / NOCLEAN but had pushback at the time; maybe folks would be OK with it now. The message was intended to encourage people to use WITH_CLEAN or WITHOUT_CLEAN instead of setting -DNO_CLEAN on the command line, to avoid a surprise if support for NO_CLEAN gets removed. If we're certain we're never going to change the default we can just remove the message and the handling for NO_CLEAN; then, setting -DNO_CLEAN would do nothing just as any other unhandled option like "-DNO_BUGS". You can in fact set WITHOUT_CLEAN in src.conf, it's just not needed as it's the default. This is true for all of the WITH_/WITHOUT_ knobs. There are some knobs that might change defaults on main vs release branches (e.g. WITH_MALLOC_PRODUCTION) so there are situations where users could leave the setting in place.
A commit in branch stable/15 references this bug: URL: https://cgit.FreeBSD.org/src/commit/?id=765442a8b5f1fda45c5a7bc10de8e56d87fc8845 commit 765442a8b5f1fda45c5a7bc10de8e56d87fc8845 Author: Ed Maste <emaste@FreeBSD.org> AuthorDate: 2026-01-02 20:16:00 +0000 Commit: Ed Maste <emaste@FreeBSD.org> CommitDate: 2026-01-06 14:30:11 +0000 Makefile.inc1: Indicate that no-clean builds are on by default PR: 292130 (cherry picked from commit a6afa194f382e4f81277fdc7e81e229d3c8caf5f) Makefile.inc1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Closing since I'm satisfied with the wording now.