1.. _yocto_project_terms:
2
3===================
4Yocto Project Terms
5===================
6
7Getting started in Yocto can be overwheming. There are many terms used that are
8specific to Yocto and Bitbake environment.
9
10A list of terms and definitions users new to the Yocto Project
11development environment might find helpful can be found `here <https://docs.
12yoctoproject.org/ref-manual/terms.html>`_.
13
14
15Yocto Variables Glossary
16************************
17
18This chapter lists basic variables used in the LVGL Yocto guide and gives an
19overview of their function and contents.
20
21A More complete variable glossary can be found in `Yocto Variable Glossary
22<https://docs.yoctoproject.org/ref-manual/variables.html>`_. This section
23covers a lot of variables used in the OpenEmbedded build system.
24
25.. _S:
26
27S
28-
29
30The location in the Build Directory where unpacked recipe source code resides.
31 By default, this directory is ${WORKDIR}/${BPN}-${PV}, where ${BPN} is the
32 base recipe name and ${PV} is the recipe version. If the source tarball
33 extracts the code to a directory named anything other than ${BPN}-${PV}, or if
34 the source code is fetched from an SCM such as Git or Subversion, then you
35 must set S in the recipe so that the OpenEmbedded build system knows where to
36 find the unpacked source.
37
38As an example, assume a Source Directory top-level folder named poky and a
39default Build Directory at poky/build. In this case, the work directory the
40build system uses to keep the unpacked recipe for db is the following:
41
42.. code-block:: bash
43
44   poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
45
46The unpacked source code resides in the db-5.1.19 folder.
47
48This next example assumes a Git repository. By default, Git repositories are
49cloned to ${WORKDIR}/git during do_fetch. Since this path is different from the
50default value of S, you must set it specifically so the source can be located:
51
52.. code-block:: bash
53
54   SRC_URI = "git://path/to/repo.git;branch=main"
55   S = "${WORKDIR}/git"
56
57
58.. _D:
59
60D
61-
62
63The destination directory. The location in the Build Directory where components
64are installed by the do_install task. This location defaults to:
65
66.. code-block:: bash
67
68   ${WORKDIR}/image
69
70.. note::
71
72    Tasks that read from or write to this directory should run under fakeroot.
73
74.. _B:
75
76B
77-
78
79The directory within the Build Directory in which the OpenEmbedded build system
80places generated objects during a recipe's build process. By default, this
81directory is the same as the S directory, which is defined as:
82
83.. code-block:: bash
84
85   S = "${WORKDIR}/${BP}"
86
87You can separate the (S) directory and the directory pointed to by the B
88variable. Most Autotools-based recipes support separating these directories.
89The build system defaults to using separate directories for gcc and some kernel
90recipes.
91
92.. _WORKDIR:
93
94WORKDIR
95-------
96
97The pathname of the work directory in which the OpenEmbedded build system
98builds a recipe. This directory is located within the TMPDIR directory
99structure and is specific to the recipe being built and the system for which it
100is being built.
101
102The WORKDIR directory is defined as follows:
103
104.. code-block:: bash
105
106   ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
107
108The actual directory depends on several things:
109
110   -  **TMPDIR**: The top-level build output directory
111   -  **MULTIMACH_TARGET_SYS**: The target system identifier
112   -  **PN**: The recipe name
113   -  **EXTENDPE**: The epoch — if PE is not specified, which is usually the
114      case for most recipes, then EXTENDPE is blank.
115   -  **PV**: The recipe version
116   -  **PR**: The recipe revision
117
118As an example, assume a Source Directory top-level folder name poky, a default
119Build Directory at poky/build, and a qemux86-poky-linux machine target system.
120Furthermore, suppose your recipe is named foo_1.3.0-r0.bb. In this case, the
121work directory the build system uses to build the package would be as follows:
122
123.. code-block:: bash
124
125   poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
126
127.. _PN:
128
129PN
130--
131
132This variable can have two separate functions depending on the context: a
133recipe name or a resulting package name.
134
135PN refers to a recipe name in the context of a file used by the OpenEmbedded
136build system as input to create a package. The name is normally extracted from
137the recipe file name. For example, if the recipe is named expat_2.0.1.bb, then
138the default value of PN will be “expat”.
139
140The variable refers to a package name in the context of a file created or
141produced by the OpenEmbedded build system.
142
143If applicable, the PN variable also contains any special suffix or prefix. For
144example, using bash to build packages for the native machine, PN is
145bash-native. Using bash to build packages for the target and for Multilib, PN
146would be bash and lib64-bash, respectively.
147
148.. _PR:
149
150PR
151--
152
153The revision of the recipe. The default value for this variable is
154"r0". Subsequent revisions of the recipe conventionally have the
155values "r1", "r2", and so forth. When PV increases,
156PR is conventionally reset to "r0".
157
158.. note::
159
160    The OpenEmbedded build system does not need the aid of PR to know when to
161    rebuild a recipe. The build system uses the task input checksums along with
162    the stamp and shared state cache mechanisms.
163
164The PR variable primarily becomes significant when a package
165manager dynamically installs packages on an already built image. In
166this case, PR, which is the default value of
167PKGR, helps the package manager distinguish which
168package is the most recent one in cases where many packages have the
169same PV (i.e. PKGV). A component having many packages with
170the same PV usually means that the packages all install the same
171upstream version, but with later (PR) version packages including
172packaging fixes.
173
174.. note::
175
176    PR does not need to be increased for changes that do not change the
177    package contents or metadata.
178
179Because manually managing PR can be cumbersome and error-prone,
180an automated solution exists. See the
181"`working with a pr service <https://docs.yoctoproject.org/dev-manual/packages.
182html#working-with-a-pr-service>`_" section in the Yocto Project Development
183Tasks Manual for more information.
184
185.. _PV:
186
187PV
188--
189
190The version of the recipe. The version is normally extracted from the recipe
191filename. For example, if the recipe is named expat_2.0.1.bb, then the default
192value of PV will be “2.0.1”. PV is generally not overridden within a recipe
193unless it is building an unstable (i.e. development) version from a source code
194repository (e.g. Git or Subversion).
195
196PV is the default value of the PKGV variable.
197