summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/sdk-manual/sdk-appendix-customizing.xml607
1 files changed, 607 insertions, 0 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-customizing.xml b/documentation/sdk-manual/sdk-appendix-customizing.xml
index d38320f8bb..9fca16571f 100644
--- a/documentation/sdk-manual/sdk-appendix-customizing.xml
+++ b/documentation/sdk-manual/sdk-appendix-customizing.xml
@@ -383,6 +383,613 @@
383 </para> 383 </para>
384</section> 384</section>
385 385
386<section id='sdk-a-closer-look-at-devtool-add'>
387 <title>A Closer Look at <filename>devtool add</filename></title>
388
389 <para>
390 The <filename>devtool add</filename> command automatically creates a
391 recipe based on the source tree with which you provide it.
392 Currently, the command has support for the following:
393 <itemizedlist>
394 <listitem><para>
395 Autotools (<filename>autoconf</filename> and
396 <filename>automake</filename>)
397 </para></listitem>
398 <listitem><para>
399 <filename>CMake</filename>
400 </para></listitem>
401 <listitem><para>
402 <filename>Scons</filename>
403 </para></listitem>
404 <listitem><para>
405 <filename>qmake</filename>
406 </para></listitem>
407 <listitem><para>
408 Plain <filename>Makefile</filename>
409 </para></listitem>
410 <listitem><para>
411 Out-of-tree kernel module
412 </para></listitem>
413 <listitem><para>
414 Binary package (i.e. "-b" option)
415 </para></listitem>
416 <listitem><para>
417 <filename>Node.js</filename> module through
418 <filename>npm</filename>
419 </para></listitem>
420 <listitem><para>
421 Python modules that use <filename>setuptools</filename>
422 or <filename>distutils</filename>
423 </para></listitem>
424 </itemizedlist>
425 </para>
426
427 <para>
428 Apart from binary packages, the determination of how a source tree
429 should be treated is automatic based on the files present within
430 that source tree.
431 For example, if a <filename>CMakeLists.txt</filename> file is found,
432 then the source tree is assumed to be using
433 <filename>CMake</filename> and is treated accordingly.
434 <note>
435 In most cases, you need to edit the automatically generated
436 recipe in order to make it build properly.
437 Typically, you would go through several edit and build cycles
438 until you can build the recipe.
439 Once the recipe can be built, you could use possible further
440 iterations to test the recipe on the target device.
441 </note>
442 </para>
443
444 <para>
445 The remainder of this section covers specifics regarding how parts
446 of the recipe are generated.
447 </para>
448
449 <section id='sdk-name-and-version'>
450 <title>Name and Version</title>
451
452 <para>
453 If you do not specify a name and version on the command
454 line, <filename>devtool add</filename> attempts to determine
455 the name and version of the software being built from
456 various metadata within the source tree.
457 Furthermore, the command sets the name of the created recipe
458 file accordingly.
459 If the name or version cannot be determined, the
460 <filename>devtool add</filename> command prints an error and
461 you must re-run the command with both the name and version
462 or just the name or version specified.
463 </para>
464
465 <para>
466 Sometimes the name or version determined from the source tree
467 might be incorrect.
468 For such a case, you must run the following commands:
469 <literallayout class='monospaced'>
470 $ devtool reset -n <replaceable>recipename</replaceable>
471 </literallayout>
472 After running the <filename>devtool reset</filename> command,
473 you need to run <filename>devtool add</filename> again and
474 provide the name or the version.
475 </para>
476 </section>
477
478 <section id='sdk-dependency-detection-and-mapping'>
479 <title>Dependency Detection and Mapping</title>
480
481 <para>
482 The <filename>devtool add</filename> command attempts to
483 detect build-time dependencies and map them to other recipes
484 in the system.
485 During this mapping, the command fills in the names of those
486 recipes in the
487 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
488 value within the recipe.
489 If a dependency cannot be mapped, then a comment is placed in
490 the recipe indicating such.
491 The inability to map a dependency might be caused because the
492 naming is not recognized or because the dependency simply is
493 not available.
494 For cases where the dependency is not available, you must use
495 the <filename>devtool add</filename> command to add an
496 additional recipe to satisfy the dependency and then come
497 back to the first recipe and add its name to
498 <filename>DEPENDS</filename>.
499 </para>
500
501 <para>
502 If you need to add runtime dependencies, you can do so by
503 adding the following to your recipe:
504 <literallayout class='monospaced'>
505 RDEPENDS_${PN} += "dependency1 dependency2 ..."
506 </literallayout>
507 <note>
508 The <filename>devtool add</filename> command often cannot
509 distinguish between mandatory and optional dependencies.
510 Consequently, some of the detected dependencies might
511 in fact be optional.
512 When in doubt, consult the documentation or the configure
513 script for the software the recipe is building for further
514 details.
515 In some cases, you might find you can substitute the
516 dependency for an option to disable the associated
517 functionality passed to the configure script.
518 </note>
519 </para>
520 </section>
521
522 <section id='sdk-license-detection'>
523 <title>License Detection</title>
524
525 <para>
526 The <filename>devtool add</filename> command attempts to
527 determine if the software you are adding is able to be
528 distributed under a common open-source license and sets the
529 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
530 value accordingly.
531 You should double-check this value against the documentation
532 or source files for the software you are building and update
533 that <filename>LICENSE</filename> value if necessary.
534 </para>
535
536 <para>
537 The <filename>devtool add</filename> command also sets the
538 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
539 value to point to all files that appear to be license-related.
540 However, license statements often appear in comments at the top
541 of source files or within documentation.
542 Consequently, you might need to amend the
543 <filename>LIC_FILES_CHKSUM</filename> variable to point to one
544 or more of those comments if present.
545 Setting <filename>LIC_FILES_CHKSUM</filename> is particularly
546 important for third-party software.
547 The command attempts to ensure correct licensing should you
548 upgrade the recipe to a newer upstream version in future.
549 Any change in licensing is detected and you receive an error
550 prompting you to check the license text again.
551 </para>
552
553 <para>
554 If the <filename>devtool add</filename> command cannot
555 determine licensing information, the
556 <filename>LICENSE</filename> value is set to "CLOSED" and the
557 <filename>LIC_FILES_CHKSUM</filename> vaule remains unset.
558 This behavior allows you to continue with development but is
559 unlikely to be correct in all cases.
560 Consequently, you should check the documentation or source
561 files for the software you are building to determine the actual
562 license.
563 </para>
564 </section>
565
566 <section id='sdk-adding-makefile-only-software'>
567 <title>Adding Makefile-Only Software</title>
568
569 <para>
570 The use of <filename>make</filename> by itself is very common
571 in both proprietary and open source software.
572 Unfortunately, Makefiles are often not written with
573 cross-compilation in mind.
574 Thus, <filename>devtool add</filename> often cannot do very
575 much to ensure that these Makefiles build correctly.
576 It is very common, for example, to explicitly call
577 <filename>gcc</filename> instead of using the
578 <filename>CC</filename> variable.
579 Usually, in a cross-compilation environment,
580 <filename>gcc</filename> is the compiler for the build host
581 and the cross-compiler is named something similar to
582 <filename>arm-poky-linux-gnueabi-gcc</filename> and might
583 require some arguments (e.g. to point to the associated sysroot
584 for the target machine).
585 </para>
586
587 <para>
588 When writing a recipe for Makefile-only software, keep the
589 following in mind:
590 <itemizedlist>
591 <listitem><para>
592 You probably need to patch the Makefile to use
593 variables instead of hardcoding tools within the
594 toolchain such as <filename>gcc</filename> and
595 <filename>g++</filename>.
596 </para></listitem>
597 <listitem><para>
598 The environment in which <filename>make</filename> runs
599 is set up with various standard variables for
600 compilation (e.g. <filename>CC</filename>,
601 <filename>CXX</filename>, and so forth) in a similar
602 manner to the environment set up by the SDK's
603 environment setup script.
604 One easy way to see these variables is to run the
605 <filename>devtool build</filename> command on the
606 recipe and then look in
607 <filename>oe-logs/run.do_compile</filename>.
608 Towards the top of this file you will see a list of
609 environment variables that are being set.
610 You can take advantage of these variables within the
611 Makefile.
612 </para></listitem>
613 <listitem><para>
614 If the Makefile sets a default for a variable, that
615 default overrides the value set in the environment,
616 which is usually not desirable.
617 In this situation, you can either patch the Makefile
618 so it sets the default using the "?=" operator, or
619 you can alternatively force the value on the
620 <filename>make</filename> command line.
621 To force the value on the command line, add the
622 variable setting to
623 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink>
624 within the recipe as follows:
625 <literallayout class='monospaced'>
626 EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
627 </literallayout>
628 In the above example, single quotes are used around the
629 variable settings as the values are likely to contain
630 spaces because required default options are passed to
631 the compiler.
632 </para></listitem>
633 <listitem><para>
634 Hardcoding paths inside Makefiles is often problematic
635 in a cross-compilation environment.
636 This is particularly true because those hardcoded paths
637 often point to locations on the build host and thus
638 will either be read-only or will introduce
639 contamination into the cross-compilation by virtue of
640 being specific to the build host rather than the target.
641 Patching the Makefile to use prefix variables or other
642 path variables is usually the way to handle this.
643 </para></listitem>
644 <listitem><para>
645 Sometimes a Makefile runs target-specific commands such
646 as <filename>ldconfig</filename>.
647 For such cases, you might be able to simply apply
648 patches that remove these commands from the Makefile.
649 </para></listitem>
650 </itemizedlist>
651 </para>
652 </section>
653
654 <section id='sdk-adding-native-tools'>
655 <title>Adding Native Tools</title>
656
657 <para>
658 Often, you need to build additional tools that run on the
659 build host system as opposed to the target.
660 You should indicate this using one of the following methods
661 when you run <filename>devtool add</filename>:
662 <itemizedlist>
663 <listitem><para>
664 Specify the name of the recipe such that it ends
665 with "-native".
666 Specifying the name like this produces a recipe that
667 only builds for the build host.
668 </para></listitem>
669 <listitem><para>
670 Specify the "&dash;&dash;also-native" option with the
671 <filename>devtool add</filename> command.
672 Specifying this option creates a recipe file that still
673 builds for the target but also creates a variant with
674 a "-native" suffix that builds for the build host.
675 </para></listitem>
676 </itemizedlist>
677 <note>
678 If you need to add a tool that is shipped as part of a
679 source tree that builds code for the target, you can
680 typically accomplish this by building the native and target
681 parts separately rather than within the same compilation
682 process.
683 Realize though that with the "&dash;&dash;also-native" option, you
684 can add the tool using just one recipe file.
685 </note>
686 </para>
687 </section>
688
689 <section id='sdk-adding-node-js-modules'>
690 <title>Adding <filename>Node.js</filename> Modules</title>
691
692 <para>
693 You can use the <filename>devtool add</filename> command in the
694 following form to add <filename>Node.js</filename> modules:
695 <literallayout class='monospaced'>
696 $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
697 </literallayout>
698 The name and version parameters are mandatory.
699 Lockdown and shrinkwrap files are generated and pointed to by
700 the recipe in order to freeze the version that is fetched for
701 the dependencies according to the first time.
702 This also saves checksums that are verified on future fetches.
703 Together, these behaviors ensure the reproducibility and
704 integrity of the build.
705 <note><title>Notes</title>
706 <itemizedlist>
707 <listitem><para>
708 You must use quotes around the URL.
709 The <filename>devtool add</filename> does not require
710 the quotes, but the shell considers ";" as a splitter
711 between multiple commands.
712 Thus, <filename>devtool add</filename> does not receive
713 the other parts resulting in several "command not found"
714 errors.
715 </para></listitem>
716 <listitem><para>
717 In order to support adding
718 <filename>Node.js</filename> modules, a
719 <filename>nodejs</filename> recipe must be part of your
720 SDK in order to provide <filename>Node.js</filename>
721 itself.
722 </para></listitem>
723 </itemizedlist>
724 </note>
725 </para>
726 </section>
727</section>
728
729<section id='sdk-working-with-recipes'>
730 <title>Working With Recipes</title>
731
732 <para>
733 When building a recipe with <filename>devtool build</filename> the
734 typical workflow is as follows:
735 <orderedlist>
736 <listitem><para>
737 Fetch the source
738 </para></listitem>
739 <listitem><para>
740 Unpack the source
741 </para></listitem>
742 <listitem><para>
743 Configure the source
744 </para></listitem>
745 <listitem><para>
746 Compiling the source
747 </para></listitem>
748 <listitem><para>
749 Install the build output
750 </para></listitem>
751 <listitem><para>
752 Package the installed output
753 </para></listitem>
754 </orderedlist>
755 For recipes in the workspace, fetching and unpacking is disabled
756 as the source tree has already been prepared and is persistent.
757 Each of these build steps is defined as a function, usually with a
758 "do_" prefix.
759 These functions are typically shell scripts but can instead be written
760 in Python.
761 </para>
762
763 <para>
764 If you look at the contents of a recipe, you will see that the
765 recipe does not include complete instructions for building the
766 software.
767 Instead, common functionality is encapsulated in classes inherited
768 with the <filename>inherit</filename> directive, leaving the recipe
769 to describe just the things that are specific to the software to be
770 built.
771 A <ulink url='ref-classes-base'><filename>base</filename></ulink>
772 class exists that is implicitly inherited by all recipes and provides
773 the functionality that most typical recipes need.
774 </para>
775
776 <para>
777 The remainder of this section presents information useful when
778 working with recipes.
779 </para>
780
781 <section id='sdk-finding-logs-and-work-files'>
782 <title>Finding Logs and Work Files</title>
783
784 <para>
785 When you are debugging a recipe that you previously created using
786 <filename>devtool add</filename> or whose source you are modifying
787 by using the <filename>devtool modify</filename> command, after
788 the first run of <filename>devtool build</filename>, you will
789 find some symbolic links created within the source tree:
790 <filename>oe-logs</filename>, which points to the directory in
791 which log files and run scripts for each build step are created
792 and <filename>oe-workdir</filename>, which points to the temporary
793 work area for the recipe.
794 You can use these links to get more information on what is
795 happening at each build step.
796 </para>
797
798 <para>
799 These locations under <filename>oe-workdir</filename> are
800 particularly useful:
801 <itemizedlist>
802 <listitem><para><filename>image/</filename>:
803 Contains all of the files installed at the
804 <ulink url='&YOCTO_DOCS_REF_URL;ref-tasks-install'><filename>do_install</filename></ulink>
805 stage.
806 Within a recipe, this directory is referred to by the
807 expression
808 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
809 </para></listitem>
810 <listitem><para><filename>sysroot-destdir/</filename>:
811 Contains a subset of files installed within
812 <filename>do_install</filename> that have been put into the
813 shared sysroot.
814 For more information, see the
815 "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
816 section.
817 </para></listitem>
818 <listitem><para><filename>packages-split/</filename>:
819 Contains subdirectories for each package produced by the
820 recipe. (more on "Packaging" below)
821 For more information, see the
822 "<link linkend='sdk-packaging'>Packaging</link>" section.
823 </para></listitem>
824 </itemizedlist>
825 </para>
826 </section>
827
828 <section id='sdk-setting-configure-arguments'>
829 <title>Setting Configure Arguments</title>
830
831 <para>
832 If the software your recipe is building uses GNU autoconf,
833 then a fixed set of arguments is passed to it to enable
834 cross-compilation plus any extras specified by
835 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
836 set within the recipe.
837 If you wish to pass additional options, add them to
838 <filename>EXTRA_OECONF</filename>.
839 Other supported build tools have similar variables
840 (e.g.
841 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink>
842 for CMake,
843 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink>
844 for <filename>Scons</filename>, and so forth).
845 If you need to pass anything on the <filename>make</filename>
846 command line, you can use <filename>EXTRA_OEMAKE</filename> to do
847 so.
848 </para>
849
850 <para>
851 You can use the <filename>devtool configure-help</filename> command
852 to help you set the arguments listed in the previous paragraph.
853 The command determines the exact options being passed, and shows
854 them to you along with any custom arguments specified through
855 <filename>EXTRA_OECONF</filename>.
856 If applicable, the command also shows you the output of the
857 configure script's "&dash;&dash;help" option as a reference.
858 </para>
859 </section>
860
861 <section id='sdk-sharing-files-between-recipes'>
862 <title>Sharing Files Between Recipes</title>
863
864 <para>
865 Recipes often need to use files provided by other recipes on
866 the build host.
867 For example, an application linking to a common library needs
868 access to the library itself and its associated headers.
869 The way this access is accomplished within the extensible SDK is
870 through the sysroot.
871 One sysroot exists per "machine" for which the SDK is being built.
872 In practical terms, this means a sysroot exists for the target
873 machine, and a sysroot exists for the build host.
874 </para>
875
876 <para>
877 Recipes should never write files directly into the sysroot.
878 Instead, files should be installed into standard locations
879 during the
880 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
881 task within the
882 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
883 directory.
884 A subset of these files automatically go into the sysroot.
885 The reason for this limitation is that almost all files that go
886 into the sysroot are cataloged in manifests in order to ensure
887 they can be removed later when a a recipe is modified or removed.
888 Thus, the sysroot is able to remain free from stale files.
889 </para>
890 </section>
891
892 <section id='sdk-packaging'>
893 <title>Packaging</title>
894
895 <para>
896 Packaging is not always particularly relevant within the
897 extensible SDK.
898 However, if you examine build output gets into the final image on
899 the target device, it is important to understand packaging
900 because the contents of the image are expressed in terms of
901 packages ... not recipes.
902 </para>
903
904 <para>
905 During the
906 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
907 task, files installed during the
908 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
909 task are split into one main package, which is almost always named
910 the same as the recipe, and several other packages.
911 This separation is done because not all of those installed files
912 are always useful in every image.
913 For example, you probably do not need any of the documentation
914 installed in a production image.
915 Consequently, for each recipe the documentation files are separated
916 into a <filename>-doc</filename> package.
917 Recipes that package software that has optional modules or
918 plugins might do additional package splitting as well.
919 </para>
920
921 <para>
922 After building a recipe you can see where files have gone by
923 looking in the <filename>oe-workdir/packages-split</filename>
924 directory, which contains a subdirectory for each package.
925 Apart from some advanced cases, the
926 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
927 and
928 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
929 variables controls splitting.
930 The <filename>PACKAGES</filename> variable lists all of the
931 packages to be produced, while the <filename>FILES</filename>
932 variable specifies which files to include in each package,
933 using an override to specify the package.
934 For example, <filename>FILES_${PN}</filename> specifies the files
935 to go into the main package (i.e. the main package is named the
936 same as the recipe and
937 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
938 evaluates to the recipe name).
939 The order of the <filename>PACKAGES</filename> value is significant.
940 For each installed file, the first package whose
941 <filename>FILES</filename> value matches the file is the package
942 into which the file goes.
943 Defaults exist for both the <filename>PACKAGES</filename> and
944 <filename>FILES</filename> variables.
945 Consequently, you might find you do not even need to set these
946 variables in your recipe unless the software the recipe is
947 building installs files into non-standard locations.
948 </para>
949 </section>
950
951 <section id='sdk-restoring-the-target-device-to-its-original-state'>
952 <title>Restoring the Target Device to its Original State</title>
953
954 <para>
955 If you use the <filename>devtool deploy-target</filename>
956 command to write a recipe's build output to the target, and
957 you are working on an existing component of the system, then you
958 might find yourself in a situation where you need to restore the
959 original files that existed prior to running the
960 <filename>devtool deploy-target</filename> command.
961 Because the <filename>devtool deploy-target</filename> command
962 backs up any files it overwrites, you can use the
963 <filename>devtool undeploy-target</filename> to restore those files
964 and remove any other files the recipe deployed.
965 Consider the following example:
966 <literallayout class='monospaced'>
967 $ devtool undeploy-target lighttpd root@192.168.7.2
968 </literallayout>
969 If you have deployed multiple applications, you can remove them
970 all at once thus restoring the target device back to its
971 original state:
972 <literallayout class='monospaced'>
973 $ devtool undeploy-target -a root@192.168.7.2
974 </literallayout>
975 Information about files deployed to the target as well as any
976 backed up files are stored on the target itself.
977 This storage of course requires some additional space
978 on the target machine.
979 <note>
980 The <filename>devtool deploy-target</filename> and
981 <filename>devtool undeploy-target</filename> command do not
982 currently interact with any package management system on the
983 target device (e.g. RPM or OPKG).
984 Consequently, you should not intermingle operations
985 <filename>devtool deploy-target</filename> and the package
986 manager operations on the target device.
987 Doing so could result in a conflicting set of files.
988 </note>
989 </para>
990 </section>
991</section>
992
386</appendix> 993</appendix>
387<!-- 994<!--
388vim: expandtab tw=80 ts=4 995vim: expandtab tw=80 ts=4