|
1 | | -# devcontainer |
2 | | -Common Devcontainer for Eclipse S-CORE |
| 1 | +# Common DevContainer for Eclipse S-CORE |
| 2 | +This repository contains the common [development container](https://containers.dev) for [Eclipse S-CORE](https://github.com/eclipse-score). |
| 3 | +It contains all tools required to develop (modify, build, ...) Eclipse S-CORE. |
| 4 | +All tool version are well-defined, and all tools are pre-configured to work as expected for Eclipse S-CORE development. |
| 5 | +The container is [pre-built](https://containers.dev/guide/prebuild) in GitHub Actions as part of this repository, tested, published, and ready for use. |
| 6 | + |
| 7 | +Using the pre-built container in an Eclipse S-CORE repository is described in the [Usage](#usage) section. |
| 8 | + |
| 9 | +Modifying the content of the container is explained in the [Development](#development) section. |
| 10 | + |
| 11 | +## Usage |
| 12 | + |
| 13 | +> **NOTE:** There are several development environments which support development containers; most notably [Visual Studio Code](https://code.visualstudio.com), but also [IntelliJ IDEA](https://www.jetbrains.com/idea) and others. |
| 14 | +> See [here](https://containers.dev/supporting) for a more complete list. |
| 15 | +> In the following, we assume that [Visual Studio Code](https://code.visualstudio.com) and its Dev Containers extension is used. |
| 16 | +The [Dev Containers extension homepage](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) has a description how to get up to speed on Windows, macOS and Linux operating systems. |
| 17 | +From here on, we assume that such a development container setup is installed and running. |
| 18 | + |
| 19 | +### First-Time Setup |
| 20 | + |
| 21 | +Add a file called `.devcontainer/devcontainer.json` to your repository. |
| 22 | +It should contain the following: |
| 23 | + |
| 24 | +````json |
| 25 | +{ |
| 26 | + "name": "eclipse-s-core", |
| 27 | + "image": "ghcr.io/eclipse-score/devcontainer:<version>", |
| 28 | + "initializeCommand": "mkdir -p ${localEnv:HOME}/.cache/bazel" |
| 29 | +} |
| 30 | +```` |
| 31 | + |
| 32 | +The `<version>` must be a [valid, published release](https://github.com/eclipse-score/devcontainer/tags). |
| 33 | +You can also use `latest` as `<version>` to automatically follow the `main` branch - but be aware that this can result in undesired updates. |
| 34 | +The `initializeCommand` is required to ensure the default Bazel cache directory exists on your host system. |
| 35 | + |
| 36 | +To start using the container, click the **Reopen in Container** button when prompted by Visual Studio Code: |
| 37 | + |
| 38 | + |
| 39 | + |
| 40 | +Alternatively, you can press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> and run from there "Dev Containers: Reopen in Container". |
| 41 | + |
| 42 | +The first time you do this, the container will be downloaded. |
| 43 | +This may take some time. |
| 44 | +Afterwards, Visual Studio Code should show this in the lower left corner of your window: |
| 45 | + |
| 46 | + |
| 47 | + |
| 48 | +### Inside the Container |
| 49 | + |
| 50 | +Open a Terminal, and - for example - type `bazel build ...` to execute the default build of the repository. |
| 51 | + |
| 52 | +After you have build the code, create [compilation databases](https://clang.llvm.org/docs/JSONCompilationDatabase.html) via Visual Studio Code [Task](https://code.visualstudio.com/docs/debugtest/tasks): |
| 53 | + |
| 54 | +- C++: <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> -> `Tasks: Run Task` -> `Update compile_commands.json` |
| 55 | +- Rust: <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> -> `Tasks: Run Task` -> `Generate rust-project.json` |
| 56 | + |
| 57 | +These databases are used by Visual Studio Code to support code navigation and auto-completion with the help of [language servers](https://microsoft.github.io/language-server-protocol/). |
| 58 | + |
| 59 | +Congratulations, you are now a dev container enthusiast 😊. |
| 60 | + |
| 61 | +## Development |
| 62 | + |
| 63 | +> **NOTE:** This is about the development *of the DevContainer*, not about development of Eclipse S-CORE *using* the DevContainer. |
| 64 | +
|
| 65 | +The [Eclipse S-CORE](https://github.com/eclipse-score) development container is developed using - a development container! |
| 66 | +That means, the usage is similarly simple: |
| 67 | + |
| 68 | +```` |
| 69 | +git clone https://github.com/eclipse-score/devcontainer.git |
| 70 | +code devcontainer |
| 71 | +```` |
| 72 | +and "Reopen in Container". |
| 73 | + |
| 74 | +### Repository Structure |
| 75 | +Ordered by importance: |
| 76 | + |
| 77 | +* `src/s-core-devcontainer/` contains the sources for the Eclipse S-CORE DevContainer. |
| 78 | +It uses pre-existing [DevContainer features](https://containers.dev/implementors/features/) to provide some standard tools like Git, LLVM, and others. |
| 79 | +In addition, it uses a so-called "local" feature (cf. `src/s-core-devcontainer/.devcontainer/s-core-local`) for the remaining tools and configuration. |
| 80 | +* `scripts/` contains scripts to build and test the container. |
| 81 | +* `.devcontainer/` contains the definition of the DevContainer for **this** repository, i.e. the "devcontainer devcontainer". |
| 82 | +There should rarely be a need to modify this. |
| 83 | +* `.github/` contains the regular GitHub setup, with code owners and CI. |
| 84 | +* `resources/` contains a few screenshots. |
| 85 | + |
| 86 | +### Modify, Build, Test, Use |
| 87 | + |
| 88 | +It is very simple to develop the development container. |
| 89 | +You can change files related to the container and then simply run the `scripts/*`. |
| 90 | +They are used by the CI, but especially the build and test scripts can be run also locally out of the box: |
| 91 | +````console |
| 92 | +$ ./scripts/build.sh |
| 93 | +[... build output..] |
| 94 | +{"outcome":"success","imageName":["vsc-s-core-devcontainer-209943ec6ff795f57b20cdf85a70c904d1e3b4a329d1e01c79f0ffea615c6e40-features"]} |
| 95 | + |
| 96 | +$ ./scripts/test.sh |
| 97 | +[... test output...] |
| 98 | +💯 All passed! |
| 99 | +```` |
| 100 | +You can now also use this freshly built development container locally on your machine, e.g. to test the container as part of an Eclipse S-CORE module. |
| 101 | +For this you must understand that you have the following situation: |
| 102 | +``` |
| 103 | ++---------------------------------+ |
| 104 | +| Development Container A | |
| 105 | +| +---------------------------+ | |
| 106 | +| | S-CORE DevContainer image | | |
| 107 | +| +---------------------------+ | |
| 108 | ++---------------------------------+ |
| 109 | +``` |
| 110 | +`Development Container A` is the one you are running right now to develop the `S-CORE DevContainer` . |
| 111 | +So in order to execute `S-CORE DevContainer` on your host (and test it as part of an S-CORE module), you need to |
| 112 | + |
| 113 | +* export this newly built S-CORE DevContainer image |
| 114 | +* import the image on your host machine |
| 115 | +* use the image name in the `.devcontainer/devcontainer.json` of the targeted S-CORE module |
| 116 | + |
| 117 | +Concretely, this can be done as follows: |
| 118 | + |
| 119 | +* Run `docker save <imageName> > export.img` in `Development Container A`. |
| 120 | +For example, given above build output, this would be `docker save vsc-s-core-devcontainer-209943ec6ff795f57b20cdf85a70c904d1e3b4a329d1e01c79f0ffea615c6e40-features > export.img` |
| 121 | +* On your **host machine** (!!), open a console and run `docker load < /path/to/export.img`. |
| 122 | +* In the working copy of the targeted S-CORE module, edit the file `.devcontainer/devcontainer.json` and change the `"image": "..."` entry to `"image": "<imageName>"`. |
| 123 | +Given above build output, this would be `"image": "vsc-s-core-devcontainer-209943ec6ff795f57b20cdf85a70c904d1e3b4a329d1e01c79f0ffea615c6e40-features"`. |
| 124 | +The Visual Studio Code instance related to the targeted S-CORE module will now ask you to rebuild the DevContainer. |
| 125 | +Do so, and you have a running instance of `S-CORE DevContainer` related to the targeted S-CORE module. |
| 126 | + |
| 127 | +### Version Pinning |
| 128 | + |
| 129 | +The `S-CORE DevContainer` pins feature and tool versions. |
| 130 | +For tools that are not part of a trusted distribution (i.e. downloaded directly), it also pins the SHA256 hash. |
| 131 | +While not being the most convenient choice for tool updates, this makes our supply chain much more secure. |
| 132 | +Additionally, there are no "surprise updates" which unexpectedly break things. |
0 commit comments