summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/sdk-manual')
-rw-r--r--documentation/sdk-manual/figures/sdk-devtool-add-flow.pngbin177945 -> 180562 bytes
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml253
2 files changed, 121 insertions, 132 deletions
diff --git a/documentation/sdk-manual/figures/sdk-devtool-add-flow.png b/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
index 985ac331f1..745a028729 100644
--- a/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
+++ b/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
Binary files differ
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index f23ecc8043..cde599d682 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -205,51 +205,13 @@
205 SDK environment now set up; additionally you may now run devtool to perform development tasks. 205 SDK environment now set up; additionally you may now run devtool to perform development tasks.
206 Run devtool --help for further details. 206 Run devtool --help for further details.
207 </literallayout> 207 </literallayout>
208<!-- 208 Running the setup script defines many environment variables needed
209 Running the setup script defines many environment variables: 209 in order to use the SDK (e.g. <filename>PATH</filename>,
210 <literallayout class='monospaced'> 210 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>,
211 <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar' 211 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>,
212 ARCH - missing this one. It gets set in meta/recipes-devtools/python/python3-native_3.5.5.bb (ARCH=${TARGET_ARCH}) 212 and so forth).
213 <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler 213 If you want to see all the environment variables the script
214 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler 214 exports, examine the installation file itself.
215 <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
216 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
217 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
218 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
219 <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flagsexport CROSS_COMPILE
220 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
221 <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
222 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></ulink>
223 <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
224 KCFLAGS - missing this one. It appears once in meta/classes/toolchain-scripts.bbclass
225 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
226 <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
227 M4 - missing this one. It appears once in meta/recipes-devtools/flex/flex_2.6.0.bb
228 <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
229 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
230 <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
231 OE_SKIP_SDK_CHECK - missing this one. It appears in meta/classes/populate_sdk_ext.bbclass
232 OECORE_ACLOCAL_OPTS - missing this one. It appears in meta/classes/toolchain-scripts.bbclass
233 OECORE_DISTRO_VERSION - missing this one. It appears in meta/classes/toolchain-scripts.bbclass
234 OECORE_NATIVE_SYSROOT - missing this one. It appears in meta/classes/toolchain-scripts.bbclass
235 OECORE_SDK_VERSION - missing this one. It appears in meta/classes/toolchain-scripts.bbclass
236 OECORE_TARGET_SYSROOT - missing this one. It appears in meta/classes/toolchain-scripts.bbclass
237 PATH - The Linux variable that specifies the set of directories where executable programs are located.
238 <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
239 PKG_CONFIG_SYSROOT_DIR - missing this one. It appears in meta/classes/cross-canadian.bbclass:export PKG_CONFIG_SYSROOT_DIR = "${STAGING_DIR_HOST}"
240 <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
241 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
242 <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run strip, which is used to strip symbols.
243 <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
244 </literallayout>
245-->
246 Running the setup script defines many environment variables needed in
247 order to use the SDK (e.g. <filename>PATH</filename>,
248 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>,
249 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>,
250 and so forth).
251 If you want to see all the environment variables the script exports,
252 examine the installation file itself.
253 </para> 215 </para>
254 </section> 216 </section>
255 217
@@ -268,7 +230,7 @@
268 the extensible SDK. 230 the extensible SDK.
269 You can use <filename>devtool</filename> to help you easily 231 You can use <filename>devtool</filename> to help you easily
270 develop any project whose build output must be part of an 232 develop any project whose build output must be part of an
271 image built using the OpenEmbedded build system. 233 image built using the build system.
272 </note> 234 </note>
273 </para> 235 </para>
274 236
@@ -288,8 +250,8 @@
288 </para> 250 </para>
289 251
290 <para> 252 <para>
291 Three <filename>devtool</filename> subcommands that provide 253 Three <filename>devtool</filename> subcommands exist that provide
292 entry-points into development are: 254 entry-points into development:
293 <itemizedlist> 255 <itemizedlist>
294 <listitem><para> 256 <listitem><para>
295 <emphasis><filename>devtool add</filename></emphasis>: 257 <emphasis><filename>devtool add</filename></emphasis>:
@@ -306,17 +268,17 @@
306 an updated set of source files. 268 an updated set of source files.
307 </para></listitem> 269 </para></listitem>
308 </itemizedlist> 270 </itemizedlist>
309 As with the OpenEmbedded build system, "recipes" represent software 271 As with the build system, "recipes" represent software packages
310 packages within <filename>devtool</filename>. 272 within <filename>devtool</filename>.
311 When you use <filename>devtool add</filename>, a recipe is 273 When you use <filename>devtool add</filename>, a recipe is
312 automatically created. 274 automatically created.
313 When you use <filename>devtool modify</filename>, the specified 275 When you use <filename>devtool modify</filename>, the specified
314 existing recipe is used in order to determine where to get the source 276 existing recipe is used in order to determine where to get the
315 code and how to patch it. 277 source code and how to patch it.
316 In both cases, an environment is set up so that when you build the 278 In both cases, an environment is set up so that when you build the
317 recipe a source tree that is under your control is used in order to 279 recipe a source tree that is under your control is used in order to
318 allow you to make changes to the source as desired. 280 allow you to make changes to the source as desired.
319 By default, both new recipes and the source go into a "workspace" 281 By default, new recipes and the source go into a "workspace"
320 directory under the SDK. 282 directory under the SDK.
321 </para> 283 </para>
322 284
@@ -363,10 +325,10 @@
363 generate a recipe based on existing source code.</para> 325 generate a recipe based on existing source code.</para>
364 326
365 <para>In a shared development environment, it is 327 <para>In a shared development environment, it is
366 typical where other developers are responsible for 328 typical for other developers to be responsible for
367 various areas of source code. 329 various areas of source code.
368 As a developer, you are probably interested in using 330 As a developer, you are probably interested in using
369 that source code as part of your development using 331 that source code as part of your development within
370 the Yocto Project. 332 the Yocto Project.
371 All you need is access to the code, a recipe, and a 333 All you need is access to the code, a recipe, and a
372 controlled area in which to do your work.</para> 334 controlled area in which to do your work.</para>
@@ -374,138 +336,164 @@
374 <para>Within the diagram, three possible scenarios 336 <para>Within the diagram, three possible scenarios
375 feed into the <filename>devtool add</filename> workflow: 337 feed into the <filename>devtool add</filename> workflow:
376 <itemizedlist> 338 <itemizedlist>
377 <listitem><para><emphasis>Left</emphasis>: 339 <listitem><para>
378 The left scenario represents a common situation 340 <emphasis>Left</emphasis>:
379 where the source code does not exist locally 341 The left scenario in the figure represents a
380 and needs to be extracted. 342 common situation where the source code does not
381 In this situation, you just let it get 343 exist locally and needs to be extracted.
382 extracted to the default workspace - you do not 344 In this situation, the source code is extracted
383 want it in some specific location outside of the 345 to the default workspace - you do not
384 workspace. 346 want the files in some specific location
385 Thus, everything you need will be located in the 347 outside of the workspace.
386 workspace: 348 Thus, everything you need will be located in
349 the workspace:
387 <literallayout class='monospaced'> 350 <literallayout class='monospaced'>
388 $ devtool add <replaceable>recipe fetchuri</replaceable> 351 $ devtool add <replaceable>recipe fetchuri</replaceable>
389 </literallayout> 352 </literallayout>
390 With this command, <filename>devtool</filename> 353 With this command, <filename>devtool</filename>
391 creates a recipe and an append file in the 354 extracts the upstream source files into a local
392 workspace as well as extracts the upstream 355 Git repository within the
393 source files into a local Git repository also 356 <filename>sources</filename> folder.
394 within the <filename>sources</filename> folder. 357 The command then creates a recipe named
358 <replaceable>recipe</replaceable> and a
359 corresponding append file in the workspace.
360 If you do not provide
361 <replaceable>recipe</replaceable>, the command
362 attempts to figure out the recipe name.
395 </para></listitem> 363 </para></listitem>
396 <listitem><para><emphasis>Middle</emphasis>: 364 <listitem><para>
397 The middle scenario also represents a situation where 365 <emphasis>Middle</emphasis>:
398 the source code does not exist locally. 366 The middle scenario in the figure also
367 represents a situation where the source code
368 does not exist locally.
399 In this case, the code is again upstream 369 In this case, the code is again upstream
400 and needs to be extracted to some 370 and needs to be extracted to some
401 local area - this time outside of the default 371 local area - this time outside of the default
402 workspace. 372 workspace.
403 If required, <filename>devtool</filename> 373 <note>
404 always creates 374 If required, <filename>devtool</filename>
405 a Git repository locally during the extraction. 375 always creates
376 a Git repository locally during the
377 extraction.
378 </note>
406 Furthermore, the first positional argument 379 Furthermore, the first positional argument
407 <replaceable>srctree</replaceable> in this case 380 <replaceable>srctree</replaceable> in this
408 identifies where the 381 case identifies where the
409 <filename>devtool add</filename> command 382 <filename>devtool add</filename> command
410 will locate the extracted code outside of the 383 will locate the extracted code outside of the
411 workspace: 384 workspace.
385 You need to specify an empty directory:
412 <literallayout class='monospaced'> 386 <literallayout class='monospaced'>
413 $ devtool add <replaceable>recipe srctree fetchuri</replaceable> 387 $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
414 </literallayout> 388 </literallayout>
415 In summary, the source code is pulled from 389 In summary, the source code is pulled from
416 <replaceable>fetchuri</replaceable> and extracted 390 <replaceable>fetchuri</replaceable> and
417 into the location defined by 391 extracted into the location defined by
418 <replaceable>srctree</replaceable> as a local 392 <replaceable>srctree</replaceable> as a local
419 Git repository.</para> 393 Git repository.</para>
420 394
421 <para>Within workspace, <filename>devtool</filename> 395 <para>Within workspace,
422 creates both the recipe and an append file 396 <filename>devtool</filename> creates a
423 for the recipe. 397 recipe named <replaceable>recipe</replaceable>
398 along with an associated append file.
424 </para></listitem> 399 </para></listitem>
425 <listitem><para><emphasis>Right</emphasis>: 400 <listitem><para>
426 The right scenario represents a situation 401 <emphasis>Right</emphasis>:
427 where the source tree (srctree) has been 402 The right scenario in the figure represents a
403 situation where the
404 <replaceable>srctree</replaceable> has been
428 previously prepared outside of the 405 previously prepared outside of the
429 <filename>devtool</filename> workspace. 406 <filename>devtool</filename> workspace.</para>
430 </para>
431 407
432 <para>The following command names the recipe 408 <para>The following command provides a new
433 and identifies where the existing source tree 409 recipe name and identifies the existing source
434 is located: 410 tree location:
435 <literallayout class='monospaced'> 411 <literallayout class='monospaced'>
436 $ devtool add <replaceable>recipe srctree</replaceable> 412 $ devtool add <replaceable>recipe srctree</replaceable>
437 </literallayout> 413 </literallayout>
438 The command examines the source code and creates 414 The command examines the source code and
439 a recipe for it placing the recipe into the 415 creates a recipe named
440 workspace.</para> 416 <replaceable>recipe</replaceable> for the code
417 and places the recipe into the workspace.
418 </para>
441 419
442 <para>Because the extracted source code already exists, 420 <para>Because the extracted source code already
443 <filename>devtool</filename> does not try to 421 exists, <filename>devtool</filename> does not
444 relocate it into the workspace - just the new 422 try to relocate the source code into the
445 the recipe is placed in the workspace.</para> 423 workspace - only the new the recipe is placed
424 in the workspace.</para>
446 425
447 <para>Aside from a recipe folder, the command 426 <para>Aside from a recipe folder, the command
448 also creates an append folder and places an initial 427 also creates an associated append folder and
449 <filename>*.bbappend</filename> within. 428 places an initial
429 <filename>*.bbappend</filename> file within.
450 </para></listitem> 430 </para></listitem>
451 </itemizedlist> 431 </itemizedlist>
452 </para></listitem> 432 </para></listitem>
453 <listitem><para><emphasis>Edit the Recipe</emphasis>: 433 <listitem><para>
454 At this point, you can use <filename>devtool edit-recipe</filename> 434 <emphasis>Edit the Recipe</emphasis>:
435 You can use <filename>devtool edit-recipe</filename>
455 to open up the editor as defined by the 436 to open up the editor as defined by the
456 <filename>$EDITOR</filename> environment variable 437 <filename>$EDITOR</filename> environment variable
457 and modify the file: 438 and modify the file:
458 <literallayout class='monospaced'> 439 <literallayout class='monospaced'>
459 $ devtool edit-recipe <replaceable>recipe</replaceable> 440 $ devtool edit-recipe <replaceable>recipe</replaceable>
460 </literallayout> 441 </literallayout>
461 From within the editor, you can make modifications to the 442 From within the editor, you can make modifications to
462 recipe that take affect when you build it later. 443 the recipe that take affect when you build it later.
463 </para></listitem> 444 </para></listitem>
464 <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>: 445 <listitem><para>
465 At this point in the flow, the next step you 446 <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
466 take depends on what you are going to do with 447 The next step you take depends on what you are going
467 the new code.</para> 448 to do with the new code.</para>
468 <para>If you need to take the build output and eventually 449
469 move it to the target hardware, you would use 450 <para>If you need to eventually move the build output
470 <filename>devtool build</filename>: 451 to the target hardware, use the following
452 <filename>devtool</filename> command:
471 <literallayout class='monospaced'> 453 <literallayout class='monospaced'>
472 $ devtool build <replaceable>recipe</replaceable> 454 $ devtool build <replaceable>recipe</replaceable>
473 </literallayout></para> 455 </literallayout></para>
456
474 <para>On the other hand, if you want an image to 457 <para>On the other hand, if you want an image to
475 contain the recipe's packages for immediate deployment 458 contain the recipe's packages from the workspace
476 onto a device (e.g. for testing purposes), you can use 459 for immediate deployment onto a device (e.g. for
460 testing purposes), you can use
477 the <filename>devtool build-image</filename> command: 461 the <filename>devtool build-image</filename> command:
478 <literallayout class='monospaced'> 462 <literallayout class='monospaced'>
479 $ devtool build-image <replaceable>image</replaceable> 463 $ devtool build-image <replaceable>image</replaceable>
480 </literallayout> 464 </literallayout>
481 </para></listitem> 465 </para></listitem>
482 <listitem><para><emphasis>Deploy the Build Output</emphasis>: 466 <listitem><para>
467 <emphasis>Deploy the Build Output</emphasis>:
483 When you use the <filename>devtool build</filename> 468 When you use the <filename>devtool build</filename>
484 command to build out your recipe, you probably want to 469 command to build out your recipe, you probably want to
485 see if the resulting build output works as expected on target 470 see if the resulting build output works as expected
486 hardware. 471 on the target hardware.
487 <note> 472 <note>
488 This step assumes you have a previously built 473 This step assumes you have a previously built
489 image that is already either running in QEMU or 474 image that is already either running in QEMU or
490 running on actual hardware. 475 is running on actual hardware.
491 Also, it is assumed that for deployment of the image 476 Also, it is assumed that for deployment of the
492 to the target, SSH is installed in the image and if 477 image to the target, SSH is installed in the image
493 the image is running on real hardware that you have 478 and, if the image is running on real hardware,
494 network access to and from your development machine. 479 you have network access to and from your
480 development machine.
495 </note> 481 </note>
496 You can deploy your build output to that target hardware by 482 You can deploy your build output to that target
497 using the <filename>devtool deploy-target</filename> command: 483 hardware by using the
484 <filename>devtool deploy-target</filename> command:
498 <literallayout class='monospaced'> 485 <literallayout class='monospaced'>
499 $ devtool deploy-target <replaceable>recipe target</replaceable> 486 $ devtool deploy-target <replaceable>recipe target</replaceable>
500 </literallayout> 487 </literallayout>
501 The <replaceable>target</replaceable> is a live target machine 488 The <replaceable>target</replaceable> is a live target
502 running as an SSH server.</para> 489 machine running as an SSH server.</para>
503 490
504 <para>You can, of course, also deploy the image you build 491 <para>You can, of course, also deploy the image you
505 using the <filename>devtool build-image</filename> command 492 build to actual hardware by using the
506 to actual hardware. 493 <filename>devtool build-image</filename> command.
507 However, <filename>devtool</filename> does not provide a 494 However, <filename>devtool</filename> does not provide
508 specific command that allows you to do this. 495 a specific command that allows you to deploy the
496 image to actual hardware.
509 </para></listitem> 497 </para></listitem>
510 <listitem><para> 498 <listitem><para>
511 <emphasis>Finish Your Work With the Recipe</emphasis>: 499 <emphasis>Finish Your Work With the Recipe</emphasis>:
@@ -522,8 +510,9 @@
522 committed to the Git repository in the source tree. 510 committed to the Git repository in the source tree.
523 </note></para> 511 </note></para>
524 512
525 <para>As mentioned, the <filename>devtool finish</filename> 513 <para>As mentioned, the
526 command moves the final recipe to its permanent layer. 514 <filename>devtool finish</filename> command moves the
515 final recipe to its permanent layer.
527 </para> 516 </para>
528 517
529 <para>As a final process of the 518 <para>As a final process of the
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-14 20:22:18 +0000