summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state.html
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-12-11 12:07:58 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-01-07 14:43:25 +0000
commited0a240e1632682ec4c33341f3e24ad71773cdfc (patch)
tree201557f498b77b9f51fad7e12a6009f74aca4c65 /documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state.html
parentaf19d889ef320f9625aae42eed6688b5cc739793 (diff)
downloadpoky-ed0a240e1632682ec4c33341f3e24ad71773cdfc.tar.gz
documentation: Rename of poky-ref-manual folder to ref-manual.
Changing the folder that holds the YP Reference Manual to be "ref-manual". This will help with confustion over the manual's intended purpose. (From yocto-docs rev: 1106442964b5080cb0b6b3bd3af32e9407c0f7c1) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state.html')
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state.html134
1 files changed, 134 insertions, 0 deletions
diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state.html
new file mode 100644
index 0000000000..e14e306eb5
--- /dev/null
+++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state.html
@@ -0,0 +1,134 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.2.3. Shared State</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="shared-state-cache.html" title="3.2. Shared State Cache">
9<link rel="prev" href="checksums.html" title="3.2.2. Checksums (Signatures)">
10<link rel="next" href="tips-and-tricks.html" title="3.2.4. Tips and Tricks">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.3. Shared State">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="shared-state"></a>3.2.3. Shared State</h3></div></div></div>
15<p>
16 Checksums and dependencies, as discussed in the previous section, solve half the
17 problem.
18 The other part of the problem is being able to use checksum information during the build
19 and being able to reuse or rebuild specific components.
20 </p>
21<p>
22 The shared state class (<code class="filename">sstate.bbclass</code>)
23 is a relatively generic implementation of how to "capture" a snapshot of a given task.
24 The idea is that the build process does not care about the source of a task's output.
25 Output could be freshly built or it could be downloaded and unpacked from
26 somewhere - the build process doesn't need to worry about its source.
27 </p>
28<p>
29 There are two types of output, one is just about creating a directory
30 in <code class="filename">WORKDIR</code>.
31 A good example is the output of either <code class="filename">do_install</code> or
32 <code class="filename">do_package</code>.
33 The other type of output occurs when a set of data is merged into a shared directory
34 tree such as the sysroot.
35 </p>
36<p>
37 The Yocto Project team has tried to keep the details of the implementation hidden in
38 <code class="filename">sstate.bbclass</code>.
39 From a user's perspective, adding shared state wrapping to a task
40 is as simple as this <code class="filename">do_deploy</code> example taken from
41 <code class="filename">do_deploy.bbclass</code>:
42 </p>
43<pre class="literallayout">
44 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
45 SSTATETASKS += "do_deploy"
46 do_deploy[sstate-name] = "deploy"
47 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
48 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
49
50 python do_deploy_setscene () {
51 sstate_setscene(d)
52 }
53 addtask do_deploy_setscene
54 </pre>
55<p>
56 In the example, we add some extra flags to the task, a name field ("deploy"), an
57 input directory where the task sends data, and the output
58 directory where the data from the task should eventually be copied.
59 We also add a <code class="filename">_setscene</code> variant of the task and add the task
60 name to the <code class="filename">SSTATETASKS</code> list.
61 </p>
62<p>
63 If you have a directory whose contents you need to preserve, you can do this with
64 a line like the following:
65 </p>
66<pre class="literallayout">
67 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
68 </pre>
69<p>
70 This method, as well as the following example, also works for multiple directories.
71 </p>
72<pre class="literallayout">
73 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
74 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
75 do_package[sstate-lockfile] = "${PACKAGELOCK}"
76 </pre>
77<p>
78 These methods also include the ability to take a lockfile when manipulating
79 shared state directory structures since some cases are sensitive to file
80 additions or removals.
81 </p>
82<p>
83 Behind the scenes, the shared state code works by looking in
84 <a class="link" href="ref-variables-glos.html#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a> and
85 <a class="link" href="ref-variables-glos.html#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>
86 for shared state files.
87 Here is an example:
88 </p>
89<pre class="literallayout">
90 SSTATE_MIRRORS ?= "\
91 file://.* http://someserver.tld/share/sstate/PATH \n \
92 file://.* file:///some/local/dir/sstate/PATH"
93 </pre>
94<p>
95 </p>
96<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
97<h3 class="title">Note</h3>
98 The shared state directory (<code class="filename">SSTATE_DIR</code>) is
99 organized into two-character subdirectories, where the subdirectory
100 names are based on the first two characters of the hash.
101 If the shared state directory structure for a mirror has the
102 same structure as <code class="filename">SSTATE_DIR</code>, you must
103 specify "PATH" as part of the URI to enable the build system
104 to map to the appropriate subdirectory.
105 </div>
106<p>
107 </p>
108<p>
109 The shared state package validity can be detected just by looking at the
110 filename since the filename contains the task checksum (or signature) as
111 described earlier in this section.
112 If a valid shared state package is found, the build process downloads it
113 and uses it to accelerate the task.
114 </p>
115<p>
116 The build processes uses the <code class="filename">*_setscene</code> tasks
117 for the task acceleration phase.
118 BitBake goes through this phase before the main execution code and tries
119 to accelerate any tasks for which it can find shared state packages.
120 If a shared state package for a task is available, the shared state
121 package is used.
122 This means the task and any tasks on which it is dependent are not
123 executed.
124 </p>
125<p>
126 As a real world example, the aim is when building an IPK-based image,
127 only the <code class="filename">do_package_write_ipk</code> tasks would have their
128 shared state packages fetched and extracted.
129 Since the sysroot is not used, it would never get extracted.
130 This is another reason why a task-based approach is preferred over a
131 recipe-based approach, which would have to install the output from every task.
132 </p>
133</div></body>
134</html>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-22 08:56:37 +0000