summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-10-16 11:14:36 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-10-17 17:32:46 +0100
commit0163821ef76add97f3e04b8209d1b3b0c7455894 (patch)
tree810c346620cfc22ebd4edc13953bed48084cbaf2 /documentation/dev-manual
parentca144a6abeac2073f49d8fe42af67d5cab4c6a98 (diff)
downloadpoky-0163821ef76add97f3e04b8209d1b3b0c7455894.tar.gz
documentation: dev-manual - lttng and Git workflow changes
* Updates to the Git Workflow section based on feedback from Darren Hart. These changes simplify the flow and make it generic. * Updates to the lttng user space tool used from within Eclipse. The legacy version of the tool is no longer supported so it had to be edited out of the description and replaced with the 2.0 version. (From yocto-docs rev: 81d2b79035fc99f92364bfef2c76076738cbaa52) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-model.xml144
1 files changed, 74 insertions, 70 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index b61eeb0678..669623bc7f 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1271,44 +1271,48 @@ directory.</para></listitem>
1271 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>. 1271 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>.
1272 <note>The <filename>oprofile-server</filename> is installed by default on 1272 <note>The <filename>oprofile-server</filename> is installed by default on
1273 the <filename>core-image-sato-sdk</filename> image.</note></para></listitem> 1273 the <filename>core-image-sato-sdk</filename> image.</note></para></listitem>
1274 <listitem><para><emphasis><filename>Lttng-ust</filename>:</emphasis> Selecting this tool runs 1274 <listitem><para><emphasis><filename>Lttng2.0 ust trace import</filename>:</emphasis>
1275 <filename>usttrace</filename> on the remote target, transfers the output data back 1275 Selecting this tool transfers the remote target's
1276 to the local host machine, and uses the <filename>lttng</filename> Eclipse plug-in to 1276 <filename>Lttng</filename> tracing data back to the local host machine
1277 graphically display the output. 1277 and uses the <filename>Lttng</filename> Eclipse plug-in to graphically
1278 For information on how to use <filename>lttng</filename> to trace an application, see 1278 display the output.
1279 <ulink url='http://lttng.org/documentation'></ulink>.</para> 1279 For information on how to use <filename>Lttng</filename> to trace an application,
1280 <para>For <filename>Application</filename>, you must supply the absolute path name of the 1280 see <ulink url='http://lttng.org/documentation'></ulink>.
1281 application to be traced by user mode <filename>lttng</filename>. 1281 <note>Do not use <filename>Lttng-user space (legacy)</filename> tool.
1282 For example, typing <filename>/path/to/foo</filename> triggers 1282 This tool no longer has any upstream support.</note>
1283 <filename>usttrace /path/to/foo</filename> on the remote target to trace the 1283 </para>
1284 program <filename>/path/to/foo</filename>.</para> 1284 <para>Before you use the <filename>Lttng2.0 ust trace import</filename> tool,
1285 <para><filename>Argument</filename> is passed to <filename>usttrace</filename> 1285 you need to setup the <filename>Lttng</filename> Eclipse plug-in and create a
1286 running on the remote target.</para> 1286 <filename>Tracing</filename> project.
1287 <para>Before you use the <filename>lttng-ust</filename> tool, you need to setup
1288 the <filename>lttng</filename> Eclipse plug-in and create a <filename>lttng</filename>
1289 project.
1290 Do the following: 1287 Do the following:
1291 <orderedlist> 1288 <orderedlist>
1292 <listitem><para>Follow the instructions from the
1293 <ulink url='http://wiki.eclipse.org/Linux_Tools_Project/LTTng2/User_Guide'>Linux Tools Projec/LTTng2/User Guide</ulink>
1294 to download and install the <filename>lttng</filename> parser library.
1295 </para></listitem>
1296 <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename> 1289 <listitem><para>Select <filename>Window -> Open Perspective -> Other</filename>
1297 and then select <filename>LTTng</filename>.</para></listitem> 1290 and then select <filename>Tracing</filename>.</para></listitem>
1298 <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective 1291 <listitem><para>Click <filename>OK</filename> to change the Eclipse perspective
1299 into the <filename>LTTng</filename> perspective.</para></listitem> 1292 into the <filename>Tracing</filename> perspective.</para></listitem>
1300 <listitem><para>Create a new <filename>LTTng</filename> project by selecting 1293 <listitem><para>Create a new <filename>Tracing</filename> project by selecting
1301 <filename>File -> New -> Project</filename>.</para></listitem> 1294 <filename>File -> New -> Project</filename>.</para></listitem>
1302 <listitem><para>Choose <filename>LTTng -> LTTng Project</filename>.</para></listitem> 1295 <listitem><para>Choose <filename>Tracing -> Tracing Project</filename>.
1303 <listitem><para>Click <filename>YoctoTools -> lttng-ust</filename> to start user mode 1296 </para></listitem>
1304 <filename>lttng</filename> on the remote target.</para></listitem> 1297 <listitem><para>Generate your tracing data on the remote target.
1305 </orderedlist></para> 1298 </para></listitem>
1306 <para>After the output data has been transferred from the remote target back to the local 1299 <listitem><para>Click
1307 host machine, new traces will be imported into the selected <filename>LTTng</filename> project. 1300 <filename>Yocto Project Tools -> Lttng2.0 ust trace import</filename>
1308 Then you can go to the <filename>LTTng</filename> project, right click the imported 1301 to start the data import process.</para></listitem>
1309 trace, and set the trace type as the <filename>LTTng</filename> kernel trace. 1302 <listitem><para>Specify your remote connection name.</para></listitem>
1310 Finally, right click the imported trace and select <filename>Open</filename> 1303 <listitem><para>For the Ust directory path, specify the location of
1311 to display the data graphically.</para></listitem> 1304 your remote tracing data.
1305 Make sure the location ends with <filename>ust</filename> (e.g.
1306 <filename>/usr/mysession/ust</filename>.</para></listitem>
1307 <listitem><para>Click <filename>OK</filename> to complete the import process.
1308 The data is now in the local tracing project you created.</para></listitem>
1309 <listitem><para>Right click on the data and then use the menu to
1310 <filename>Select Trace Type... -> Common Trace Format -> Generic CTF Trace</filename>
1311 to map the tracing type.</para></listitem>
1312 <listitem><para>Right click the mouse and select <filename>Open</filename>
1313 to bring up the Eclipse <filename>Lttng</filename> Trace Viewer so you
1314 view the tracing data.</para></listitem>
1315 </orderedlist></para></listitem>
1312 <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> Selecting this tool runs 1316 <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> Selecting this tool runs
1313 <filename>powertop</filename> on the remote target machine and displays the results in a 1317 <filename>powertop</filename> on the remote target machine and displays the results in a
1314 new view called <filename>powertop</filename>.</para> 1318 new view called <filename>powertop</filename>.</para>
@@ -1540,10 +1544,12 @@ directory.</para></listitem>
1540 </literallayout> 1544 </literallayout>
1541 Again, assuming top-level Source Directory named <filename>poky</filename> 1545 Again, assuming top-level Source Directory named <filename>poky</filename>
1542 and a default build directory of <filename>poky/build</filename>, the 1546 and a default build directory of <filename>poky/build</filename>, the
1543 following is the work directory for the <filename>acl</filename> package that is being 1547 following are the work and temporary source directories, respectively,
1548 for the <filename>acl</filename> package that is being
1544 built for a MIPS-based device: 1549 built for a MIPS-based device:
1545 <literallayout class='monospaced'> 1550 <literallayout class='monospaced'>
1546 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 1551 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
1552 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2/acl-2.2.51
1547 </literallayout> 1553 </literallayout>
1548 </para> 1554 </para>
1549 1555
@@ -1593,7 +1599,7 @@ directory.</para></listitem>
1593 <listitem><para><emphasis>Change Your Working Directory:</emphasis> 1599 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1594 You need to be in the directory that has the temporary source code. 1600 You need to be in the directory that has the temporary source code.
1595 That directory is defined by the 1601 That directory is defined by the
1596 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink> 1602 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1597 variable.</para></listitem> 1603 variable.</para></listitem>
1598 <listitem><para><emphasis>Create a New Patch:</emphasis> 1604 <listitem><para><emphasis>Create a New Patch:</emphasis>
1599 Before modifying source code, you need to create a new patch. 1605 Before modifying source code, you need to create a new patch.
@@ -1602,14 +1608,16 @@ directory.</para></listitem>
1602 $ quilt new my_changes.patch 1608 $ quilt new my_changes.patch
1603 </literallayout></para></listitem> 1609 </literallayout></para></listitem>
1604 <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis> 1610 <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
1605 After creating the patch, you need to notify Quilt about the files you will 1611 After creating the patch, you need to notify Quilt about the files
1606 be changing. 1612 you plan to edit.
1607 Add the files you will be modifying into the patch you just created: 1613 You notify Quilt by adding the files to the patch you just created:
1608 <literallayout class='monospaced'> 1614 <literallayout class='monospaced'>
1609 $ quilt add file1.c file2.c file3.c 1615 $ quilt add file1.c file2.c file3.c
1610 </literallayout></para></listitem> 1616 </literallayout>
1617 </para></listitem>
1611 <listitem><para><emphasis>Edit the Files:</emphasis> 1618 <listitem><para><emphasis>Edit the Files:</emphasis>
1612 Make the changes to the temporary source code.</para></listitem> 1619 Make your changes in the temporary source code to the files you added
1620 to the patch.</para></listitem>
1613 <listitem><para><emphasis>Test Your Changes:</emphasis> 1621 <listitem><para><emphasis>Test Your Changes:</emphasis>
1614 Once you have modified the source code, the easiest way to test your changes 1622 Once you have modified the source code, the easiest way to test your changes
1615 is by calling the <filename>compile</filename> task as shown in the following example: 1623 is by calling the <filename>compile</filename> task as shown in the following example:
@@ -1641,7 +1649,9 @@ directory.</para></listitem>
1641 subdirectory of the source (<filename>S</filename>) directory.</para></listitem> 1649 subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
1642 <listitem><para><emphasis>Copy the Patch File:</emphasis> 1650 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1643 For simplicity, copy the patch file into a directory named <filename>files</filename>, 1651 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1644 which you can create in the same directory as the recipe. 1652 which you can create in the same directory that holds the recipe
1653 (<filename>.bb</filename>) file or the
1654 append (<filename>.bbappend</filename>) file.
1645 Placing the patch here guarantees that the OpenEmbedded build system will find 1655 Placing the patch here guarantees that the OpenEmbedded build system will find
1646 the patch. 1656 the patch.
1647 Next, add the patch into the 1657 Next, add the patch into the
@@ -1687,33 +1697,24 @@ directory.</para></listitem>
1687 <listitem><para><emphasis>Change Your Working Directory:</emphasis> 1697 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
1688 You need to be in the directory that has the temporary source code. 1698 You need to be in the directory that has the temporary source code.
1689 That directory is defined by the 1699 That directory is defined by the
1690 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink> 1700 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
1691 variable. 1701 variable.</para></listitem>
1692 If you are working with a kernel, you need to be in the
1693 <filename>${S}/linux</filename> directory.</para></listitem>
1694 <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis> 1702 <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis>
1695 If you are not already in a Git repository, use the 1703 If the recipe you are working with does not use a Git fetcher,
1696 <filename>git init</filename> command to initialize a new local repository 1704 you need to set up a Git repository as follows:
1697 that is based on the work directory:
1698 <literallayout class='monospaced'> 1705 <literallayout class='monospaced'>
1699 $ git init 1706 $ git init
1700 </literallayout></para></listitem>
1701 <listitem><para><emphasis>Stage all the files:</emphasis>
1702 Use the <filename>git add *</filename> command to stage all the files in the source
1703 code directory so that they can be committed:
1704 <literallayout class='monospaced'>
1705 $ git add * 1707 $ git add *
1706 </literallayout></para></listitem>
1707 <listitem><para><emphasis>Commit the Source Files:</emphasis>
1708 Use the <filename>git commit</filename> command to initially commit all the files in
1709 the work directory:
1710 <literallayout class='monospaced'>
1711 $ git commit 1708 $ git commit
1712 </literallayout> 1709 </literallayout>
1710 The above Git commands initialize a Git repository that is based on the
1711 files in your current working directory, stage all the files, and commit
1712 the files.
1713 At this point, your Git repository is aware of all the source code files. 1713 At this point, your Git repository is aware of all the source code files.
1714 Any edits you now make to files will be tracked by Git.</para></listitem> 1714 Any edits you now make to files can be committed later and will be tracked by
1715 Git.</para></listitem>
1715 <listitem><para><emphasis>Edit the Files:</emphasis> 1716 <listitem><para><emphasis>Edit the Files:</emphasis>
1716 Make the changes to the temporary source code.</para></listitem> 1717 Make your changes to the temporary source code.</para></listitem>
1717 <listitem><para><emphasis>Test Your Changes:</emphasis> 1718 <listitem><para><emphasis>Test Your Changes:</emphasis>
1718 Once you have modified the source code, the easiest way to test your changes 1719 Once you have modified the source code, the easiest way to test your changes
1719 is by calling the <filename>compile</filename> task as shown in the following example: 1720 is by calling the <filename>compile</filename> task as shown in the following example:
@@ -1725,8 +1726,8 @@ directory.</para></listitem>
1725 If you find problems with your code, you can just keep editing and 1726 If you find problems with your code, you can just keep editing and
1726 re-testing iteratively until things work as expected. 1727 re-testing iteratively until things work as expected.
1727 <note>All the modifications you make to the temporary source code 1728 <note>All the modifications you make to the temporary source code
1728 disappear once you <filename>-c clean</filename> or 1729 disappear once you <filename>-c clean</filename>, <filename>-c cleansstate</filename>,
1729 <filename>-c cleanall</filename> with BitBake for the package. 1730 or <filename>-c cleanall</filename> with BitBake for the package.
1730 Modifications will also disappear if you use the <filename>rm_work</filename> 1731 Modifications will also disappear if you use the <filename>rm_work</filename>
1731 feature as described in the 1732 feature as described in the
1732 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 1733 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
@@ -1742,11 +1743,9 @@ directory.</para></listitem>
1742 </literallayout></para></listitem> 1743 </literallayout></para></listitem>
1743 <listitem><para><emphasis>Stage the Modified Files:</emphasis> 1744 <listitem><para><emphasis>Stage the Modified Files:</emphasis>
1744 Use the <filename>git add</filename> command to stage the changed files so they 1745 Use the <filename>git add</filename> command to stage the changed files so they
1745 can be committed as follows. 1746 can be committed as follows:
1746 Again, for this discussion assume the files changed are in the <filename>linux</filename>
1747 directory:
1748 <literallayout class='monospaced'> 1747 <literallayout class='monospaced'>
1749 $ git add &lt;somepath&gt;/file1.c &lt;somepath&gt;/file2.c &lt;somepath&gt;/file3.c 1748 $ git add file1.c file2.c file3.c
1750 </literallayout></para></listitem> 1749 </literallayout></para></listitem>
1751 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis> 1750 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
1752 Use the <filename>git commit</filename> command to commit the changes to the 1751 Use the <filename>git commit</filename> command to commit the changes to the
@@ -1754,9 +1753,11 @@ directory.</para></listitem>
1754 Once you have committed the files, you can use the <filename>git log</filename> 1753 Once you have committed the files, you can use the <filename>git log</filename>
1755 command to see your changes: 1754 command to see your changes:
1756 <literallayout class='monospaced'> 1755 <literallayout class='monospaced'>
1757 $ git commit 1756 $ git commit -m "&lt;commit-summary-message&gt;"
1758 $ git log 1757 $ git log
1759 </literallayout></para></listitem> 1758 </literallayout>
1759 <note>The name of the patch file created in the next step is based on your
1760 <filename>commit-summary-message</filename>.</note></para></listitem>
1760 <listitem><para><emphasis>Generate the Patch:</emphasis> 1761 <listitem><para><emphasis>Generate the Patch:</emphasis>
1761 Once the changes are committed, use the <filename>git format-patch</filename> 1762 Once the changes are committed, use the <filename>git format-patch</filename>
1762 command to generate a patch file: 1763 command to generate a patch file:
@@ -1768,11 +1769,14 @@ directory.</para></listitem>
1768 <para>At this point, the patch file has all your edits made 1769 <para>At this point, the patch file has all your edits made
1769 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and 1770 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1770 <filename>file3.c</filename> files. 1771 <filename>file3.c</filename> files.
1771 You can find the resulting patch file in the current directory. 1772 You can find the resulting patch file in the current directory and it
1773 is named according to the <filename>git commit</filename> summary line.
1772 The patch file ends with <filename>.patch</filename>.</para></listitem> 1774 The patch file ends with <filename>.patch</filename>.</para></listitem>
1773 <listitem><para><emphasis>Copy the Patch File:</emphasis> 1775 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1774 For simplicity, copy the patch file into a directory named <filename>files</filename>, 1776 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1775 which you can create in the same directory as the recipe. 1777 which you can create in the same directory that holds the recipe
1778 (<filename>.bb</filename>) file or the
1779 append (<filename>.bbappend</filename>) file.
1776 Placing the patch here guarantees that the OpenEmbedded build system will find 1780 Placing the patch here guarantees that the OpenEmbedded build system will find
1777 the patch. 1781 the patch.
1778 Next, add the patch into the 1782 Next, add the patch into the