Add option UNIFIED_OBJDIR, on by default, which moves the default build OBJDIR.

This changes the build OBJDIR from the older style of /usr/obj/<srcdir> for
native builds, and /usr/obj/<target>.<target_arch>/<srcdir> for cross builds to
a new simpler format of /usr/obj/<srcdir>/<target>.<target_arch>.  This
new format is used regardless of cross or native build.  It allows
easier management of multiple source tree object directories.

The UNIFIED_OBJDIR option will be removed and its feature made permanent
for the 12.0 release.

Relnotes:	yes (don't note UNIFIED_OBJDIR option since it will be removed)
Prior work:	D3711 D874
Reviewed by:	gjb, sjg
Discussed at:	https://lists.freebsd.org/pipermail/freebsd-arch/2016-May/017805.html
Discussed with:	emaste
Sponsored by:	Dell EMC Isilon
Differential Revision:	https://reviews.freebsd.org/D12840

14 files changed, 193 insertions, 95 deletions

diff --git a/Makefile.inc1 b/Makefile.inc1
index ea30d6d90d407..5d33ac280b0fe 100644
--- a/Makefile.inc1
+++ b/Makefile.inc1
@@ -78,18 +78,11 @@ MK_CLANG_BOOTSTRAP=	no
 MK_GCC_BOOTSTRAP=	no
 .endif
 
-MAKEOBJDIRPREFIX?=	/usr/obj
-.if ${MACHINE} == ${TARGET} && ${MACHINE_ARCH} == ${TARGET_ARCH} && !defined(CROSS_BUILD_TESTING)
-OBJTREE=	${MAKEOBJDIRPREFIX}
-.else
-OBJTREE=	${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}
-.endif
-
 # Pull in compiler metadata from buildworld/toolchain if possible to avoid
 # running CC from bsd.compiler.mk.
 .if make(installworld) || make(install) || make(distributeworld) || \
     make(stageworld)
-.-include "${OBJTREE}${.CURDIR}/compiler-metadata.mk"
+.-include "${OBJTOP}/compiler-metadata.mk"
 .endif
 
 # Pull in COMPILER_TYPE and COMPILER_FREEBSD_VERSION early.
@@ -450,7 +443,7 @@ BUILD_ARCH!=	uname -p
 .error To cross-build, set TARGET_ARCH.
 .endif
 .endif
-WORLDTMP=	${OBJTREE}${.CURDIR}/tmp
+WORLDTMP?=	${OBJTOP}/tmp
 BPATH=		${CCACHE_WRAPPER_PATH_PFX}${WORLDTMP}/legacy/usr/sbin:${WORLDTMP}/legacy/usr/bin:${WORLDTMP}/legacy/bin
 XPATH=		${WORLDTMP}/usr/sbin:${WORLDTMP}/usr/bin
 STRICTTMPPATH=	${BPATH}:${XPATH}
@@ -508,7 +501,7 @@ MINIMUM_SUPPORTED_OSREL?= 900044
 MINIMUM_SUPPORTED_REL?= 9.1
 
 # Common environment for world related stages
-CROSSENV+=	MAKEOBJDIRPREFIX=${OBJTREE} \
+CROSSENV+=	\
 		MACHINE_ARCH=${TARGET_ARCH} \
 		MACHINE=${TARGET} \
 		CPUTYPE=${TARGET_CPUTYPE}
@@ -543,7 +536,7 @@ BMAKE=		MAKEOBJDIRPREFIX=${WORLDTMP} \
 		${BSARGS}
 
 # build-tools stage
-TMAKE=		MAKEOBJDIRPREFIX=${OBJTREE} \
+TMAKE=		\
 		${BMAKEENV} ${MAKE} ${WORLD_FLAGS} -f Makefile.inc1 \
 		TARGET=${TARGET} TARGET_ARCH=${TARGET_ARCH} \
 		DESTDIR= \
@@ -670,10 +663,10 @@ LIBCOMPAT= SOFT
 META_MODE_BAD_ABI_VERS+=	1200031
 
 .if !defined(OBJDIR_HOST_OSRELDATE)
-.if exists(${OBJTREE}${.CURDIR}/host-osreldate.h)
+.if exists(${OBJTOP}/host-osreldate.h)
 OBJDIR_HOST_OSRELDATE!=	\
     awk '/^\#define[[:space:]]*__FreeBSD_version/ { print $$3 }' \
-    ${OBJTREE}${.CURDIR}/host-osreldate.h
+    ${OBJTOP}/host-osreldate.h
 .elif exists(${WORLDTMP}/usr/include/osreldate.h)
 OBJDIR_HOST_OSRELDATE=	0
 .endif
@@ -778,36 +771,36 @@ _cleanobj_fast_depend_hack: .PHONY
 # 20160829  r305012  ptrace
 # 20170624  r320278  fstat fstatat fstatfs getdirentries getfsstat statfs
 .for f in fstat fstatat fstatfs getdirentries getfsstat ptrace statfs           
-.if exists(${OBJTREE}${.CURDIR}/lib/libc/.depend.${f}.o)
+.if exists(${OBJTOP}/lib/libc/.depend.${f}.o)
 	@if egrep -qw '${f}\.[sS]' \
-	    ${OBJTREE}${.CURDIR}/lib/libc/.depend.${f}.o; then \
+	    ${OBJTOP}/lib/libc/.depend.${f}.o; then \
 		echo Removing stale dependencies for ${f} syscall wrappers; \
-		rm -f ${OBJTREE}${.CURDIR}/lib/libc/.depend.${f}.* \
-		   ${LIBCOMPAT:D${LIBCOMPAT_OBJTREE}${.CURDIR}/lib/libc/.depend.${f}.*}; \
+		rm -f ${OBJTOP}/lib/libc/.depend.${f}.* \
+		   ${LIBCOMPAT:D${LIBCOMPAT_OBJTOP}/lib/libc/.depend.${f}.*}; \
 	fi
 .endif
 .endfor
 # 20170607 remove stale dependencies for utimens* wrappers removed in r319663
 .for f in futimens utimensat
-.if exists(${OBJTREE}${.CURDIR}/lib/libc/.depend.${f}.o)
+.if exists(${OBJTOP}/lib/libc/.depend.${f}.o)
 	@if egrep -q '/${f}.c' \
-	    ${OBJTREE}${.CURDIR}/lib/libc/.depend.${f}.o; then \
+	    ${OBJTOP}/lib/libc/.depend.${f}.o; then \
 		echo Removing stale dependencies for ${f} syscall wrappers; \
-		rm -f ${OBJTREE}${.CURDIR}/lib/libc/.depend.${f}.* \
-		   ${LIBCOMPAT:D${LIBCOMPAT_OBJTREE}${.CURDIR}/lib/libc/.depend.${f}.*}; \
+		rm -f ${OBJTOP}/lib/libc/.depend.${f}.* \
+		   ${LIBCOMPAT:D${LIBCOMPAT_OBJTOP}/lib/libc/.depend.${f}.*}; \
 	fi
 .endif
 .endfor
 # 20170523 remove stale generated asm files for functions which are no longer
 # syscalls after r302092 (pipe) and r318736 (others)
 .for f in getdents lstat mknod pipe stat
-.if exists(${OBJTREE}${.CURDIR}/lib/libc/${f}.s) || \
-    exists(${OBJTREE}${.CURDIR}/lib/libc/${f}.S)
+.if exists(${OBJTOP}/lib/libc/${f}.s) || \
+    exists(${OBJTOP}/lib/libc/${f}.S)
 	@echo Removing stale generated ${f} syscall files
-	@rm -f ${OBJTREE}${.CURDIR}/lib/libc/${f}.* \
-	    ${OBJTREE}${.CURDIR}/lib/libc/.depend.${f}.* \
-	    ${LIBCOMPAT:D${LIBCOMPAT_OBJTREE}${.CURDIR}/lib/libc/${f}.*} \
-	    ${LIBCOMPAT:D${LIBCOMPAT_OBJTREE}${.CURDIR}/lib/libc/.depend.${f}.*}
+	@rm -f ${OBJTOP}/lib/libc/${f}.* \
+	    ${OBJTOP}/lib/libc/.depend.${f}.* \
+	    ${LIBCOMPAT:D${LIBCOMPAT_OBJTOP}/lib/libc/${f}.*} \
+	    ${LIBCOMPAT:D${LIBCOMPAT_OBJTOP}/lib/libc/.depend.${f}.*}
 .endif
 .endfor
 
@@ -899,7 +892,7 @@ _cross-tools:
 	@echo "--------------------------------------------------------------"
 	@echo ">>> stage 3: cross tools"
 	@echo "--------------------------------------------------------------"
-	@rm -f ${OBJTREE}${.CURDIR}/compiler-metadata.mk
+	@rm -f ${OBJTOP}/compiler-metadata.mk
 	${_+_}cd ${.CURDIR}; ${XMAKE} cross-tools
 	${_+_}cd ${.CURDIR}; ${XMAKE} kernel-tools
 _build-metadata:
@@ -1071,7 +1064,7 @@ __installcheck_UGID: .PHONY
     (empty(DESTDIR) || ${DESTDIR} == "/") && empty(BYPASS_INSTALLCHECK_SH)
 _installcheck_world: __installcheck_sh_check
 __installcheck_sh_check: .PHONY
-	@if [ "`${OBJTREE}${.CURDIR}/rescue/rescue/rescue sh -c 'echo OK'`" != \
+	@if [ "`${OBJTOP}/rescue/rescue/rescue sh -c 'echo OK'`" != \
 	    OK ]; then \
 		echo "rescue/sh check failed, installation aborted" >&2; \
 		false; \
@@ -1333,7 +1326,7 @@ INSTKERNNAME?=	kernel
 
 KERNSRCDIR?=	${.CURDIR}/sys
 KRNLCONFDIR=	${KERNSRCDIR}/${TARGET}/conf
-KRNLOBJDIR=	${OBJTREE}${KERNSRCDIR}
+KRNLOBJDIR=	${OBJTOP}${KERNSRCDIR:C,^${.CURDIR},,}
 KERNCONFDIR?=	${KRNLCONFDIR}
 
 BUILDKERNELS=
@@ -1541,9 +1534,9 @@ stagekernel: .PHONY
 	${_+_}${MAKE} -C ${.CURDIR} ${.MAKEFLAGS} distributekernel
 
 PORTSDIR?=	/usr/ports
-WSTAGEDIR?=	${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH}/worldstage
-KSTAGEDIR?=	${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH}/kernelstage
-REPODIR?=	${MAKEOBJDIRPREFIX}${.CURDIR}/repo
+WSTAGEDIR?=	${OBJTOP}/worldstage
+KSTAGEDIR?=	${OBJTOP}/kernelstage
+REPODIR?=	${OBJROOT}repo
 PKGSIGNKEY?=	# empty
 
 .ORDER:		stage-packages create-packages
@@ -1806,10 +1799,10 @@ legacy: .PHONY
 	${_+_}@${ECHODIR} "===> ${_tool} (obj,includes,all,install)"; \
 	    cd ${.CURDIR}/${_tool}; \
 	    if [ -z "${NO_OBJ}" ]; then ${MAKE} DIRPRFX=${_tool}/ obj; fi; \
-	    ${MAKE} DIRPRFX=${_tool}/ DESTDIR=${MAKEOBJDIRPREFIX}/legacy includes; \
+	    ${MAKE} DIRPRFX=${_tool}/ DESTDIR=${WORLDTMP}/legacy includes; \
 	    ${MAKE} DIRPRFX=${_tool}/ MK_INCLUDES=no all; \
 	    ${MAKE} DIRPRFX=${_tool}/ MK_INCLUDES=no \
-	        DESTDIR=${MAKEOBJDIRPREFIX}/legacy install
+	        DESTDIR=${WORLDTMP}/legacy install
 .endfor
 
 #
@@ -1953,7 +1946,7 @@ ${_bt}-${_tool}: .PHONY .MAKE
 		cd ${.CURDIR}/${_tool}; \
 		if [ -z "${NO_OBJ}" ]; then ${MAKE} DIRPRFX=${_tool}/ obj; fi; \
 		${MAKE} DIRPRFX=${_tool}/ all; \
-		${MAKE} DIRPRFX=${_tool}/ DESTDIR=${MAKEOBJDIRPREFIX}/legacy install
+		${MAKE} DIRPRFX=${_tool}/ DESTDIR=${WORLDTMP}/legacy install
 
 bootstrap-tools: ${_bt}-${_tool}
 .endfor
@@ -2011,9 +2004,9 @@ build-tools: build-tools_${_tool}
 # kernel-tools: Build kernel-building tools
 #
 kernel-tools: .PHONY
-	mkdir -p ${MAKEOBJDIRPREFIX}/usr
+	mkdir -p ${WORLDTMP}/usr
 	mtree -deU -f ${.CURDIR}/etc/mtree/BSD.usr.dist \
-	    -p ${MAKEOBJDIRPREFIX}/usr >/dev/null
+	    -p ${WORLDTMP}/usr >/dev/null
 
 #
 # cross-tools: All the tools needed to build the rest of the system after
@@ -2089,7 +2082,7 @@ cross-tools: .MAKE .PHONY
 		cd ${.CURDIR}/${_tool}; \
 		if [ -z "${NO_OBJ}" ]; then ${MAKE} DIRPRFX=${_tool}/ obj; fi; \
 		${MAKE} DIRPRFX=${_tool}/ all; \
-		${MAKE} DIRPRFX=${_tool}/ DESTDIR=${MAKEOBJDIRPREFIX} install
+		${MAKE} DIRPRFX=${_tool}/ DESTDIR=${WORLDTMP} install
 .endfor
 
 #
@@ -2100,7 +2093,8 @@ cross-tools: .MAKE .PHONY
 # already built.  It then installs the static tools to NXBDESTDIR for Poudriere
 # to pickup.
 #
-NXBOBJDIR=	${MAKEOBJDIRPREFIX}/nxb/${TARGET}.${TARGET_ARCH}
+NXBOBJROOT=	${OBJROOT}nxb/
+NXBOBJTOP=	${NXBOBJROOT}${TARGET}.${TARGET_ARCH}
 NXTP?=		/nxb-bin
 .if ${NXTP:N/*}
 .error NXTP variable should be an absolute path
@@ -2181,11 +2175,9 @@ NXBDIRS+=	gnu/usr.bin/cc
 NXBDIRS+=	gnu/usr.bin/binutils
 .endif
 
-NXBMAKEENV+= \
-	MAKEOBJDIRPREFIX=${NXBOBJDIR:Q}
-
 NXBMAKEARGS+= \
-	OBJTREE=${NXBOBJDIR:Q} \
+	OBJTOP=${NXBOBJTOP:Q} \
+	OBJROOT=${NXBOBJROOT:Q} \
 	-DNO_SHARED \
 	-DNO_CPU_CFLAGS \
 	-DNO_PIC \
@@ -2759,7 +2751,7 @@ builddtb: .PHONY
 # in this makefile.  We don't do a cleandir walk if MK_AUTO_OBJ is yes
 # since it is not possible for files to land in the wrong place.
 #
-BW_CANONICALOBJDIR:=${OBJTREE}${.CURDIR}
+BW_CANONICALOBJDIR:=${OBJTOP}
 cleanworld: .PHONY
 .if exists(${BW_CANONICALOBJDIR}/)
 	-rm -rf ${BW_CANONICALOBJDIR}/*
@@ -2791,7 +2783,7 @@ XDTP?=/usr/${XDDIR}
 .error XDTP variable should be an absolute path
 .endif
 
-CDBENV=MAKEOBJDIRPREFIX=${MAKEOBJDIRPREFIX}/${XDDIR} \
+CDBENV=MAKEOBJDIRPREFIX=${OBJTOP}/${XDDIR} \
 	INSTALL="sh ${.CURDIR}/tools/install.sh"
 CDENV= ${CDBENV} \
 	TOOLS_PREFIX=${XDTP}
@@ -2816,7 +2808,7 @@ CD2ENV=${CDENV} CC="${CC} ${CD2CFLAGS}" CXX="${CXX} ${CD2CXXFLAGS} ${CD2CFLAGS}"
 	CPP="${CPP} ${CD2CFLAGS}" \
 	MACHINE=${TARGET} MACHINE_ARCH=${TARGET_ARCH}
 
-CDTMP=	${MAKEOBJDIRPREFIX}/${XDDIR}/${.CURDIR}/tmp
+CDTMP=	${OBJTOP}/${XDDIR}/tmp
 CDMAKE=${CDENV} PATH=${CDTMP}/usr/bin:${PATH} ${MAKE} ${NOFUN}
 CD2MAKE=${CD2ENV} PATH=${CDTMP}/usr/bin:${XDDESTDIR}/usr/bin:${PATH} ${MAKE} ${NOFUN}
 .if ${MK_META_MODE} != "no"
diff --git a/Makefile.libcompat b/Makefile.libcompat
index 29319f6dfe7e5..5ec84fd42ca23 100644
--- a/Makefile.libcompat
+++ b/Makefile.libcompat
@@ -70,7 +70,7 @@ LIBSOFTWMAKEFLAGS=        -DCOMPAT_SOFTFP
 # Generic code for each type.
 # Set defaults based on type.
 libcompat=	${LIBCOMPAT:tl}
-_LIBCOMPAT_MAKEVARS=	_OBJTREE TMP CPUFLAGS CFLAGS CXXFLAGS WMAKEENV \
+_LIBCOMPAT_MAKEVARS=	_OBJTOP TMP CPUFLAGS CFLAGS CXXFLAGS WMAKEENV \
 			WMAKEFLAGS WMAKE
 .for _var in ${_LIBCOMPAT_MAKEVARS}
 .if !empty(LIB${LIBCOMPAT}${_var})
@@ -79,8 +79,8 @@ LIBCOMPAT${_var}?=	${LIB${LIBCOMPAT}${_var}}
 .endfor
 
 # Shared flags
-LIBCOMPAT_OBJTREE?=	${OBJTREE}${.CURDIR}/obj-lib${libcompat}
-LIBCOMPATTMP?=		${LIBCOMPAT_OBJTREE}/tmp
+LIBCOMPAT_OBJTOP?=	${OBJTOP}/obj-lib${libcompat}
+LIBCOMPATTMP?=		${LIBCOMPAT_OBJTOP}/tmp
 
 LIBCOMPATCFLAGS+=	${LIBCOMPATCPUFLAGS} \
 			-L${LIBCOMPATTMP}/usr/lib${libcompat} \
@@ -107,7 +107,8 @@ LIBCOMPATCXXFLAGS+=	-isystem ${LIBCOMPATTMP}/usr/include/c++/v1 -std=c++11 \
 .endif
 
 # Yes, the flags are redundant.
-LIBCOMPATWMAKEENV+= MAKEOBJDIRPREFIX=${LIBCOMPAT_OBJTREE} \
+LIBCOMPATWMAKEENV+= \
+		MAKEOBJDIRPREFIX=${LIBCOMPAT_OBJTOP} \
 		INSTALL="sh ${.CURDIR}/tools/install.sh" \
 		PATH=${TMPPATH} \
 		SYSROOT=${LIBCOMPATTMP} \
@@ -183,7 +184,8 @@ build${libcompat}: .PHONY
 	${_+_}cd ${.CURDIR}/${_dir}; \
 	    WORLDTMP=${WORLDTMP} \
 	    MAKEFLAGS="-m ${.CURDIR}/tools/build/mk ${.MAKEFLAGS}" \
-	    MAKEOBJDIRPREFIX=${LIBCOMPAT_OBJTREE} ${MAKE} SSP_CFLAGS= DESTDIR= \
+	    MAKEOBJDIRPREFIX=${LIBCOMPAT_OBJTOP} \
+	    ${MAKE} SSP_CFLAGS= DESTDIR= \
 	    DIRPRFX=${_dir}/ -DNO_LINT -DNO_CPU_CFLAGS MK_WARNS=no MK_CTF=no \
 	    build-tools
 .endfor
diff --git a/UPDATING b/UPDATING
index 5b07e79c360ca..3808ea0167af5 100644
--- a/UPDATING
+++ b/UPDATING
@@ -51,6 +51,17 @@ NOTE TO PEOPLE WHO THINK THAT FreeBSD 12.x IS SLOW:
 
 ****************************** SPECIAL WARNING: ******************************
 
+20171101:
+	The default MAKEOBJDIR has changed from /usr/obj/<srcdir> for native
+	builds, and /usr/obj/<arch>/<srcdir> for cross-builds, to a unified
+	/usr/obj/<srcdir>/<arch>.  This behavior can be changed to the old
+	format by setting WITHOUT_UNIFIED_OBJDIR=yes in /etc/src-env.conf,
+	the environment, or with -DWITHOUT_UNIFIED_OBJDIR when building.
+	The UNIFIED_OBJDIR option is a transitional feature that will be
+	removed for 12.0 release; please migrate to the new format for any
+	tools by looking up the OBJDIR used by 'make -V .OBJDIR' means rather
+	than hardcoding paths.
+
 20171028:
 	The native-xtools target no longer installs the files by default to the
 	OBJDIR.  Use the native-xtools-install target with a DESTDIR to install
diff --git a/release/arm64/RPI3.conf b/release/arm64/RPI3.conf
index a8eaff9bf04d3..8636ddbfa8ba4 100644
--- a/release/arm64/RPI3.conf
+++ b/release/arm64/RPI3.conf
@@ -42,13 +42,11 @@ arm_install_uboot() {
 			"${DTB_REPO}/overlays/${_OL}?raw=true"
 	done
 
-	_OBJDIR="$(chroot ${CHROOTDIR} make -C ${WORLDDIR} -V .OBJDIR)"
-	_OBJDIR="$(realpath ${_OBJDIR})"
-	if [ -d "${CHROOTDIR}/${_OBJDIR%%/usr/src}/${EMBEDDED_TARGET}.${EMBEDDED_TARGET_ARCH}" ]; then
-		BOOTFILES="/${_OBJDIR%%/usr/src}/${EMBEDDED_TARGET}.${EMBEDDED_TARGET_ARCH}/usr/src/sys/boot"
-	else
-		BOOTFILES="/${_OBJDIR}/sys/boot"
-	fi
+	BOOTFILES="$(chroot ${CHROOTDIR} \
+	    env TARGET=${EMBEDDED_TARGET} TARGET_ARCH=${EMBEDDED_TARGET_ARCH} \
+	    WITH_UNIFIED_OBJDIR=yes \
+	    make -C ${WORLDDIR}/sys/boot -V .OBJDIR)"
+	BOOTFILES="$(realpath ${BOOTFILES})"
 
 	chroot ${CHROOTDIR} mkdir -p ${FATMOUNT}/EFI/BOOT
 	chroot ${CHROOTDIR} cp -p ${BOOTFILES}/efi/boot1/boot1.efi \
diff --git a/release/tools/vmimage.subr b/release/tools/vmimage.subr
index 6ba7e185a33ff..78e7839d64e4f 100644
--- a/release/tools/vmimage.subr
+++ b/release/tools/vmimage.subr
@@ -14,13 +14,10 @@ write_partition_layout() {
 		SWAPOPT="-p freebsd-swap/swapfs::${SWAPSIZE}"
 	fi
 
-	_OBJDIR="$(make -C ${WORLDDIR} -V .OBJDIR)"
-	_OBJDIR="$(realpath ${_OBJDIR})"
-	if [ -d "${_OBJDIR%%/usr/src}/${TARGET}.${TARGET_ARCH}" ]; then
-		BOOTFILES="/${_OBJDIR%%/usr/src}/${TARGET}.${TARGET_ARCH}/usr/src/sys/boot"
-	else
-		BOOTFILES="/${_OBJDIR}/sys/boot"
-	fi
+	BOOTFILES="$(env TARGET=${TARGET} TARGET_ARCH=${TARGET_ARCH} \
+	    WITH_UNIFIED_OBJDIR=yes \
+	    make -C ${WORLDDIR}/sys/boot -V .OBJDIR)"
+	BOOTFILES="$(realpath ${BOOTFILES})"
 
 	case "${TARGET}:${TARGET_ARCH}" in
 		amd64:amd64 | i386:i386)
diff --git a/share/man/man7/build.7 b/share/man/man7/build.7
index e9b22cd46abdc..b0b634654c84d 100644
--- a/share/man/man7/build.7
+++ b/share/man/man7/build.7
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 11, 2017
+.Dd October 26, 2017
 .Dt BUILD 7
 .Os
 .Sh NAME
@@ -82,18 +82,7 @@ or under
 if variable
 .Va MAKEOBJDIRPREFIX
 is not set.
-For a given source directory, its canonical object directory
-would be
-.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
-if
-.Xr make 1
-variable
-.Va MAKEOBJDIRPREFIX
-is set, or
-.Pa /usr/obj${.CURDIR}
-if this variable is not set.
-Cross-builds set the object directory as described in the
-documentation for the
+The canonical object directory is described in the documentation for the
 .Cm buildworld
 target below.
 .Pp
@@ -201,10 +190,18 @@ by setting the
 .Pa MAKEOBJDIRPREFIX
 .Xr make 1
 variable.
-The actual build location prefix used is
+The actual build location prefix used
+depends on the
+.Va WITH_UNIFIED_OBJDIR
+option from
+.Xr src.conf 5 .
+If enabled it is
+.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH}
+for all builds.
+If disabled it is
 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
 for native builds, and
-.Pa ${MAKEOBJDIRPREFIX}/${TARGET}${.CURDIR}
+.Pa ${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}${.CURDIR}
 for cross builds and native builds with variable
 .Va CROSS_BUILD_TESTING
 set.
@@ -460,8 +457,12 @@ Defines the prefix for directory names in the tree of built objects.
 Defaults to
 .Pa /usr/obj
 if not defined.
-This variable should only be set in the environment and not via
+This variable should only be set in the environment or
+.Pa /etc/src-env.conf
+and not via
 .Pa /etc/make.conf
+or
+.Pa /etc/src.conf
 or the command line.
 .It Va NO_WERROR
 If defined, compiler warnings will not cause the build to halt,
diff --git a/share/mk/bsd.obj.mk b/share/mk/bsd.obj.mk
index c9b099b86889c..efbf59b854077 100644
--- a/share/mk/bsd.obj.mk
+++ b/share/mk/bsd.obj.mk
@@ -75,7 +75,7 @@ __objdir_made != umask ${OBJDIR_UMASK:U002}; ${Mkdirs}; \
 	done
 .endif
 .endif	# !empty(SRCS:M*/*) || !empty(DPSRCS:M*/*)
-.elif defined(MAKEOBJDIRPREFIX)
+.elif !empty(MAKEOBJDIRPREFIX)
 CANONICALOBJDIR:=${MAKEOBJDIRPREFIX}${.CURDIR}
 .elif defined(MAKEOBJDIR) && ${MAKEOBJDIR:M/*} != ""
 CANONICALOBJDIR:=${MAKEOBJDIR}
diff --git a/share/mk/local.meta.sys.mk b/share/mk/local.meta.sys.mk
index 06f603e38af9f..ce7e35bd72a19 100644
--- a/share/mk/local.meta.sys.mk
+++ b/share/mk/local.meta.sys.mk
@@ -7,9 +7,6 @@
 # we need this until there is an alternative
 MK_INSTALL_AS_USER= yes
 
-# Default OBJROOT/MAKEOBJDIR handled in local.sys.obj.mk
-.include <src.sys.obj.mk>
-
 .if !defined(HOST_TARGET)
 # we need HOST_TARGET etc below.
 .include <host-target.mk>
diff --git a/share/mk/src.sys.env.mk b/share/mk/src.sys.env.mk
index f068f8f825346..b100c2ad1429c 100644
--- a/share/mk/src.sys.env.mk
+++ b/share/mk/src.sys.env.mk
@@ -43,3 +43,5 @@ MAKESYSPATH:= ${MAKESYSPATH:S,.../share/mk,${.PARSEDIR:tA},}
 MAKESYSPATH:=	${.PARSEDIR:tA}
 .export MAKESYSPATH
 .endif
+
+.include <src.sys.obj.mk>
diff --git a/share/mk/src.sys.obj.mk b/share/mk/src.sys.obj.mk
index 1707d7831f1d3..b5b27c36bfadc 100644
--- a/share/mk/src.sys.obj.mk
+++ b/share/mk/src.sys.obj.mk
@@ -1,9 +1,45 @@
 # $FreeBSD$
+#
+# Early setup of MAKEOBJDIR
+#
+# Default format is: /usr/obj/usr/src/[${TARGET}.${TARGET_ARCH}/]bin/sh
+#  MAKEOBJDIRPREFIX is	/usr/obj
+#  OBJROOT is		/usr/obj/usr/src/
+#  OBJTOP is		/usr/obj/usr/src/[${TARGET}.${TARGET_ARCH}/]
+#  MAKEOBJDIR is	/usr/obj/usr/src/[${TARGET}.${TARGET_ARCH}/]bin/sh
+#
+#  MAKEOBJDIRPREFIX will override the default pattern above and internally
+#  set MAKEOBJDIR.  If OBJROOT is set then MAKEOBJDIRPREFIX is rooted inside
+#  of there.
+#
+#  If MK_UNIFIED_OBJDIR is no then OBJROOT will always match OBJTOP.
+#
+#  If .MAKE.LEVEL == 0 then the TARGET.TARGET_ARCH is potentially added on.
+#  If .MAKE.LEVEL >  0 and MAKEOBJDIRPREFIX is set then it will not get
+#  TARGET.TARGET_ARCH added in as it assumes that MAKEOBJDIRPREFIX is
+#  nested in the existing OBJTOP with TARGET.TARGET_ARCH in it.
+#
 
+_default_makeobjdirprefix?=	/usr/obj
 _default_makeobjdir=	$${.CURDIR:S,^$${SRCTOP},$${OBJTOP},}
 
-.if empty(OBJROOT) || ${.MAKE.LEVEL} == 0
-.if defined(MAKEOBJDIRPREFIX) && !empty(MAKEOBJDIRPREFIX)
+.include <bsd.mkopt.mk>
+
+.if ${.MAKE.LEVEL} == 0 || empty(OBJROOT)
+.if ${MK_UNIFIED_OBJDIR} == "no"
+# Fall back to historical behavior.
+# We always want to set a default MAKEOBJDIRPREFIX...
+MAKEOBJDIRPREFIX?=	${_default_makeobjdirprefix}
+# but don't enforce TARGET.TARGET_ARCH unless we're at the top-level directory.
+.if ${.CURDIR} == ${SRCTOP} && \
+    !(defined(TARGET) && defined(TARGET_ARCH) && \
+    ${MACHINE} == ${TARGET} && ${MACHINE_ARCH} == ${TARGET_ARCH} && \
+    !defined(CROSS_BUILD_TESTING))
+MAKEOBJDIRPREFIX:=	${MAKEOBJDIRPREFIX}${TARGET:D/${TARGET}.${TARGET_ARCH}}
+.endif
+.endif	# ${MK_UNIFIED_OBJDIR} == "no"
+
+.if !empty(MAKEOBJDIRPREFIX)
 # put things approximately where they want
 OBJROOT:=	${MAKEOBJDIRPREFIX}${SRCTOP}/
 MAKEOBJDIRPREFIX=
@@ -17,24 +53,59 @@ MAKEOBJDIR=	${_default_makeobjdir}
 # Expand for our own use
 MAKEOBJDIR:=	${MAKEOBJDIR}
 .endif
+# SB documented at http://www.crufty.net/sjg/docs/sb-tools.htm
 .if !empty(SB)
 SB_OBJROOT?=	${SB}/obj/
 # this is what we use below
 OBJROOT?=	${SB_OBJROOT}
 .endif
-OBJROOT?=	/usr/obj${SRCTOP}/
+OBJROOT?=	${_default_makeobjdirprefix}${SRCTOP}/
 .if ${OBJROOT:M*/} != ""
 OBJROOT:=	${OBJROOT:H:tA}/
 .else
 OBJROOT:=	${OBJROOT:H:tA}/${OBJROOT:T}
 .endif
+# Must export since OBJDIR will dynamically be based on it
 .export OBJROOT SRCTOP
 .endif
 
-.if 0
+.if ${MK_UNIFIED_OBJDIR} == "yes"
+OBJTOP:=	${OBJROOT}${TARGET:D${TARGET}.${TARGET_ARCH}:U${MACHINE}.${MACHINE_ARCH}}
+.else
+# TARGET.TARGET_ARCH handled in OBJROOT already.
+OBJTOP:=	${OBJROOT:H}
+.endif	# ${MK_UNIFIED_OBJDIR} == "yes"
+
+# Wait to validate MAKEOBJDIR until OBJTOP is set.
 .if defined(MAKEOBJDIR)
 .if ${MAKEOBJDIR:M/*} == ""
 .error Cannot use MAKEOBJDIR=${MAKEOBJDIR}${.newline}Unset MAKEOBJDIR to get default:  MAKEOBJDIR='${_default_makeobjdir}'
 .endif
 .endif
+
+# Fixup OBJROOT/OBJTOP if using MAKEOBJDIRPREFIX but leave it alone
+# for DIRDEPS_BUILD which really wants to know the absolute top at
+# all times.  This intenionally comes after adding TARGET.TARGET_ARCH
+# so that is truncated away for nested objdirs.  This logic also
+# will not trigger if the OBJROOT block above unsets MAKEOBJDIRPREFIX.
+.if !empty(MAKEOBJDIRPREFIX) && ${MK_DIRDEPS_BUILD} == "no"
+OBJTOP:=	${MAKEOBJDIRPREFIX}${SRCTOP}
+OBJROOT:=	${OBJTOP}/
+.endif
+
+# Assign this directory as .OBJDIR if possible
+.if ${MK_AUTO_OBJ} == "no"
+# The expected OBJDIR already exists, set it as .OBJDIR.
+.if !empty(MAKEOBJDIRPREFIX) && exists(${MAKEOBJDIRPREFIX}${.CURDIR})
+.OBJDIR: ${MAKEOBJDIRPREFIX}${.CURDIR}
+.elif exists(${MAKEOBJDIR})
+.OBJDIR: ${MAKEOBJDIR}
+# Special case to work around bmake bug.  If the top-level .OBJDIR does not yet
+# exist and MAKEOBJDIR is passed into environment and yield a blank value,
+# bmake will incorrectly set .OBJDIR=${SRCTOP}/ rather than the expected
+# ${SRCTOP} to match ${.CURDIR}.
+.elif ${MAKE_VERSION} <= 20170720 && \
+    ${.CURDIR} == ${SRCTOP} && ${.OBJDIR} == ${SRCTOP}/
+.OBJDIR: ${.CURDIR}
 .endif
+.endif	# ${MK_AUTO_OBJ} == "no"
diff --git a/share/mk/sys.mk b/share/mk/sys.mk
index 2016e4dcdb655..ea3d03f70e028 100644
--- a/share/mk/sys.mk
+++ b/share/mk/sys.mk
@@ -17,6 +17,8 @@ __TO_CPUARCH=C/mips(n32|64)?(el)?(hf)?/mips/:C/arm(v[67])?(eb)?/arm/:C/powerpc(6
 MACHINE_CPUARCH=${MACHINE_ARCH:${__TO_CPUARCH}}
 .endif
 
+__DEFAULT_YES_OPTIONS+= \
+	UNIFIED_OBJDIR
 
 # Some options we need now
 __DEFAULT_NO_OPTIONS= \
diff --git a/tools/build/options/WITHOUT_UNIFIED_OBJDIR b/tools/build/options/WITHOUT_UNIFIED_OBJDIR
new file mode 100644
index 0000000000000..355730c4a17e5
--- /dev/null
+++ b/tools/build/options/WITHOUT_UNIFIED_OBJDIR
@@ -0,0 +1,15 @@
+.\" $FreeBSD$
+Set to use the historical object directory format for
+.Xr build 7
+targets.
+For native-builds and builds done directly in sub-directories the format of
+.Pa ${MAKEOBJDIRPREFIX}/${.CURDIR}
+is used,
+while for cross-builds
+.Pa ${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}/${.CURDIR}
+is used.
+.Pp
+This option is transitional and will be removed before the 12.0 release,
+at which time
+.va WITH_UNIFIED_OBJDIR
+will be enabled permanently.
diff --git a/tools/build/options/WITH_UNIFIED_OBJDIR b/tools/build/options/WITH_UNIFIED_OBJDIR
new file mode 100644
index 0000000000000..6efc01d09c5ec
--- /dev/null
+++ b/tools/build/options/WITH_UNIFIED_OBJDIR
@@ -0,0 +1,12 @@
+.\" $FreeBSD$
+Set to use the unified object directory format for
+.Xr build 7
+targets.
+For cross-builds, native-builds, and sub-directory builds, the format of
+.Pa ${MAKEOBJDIRPREFIX}/${.CURDIR}/${TARGET}.${TARGET_ARCH}
+is used.
+.Pp
+This option is transitional and will be removed before the 12.0 release,
+at which time
+.va WITH_UNIFIED_OBJDIR
+will be enabled permanently.
diff --git a/tools/build/options/makeman b/tools/build/options/makeman
index 6bcc7104dc484..c59c7179a8563 100755
--- a/tools/build/options/makeman
+++ b/tools/build/options/makeman
@@ -217,12 +217,10 @@ variable, which defaults to
 Some examples that may only be set in this file are
 .Va WITH_DIRDEPS_BUILD ,
 and
-.Va WITH_META_MODE
-as they are environment-only variables.
-Note that
+.Va WITH_META_MODE ,
+and
 .Va MAKEOBJDIRPREFIX
-may be set here only when using
-.Va WITH_DIRDEPS_BUILD .
+as they are environment-only variables.
 .Pp
 The values of variables are ignored regardless of their setting;
 even if they would be set to