chore: import 'building' README section from jenkinsci/docker-ssh-agent

Ref: https://github.com/jenkinsci/docker-ssh-agent/blob/d1bfd814232ea509e555d50c55c972a5f24fb941/README.md

README.md

@@ -19,3 +19,164 @@ See [the `agent` README](./README_agent.md)
 This is an image based on `agent` for [Jenkins](https://jenkins.io) agents using TCP or WebSockets to establish inbound connection to the Jenkins controller.
 
 See [the `inbound-agent` README](./README_inbound-agent.md)
+
+## Building
+
+### Building and testing on Linux
+
+#### Target images
+
+If you want to see the target images that will be built, you can issue the following command:
+
+```bash
+$ make list
+alpine_jdk11
+alpine_jdk17
+debian_jdk11
+debian_jdk17
+```
+
+#### Building a specific image
+
+If you want to build a specific image, you can issue the following command:
+
+```bash
+make build-<OS>_<JDK_VERSION>
+```
+
+That would give for JDK 17 on Alpine Linux:
+
+```bash
+make build-alpine_jdk17
+```
+
+#### Building images supported by your current architecture
+
+Then, you can build the images supported by your current architecture by running:
+
+```bash
+make build
+```
+
+#### Testing all images
+
+If you want to test these images, you can run:
+
+```bash
+make test
+```
+#### Testing a specific image
+
+If you want to test a specific image, you can run:
+
+```bash
+make test-<OS>_<JDK_VERSION>
+```
+
+That would give for JDK 17 on Alpine Linux:
+
+```bash
+make test-alpine_jdk17
+```
+
+#### Building all images
+
+You can build all images (even those unsupported by your current architecture) by running:
+
+```bash
+make every-build
+```
+
+#### Other `make` targets
+
+`show` gives us a detailed view of the images that will be built, with the tags, platforms, and Dockerfiles.
+
+```bash
+make show
+{
+  "group": {
+    "default": {
+      "targets": [
+        "alpine_jdk17",
+        "alpine_jdk11",
+        "debian_jdk11",
+        "debian_jdk17",
+      ]
+    }
+  },
+  "target": {
+    "alpine_jdk11": {
+      "context": ".",
+      "dockerfile": "alpine/Dockerfile",
+      "tags": [
+        "docker.io/jenkins/ssh-agent:alpine-jdk11",
+        "docker.io/jenkins/ssh-agent:latest-alpine-jdk11"
+      ],
+      "platforms": [
+        "linux/amd64"
+      ],
+      "output": [
+        "type=docker"
+      ]
+    },
+    [...]
+```
+
+`bats` is a dependency target. It will update the [`bats` submodule](https://github.com/bats-core/bats-core) and run the tests.
+
+```bash
+make bats
+make: 'bats' is up to date.
+```
+
+`publish` allows the publication of all images targeted by 'linux' to a registry.
+
+`docker-init` is dedicated to Jenkins infrastructure for initializing docker and isn't required in other contexts.
+
+### Building and testing on Windows
+
+#### Building all images
+
+Run `.\build.ps1` to launch the build of the images corresponding to the "windows" target of docker-bake.hcl.
+
+Internally, the first time you'll run this script and if there is no build-windows.yaml file in your repository, it will use a combination of `docker buildx bake` and `yq` to generate a  build-windows.yaml docker compose file containing all Windows image definitions from docker-bake.hcl. Then it will run `docker compose` on this file to build these images.
+
+You can modify this docker compose file as you want, then rerun `.\build.ps1`.
+It won't regenerate the docker compose file from docker-bake.hcl unless you add the `-OverwriteDockerComposeFile` build.ps1 parameter:  `.\build.ps1 -OverwriteDockerComposeFile`.
+
+Note: you can generate this docker compose file from docker-bake.hcl yourself with the following command (require `docker buildx` and `yq`):
+
+```console
+# - Use docker buildx bake to output image definitions from the "windows" bake target
+# - Convert with yq to the format expected by docker compose
+# - Store the result in the docker compose file
+
+$ docker buildx bake --progress=plain --file=docker-bake.hcl windows --print `
+    | yq --prettyPrint '.target[] | del(.output) | {(. | key): {\"image\": .tags[0], \"build\": .}}' | yq '{\"services\": .}' `
+    | Out-File -FilePath build-windows.yaml
+```
+
+Note that you don't need build.ps1 to build (or to publish) your images from this docker compose file, you can use `docker compose --file=build-windows.yaml build`.
+
+#### Testing all images
+
+Run `.\build.ps1 test` if you also want to run the tests harness suit.
+
+Run `.\build.ps1 test -TestsDebug 'debug'` to also get commands & stderr of tests, displayed on top of them.
+You can set it to `'verbose'` to also get stdout of every test command.
+
+Note that instead of passing `-TestsDebug` parameter to build.ps1, you can set the  $env:TESTS_DEBUG environment variable to the desired value.
+
+Also note that contrary to the Linux part, you have to build the images before testing them.
+
+#### Dry run
+
+Add the `-DryRun` parameter to print out any build, publish or tests commands instead of executing them: `.\build.ps1 test -DryRun`
+
+#### Building and testing a specific image
+
+You can build (and test) only one image type by setting `-ImageType` to a combination of Windows flavors ("nanoserver" & "windowsservercore") and Windows versions ("1809", "ltsc2019", "ltsc2022").
+
+Ex: `.\build.ps1 -ImageType 'nanoserver-ltsc2019'`
+
+Warning: trying to build `windowsservercore-1809` will fail as there is no corresponding image from Microsoft.