summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-model.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-model.xml')
-rw-r--r--documentation/dev-manual/dev-manual-model.xml175
1 files changed, 0 insertions, 175 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 173871a843..aeaa3fd9d3 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -718,179 +718,4 @@
718 </section> 718 </section>
719</section> 719</section>
720 720
721<section id="platdev-appdev-devshell">
722 <title>Using a Development Shell</title>
723
724 <para>
725 When debugging certain commands or even when just editing packages,
726 <filename>devshell</filename> can be a useful tool.
727 When you invoke <filename>devshell</filename>, all tasks up to and
728 including
729 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
730 are run for the specified target.
731 Then, a new terminal is opened and you are placed in
732 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
733 the source directory.
734 In the new terminal, all the OpenEmbedded build-related environment variables are
735 still defined so you can use commands such as <filename>configure</filename> and
736 <filename>make</filename>.
737 The commands execute just as if the OpenEmbedded build system were executing them.
738 Consequently, working this way can be helpful when debugging a build or preparing
739 software to be used with the OpenEmbedded build system.
740 </para>
741
742 <para>
743 Following is an example that uses <filename>devshell</filename> on a target named
744 <filename>matchbox-desktop</filename>:
745 <literallayout class='monospaced'>
746 $ bitbake matchbox-desktop -c devshell
747 </literallayout>
748 </para>
749
750 <para>
751 This command spawns a terminal with a shell prompt within the OpenEmbedded build environment.
752 The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
753 variable controls what type of shell is opened.
754 </para>
755
756 <para>
757 For spawned terminals, the following occurs:
758 <itemizedlist>
759 <listitem><para>The <filename>PATH</filename> variable includes the
760 cross-toolchain.</para></listitem>
761 <listitem><para>The <filename>pkgconfig</filename> variables find the correct
762 <filename>.pc</filename> files.</para></listitem>
763 <listitem><para>The <filename>configure</filename> command finds the
764 Yocto Project site files as well as any other necessary files.</para></listitem>
765 </itemizedlist>
766 </para>
767
768 <para>
769 Within this environment, you can run configure or compile
770 commands as if they were being run by
771 the OpenEmbedded build system itself.
772 As noted earlier, the working directory also automatically changes to the
773 Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
774 </para>
775
776 <para>
777 To manually run a specific task using <filename>devshell</filename>,
778 run the corresponding <filename>run.*</filename> script in
779 the
780 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp</filename>
781 directory (e.g.,
782 <filename>run.do_configure.</filename><replaceable>pid</replaceable>).
783 If a task's script does not exist, which would be the case if the task was
784 skipped by way of the sstate cache, you can create the task by first running
785 it outside of the <filename>devshell</filename>:
786 <literallayout class='monospaced'>
787 $ bitbake -c <replaceable>task</replaceable>
788 </literallayout>
789 <note><title>Notes</title>
790 <itemizedlist>
791 <listitem><para>Execution of a task's <filename>run.*</filename>
792 script and BitBake's execution of a task are identical.
793 In other words, running the script re-runs the task
794 just as it would be run using the
795 <filename>bitbake -c</filename> command.
796 </para></listitem>
797 <listitem><para>Any <filename>run.*</filename> file that does not
798 have a <filename>.pid</filename> extension is a
799 symbolic link (symlink) to the most recent version of that
800 file.
801 </para></listitem>
802 </itemizedlist>
803 </note>
804 </para>
805
806 <para>
807 Remember, that the <filename>devshell</filename> is a mechanism that allows
808 you to get into the BitBake task execution environment.
809 And as such, all commands must be called just as BitBake would call them.
810 That means you need to provide the appropriate options for
811 cross-compilation and so forth as applicable.
812 </para>
813
814 <para>
815 When you are finished using <filename>devshell</filename>, exit the shell
816 or close the terminal window.
817 </para>
818
819 <note><title>Notes</title>
820 <itemizedlist>
821 <listitem><para>
822 It is worth remembering that when using <filename>devshell</filename>
823 you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename>
824 instead of just using <filename>gcc</filename>.
825 The same applies to other applications such as <filename>binutils</filename>,
826 <filename>libtool</filename> and so forth.
827 BitBake sets up environment variables such as <filename>CC</filename>
828 to assist applications, such as <filename>make</filename> to find the correct tools.
829 </para></listitem>
830 <listitem><para>
831 It is also worth noting that <filename>devshell</filename> still works over
832 X11 forwarding and similar situations.
833 </para></listitem>
834 </itemizedlist>
835 </note>
836</section>
837
838<section id="platdev-appdev-devpyshell">
839 <title>Using a Development Python Shell</title>
840
841 <para>
842 Similar to working within a development shell as described in
843 the previous section, you can also spawn and work within an
844 interactive Python development shell.
845 When debugging certain commands or even when just editing packages,
846 <filename>devpyshell</filename> can be a useful tool.
847 When you invoke <filename>devpyshell</filename>, all tasks up to and
848 including
849 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
850 are run for the specified target.
851 Then a new terminal is opened.
852 Additionally, key Python objects and code are available in the same
853 way they are to BitBake tasks, in particular, the data store 'd'.
854 So, commands such as the following are useful when exploring the data
855 store and running functions:
856 <literallayout class='monospaced'>
857 pydevshell> d.getVar("STAGING_DIR", True)
858 '/media/build1/poky/build/tmp/sysroots'
859 pydevshell> d.getVar("STAGING_DIR", False)
860 '${TMPDIR}/sysroots'
861 pydevshell> d.setVar("FOO", "bar")
862 pydevshell> d.getVar("FOO", True)
863 'bar'
864 pydevshell> d.delVar("FOO")
865 pydevshell> d.getVar("FOO", True)
866 pydevshell> bb.build.exec_func("do_unpack", d)
867 pydevshell>
868 </literallayout>
869 The commands execute just as if the OpenEmbedded build system were executing them.
870 Consequently, working this way can be helpful when debugging a build or preparing
871 software to be used with the OpenEmbedded build system.
872 </para>
873
874 <para>
875 Following is an example that uses <filename>devpyshell</filename> on a target named
876 <filename>matchbox-desktop</filename>:
877 <literallayout class='monospaced'>
878 $ bitbake matchbox-desktop -c devpyshell
879 </literallayout>
880 </para>
881
882 <para>
883 This command spawns a terminal and places you in an interactive
884 Python interpreter within the OpenEmbedded build environment.
885 The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
886 variable controls what type of shell is opened.
887 </para>
888
889 <para>
890 When you are finished using <filename>devpyshell</filename>, you
891 can exit the shell either by using Ctrl+d or closing the terminal
892 window.
893 </para>
894</section>
895
896</chapter> 721</chapter>