prepare_build_dirs.py: Support for new home-dir-template-copy FEATURE

If enabled, as part of the ebuild environment setup, copies the PORTAGE_USERNAME
home directory into the build environment HOME directory. Useful predominantly
for ebuilds that use the git-r3 eclass, to give a place to put SSH keys and user-
specific git configuration files used during the build.

Bug: https://bugs.gentoo.org/947822
Closes: #1424
Signed-off-by: Zac Medico <zmedico@gentoo.org>

NEWS

@@ -39,6 +39,8 @@ Bug fixes:
 
 * Preserve PORTAGE_BZIP2_COMMAND in environment.bz2 (bug #948067).
 
+* Support for new home-dir-template-copy FEATURE (bug #947822).
+
 portage-3.0.66.1 (2024-09-18)
 --------------
 

lib/portage/const.py

@@ -189,6 +189,7 @@
         "force-mirror",
         "getbinpkg",
         "gpg-keepalive",
+        "home-dir-template-copy",
         "icecream",
         "installsources",
         "ipc-sandbox",

lib/portage/package/ebuild/prepare_build_dirs.py

@@ -7,6 +7,7 @@
 import gzip
 import stat
 import time
+import pwd
 
 import portage
 from portage import os, shutil, _encodings, _unicode_encode, _unicode_decode
@@ -133,6 +134,27 @@ def makedirs(dir_path):
         # Avoid spurious permissions adjustments when fetching with
         # a temporary PORTAGE_TMPDIR setting (for fetchonly).
         _prepare_features_dirs(mysettings)
+        # Support for home-dir-template-copy FEATURE:
+        if "home-dir-template-copy" in settings.features:
+            portage_username = mysettings.get("PORTAGE_USERNAME", "portage")
+            home_template_dir = pwd.getpwnam(portage_username).pw_dir
+            build_env_home_dir = mysettings["HOME"]
+            # Sanity checks on above values.
+            if not os.path.exists(home_template_dir):
+                writemsg(
+                    f"FEATURES home-dir-template-copy enabled but specified Linux home directory {home_template_dir} does not exist.",
+                    noiselevel=-1,
+                )
+                return 1
+            if not os.path.exists(build_env_home_dir):
+                writemsg(
+                    f"FEATURES home-dir-template-copy enabled but build HOME directory {build_env_home_dir} does not exist.",
+                    noiselevel=-1,
+                )
+                return 1
+            shutil.copytree(
+                home_template_dir, build_env_home_dir, symlinks=True, dirs_exist_ok=True
+            )
 
 
 def _adjust_perms_msg(settings, msg):

man/make.conf.5

@@ -535,6 +535,23 @@ Force emerges to always try to fetch files from the \fIPORTAGE_BINHOST\fR.  See
 .B gpg-keepalive
 Run GPG unlock command every 5 mins to avoid the passphrase expired.
 If your GPG is auto unlocked on login, you do not need this.
+.TP
+.B home\-dir\-template\-copy
+As part of the ebuild environment setup, copy the PORTAGE_USERNAME (default
+"portage") home directory (currently /var/lib/portage/home) into the build environment
+HOME directory. By default, Portage uses an empty home directory for each new build.
+
+This is useful, for example, if the git-r3 eclass is being used to access a repository
+via ssh where keys and known_hosts values need to be specified in the ~/.ssh
+directory.
+
+It's also useful for adressing git's "fatal: detected dubious ownership in
+repository at..." error, which can occur when the ebuild is fetching from a
+local filesystem-resident repo. Running git to create an "--add safe.directory"
+exception \fInarrowly\fR to apply only to the portage user can be done as follows:
+
+    sudo -u portage git config --global --add safe.directory ...
+
 .TP
 .B icecream
 Enable portage support for the icecream package.