summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml175
-rw-r--r--documentation/dev-manual/dev-manual-model.xml175
2 files changed, 175 insertions, 175 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index b01871bfe7..c6efcf6699 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4202,6 +4202,181 @@
4202 </para> 4202 </para>
4203 </section> 4203 </section>
4204 4204
4205 <section id="platdev-appdev-devshell">
4206 <title>Using a Development Shell</title>
4207
4208 <para>
4209 When debugging certain commands or even when just editing packages,
4210 <filename>devshell</filename> can be a useful tool.
4211 When you invoke <filename>devshell</filename>, all tasks up to and
4212 including
4213 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
4214 are run for the specified target.
4215 Then, a new terminal is opened and you are placed in
4216 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>,
4217 the source directory.
4218 In the new terminal, all the OpenEmbedded build-related environment variables are
4219 still defined so you can use commands such as <filename>configure</filename> and
4220 <filename>make</filename>.
4221 The commands execute just as if the OpenEmbedded build system were executing them.
4222 Consequently, working this way can be helpful when debugging a build or preparing
4223 software to be used with the OpenEmbedded build system.
4224 </para>
4225
4226 <para>
4227 Following is an example that uses <filename>devshell</filename> on a target named
4228 <filename>matchbox-desktop</filename>:
4229 <literallayout class='monospaced'>
4230 $ bitbake matchbox-desktop -c devshell
4231 </literallayout>
4232 </para>
4233
4234 <para>
4235 This command spawns a terminal with a shell prompt within the OpenEmbedded build environment.
4236 The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
4237 variable controls what type of shell is opened.
4238 </para>
4239
4240 <para>
4241 For spawned terminals, the following occurs:
4242 <itemizedlist>
4243 <listitem><para>The <filename>PATH</filename> variable includes the
4244 cross-toolchain.</para></listitem>
4245 <listitem><para>The <filename>pkgconfig</filename> variables find the correct
4246 <filename>.pc</filename> files.</para></listitem>
4247 <listitem><para>The <filename>configure</filename> command finds the
4248 Yocto Project site files as well as any other necessary files.</para></listitem>
4249 </itemizedlist>
4250 </para>
4251
4252 <para>
4253 Within this environment, you can run configure or compile
4254 commands as if they were being run by
4255 the OpenEmbedded build system itself.
4256 As noted earlier, the working directory also automatically changes to the
4257 Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
4258 </para>
4259
4260 <para>
4261 To manually run a specific task using <filename>devshell</filename>,
4262 run the corresponding <filename>run.*</filename> script in
4263 the
4264 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp</filename>
4265 directory (e.g.,
4266 <filename>run.do_configure.</filename><replaceable>pid</replaceable>).
4267 If a task's script does not exist, which would be the case if the task was
4268 skipped by way of the sstate cache, you can create the task by first running
4269 it outside of the <filename>devshell</filename>:
4270 <literallayout class='monospaced'>
4271 $ bitbake -c <replaceable>task</replaceable>
4272 </literallayout>
4273 <note><title>Notes</title>
4274 <itemizedlist>
4275 <listitem><para>Execution of a task's <filename>run.*</filename>
4276 script and BitBake's execution of a task are identical.
4277 In other words, running the script re-runs the task
4278 just as it would be run using the
4279 <filename>bitbake -c</filename> command.
4280 </para></listitem>
4281 <listitem><para>Any <filename>run.*</filename> file that does not
4282 have a <filename>.pid</filename> extension is a
4283 symbolic link (symlink) to the most recent version of that
4284 file.
4285 </para></listitem>
4286 </itemizedlist>
4287 </note>
4288 </para>
4289
4290 <para>
4291 Remember, that the <filename>devshell</filename> is a mechanism that allows
4292 you to get into the BitBake task execution environment.
4293 And as such, all commands must be called just as BitBake would call them.
4294 That means you need to provide the appropriate options for
4295 cross-compilation and so forth as applicable.
4296 </para>
4297
4298 <para>
4299 When you are finished using <filename>devshell</filename>, exit the shell
4300 or close the terminal window.
4301 </para>
4302
4303 <note><title>Notes</title>
4304 <itemizedlist>
4305 <listitem><para>
4306 It is worth remembering that when using <filename>devshell</filename>
4307 you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename>
4308 instead of just using <filename>gcc</filename>.
4309 The same applies to other applications such as <filename>binutils</filename>,
4310 <filename>libtool</filename> and so forth.
4311 BitBake sets up environment variables such as <filename>CC</filename>
4312 to assist applications, such as <filename>make</filename> to find the correct tools.
4313 </para></listitem>
4314 <listitem><para>
4315 It is also worth noting that <filename>devshell</filename> still works over
4316 X11 forwarding and similar situations.
4317 </para></listitem>
4318 </itemizedlist>
4319 </note>
4320 </section>
4321
4322 <section id="platdev-appdev-devpyshell">
4323 <title>Using a Development Python Shell</title>
4324
4325 <para>
4326 Similar to working within a development shell as described in
4327 the previous section, you can also spawn and work within an
4328 interactive Python development shell.
4329 When debugging certain commands or even when just editing packages,
4330 <filename>devpyshell</filename> can be a useful tool.
4331 When you invoke <filename>devpyshell</filename>, all tasks up to and
4332 including
4333 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
4334 are run for the specified target.
4335 Then a new terminal is opened.
4336 Additionally, key Python objects and code are available in the same
4337 way they are to BitBake tasks, in particular, the data store 'd'.
4338 So, commands such as the following are useful when exploring the data
4339 store and running functions:
4340 <literallayout class='monospaced'>
4341 pydevshell> d.getVar("STAGING_DIR", True)
4342 '/media/build1/poky/build/tmp/sysroots'
4343 pydevshell> d.getVar("STAGING_DIR", False)
4344 '${TMPDIR}/sysroots'
4345 pydevshell> d.setVar("FOO", "bar")
4346 pydevshell> d.getVar("FOO", True)
4347 'bar'
4348 pydevshell> d.delVar("FOO")
4349 pydevshell> d.getVar("FOO", True)
4350 pydevshell> bb.build.exec_func("do_unpack", d)
4351 pydevshell>
4352 </literallayout>
4353 The commands execute just as if the OpenEmbedded build system were executing them.
4354 Consequently, working this way can be helpful when debugging a build or preparing
4355 software to be used with the OpenEmbedded build system.
4356 </para>
4357
4358 <para>
4359 Following is an example that uses <filename>devpyshell</filename> on a target named
4360 <filename>matchbox-desktop</filename>:
4361 <literallayout class='monospaced'>
4362 $ bitbake matchbox-desktop -c devpyshell
4363 </literallayout>
4364 </para>
4365
4366 <para>
4367 This command spawns a terminal and places you in an interactive
4368 Python interpreter within the OpenEmbedded build environment.
4369 The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
4370 variable controls what type of shell is opened.
4371 </para>
4372
4373 <para>
4374 When you are finished using <filename>devpyshell</filename>, you
4375 can exit the shell either by using Ctrl+d or closing the terminal
4376 window.
4377 </para>
4378 </section>
4379
4205 <section id='platdev-building-targets-with-multiple-configurations'> 4380 <section id='platdev-building-targets-with-multiple-configurations'>
4206 <title>Building Targets with Multiple Configurations</title> 4381 <title>Building Targets with Multiple Configurations</title>
4207 4382
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>