diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml index eb4f2d4ae3..50e3400ae5 100644 --- a/documentation/poky-ref-manual/ref-variables.xml +++ b/documentation/poky-ref-manual/ref-variables.xml @@ -1415,11 +1415,42 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" MACHINE - Specifies the target device. - This variable corresponds to a file with the - extension .conf located in a - conf/machine directory - within the metadata that contains the target device configuration. + Specifies the target device for which the image is built. + You define MACHINE in the + local.conf file found in the + Build Directory. + By default, MACHINE is set to + "qemux86", which is a basic x86 architecture to be run on + the emulator (QEMU): + + MACHINE ?= "qemux86" + + The variable corresponds to a machine configuration file of the + same name, through which machine-specific configurations are set. + Thus, when MACHINE is set to "qemux86" there + exists the corresponding qemux86.conf machine + configuration file, which can be found in the + Source Directory + in meta/conf/machine. + + + + The possible settings for MACHINE that ship with + the Yocto Project as defined in the local.conf + include the following: + + MACHINE ?= "qemuarm" + MACHINE ?= "qemumips" + MACHINE ?= "qemuppc" + MACHINE ?= "qemux86" + MACHINE ?= "qemux86-64" + MACHINE ?= "atom-pc" + MACHINE ?= "beagleboard" + MACHINE ?= "mpc8315e-rdb" + MACHINE ?= "routerstationpro" + + The last four are target machines for hardware boards used + for demonstration. @@ -1433,7 +1464,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The build process depends on these packages being present. Furthermore, because this is a "machine essential" variable, the list of packages are essential for the machine to boot. - The impact of this variable affects images based on packagegroup-core-boot, + The impact of this variable affects images based on + packagegroup-core-boot, including the core-image-minimal image. @@ -1444,11 +1476,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" In other words, the image will not build if a file in this list is not found. - For example, suppose the machine for which you are building requires - a specific program to be run during boot to initialise the hardware. - In this case, assuming the package name for the program was - example-init, you would use the following in the - .conf file for the machine: + As an example, suppose the machine for which you are building requires + example-init to be run during boot to initialize the hardware. + In this case, you would use the following in the machine's + .conf configuration file: MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" @@ -1463,9 +1494,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" A list of recommended machine-specific packages to install as part of the image being built. The build process does not depend on these packages being present. - Furthermore, because this is a "machine essential" variable, the list of + However, because this is a "machine essential" variable, the list of packages are essential for the machine to boot. - The impact of this variable affects images based on packagegroup-core-boot, + The impact of this variable affects images based on + packagegroup-core-boot, including the core-image-minimal image. @@ -1480,16 +1512,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Consider an example where you have a custom kernel where a specific touchscreen - driver is required for the machine to be usable, but may be built as a module or + driver is required for the machine to be usable. + However, the driver can be built as a module or into the kernel depending on the kernel configuration. If the driver is built as a module, you want it to be installed. - However if - the driver is built into the kernel you still want the build to succeed. + But, when the driver is built into the kernel, you still want the + build to succeed. This variable sets up a "recommends" relationship so that in the latter case, the build will not fail due to the missing package. To accomplish this, assuming the package for the module was called kernel-module-ab123, you would use the - following in the .conf file for the machine: + following in the machine's .conf configuration + file: MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" @@ -1504,16 +1538,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" MACHINE_EXTRA_RDEPENDS - A list of machine-specific packages that are not essential for booting to install as - part of the image being built. - The build process for more fully-featured images depends on them being present. - The impact of this variable affects all images based on + A list of machine-specific packages to install as part of the + image being built that are not essential for the machine to boot. + However, the build process for more fully-featured images + depends on the packages being present. + + + This variable affects all images based on packagegroup-base, which does not include the core-image-minimal or core-image-basic images. - This variable is similar to the + The variable is similar to the MACHINE_EXTRA_RRECOMMENDS variable with the exception that the image being built has a build dependency on the variable's list of packages. @@ -1541,11 +1578,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" - A list of machine-specific packages that are not essential for booting - to install as part of the image being built, if present. - The image being built has no build dependency on the list of packages - with this variable. - The impact of this variable affects only images based on + A list of machine-specific packages to install as part of the + image being built that are not essential for booting the machine. + The image being built has no build dependency on this list of packages. + + + This variable affects only images based on packagegroup-base, which does not include the core-image-minimal or core-image-basic images. @@ -1577,9 +1615,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" MACHINE_FEATURES - Specifies the list of device features. - See the "Machine" section for - more information. + Specifies the list of hardware features the + MACHINE supports. + For a list of valid features you can provide, see the + "Machine" section.