diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml index 97c8a9e1dd..a9559bbb0b 100644 --- a/documentation/ref-manual/ref-tasks.xml +++ b/documentation/ref-manual/ref-tasks.xml @@ -241,11 +241,48 @@ <filename>do_install</filename> - Copies files from the compilation directory, which is defined by - the - B variable, - to a holding area defined by the - D variable. + Copies files that are to be packaged into the holding area + ${D}. + This task runs with the current working directory set to + ${B}, + which is the compilation directory. + + Caution + + + When installing files, be careful not to set the owner and + group IDs of the installed files to unintended values. + Some methods of copying files, notably when using the + recursive cp command, can preserve the + UID and/or GID of the original file, which is usually not + what you want. + The host-user-contaminated QA check checks for files + that probably have the wrong ownership. + + + + Safe methods for installing files include the following: + + + The install utility. + This utility is the preferred method. + + + The cp command with the + "--no-preserve=ownership" option. + + + The tar command with the + "--no-same-owner" option. + See the bin_package.bbclass + file in the meta/classes + directory of the + Source Directory + for an example. + + + +