docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

build: add svg diagrams to cache docs 

Also adds the graphviz generation code.

Signed-off-by: Justin Chadwell <me@jedevc.com>
This commit is contained in:
Justin Chadwell 2022-09-12 10:35:46 +01:00
parent 55ebeda0cc
commit c42962dc87
8 changed files with 286 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
_scss/_night-mode.scss
View File

@ -181,6 +181,11 @@ body.night {
background-color: white; background-color: white;
} }
/* apply to images that support being inverted */
img.invertible {
filter: invert(100%) hue-rotate(180deg);
}
/* accordion */ /* accordion */
.panel { .panel {
color: $body-text-night; color: $body-text-night;

15
build/building/cache.md
View File

@ -23,7 +23,7 @@ might be used to create a C/C++ program:
```dockerfile ```dockerfile
FROM ubuntu:latest FROM ubuntu:latest
RUN apt-get update && apt-get upgrade -y build-essentials RUN apt-get update && apt-get install -y build-essentials
COPY . /src/ COPY . /src/
WORKDIR /src/ WORKDIR /src/
RUN make build RUN make build
@ -33,27 +33,22 @@ Each instruction in this Dockerfile (roughly) translates into a layer in your
final image. You can think of layers in a stack, with each layer adding more final image. You can think of layers in a stack, with each layer adding more
content to the filesystem on top of the layer before it: content to the filesystem on top of the layer before it:
``` ![Image layer diagram showing the above commands chained together one after the other](../images/cache-stack.svg){:.invertible}
stack diagram
```
Now, if one of the layers changes, somewhere - for example, suppose you make a Now, if one of the layers changes, somewhere - for example, suppose you make a
change to your C/C++ program in `main.c`. After this change, the `COPY` command change to your C/C++ program in `main.c`. After this change, the `COPY` command
will have to run again, so that the layer changes, so the cache for that layer will have to run again, so that the layer changes, so the cache for that layer
has been invalidated. has been invalidated.
``` ![Image layer diagram, but now with the link between COPY and WORKDIR marked as invalid](../images/cache-stack-invalidate-copy.svg){:.invertible}
stack diagram with COPY layer cache invalidated
```
But since we have a change to that file, we now need to run our `make build` But since we have a change to that file, we now need to run our `make build`
step again, so that those changes are built into our program. So since our step again, so that those changes are built into our program. So since our
cache for `COPY` was invalidated, we also have to invalidate the cache for all cache for `COPY` was invalidated, we also have to invalidate the cache for all
the layers after it, including our `RUN make build`, so that it will run again: the layers after it, including our `RUN make build`, so that it will run again:
``` ![Image layer diagram, but now with all links after COPY marked as invalid](../images/cache-stack-invalidate-rest.svg){:.invertible}
stack diagram with COPY + other layer cache invalidated
```
That's pretty much all there is to understand the cache - once there's a change That's pretty much all there is to understand the cache - once there's a change
in a layer, then all the layers after it will need to be rebuilt as well (even in a layer, then all the layers after it will need to be rebuilt as well (even

19
build/images/cache-stack-invalidate-copy.dot Normal file
View File

@ -0,0 +1,19 @@
// dot -Tsvg ./cache-invalidate-copy.dot > ./cache-invalidate-copy.svg
digraph {
rankdir="LR";
nodesep=0.3;
edge[minlen=0];
bgcolor="#00000000";
node [ shape=rect, width=5, height=0.4, fontname=monospace, fontsize=10 ];
from [ label = <<B>FROM </B>ubuntu:latest> ];
deps [ label = <<B>RUN </B>apt-get update &amp;&amp; \\<br/>apt-get install -y build-essentials> ];
copy [ label = <<B>COPY </B>. /src/>, color = "red" ];
workdir [ label = <<B>WORKDIR </B>/src/> ];
build [ label = <<B>RUN </B>make build> ];
from -> deps;
deps -> copy;
copy -> workdir [ color = "red", label = " ❌ " ];
workdir -> build;
}

73
build/images/cache-stack-invalidate-copy.svg Normal file
View File

@ -0,0 +1,73 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 5.0.0 (0)
-->
<!-- Pages: 1 -->
<svg width="368pt" height="256pt"
viewBox="0.00 0.00 368.00 256.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 252)">
<polygon fill="transparent" stroke="transparent" points="-4,4 -4,-252 364,-252 364,4 -4,4"/>
<!-- from -->
<g id="node1" class="node">
<title>from</title>
<polygon fill="none" stroke="black" points="360,-248 0,-248 0,-219 360,-219 360,-248"/>
<text text-anchor="start" x="125" y="-232" font-family="monospace" font-weight="bold" font-size="10.00">FROM </text>
<text text-anchor="start" x="156" y="-232" font-family="monospace" font-size="10.00">ubuntu:latest</text>
</g>
<!-- deps -->
<g id="node2" class="node">
<title>deps</title>
<polygon fill="none" stroke="black" points="360,-197 0,-197 0,-168 360,-168 360,-197"/>
<text text-anchor="start" x="110" y="-185.5" font-family="monospace" font-weight="bold" font-size="10.00">RUN </text>
<text text-anchor="start" x="135" y="-185.5" font-family="monospace" font-size="10.00">apt&#45;get update &amp;&amp; \</text>
<text text-anchor="start" x="74.5" y="-175.5" font-family="monospace" font-size="10.00">apt&#45;get install &#45;y build&#45;essentials</text>
</g>
<!-- from&#45;&gt;deps -->
<g id="edge1" class="edge">
<title>from&#45;&gt;deps</title>
<path fill="none" stroke="black" d="M180,-218.77C180,-214.96 180,-211.15 180,-207.33"/>
<polygon fill="black" stroke="black" points="183.5,-207.24 180,-197.24 176.5,-207.24 183.5,-207.24"/>
</g>
<!-- copy -->
<g id="node3" class="node">
<title>copy</title>
<polygon fill="none" stroke="red" points="360,-146 0,-146 0,-117 360,-117 360,-146"/>
<text text-anchor="start" x="143" y="-130" font-family="monospace" font-weight="bold" font-size="10.00">COPY </text>
<text text-anchor="start" x="174" y="-130" font-family="monospace" font-size="10.00">. /src/</text>
</g>
<!-- deps&#45;&gt;copy -->
<g id="edge2" class="edge">
<title>deps&#45;&gt;copy</title>
<path fill="none" stroke="black" d="M180,-167.77C180,-163.96 180,-160.15 180,-156.33"/>
<polygon fill="black" stroke="black" points="183.5,-156.24 180,-146.24 176.5,-156.24 183.5,-156.24"/>
</g>
<!-- workdir -->
<g id="node4" class="node">
<title>workdir</title>
<polygon fill="none" stroke="black" points="360,-80 0,-80 0,-51 360,-51 360,-80"/>
<text text-anchor="start" x="140" y="-64" font-family="monospace" font-weight="bold" font-size="10.00">WORKDIR </text>
<text text-anchor="start" x="189" y="-64" font-family="monospace" font-size="10.00">/src/</text>
</g>
<!-- copy&#45;&gt;workdir -->
<g id="edge3" class="edge">
<title>copy&#45;&gt;workdir</title>
<path fill="none" stroke="red" d="M180,-116.89C180,-109.12 180,-99.36 180,-90.43"/>
<polygon fill="red" stroke="red" points="183.5,-90.15 180,-80.15 176.5,-90.15 183.5,-90.15"/>
<text text-anchor="middle" x="169.5" y="-94.8" font-family="Times,serif" font-size="14.00"> ❌ &#160;</text>
</g>
<!-- build -->
<g id="node5" class="node">
<title>build</title>
<polygon fill="none" stroke="black" points="360,-29 0,-29 0,0 360,0 360,-29"/>
<text text-anchor="start" x="137" y="-13" font-family="monospace" font-weight="bold" font-size="10.00">RUN </text>
<text text-anchor="start" x="162" y="-13" font-family="monospace" font-size="10.00">make build</text>
</g>
<!-- workdir&#45;&gt;build -->
<g id="edge4" class="edge">
<title>workdir&#45;&gt;build</title>
<path fill="none" stroke="black" d="M180,-50.77C180,-46.96 180,-43.15 180,-39.33"/>
<polygon fill="black" stroke="black" points="183.5,-39.24 180,-29.24 176.5,-39.24 183.5,-39.24"/>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 3.7 KiB

19
build/images/cache-stack-invalidate-rest.dot Normal file
View File

@ -0,0 +1,19 @@
// dot -Tsvg ./cache-invalidate-rest.dot > ./cache-invalidate-rest.svg
digraph {
rankdir="LR";
nodesep=0.3;
edge[minlen=0];
bgcolor="#00000000";
node [ shape=rect, width=5, height=0.4, fontname=monospace, fontsize=10 ];
from [ label = <<B>FROM </B>ubuntu:latest> ];
deps [ label = <<B>RUN </B>apt-get update &amp;&amp; \\<br/>apt-get install -y build-essentials> ];
copy [ label = <<B>COPY </B>. /src/>, color = "red" ];
workdir [ label = <<B>WORKDIR </B>/src/>, color = "red" ];
build [ label = <<B>RUN </B>make build>, color = "red" ];
from -> deps;
deps -> copy;
copy -> workdir [ color = "red", label = " ❌ " ];
workdir -> build [ color = "red", label = " ❌ " ];
}

74
build/images/cache-stack-invalidate-rest.svg Normal file
View File

@ -0,0 +1,74 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 5.0.0 (0)
-->
<!-- Pages: 1 -->
<svg width="368pt" height="271pt"
viewBox="0.00 0.00 368.00 271.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 267)">
<polygon fill="transparent" stroke="transparent" points="-4,4 -4,-267 364,-267 364,4 -4,4"/>
<!-- from -->
<g id="node1" class="node">
<title>from</title>
<polygon fill="none" stroke="black" points="360,-263 0,-263 0,-234 360,-234 360,-263"/>
<text text-anchor="start" x="125" y="-247" font-family="monospace" font-weight="bold" font-size="10.00">FROM </text>
<text text-anchor="start" x="156" y="-247" font-family="monospace" font-size="10.00">ubuntu:latest</text>
</g>
<!-- deps -->
<g id="node2" class="node">
<title>deps</title>
<polygon fill="none" stroke="black" points="360,-212 0,-212 0,-183 360,-183 360,-212"/>
<text text-anchor="start" x="110" y="-200.5" font-family="monospace" font-weight="bold" font-size="10.00">RUN </text>
<text text-anchor="start" x="135" y="-200.5" font-family="monospace" font-size="10.00">apt&#45;get update &amp;&amp; \</text>
<text text-anchor="start" x="74.5" y="-190.5" font-family="monospace" font-size="10.00">apt&#45;get install &#45;y build&#45;essentials</text>
</g>
<!-- from&#45;&gt;deps -->
<g id="edge1" class="edge">
<title>from&#45;&gt;deps</title>
<path fill="none" stroke="black" d="M180,-233.77C180,-229.96 180,-226.15 180,-222.33"/>
<polygon fill="black" stroke="black" points="183.5,-222.24 180,-212.24 176.5,-222.24 183.5,-222.24"/>
</g>
<!-- copy -->
<g id="node3" class="node">
<title>copy</title>
<polygon fill="none" stroke="red" points="360,-161 0,-161 0,-132 360,-132 360,-161"/>
<text text-anchor="start" x="143" y="-145" font-family="monospace" font-weight="bold" font-size="10.00">COPY </text>
<text text-anchor="start" x="174" y="-145" font-family="monospace" font-size="10.00">. /src/</text>
</g>
<!-- deps&#45;&gt;copy -->
<g id="edge2" class="edge">
<title>deps&#45;&gt;copy</title>
<path fill="none" stroke="black" d="M180,-182.77C180,-178.96 180,-175.15 180,-171.33"/>
<polygon fill="black" stroke="black" points="183.5,-171.24 180,-161.24 176.5,-171.24 183.5,-171.24"/>
</g>
<!-- workdir -->
<g id="node4" class="node">
<title>workdir</title>
<polygon fill="none" stroke="red" points="360,-95 0,-95 0,-66 360,-66 360,-95"/>
<text text-anchor="start" x="140" y="-79" font-family="monospace" font-weight="bold" font-size="10.00">WORKDIR </text>
<text text-anchor="start" x="189" y="-79" font-family="monospace" font-size="10.00">/src/</text>
</g>
<!-- copy&#45;&gt;workdir -->
<g id="edge3" class="edge">
<title>copy&#45;&gt;workdir</title>
<path fill="none" stroke="red" d="M180,-131.89C180,-124.12 180,-114.36 180,-105.43"/>
<polygon fill="red" stroke="red" points="183.5,-105.15 180,-95.15 176.5,-105.15 183.5,-105.15"/>
<text text-anchor="middle" x="169.5" y="-109.8" font-family="Times,serif" font-size="14.00"> ❌ &#160;</text>
</g>
<!-- build -->
<g id="node5" class="node">
<title>build</title>
<polygon fill="none" stroke="red" points="360,-29 0,-29 0,0 360,0 360,-29"/>
<text text-anchor="start" x="137" y="-13" font-family="monospace" font-weight="bold" font-size="10.00">RUN </text>
<text text-anchor="start" x="162" y="-13" font-family="monospace" font-size="10.00">make build</text>
</g>
<!-- workdir&#45;&gt;build -->
<g id="edge4" class="edge">
<title>workdir&#45;&gt;build</title>
<path fill="none" stroke="red" d="M180,-65.89C180,-58.12 180,-48.36 180,-39.43"/>
<polygon fill="red" stroke="red" points="183.5,-39.15 180,-29.15 176.5,-39.15 183.5,-39.15"/>
<text text-anchor="middle" x="169.5" y="-43.8" font-family="Times,serif" font-size="14.00"> ❌ &#160;</text>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 3.8 KiB

19
build/images/cache-stack.dot Normal file
View File

@ -0,0 +1,19 @@
// dot -Tsvg ./cache-stack.dot > ./cache-stack.svg
digraph {
rankdir="LR";
nodesep=0.3;
edge[minlen=0];
bgcolor="#00000000";
node [ shape=rect, width=5, height=0.4, fontname=monospace, fontsize=10 ];
from [ label = <<B>FROM </B>ubuntu:latest> ];
deps [ label = <<B>RUN </B>apt-get update &amp;&amp; \\<br/>apt-get install -y build-essentials> ];
copy [ label = <<B>COPY </B>. /src/> ];
workdir [ label = <<B>WORKDIR </B>/src/> ];
build [ label = <<B>RUN </B>make build> ];
from -> deps;
deps -> copy;
copy -> workdir;
workdir -> build;
}

72
build/images/cache-stack.svg Normal file
View File

@ -0,0 +1,72 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 5.0.0 (0)
-->
<!-- Pages: 1 -->
<svg width="368pt" height="241pt"
viewBox="0.00 0.00 368.00 241.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 237)">
<polygon fill="transparent" stroke="transparent" points="-4,4 -4,-237 364,-237 364,4 -4,4"/>
<!-- from -->
<g id="node1" class="node">
<title>from</title>
<polygon fill="none" stroke="black" points="360,-233 0,-233 0,-204 360,-204 360,-233"/>
<text text-anchor="start" x="125" y="-217" font-family="monospace" font-weight="bold" font-size="10.00">FROM </text>
<text text-anchor="start" x="156" y="-217" font-family="monospace" font-size="10.00">ubuntu:latest</text>
</g>
<!-- deps -->
<g id="node2" class="node">
<title>deps</title>
<polygon fill="none" stroke="black" points="360,-182 0,-182 0,-153 360,-153 360,-182"/>
<text text-anchor="start" x="110" y="-170.5" font-family="monospace" font-weight="bold" font-size="10.00">RUN </text>
<text text-anchor="start" x="135" y="-170.5" font-family="monospace" font-size="10.00">apt&#45;get update &amp;&amp; \</text>
<text text-anchor="start" x="74.5" y="-160.5" font-family="monospace" font-size="10.00">apt&#45;get install &#45;y build&#45;essentials</text>
</g>
<!-- from&#45;&gt;deps -->
<g id="edge1" class="edge">
<title>from&#45;&gt;deps</title>
<path fill="none" stroke="black" d="M180,-203.77C180,-199.96 180,-196.15 180,-192.33"/>
<polygon fill="black" stroke="black" points="183.5,-192.24 180,-182.24 176.5,-192.24 183.5,-192.24"/>
</g>
<!-- copy -->
<g id="node3" class="node">
<title>copy</title>
<polygon fill="none" stroke="black" points="360,-131 0,-131 0,-102 360,-102 360,-131"/>
<text text-anchor="start" x="143" y="-115" font-family="monospace" font-weight="bold" font-size="10.00">COPY </text>
<text text-anchor="start" x="174" y="-115" font-family="monospace" font-size="10.00">. /src/</text>
</g>
<!-- deps&#45;&gt;copy -->
<g id="edge2" class="edge">
<title>deps&#45;&gt;copy</title>
<path fill="none" stroke="black" d="M180,-152.77C180,-148.96 180,-145.15 180,-141.33"/>
<polygon fill="black" stroke="black" points="183.5,-141.24 180,-131.24 176.5,-141.24 183.5,-141.24"/>
</g>
<!-- workdir -->
<g id="node4" class="node">
<title>workdir</title>
<polygon fill="none" stroke="black" points="360,-80 0,-80 0,-51 360,-51 360,-80"/>
<text text-anchor="start" x="140" y="-64" font-family="monospace" font-weight="bold" font-size="10.00">WORKDIR </text>
<text text-anchor="start" x="189" y="-64" font-family="monospace" font-size="10.00">/src/</text>
</g>
<!-- copy&#45;&gt;workdir -->
<g id="edge3" class="edge">
<title>copy&#45;&gt;workdir</title>
<path fill="none" stroke="black" d="M180,-101.77C180,-97.96 180,-94.15 180,-90.33"/>
<polygon fill="black" stroke="black" points="183.5,-90.24 180,-80.24 176.5,-90.24 183.5,-90.24"/>
</g>
<!-- build -->
<g id="node5" class="node">
<title>build</title>
<polygon fill="none" stroke="black" points="360,-29 0,-29 0,0 360,0 360,-29"/>
<text text-anchor="start" x="137" y="-13" font-family="monospace" font-weight="bold" font-size="10.00">RUN </text>
<text text-anchor="start" x="162" y="-13" font-family="monospace" font-size="10.00">make build</text>
</g>
<!-- workdir&#45;&gt;build -->
<g id="edge4" class="edge">
<title>workdir&#45;&gt;build</title>
<path fill="none" stroke="black" d="M180,-50.77C180,-46.96 180,-43.15 180,-39.33"/>
<polygon fill="black" stroke="black" points="183.5,-39.24 180,-29.24 176.5,-39.24 183.5,-39.24"/>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 3.6 KiB