aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJamie Lenehan <lenehan@twibble.org>2007-05-05 01:55:14 +0000
committerJamie Lenehan <lenehan@twibble.org>2007-05-05 01:55:14 +0000
commite877fdd56731a068fe9a3700bdb7e3c79419dcaa (patch)
treed2280274da6ec8de824540f0a4724185b5eb4c20
parentb13777c68faa3a75b44d6c3985406b4552244ba9 (diff)
downloadopenembedded-e877fdd56731a068fe9a3700bdb7e3c79419dcaa.tar.gz
openembedded-e877fdd56731a068fe9a3700bdb7e3c79419dcaa.tar.bz2
openembedded-e877fdd56731a068fe9a3700bdb7e3c79419dcaa.zip
usermanual: Add some details in the usage section on how to bring up a devshell.
-rw-r--r--usermanual/chapters/usage.xml148
1 files changed, 123 insertions, 25 deletions
diff --git a/usermanual/chapters/usage.xml b/usermanual/chapters/usage.xml
index e4f056a764..4c58fc700a 100644
--- a/usermanual/chapters/usage.xml
+++ b/usermanual/chapters/usage.xml
@@ -136,7 +136,7 @@
that this may not be exactly what see - there are a lot of options that
can effect exactly how things are done, but it gives us a pretty good idea
of whats going on. What we are looking at here is the tmp directory (as
- specified by TMPDIR in your local.conf):<screen>%&gt; find tmp -maxdepth 2 -type d
+ specified by TMPDIR in your local.conf):<screen>~%&gt; find tmp -maxdepth 2 -type d
tmp
tmp/stamps
tmp/cross
@@ -314,7 +314,7 @@ tmp/work/sh4-linux/arpwatch-2.1a15-r2</screen></para>
distribution is using it.</para>
<para>Using lzo 1.08 as an example we'll examine the contents of the
- working directory for a typical recipe:<screen>%&gt; find tmp/work/lzo-1.08-r14 -maxdepth 1
+ working directory for a typical recipe:<screen>~%&gt; find tmp/work/lzo-1.08-r14 -maxdepth 1
tmp/work/lzo-1.08-r14
tmp/work/lzo-1.08-r14/temp
tmp/work/lzo-1.08-r14/lzo-1.08
@@ -413,7 +413,7 @@ tmp/work/lzo-1.08-r14/image</screen></para>
</variablelist>
<para>So lets show some examples of the useful information you now have
- access to. </para>
+ access to.</para>
<para>How about checking out what happened during the configuration of
lzo? Well that requires checking the log file for configure that is
@@ -748,7 +748,7 @@ NOTE: build 200705041709: completed</screen><note>
<emphasis>x</emphasis> is implemented via a function called
<emphasis>do_x</emphasis> in the class or recipe where it is defined.
See places refer to the tasks via their name only and some with the
- <emphasis>do</emphasis> prefix. </para>
+ <emphasis>do</emphasis> prefix.</para>
</note>
<para>You will almost certainly notice tasks beyond these ones - there are
@@ -760,7 +760,7 @@ NOTE: build 200705041709: completed</screen><note>
<emphasis>configure</emphasis> and <emphasis>compile</emphasis> tasks and
another new task called <emphasis>qa_staging</emphasis> between
<emphasis>populate_staging</emphasis> and <emphasis>build</emphasis>
- tasks. The format validates the result of the
+ tasks. The former validates the result of the
<emphasis>configure</emphasis> task and the late the results of the
<emphasis>populate_staging</emphasis> task.</para>
@@ -813,12 +813,12 @@ NOTE: package perl-5.8.8: completed
by passing it via the <emphasis role="bold">-b</emphasis> parameter. This
option takes the recipe as a parameter and instructs bitbake to process
the named recipe only. Note that this ignores any dependencies that are in
- the recipe, so these must have already been built previously. </para>
+ the recipe, so these must have already been built previously.</para>
<para>Here's a typically example that cleans up the package (using the
<emphasis>clean</emphasis> task) and the rebuilds it with debugging output
- from bitbake enabled:<screen>%&gt; bitbake -b &lt;bb-file&gt; -c clean
-%&gt; bitbake -b &lt;bb-file&gt; -D</screen></para>
+ from bitbake enabled:<screen>~%&gt; bitbake -b &lt;bb-file&gt; -c clean
+~%&gt; bitbake -b &lt;bb-file&gt; -D</screen></para>
<para>The options to bitbake that are most useful here are:</para>
@@ -958,28 +958,28 @@ NOTE: package perl-5.8.8: completed
actions.</para>
<para>A typically development session might involve editing files in the
- working directory and then recompiling until it all works:<screen>[... test ...]
-%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D
+ working directory and then recompiling until it all works:<screen>[<emphasis>... test ...</emphasis>]
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D
-[... save a copy of main.c and make some changes ...]
-%&gt; vi tmp/work/testapp-4.3-r0/main.c
-%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D -f
+[<emphasis>... save a copy of main.c and make some changes ...</emphasis>]
+~%&gt; vi tmp/work/testapp-4.3-r0/main.c
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D -f
-[... create a patch and add it to the recipe ...]
-%&gt; vi packages/testapp/testapp_4.3.bb
+[<emphasis>... create a patch and add it to the recipe ...</emphasis>]
+~%&gt; vi packages/testapp/testapp_4.3.bb
-[... test from clean ...]
-%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c clean
-%&gt; bitbake -b packages/testapp/testapp_4.3.bb
+[<emphasis>... test from clean ...</emphasis>]
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c clean
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb
-[... NOTE: How to create the patch is not covered at this point ...]</screen></para>
+[<emphasis>... NOTE: How to create the patch is not covered at this point ...</emphasis>]</screen></para>
<para>Here's another example showing how you might go about fixing up the
- packaging in your recipe:<screen>%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c install -f
-%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c stage -f
-%&gt; find tmp/work/testapp_4.3/install
+ packaging in your recipe:<screen>~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c install -f
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c stage -f
+~%&gt; find tmp/work/testapp_4.3/install
...
-%&gt; vi packages/testapp/testapp_4.3.bb</screen>At this stage you play with
+~%&gt; vi packages/testapp/testapp_4.3.bb</screen>At this stage you play with
the <emphasis role="bold">PACKAGE_</emphasis> and <emphasis
role="bold">FILES_</emphasis> variables and then repeat the above
sequence.</para>
@@ -1001,7 +1001,7 @@ NOTE: package perl-5.8.8: completed
<section id="usage_interactive_bitbake" xreflabel="interactive bitbake">
<title>Interactive bitbake</title>
- <para>To interactively test things use:<screen>%&gt; bitbake -i</screen>this
+ <para>To interactively test things use:<screen>~%&gt; bitbake -i</screen>this
will open the bitbake shell. From here there are a lot of commands
available (try help).</para>
@@ -1023,7 +1023,105 @@ BB&gt;&gt; build net-snmp</screen>Note that you can use wildcards in the
<section id="usage_devshell" xreflabel="devshell">
<title>Devshell</title>
- <para>[To be done]</para>
+ <para>One of the areas in which OpenEmbedded helps you out is by setting
+ various environment variables, such as <emphasis role="bold">CC</emphasis>
+ and <emphasis role="bold">PATH</emphasis> etc, to values suitable for
+ cross-compiling. If you wish to manually run configure scripts and compile
+ file during development it would be nice to have all those values set for
+ you. This is what devshell does - it provides you with an interactive
+ shell with all the appropriate variables set for cross-compiling.</para>
+
+ <section>
+ <title>devshell via inherit</title>
+
+ <para>This is the newer method of obtaining a devshell and is the
+ recommended way for most users now. The newer method requires that the
+ devshell class be added to you configuration by inheriting it. This is
+ usually done in your <emphasis role="bold">local.conf</emphasis> or your
+ distributions conf file:<screen><emphasis role="bold">INHERIT +=</emphasis> "src_distribute_local insane multimachine <emphasis
+ role="bold">devshell</emphasis>"</screen></para>
+
+ <para>With the inclusion of this class you'll find that devshell is
+ added as a new task that you can use on recipes:<screen>~%&gt; bitbake -b packages/lzo/lzo_1.08.bb -c listtasks
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task do_listtasks: started
+<emphasis role="bold">do_devshell</emphasis>
+do_fetchall
+do_listtasks
+do_rebuild
+do_compile
+do_build
+do_mrproper
+do_fetch
+do_configure
+do_clean
+do_populate_staging
+do_package
+do_unpack
+do_install
+do_package_write
+do_distribute_sources
+do_showdata
+do_qa_staging
+do_qa_configure
+do_patch
+NOTE: package lzo-1.08-r14: task do_listtasks: completed
+NOTE: package lzo-1.08: completed</screen></para>
+
+ <para>To bring up the devshell you call bitbake on a recipe and ask it
+ for the devshell task:<screen>~%&gt; ./bb -b packages/lzo/lzo_1.08.bb -c devshell
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task do_devshell: started
+[<emphasis>... devshell will appear here ...</emphasis>]
+NOTE: package lzo-1.08-r14: task do_devshell: completed
+NOTE: package lzo-1.08: completed</screen></para>
+
+ <para>How the devshell appears depends on the settings of the <emphasis
+ role="bold">TERMCMD</emphasis> variable - you can see the default
+ settings and other possible values in <emphasis
+ role="bold">conf/bitbake.conf</emphasis>. Feel free to try settings this
+ to something else in your local.conf. Usually you will see a new
+ terminal window open which is the devshell window.</para>
+
+ <para>The devshell task is inserted after the patch task, so if you have
+ not already run bitbake on the recipe it will download the source and
+ apply any patches prior to opening the shell.</para>
+
+ <note>
+ <para>This method of obtaining a devshell works if you using <emphasis
+ role="bold">bash</emphasis> as your shell, it does not work if you are
+ using <emphasis role="bold">zsh</emphasis> as your shell. Other shells
+ may or may not work.</para>
+ </note>
+ </section>
+
+ <section>
+ <title>devshell addon</title>
+
+ <para>The devshell addon was the original method that was used to create
+ a devshell.</para>
+
+ <para>It requires no changes to your configuration, instead you simply
+ build the devshell recipe:<screen>bitabike devshell</screen></para>
+
+ <para>and then manually startup the shell. Once in the shell you'll
+ usually want to change into the working directory for the recipe you are
+ working on:<screen>~%&gt; ./tmp/deploy/addons/sh4-linux-erouter-titan-devshell
+bash: alias: `./configure': invalid alias name
+[OE::sh4-linux-erouter-titan]:~$ cd tmp/work/lzo-1.08-r14/lzo-1.08
+[OE::sh4-linux-erouter-titan]:~tmp/work/lzo-1.08-r14/lzo-1.08$</screen><note>
+ <para>The name of the devshell addon depends on the target
+ architecture, operating system and machine name. So you name will be
+ different - just check for the appropriate name ending in
+ -devshell.</para>
+ </note></para>
+ </section>
+
+ <section>
+ <title>Working in the devshell</title>
+
+ <para>[To be done]</para>
+ </section>
</section>
<section id="usage_patches" xreflabel="patching">