From c42962dc875916bd71578749833e9bc72ed06757 Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Mon, 12 Sep 2022 10:35:46 +0100 Subject: [PATCH] build: add svg diagrams to cache docs Also adds the graphviz generation code. Signed-off-by: Justin Chadwell --- _scss/_night-mode.scss | 5 ++ build/building/cache.md | 15 ++-- build/images/cache-stack-invalidate-copy.dot | 19 +++++ build/images/cache-stack-invalidate-copy.svg | 73 +++++++++++++++++++ build/images/cache-stack-invalidate-rest.dot | 19 +++++ build/images/cache-stack-invalidate-rest.svg | 74 ++++++++++++++++++++ build/images/cache-stack.dot | 19 +++++ build/images/cache-stack.svg | 72 +++++++++++++++++++ 8 files changed, 286 insertions(+), 10 deletions(-) create mode 100644 build/images/cache-stack-invalidate-copy.dot create mode 100644 build/images/cache-stack-invalidate-copy.svg create mode 100644 build/images/cache-stack-invalidate-rest.dot create mode 100644 build/images/cache-stack-invalidate-rest.svg create mode 100644 build/images/cache-stack.dot create mode 100644 build/images/cache-stack.svg diff --git a/_scss/_night-mode.scss b/_scss/_night-mode.scss index 93bd70cffc..3a26635d62 100755 --- a/_scss/_night-mode.scss +++ b/_scss/_night-mode.scss @@ -180,6 +180,11 @@ body.night { img.white-bg { background-color: white; } + + /* apply to images that support being inverted */ + img.invertible { + filter: invert(100%) hue-rotate(180deg); + } /* accordion */ .panel { diff --git a/build/building/cache.md b/build/building/cache.md index 3cc1daab67..555fe9c075 100644 --- a/build/building/cache.md +++ b/build/building/cache.md @@ -23,7 +23,7 @@ might be used to create a C/C++ program: ```dockerfile 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/ WORKDIR /src/ 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 content to the filesystem on top of the layer before it: -``` -stack diagram -``` +![Image layer diagram showing the above commands chained together one after the other](../images/cache-stack.svg){:.invertible} + 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 will have to run again, so that the layer changes, so the cache for that layer has been invalidated. -``` -stack diagram with COPY layer cache invalidated -``` +![Image layer diagram, but now with the link between COPY and WORKDIR marked as invalid](../images/cache-stack-invalidate-copy.svg){:.invertible} 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 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: -``` -stack diagram with COPY + other layer cache invalidated -``` +![Image layer diagram, but now with all links after COPY marked as invalid](../images/cache-stack-invalidate-rest.svg){:.invertible} 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 diff --git a/build/images/cache-stack-invalidate-copy.dot b/build/images/cache-stack-invalidate-copy.dot new file mode 100644 index 0000000000..beb4bfd11a --- /dev/null +++ b/build/images/cache-stack-invalidate-copy.dot @@ -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 = <FROM ubuntu:latest> ]; + deps [ label = <RUN apt-get update && \\
apt-get install -y build-essentials> ]; + copy [ label = <COPY . /src/>, color = "red" ]; + workdir [ label = <WORKDIR /src/> ]; + build [ label = <RUN make build> ]; + + from -> deps; + deps -> copy; + copy -> workdir [ color = "red", label = " ❌ " ]; + workdir -> build; +} diff --git a/build/images/cache-stack-invalidate-copy.svg b/build/images/cache-stack-invalidate-copy.svg new file mode 100644 index 0000000000..cd80c60f21 --- /dev/null +++ b/build/images/cache-stack-invalidate-copy.svg @@ -0,0 +1,73 @@ + + + + + + + + + +from + +FROM +ubuntu:latest + + + +deps + +RUN +apt-get update && \ +apt-get install -y build-essentials + + + +from->deps + + + + + +copy + +COPY +. /src/ + + + +deps->copy + + + + + +workdir + +WORKDIR +/src/ + + + +copy->workdir + + + ❌   + + + +build + +RUN +make build + + + +workdir->build + + + + + diff --git a/build/images/cache-stack-invalidate-rest.dot b/build/images/cache-stack-invalidate-rest.dot new file mode 100644 index 0000000000..f7956776e0 --- /dev/null +++ b/build/images/cache-stack-invalidate-rest.dot @@ -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 = <FROM ubuntu:latest> ]; + deps [ label = <RUN apt-get update && \\
apt-get install -y build-essentials> ]; + copy [ label = <COPY . /src/>, color = "red" ]; + workdir [ label = <WORKDIR /src/>, color = "red" ]; + build [ label = <RUN make build>, color = "red" ]; + + from -> deps; + deps -> copy; + copy -> workdir [ color = "red", label = " ❌ " ]; + workdir -> build [ color = "red", label = " ❌ " ]; +} diff --git a/build/images/cache-stack-invalidate-rest.svg b/build/images/cache-stack-invalidate-rest.svg new file mode 100644 index 0000000000..fb85cf43d6 --- /dev/null +++ b/build/images/cache-stack-invalidate-rest.svg @@ -0,0 +1,74 @@ + + + + + + + + + +from + +FROM +ubuntu:latest + + + +deps + +RUN +apt-get update && \ +apt-get install -y build-essentials + + + +from->deps + + + + + +copy + +COPY +. /src/ + + + +deps->copy + + + + + +workdir + +WORKDIR +/src/ + + + +copy->workdir + + + ❌   + + + +build + +RUN +make build + + + +workdir->build + + + ❌   + + + diff --git a/build/images/cache-stack.dot b/build/images/cache-stack.dot new file mode 100644 index 0000000000..95c4573435 --- /dev/null +++ b/build/images/cache-stack.dot @@ -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 = <FROM ubuntu:latest> ]; + deps [ label = <RUN apt-get update && \\
apt-get install -y build-essentials> ]; + copy [ label = <COPY . /src/> ]; + workdir [ label = <WORKDIR /src/> ]; + build [ label = <RUN make build> ]; + + from -> deps; + deps -> copy; + copy -> workdir; + workdir -> build; +} diff --git a/build/images/cache-stack.svg b/build/images/cache-stack.svg new file mode 100644 index 0000000000..6afd17e4c9 --- /dev/null +++ b/build/images/cache-stack.svg @@ -0,0 +1,72 @@ + + + + + + + + + +from + +FROM +ubuntu:latest + + + +deps + +RUN +apt-get update && \ +apt-get install -y build-essentials + + + +from->deps + + + + + +copy + +COPY +. /src/ + + + +deps->copy + + + + + +workdir + +WORKDIR +/src/ + + + +copy->workdir + + + + + +build + +RUN +make build + + + +workdir->build + + + + +