6 files changed, 26 insertions, 23 deletions

diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
index c649e2bd60..454c72bcd2 100644
--- a/documentation/dev-manual/layers.rst
+++ b/documentation/dev-manual/layers.rst
@@ -507,7 +507,7 @@ the "meta" layer at ``meta/recipes-bsp/formfactor``::
    PR = "r45"
 
    SRC_URI = "file://config file://machconfig"
-   S = "${WORKDIR}"
+   S = "${UNPACKDIR}"
 
    PACKAGE_ARCH = "${MACHINE_ARCH}"
    INHIBIT_DEFAULT_DEPS = "1"
@@ -586,7 +586,7 @@ Directory`.  Here is the main ``xserver-xf86-config`` recipe, which is named
 
    SRC_URI = "file://xorg.conf"
 
-   S = "${WORKDIR}"
+   S = "${UNPACKDIR}"
 
    CONFFILES:${PN} = "${sysconfdir}/X11/xorg.conf"
 
@@ -594,9 +594,9 @@ Directory`.  Here is the main ``xserver-xf86-config`` recipe, which is named
    ALLOW_EMPTY:${PN} = "1"
 
    do_install () {
-        if test -s ${WORKDIR}/xorg.conf; then
+        if test -s ${UNPACKDIR}/xorg.conf; then
                 install -d ${D}/${sysconfdir}/X11
-                install -m 0644 ${WORKDIR}/xorg.conf ${D}/${sysconfdir}/X11/
+                install -m 0644 ${UNPACKDIR}/xorg.conf ${D}/${sysconfdir}/X11/
         fi
    }
 
@@ -614,8 +614,8 @@ file is in the layer at ``recipes-graphics/xorg-xserver``::
        PITFT="${@bb.utils.contains("MACHINE_FEATURES", "pitft", "1", "0", d)}"
        if [ "${PITFT}" = "1" ]; then
            install -d ${D}/${sysconfdir}/X11/xorg.conf.d/
-           install -m 0644 ${WORKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
-           install -m 0644 ${WORKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
+           install -m 0644 ${UNPACKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
+           install -m 0644 ${UNPACKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/
        fi
    }
 
diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst
index bffff3675f..7d6636eeff 100644
--- a/documentation/dev-manual/licenses.rst
+++ b/documentation/dev-manual/licenses.rst
@@ -55,11 +55,11 @@ Consider this next example::
 
    LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
                                        md5=bb14ed3c4cda583abc85401304b5cd4e"
-   LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
+   LIC_FILES_CHKSUM = "file://${UNPACKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
 
 The first line locates a file in ``${S}/src/ls.c`` and isolates lines
 five through 16 as license text. The second line refers to a file in
-:term:`WORKDIR`.
+:term:`UNPACKDIR`.
 
 Note that :term:`LIC_FILES_CHKSUM` variable is mandatory for all recipes,
 unless the :term:`LICENSE` variable is set to "CLOSED".
diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst
index c49881efe6..7b39b9984e 100644
--- a/documentation/dev-manual/new-recipe.rst
+++ b/documentation/dev-manual/new-recipe.rst
@@ -706,7 +706,7 @@ hierarchy to locations that would mirror their locations on the target
 device. The installation process copies files from the
 ``${``\ :term:`S`\ ``}``,
 ``${``\ :term:`B`\ ``}``, and
-``${``\ :term:`WORKDIR`\ ``}``
+``${``\ :term:`UNPACKDIR`\ ``}``
 directories to the ``${``\ :term:`D`\ ``}``
 directory to create the structure as it should appear on the target
 system.
@@ -1145,7 +1145,7 @@ Building an application from a single file that is stored locally (e.g. under
 ``files``) requires a recipe that has the file listed in the :term:`SRC_URI`
 variable. Additionally, you need to manually write the :ref:`ref-tasks-compile`
 and :ref:`ref-tasks-install` tasks. The :term:`S` variable defines the
-directory containing the source code, which is set to :term:`WORKDIR` in this
+directory containing the source code, which is set to :term:`UNPACKDIR` in this
 case --- the directory BitBake uses for the build::
 
    SUMMARY = "Simple helloworld application"
@@ -1155,7 +1155,7 @@ case --- the directory BitBake uses for the build::
 
    SRC_URI = "file://helloworld.c"
 
-   S = "${WORKDIR}"
+   S = "${UNPACKDIR}"
 
    do_compile() {
        ${CC} ${LDFLAGS} helloworld.c -o helloworld
@@ -1211,8 +1211,6 @@ In the following example, ``lz4`` is a makefile-based package::
               "
    UPSTREAM_CHECK_GITTAGREGEX = "v(?P<pver>.*)"
 
-   S = "${WORKDIR}/git"
-
    CVE_STATUS[CVE-2014-4715] = "fixed-version: Fixed in r118, which is larger than the current version"
 
    EXTRA_OEMAKE = "PREFIX=${prefix} CC='${CC}' CFLAGS='${CFLAGS}' DESTDIR=${D} LIBDIR=${libdir} INCLUDEDIR=${includedir} BUILD_STATIC=no"
@@ -1271,8 +1269,6 @@ is a simple example of an application without dependencies::
    SRC_URI = "git://gitlab.com/ipcalc/ipcalc.git;protocol=https;branch=master"
    SRCREV = "4c4261a47f355946ee74013d4f5d0494487cc2d6"
 
-   S = "${WORKDIR}/git"
-
    inherit meson
 
 Applications with dependencies are likely to inherit the
@@ -1428,7 +1424,7 @@ chapter of the BitBake User Manual.
    The following example shows some of the ways you can use variables in
    recipes::
 
-      S = "${WORKDIR}/postfix-${PV}"
+      S = "${UNPACKDIR}/postfix-${PV}"
       CFLAGS += "-DNO_ASM"
       CFLAGS:append = " --enable-important-feature"
 
diff --git a/documentation/dev-manual/packages.rst b/documentation/dev-manual/packages.rst
index 8845bf2fab..8bd48c8e8f 100644
--- a/documentation/dev-manual/packages.rst
+++ b/documentation/dev-manual/packages.rst
@@ -1024,7 +1024,7 @@ The ``devtool edit-recipe`` command lets you take a look at the recipe::
        npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \
        "
 
-   S = "${WORKDIR}/npm"
+   S = "${UNPACKDIR}/npm"
 
    inherit npm
 
diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst
index a05f39ca1e..d138358eae 100644
--- a/documentation/dev-manual/prebuilt-libraries.rst
+++ b/documentation/dev-manual/prebuilt-libraries.rst
@@ -97,7 +97,7 @@ The complete recipe would look like this::
    # we use a local link.
    SRC_URI = "file://libft4222-linux-${PV}.tgz"
 
-   S = "${WORKDIR}"
+   S = "${UNPACKDIR}"
 
    ARCH_DIR:x86-64 = "build-x86_64"
    ARCH_DIR:i586 = "build-i386"
@@ -204,6 +204,6 @@ versioned library example. The "magic" is setting the :term:`SOLIBS` and
 
    do_install () {
            install -d ${D}${libdir}
-           install -m 0755 ${WORKDIR}/libfoo.so ${D}${libdir}
+           install -m 0755 ${UNPACKDIR}/libfoo.so ${D}${libdir}
    }
 
diff --git a/documentation/dev-manual/temporary-source-code.rst b/documentation/dev-manual/temporary-source-code.rst
index 08bf68d982..9a7cd0f771 100644
--- a/documentation/dev-manual/temporary-source-code.rst
+++ b/documentation/dev-manual/temporary-source-code.rst
@@ -18,11 +18,10 @@ build packages is available in the :term:`Build Directory` as defined by the
 defined in the ``meta/conf/bitbake.conf`` configuration file in the
 :term:`Source Directory`::
 
-   S = "${WORKDIR}/${BP}"
+   S = "${UNPACKDIR}/${BP}"
 
 You should be aware that many recipes override the
-:term:`S` variable. For example, recipes that fetch their source from Git
-usually set :term:`S` to ``${WORKDIR}/git``.
+:term:`S` variable when the default isn't accurate.
 
 .. note::
 
@@ -31,8 +30,16 @@ usually set :term:`S` to ``${WORKDIR}/git``.
 
            BP = "${BPN}-${PV}"
 
+   This matches the location that the git fetcher unpacks to, and usually
+   matches unpacked content of release tarballs (e.g. they contain a single
+   directory which matches value of ${BP} exactly).
 
-The path to the work directory for the recipe
+The path to the unpack directory for the recipe
+(:term:`UNPACKDIR`) is defined as follows::
+
+   ${WORKDIR}/sources
+
+In turn, the path to the work directory for the recipe
 (:term:`WORKDIR`) is defined as
 follows::