diff options
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.html | 134 |
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> | ||