summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml456
1 files changed, 456 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 745e1c0ab6..8264331dd1 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4068,6 +4068,462 @@
4068 </section> 4068 </section>
4069 </section> 4069 </section>
4070 4070
4071 <section id='gs-upgrading-recipes'>
4072 <title>Upgrading Recipes</title>
4073
4074 <para>
4075 Over time, upstream developers publish new versions for software
4076 built by layer recipes.
4077 It is recommended to keep recipes up-to-date with upstream
4078 version releases.
4079 You can use the Automated Upgrade Helper (AUH) to set up
4080 automatic version upgrades.
4081 Alternatively, you can use <filename>devtool upgrade</filename>
4082 to set up semi-automatic version upgrades.
4083 Finally, you can even manually upgrade a recipe by editing the
4084 recipe itself.
4085 </para>
4086
4087 <section id='gs-using-the-auto-upgrade-helper'>
4088 <title>Using the Auto Upgrade Helper (AUH)</title>
4089
4090 <para>
4091 The AUH utility works in conjunction with the
4092 OpenEmbedded build system in order to automatically generate
4093 upgrades for recipes based on new versions being
4094 published upstream.
4095 Use AUH when you want to create a service that performs the
4096 upgrades automatically and optionally sends you an email with
4097 the results.
4098 </para>
4099
4100 <para>
4101 AUH allows you to update several recipes with a single use.
4102 You can also optionally perform build and integration tests
4103 using images with the results saved to your hard drive and
4104 emails of results optionally sent to recipe maintainers.
4105 Finally, AUH creates Git commits with appropriate commit
4106 messages in the layer's tree for the changes made to recipes.
4107 <note>
4108 Conditions do exist when you should not use AUH to upgrade
4109 recipes and you should instead use either
4110 <filename>devtool upgrade</filename> or upgrade your
4111 recipes manually:
4112 <itemizedlist>
4113 <listitem><para>
4114 When AUH cannot complete the upgrade sequence.
4115 This situation usually results because custom
4116 patches carried by the recipe cannot be
4117 automatically rebased to the new version.
4118 In this case, <filename>devtool upgrade</filename>
4119 allows you to manually resolve conflicts.
4120 </para></listitem>
4121 <listitem><para>
4122 When for any reason you want fuller control over
4123 the upgrade process.
4124 For example, when you want special arrangements
4125 for testing.
4126 </para></listitem>
4127 </itemizedlist>
4128 </note>
4129 </para>
4130
4131 <para>
4132 The following steps describe how to set up the AUH utility:
4133 <orderedlist>
4134 <listitem><para>
4135 <emphasis>Be Sure the Development Host is Set Up:</emphasis>
4136 You need to be sure that your development host is
4137 set up to use the Yocto Project.
4138 For information on how to set up your host, see the
4139 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
4140 section in the Yocto Project Development Tasks Manual.
4141 </para></listitem>
4142 <listitem><para>
4143 <emphasis>Make Sure Git is Configured:</emphasis>
4144 The AUH utility requires Git to be configured because
4145 AUH uses Git to save upgrades.
4146 Thus, you must have Git user and email configured.
4147 The following command shows your configurations:
4148 <literallayout class='monospaced'>
4149 $ git config --list
4150 </literallayout>
4151 If you do not have the user and email configured, you
4152 can use the following commands to do so:
4153 <literallayout class='monospaced'>
4154 $ git config --global user.name <replaceable>some_name</replaceable>
4155 $ git config --global user.email <replaceable>username</replaceable>@<replaceable>domain</replaceable>.com
4156 </literallayout>
4157 </para></listitem>
4158 <listitem><para>
4159 <emphasis>Clone the AUH Respository:</emphasis>
4160 To use AUH, you must clone the repository onto your
4161 development host.
4162 The following command uses Git to create a local
4163 copy of the repository on your system:
4164 <literallayout class='monospaced'>
4165 $ git clone git://git.yoctoproject.org/auto-upgrade-helper
4166 Cloning into 'auto-upgrade-helper'...
4167 remote: Counting objects: 768, done.
4168 remote: Compressing objects: 100% (300/300), done.
4169 remote: Total 768 (delta 499), reused 703 (delta 434)
4170 Receiving objects: 100% (768/768), 191.47 KiB | 98.00 KiB/s, done.
4171 Resolving deltas: 100% (499/499), done.
4172 Checking connectivity... done.
4173 </literallayout>
4174 AUH is not part of the
4175 <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core (OE-Core)</ulink>
4176 or
4177 <ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>
4178 repositories.
4179 </para></listitem>
4180 <listitem><para>
4181 <emphasis>Create a Dedicated Build Directory:</emphasis>
4182 Run the
4183 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>
4184 script to create a fresh build directory that you
4185 use exclusively for running the AUH utility:
4186 <literallayout class='monospaced'>
4187 $ cd ~/poky
4188 $ source oe-init-build-env <replaceable>your_AUH_build_directory</replaceable>
4189 </literallayout>
4190 Re-using an existing build directory and its
4191 configurations is not recommended as existing settings
4192 could cause AUH to fail or behave undesirably.
4193 </para></listitem>
4194 <listitem><para>
4195 <emphasis>Make Configurations in Your Local Configuration File:</emphasis>
4196 Several settings need to exist in the
4197 <filename>local.conf</filename> file in the build
4198 directory you just created for AUH.
4199 Make these following configurations:
4200 <itemizedlist>
4201 <listitem><para>
4202 Enable "distrodata" as follows:
4203 <literallayout class='monospaced'>
4204 INHERIT =+ "distrodata"
4205 </literallayout>
4206 </para></listitem>
4207 <listitem><para>
4208 If you want to enable
4209 <ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Build History</ulink>,
4210 which is optional, you need the following
4211 lines in the
4212 <filename>conf/local.conf</filename> file:
4213 <literallayout class='monospaced'>
4214 INHERIT =+ "buildhistory"
4215 BUILDHISTORY_COMMIT = "1"
4216 </literallayout>
4217 With this configuration and a successful
4218 upgrade, a build history "diff" file appears in
4219 the
4220 <filename>upgrade-helper/work/recipe/buildhistory-diff.txt</filename>
4221 file found in your build directory.
4222 </para></listitem>
4223 <listitem><para>
4224 If you want to enable testing through the
4225 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage*'><filename>testimage</filename></ulink>
4226 class, which is optional, you need to have the
4227 following set in your
4228 <filename>conf/local.conf</filename> file:
4229 <literallayout class='monospaced'>
4230 INHERIT += "testimage"
4231 </literallayout>
4232 <note>
4233 If your distro does not enable by default
4234 ptest, which Poky does, you need the
4235 following in your
4236 <filename>local.conf</filename> file:
4237 <literallayout class='monospaced'>
4238 DISTRO_FEATURES_append = " ptest"
4239 </literallayout>
4240 </note>
4241 </para></listitem>
4242 </itemizedlist>
4243 </para></listitem>
4244 <listitem><para>
4245 <emphasis>Optionally Start a vncserver:</emphasis>
4246 If you are running in a server without an X11 session,
4247 you need to start a vncserver:
4248 <literallayout class='monospaced'>
4249 $ vncserver :1
4250 $ export DISPLAY=:1
4251 </literallayout>
4252 </para></listitem>
4253 <listitem><para>
4254 <emphasis>Create and Edit an AUH Configuration File:</emphasis>
4255 You need to have the
4256 <filename>upgrade-helper/upgrade-helper.conf</filename>
4257 configuration file in your build directory.
4258 You can find a sample configuration file in the
4259 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/tree/'>AUH source repository</ulink>.
4260 </para>
4261
4262 <para>Read through the sample file and make
4263 configurations as needed.
4264 For example, if you enabled build history in your
4265 <filename>local.conf</filename> as described earlier,
4266 you must enable it in
4267 <filename>upgrade-helper.conf</filename>.</para>
4268
4269 <para>Also, if you are using the default
4270 <filename>maintainers.inc</filename> file supplied
4271 with Poky and located in
4272 <filename>meta-yocto</filename> and you do not set a
4273 "maintainers_whitelist" or "global_maintainer_override"
4274 in the <filename>upgrade-helper.conf</filename>
4275 configuration, and you specify "-e all" on the
4276 AUH command-line, the utility automatically sends out
4277 emails to all the default maintainers.
4278 Please avoid this.
4279 </para></listitem>
4280 </orderedlist>
4281 </para>
4282
4283 <para>
4284 This next set of examples describes how to use the AUH:
4285 <itemizedlist>
4286 <listitem><para>
4287 <emphasis>Upgrading a Specific Recipe:</emphasis>
4288 To upgrade a specific recipe, use the following
4289 form:
4290 <literallayout class='monospaced'>
4291 $ upgrade-helper.py <replaceable>recipe_name</replaceable>
4292 </literallayout>
4293 For example, this command upgrades the
4294 <filename>xmodmap</filename> recipe:
4295 <literallayout class='monospaced'>
4296 $ upgrade-helper.py xmodmap
4297 </literallayout>
4298 </para></listitem>
4299 <listitem><para>
4300 <emphasis>Upgrading a Specific Recipe to a Particular Version:</emphasis>
4301 To upgrade a specific recipe to a particular version,
4302 use the following form:
4303 <literallayout class='monospaced'>
4304 $ upgrade-helper.py <replaceable>recipe_name</replaceable> -t <replaceable>version</replaceable>
4305 </literallayout>
4306 For example, this command upgrades the
4307 <filename>xmodmap</filename> recipe to version
4308 1.2.3:
4309 <literallayout class='monospaced'>
4310 $ upgrade-helper.py xmodmap -t 1.2.3
4311 </literallayout>
4312 </para></listitem>
4313 <listitem><para>
4314 <emphasis>Upgrading all Recipes to the Latest Versions and Suppressing Email Notifications:</emphasis>
4315 To upgrade all recipes to their most recent versions
4316 and suppress the email notifications, use the following
4317 command:
4318 <literallayout class='monospaced'>
4319 $ upgrade-helper.py all
4320 </literallayout>
4321 </para></listitem>
4322 <listitem><para>
4323 <emphasis>Upgrading all Recipes to the Latest Versions and Send Email Notifications:</emphasis>
4324 To upgrade all recipes to their most recent versions
4325 and send email messages to maintainers for each
4326 attempted recipe as well as a status email, use the
4327 following command:
4328 <literallayout class='monospaced'>
4329 $ upgrade-helper.py -e all
4330 </literallayout>
4331 </para></listitem>
4332 </itemizedlist>
4333 </para>
4334
4335 <para>
4336 Once you have run the AUH utility, you can find the results
4337 in the AUH build directory:
4338 <literallayout class='monospaced'>
4339 ${BUILDDIR}/upgrade-helper/<replaceable>timestamp</replaceable>
4340 </literallayout>
4341 The AUH utility also creates recipe update commits from
4342 successful upgrade attempts in the layer tree.
4343 </para>
4344
4345 <para>
4346 You can easily set up to run the AUH utility on a regular
4347 basis by using a cron job.
4348 See the
4349 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/tree/weeklyjob.sh'><filename>weeklyjob.sh</filename></ulink>
4350 file distributed with the utility for an example.
4351 </para>
4352 </section>
4353
4354 <section id='gs-using-devtool-upgrade'>
4355 <title>Using <filename>devtool upgrade</filename></title>
4356
4357 <para>
4358 As mentioned earlier, an alternative method for upgrading
4359 recipes to newer versions is to use
4360 <ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool upgrade</filename></ulink>.
4361 You can read about <filename>devtool upgrade</filename> in
4362 general in the
4363 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</ulink>"
4364 section in the Yocto Project Application Development and the
4365 Extensible Software Development Kit (eSDK) Manual.
4366 </para>
4367
4368 <para>
4369 To see all the command-line options available with
4370 <filename>devtool upgrade</filename>, use the following help
4371 command:
4372 <literallayout class='monospaced'>
4373 $ devtool upgrade -h
4374 </literallayout>
4375 </para>
4376
4377 <para>
4378 If you want to find out what version a recipe is currently at
4379 upstream without any attempt to upgrade your local version of
4380 the recipe, you can use the following command:
4381 <literallayout class='monospaced'>
4382 $ devtool latest-version <replaceable>recipe_name</replaceable>
4383 </literallayout>
4384 </para>
4385
4386 <para>
4387 As mentioned in the previous section describing AUH,
4388 <filename>devtool upgrade</filename> works in a
4389 less-automated manner than AUH.
4390 Specifically, <filename>devtool upgrade</filename> only
4391 works on a single recipe that you name on the command line,
4392 cannot perform build and integration testing using images,
4393 and does not automatically generate commits for changes in
4394 the source tree.
4395 Despite all these "limitations",
4396 <filename>devtool upgrade</filename> updates the recipe file
4397 to the new upstream version and attempts to rebase custom
4398 patches contained by the recipe as needed.
4399 <note>
4400 AUH uses much of <filename>devtool upgrade</filename>
4401 behind the scenes making AUH somewhat of a "wrapper"
4402 application for <filename>devtool upgrade</filename>.
4403 </note>
4404 </para>
4405
4406 <para>
4407 A typical scenario involves having used Git to clone an
4408 upstream repository that you use during build operations.
4409 Because you are (or have) built the recipe in the past, the
4410 layer is likely added to your configuration already.
4411 If for some reason, the layer is not added, you could add
4412 it easily using the
4413 <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'><filename>bitbake-layers</filename></ulink>
4414 script.
4415 For example, suppose you use the <filename>nano.bb</filename>
4416 recipe from the <filename>meta-oe</filename> layer in the
4417 <filename>meta-openembedded</filename> repository.
4418 For this example, assume that the layer has been cloned into
4419 following area:
4420 <literallayout class='monospaced'>
4421 /home/scottrif/meta-openembedded
4422 </literallayout>
4423 The following command from your
4424 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
4425 adds the layer to your build configuration (i.e.
4426 <filename>${BUILDDIR}/conf/bblayers.conf</filename>):
4427 <literallayout class='monospaced'>
4428 $ bitbake-layers add-layer /home/scottrif/meta-openembedded/meta-oe
4429 NOTE: Starting bitbake server...
4430 Parsing recipes: 100% |##########################################| Time: 0:00:55
4431 Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
4432 Removing 12 recipes from the x86_64 sysroot: 100% |##############| Time: 0:00:00
4433 Removing 1 recipes from the x86_64_i586 sysroot: 100% |##########| Time: 0:00:00
4434 Removing 5 recipes from the i586 sysroot: 100% |#################| Time: 0:00:00
4435 Removing 5 recipes from the qemux86 sysroot: 100% |##############| Time: 0:00:00
4436 </literallayout>
4437 For this example, assume that the <filename>nano.bb</filename>
4438 recipe that is upstream has a 2.9.3 version number.
4439 However, the version in the local repository is 2.7.4.
4440 The following command from your build directory automatically
4441 upgrades the recipe for you:
4442 <note>
4443 Using the <filename>-V</filename> option is not necessary.
4444 Omitting the version number causes
4445 <filename>devtool upgrade</filename> to upgrade the recipe
4446 to the most recent version.
4447 </note>
4448 <literallayout class='monospaced'>
4449 $ devtool upgrade nano -V 2.9.3
4450 NOTE: Starting bitbake server...
4451 NOTE: Creating workspace layer in /home/scottrif/poky/build/workspace
4452 Parsing recipes: 100% |##########################################| Time: 0:00:46
4453 Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
4454 NOTE: Extracting current version source...
4455 NOTE: Resolving any missing task queue dependencies
4456 .
4457 .
4458 .
4459 NOTE: Executing SetScene Tasks
4460 NOTE: Executing RunQueue Tasks
4461 NOTE: Tasks Summary: Attempted 74 tasks of which 72 didn't need to be rerun and all succeeded.
4462 Adding changed files: 100% |#####################################| Time: 0:00:00
4463 NOTE: Upgraded source extracted to /home/scottrif/poky/build/workspace/sources/nano
4464 NOTE: New recipe is /home/scottrif/poky/build/workspace/recipes/nano/nano_2.9.3.bb
4465 </literallayout>
4466 Continuing with this example, you can use
4467 <filename>devtool build</filename> to build the newly upgraded
4468 recipe:
4469 <literallayout class='monospaced'>
4470 $ devtool build nano
4471 NOTE: Starting bitbake server...
4472 Loading cache: 100% |################################################################################################| Time: 0:00:01
4473 Loaded 2040 entries from dependency cache.
4474 Parsing recipes: 100% |##############################################################################################| Time: 0:00:00
4475 Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors.
4476 NOTE: Resolving any missing task queue dependencies
4477 .
4478 .
4479 .
4480 NOTE: Executing SetScene Tasks
4481 NOTE: Executing RunQueue Tasks
4482 NOTE: nano: compiling from external source tree /home/scottrif/poky/build/workspace/sources/nano
4483 NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded.
4484 </literallayout>
4485 Within the <filename>devtool upgrade</filename> workflow,
4486 opportunity exists to deploy and test your rebuilt software.
4487 For this example, however, running
4488 <filename>devtool finish</filename> cleans up the workspace
4489 once the source in your workspace is clean.
4490 This usually means using Git to stage and submit commits
4491 for the changes generated by the upgrade process.
4492 </para>
4493
4494 <para>
4495 Once the tree is clean, you can clean things up in this
4496 example with the following command from the
4497 <filename>${BUILDDIR}/workspace/sources/nano</filename>
4498 directory:
4499 <literallayout class='monospaced'>
4500 $ devtool finish nano meta-oe
4501 NOTE: Starting bitbake server...
4502 Loading cache: 100% |################################################################################################| Time: 0:00:00
4503 Loaded 2040 entries from dependency cache.
4504 Parsing recipes: 100% |##############################################################################################| Time: 0:00:01
4505 Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors.
4506 NOTE: Adding new patch 0001-nano.bb-Stuff-I-changed-when-upgrading-nano.bb.patch
4507 NOTE: Updating recipe nano_2.9.3.bb
4508 NOTE: Removing file /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano/nano_2.7.4.bb
4509 NOTE: Moving recipe file to /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano
4510 NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/nano as-is; if you no longer need it then please delete it manually
4511 </literallayout>
4512 Using the <filename>devtool finish</filename> command cleans
4513 up the workspace and creates a patch file based on your
4514 commits.
4515 The tool puts all patch files back into the source directory
4516 in a sub-directory named <filename>nano</filename> in this
4517 case.
4518 </para>
4519 </section>
4520
4521 <section id='dev-manually-upgrading-a-recipe'>
4522 <title>Manually Upgrading a Recipe</title>
4523
4524 </section>
4525 </section>
4526
4071 <section id='finding-the-temporary-source-code'> 4527 <section id='finding-the-temporary-source-code'>
4072 <title>Finding Temporary Source Code</title> 4528 <title>Finding Temporary Source Code</title>
4073 4529
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-09 20:00:16 +0000