Bug 263958

Summary: FreeBSD Handbook: Updating and Upgrading FreeBSD: add info for re-using /usr/obj for builds
Product: Documentation Reporter: Jonathan Vasquez <jon>
Component: Books & ArticlesAssignee: freebsd-doc (Nobody) <doc>
Status: Open ---    
Severity: Affects Some People CC: doctorwhoguy, imp
Priority: --- Keywords: needs-qa
Version: Latest   
Hardware: Any   
OS: Any   
URL: https://docs.freebsd.org/en/books/handbook/cutting-edge/#updating-src-building-clean-build
Bug Depends on:    
Bug Blocks: 263315    
Attachments:
Description Flags
[patch] Added info for re-using /usr/obj for builds none

Description Jonathan Vasquez 2022-05-13 19:24:14 UTC 
Created attachment 233898 [details]
[patch] Added info for re-using /usr/obj for builds

Started as an observation here: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=263880

I've added a bit more info to the "24.6.4.1. Performing a Clean Build" section since at the moment it reads as if re-using /usr/obj is the default and you have to explicitly clean up. On my FreeBSD 13.1-STABLE box (and also 14-CURRENT, and also stated here: https://forums.freebsd.org/threads/make-buildworld-speed-up-possibilities.73127/#post-445913) I've observed that make will clean up automatically before doing 'buildworld buildkernel'. Adding the -DNO_CACHE option or specifying "WITHOUT_CLEAN=" in /etc/src.conf does what we want (re-using /usr/obj and speeding up builds).

I've also added a warning (based on my previous experience running Gentoo and ccache) letting the user know that re-using build objects could lead to situations where there are bugs/instabilities/weirdness and that if in doubt, one should clean world and compile/install fresh sources.

Since I'm not familiar with building FreeBSD pre v13, someone more experienced than me can confirm and probably help me rewrite this part "Some versions of the FreeBSD build system leave previously-", where "some" is what I don't know, thus I specified 13 or later explicitly. Also if you are confident that there wouldn't be any weirdness with re-using the /usr/obj build objects, we can drop the warning all together.
Comment 1 Jonathan Vasquez 2023-05-05 13:55:01 UTC 
Hello, just following up if there is anything else I need to do for this to be merged in? Thank you!
Comment 2 Warner Losh freebsd_committer freebsd_triage 2023-07-14 12:32:43 UTC 
In both 13 and current, WITHOUT_CLEAN builds have been the default for some ... so I don't understand why you have to add that...
Comment 3 Jonathan Vasquez 2023-07-14 13:27:52 UTC 
Hey Warner,

I'm not sure what you mean. In FreeBSD 13, the default behavior is that every build will start from a clean slate, so objects will be cleaned up. The instructions add/clarify instructions for people that want to re-use those objects again to speed up builds. I've also included a warning about potential issues that could arise from someone deciding to always re-use those objects as well.

- Jonathan
Comment 4 Warner Losh freebsd_committer freebsd_triage 2023-07-20 03:04:03 UTC 
Ah yes. 13.x does have a WITH_CLEAN default. WITHOUT_CLEAN is the default on 14 and newer