Bug #273648 - Document restriction of S to WORKDIR fallback in EAPI 4.

diff --git a/doc/package/ebuild/eapi/4.docbook b/doc/package/ebuild/eapi/4.docbook
index 44e005f453db8bc65d6d355f31afa6b12dd783ad..a96910e83ffa081436ede3055a3e9331a1c3b09c 100644 (file)
--- a/doc/package/ebuild/eapi/4.docbook
+++ b/doc/package/ebuild/eapi/4.docbook
@@ -193,6 +193,19 @@ src_install() {
 }
                        </programlisting>
                </section>
+               <section id='package-ebuild-eapi-4_pre1-phases-s-workdir-fallback'>
+                       <title>S to WORKDIR fallback restricted</title>
+                       <para>
+                       For any of the src_* phases that executes after src_unpack,
+                       it is invalid for the S variable to refer to a non-existent
+                       directory. However, these src_* phases are exempt from this
+                       requirement if none of the prior src_* phases are defined by the
+                       ebuild. When a src_* phase is exempt from this requirement, if the
+                       S variable does not refer to an existing directory, the
+                       WORKDIR directory will be used instead of S as the initial working
+                       directory.
+                       </para>
+               </section>
        </section>
        <section id='package-ebuild-eapi-4_pre1-variables'>
                <title>Variables</title>