summaryrefslogtreecommitdiffstats
path: root/documentation/profile-manual/profile-manual-intro.rst
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-06-26 19:10:51 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-17 10:09:33 +0100
commit9bd69b1f1d71a9692189beeac75af9dfbad816cc (patch)
tree305347fca899074aed5610e0e82eaec180bf630c /documentation/profile-manual/profile-manual-intro.rst
parentc40a8d5904c29046f1cbbeb998e6cd7c24f9b206 (diff)
downloadpoky-9bd69b1f1d71a9692189beeac75af9dfbad816cc.tar.gz
sphinx: initial sphinx support
This commit is autogenerated pandoc to generate an inital set of reST files based on DocBook XML files. A .rst file is generated for each .xml files in all manuals with this command: cd <manual> for i in *.xml; do \ pandoc -f docbook -t rst --shift-heading-level-by=-1 \ $i -o $(basename $i .xml).rst \ done The conversion was done with: pandoc 2.9.2.1-91 (Arch Linux). Also created an initial top level index file for each document, and added all 'books' to the top leve index.rst file. The YP manuals layout is organized as: Book Chapter Section Section Section Sphinx uses section headers to create the document structure. ReStructuredText defines sections headers like that: To break longer text up into sections, you use section headers. These are a single line of text (one or more words) with adornment: an underline alone, or an underline and an overline together, in dashes "-----", equals "======", tildes "~~~~~~" or any of the non-alphanumeric characters = - ` : ' " ~ ^ _ * + # < > that you feel comfortable with. An underline-only adornment is distinct from an overline-and-underline adornment using the same character. The underline/overline must be at least as long as the title text. Be consistent, since all sections marked with the same adornment style are deemed to be at the same level: Let's define the following convention when converting from Docbook: Book => overline === (Title) Chapter => overline *** (1.) Section => ==== (1.1) Section => ---- (1.1.1) Section => ~~~~ (1.1.1.1) Section => ^^^^ (1.1.1.1.1) During the conversion with pandoc, we used --shift-heading-level=-1 to convert most of DocBook headings automatically. However with this setting, the Chapter header was removed, so I added it back manually. Without this setting all headings were off by one, which was more difficult to manually fix. At least with this change, we now have the same TOC with Sphinx and DocBook. (From yocto-docs rev: 3c73d64a476d4423ee4c6808c685fa94d88d7df8) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/profile-manual/profile-manual-intro.rst')
-rw-r--r--documentation/profile-manual/profile-manual-intro.rst67
1 files changed, 67 insertions, 0 deletions
diff --git a/documentation/profile-manual/profile-manual-intro.rst b/documentation/profile-manual/profile-manual-intro.rst
new file mode 100644
index 0000000000..40febd8b4e
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-intro.rst
@@ -0,0 +1,67 @@
1******************************************
2Yocto Project Profiling and Tracing Manual
3******************************************
4
5.. _profile-intro:
6
7Introduction
8============
9
10Yocto bundles a number of tracing and profiling tools - this 'HOWTO'
11describes their basic usage and shows by example how to make use of them
12to examine application and system behavior.
13
14The tools presented are for the most part completely open-ended and have
15quite good and/or extensive documentation of their own which can be used
16to solve just about any problem you might come across in Linux. Each
17section that describes a particular tool has links to that tool's
18documentation and website.
19
20The purpose of this 'HOWTO' is to present a set of common and generally
21useful tracing and profiling idioms along with their application (as
22appropriate) to each tool, in the context of a general-purpose
23'drill-down' methodology that can be applied to solving a large number
24(90%?) of problems. For help with more advanced usages and problems,
25please see the documentation and/or websites listed for each tool.
26
27The final section of this 'HOWTO' is a collection of real-world examples
28which we'll be continually adding to as we solve more problems using the
29tools - feel free to add your own examples to the list!
30
31.. _profile-manual-general-setup:
32
33General Setup
34=============
35
36Most of the tools are available only in 'sdk' images or in images built
37after adding 'tools-profile' to your local.conf. So, in order to be able
38to access all of the tools described here, please first build and boot
39an 'sdk' image e.g. $ bitbake core-image-sato-sdk or alternatively by
40adding 'tools-profile' to the EXTRA_IMAGE_FEATURES line in your
41local.conf: EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile" If you
42use the 'tools-profile' method, you don't need to build an sdk image -
43the tracing and profiling tools will be included in non-sdk images as
44well e.g.: $ bitbake core-image-sato
45
46.. note::
47
48 By default, the Yocto build system strips symbols from the binaries
49 it packages, which makes it difficult to use some of the tools.
50
51 You can prevent that by setting the
52 ```INHIBIT_PACKAGE_STRIP`` <&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_STRIP>`__
53 variable to "1" in your ``local.conf`` when you build the image:
54
55INHIBIT_PACKAGE_STRIP = "1" The above setting will noticeably increase
56the size of your image.
57
58If you've already built a stripped image, you can generate debug
59packages (xxx-dbg) which you can manually install as needed.
60
61To generate debug info for packages, you can add dbg-pkgs to
62EXTRA_IMAGE_FEATURES in local.conf. For example: EXTRA_IMAGE_FEATURES =
63"debug-tweaks tools-profile dbg-pkgs" Additionally, in order to generate
64the right type of debuginfo, we also need to set
65```PACKAGE_DEBUG_SPLIT_STYLE`` <&YOCTO_DOCS_REF_URL;#var-PACKAGE_DEBUG_SPLIT_STYLE>`__
66in the ``local.conf`` file: PACKAGE_DEBUG_SPLIT_STYLE =
67'debug-file-directory'