Update README to improve build documentation

Improve build documentation.
Fix devcontainer.
Remove unneccessary builds from yarn scripts.

Contributed on behalf of STMicroelectronics

.devcontainer/devcontainer.json

@@ -1,44 +1,34 @@
-// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
-// https://github.com/microsoft/vscode-dev-containers/tree/v0.231.5/containers/typescript-node
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/docker-existing-dockerfile
 {
 	"name": "Node.js & TypeScript",
 	"build": {
-		"dockerfile": "Dockerfile.dev",
-		// Update 'VARIANT' to pick a Node version: 16, 14, 12.
-		// Append -bullseye or -buster to pin to an OS version.
-		// Use -bullseye variants on local on arm64/Apple Silicon.
-		"args": { 
-			"VARIANT": "12-bullseye"
-		}
+		// Sets the run context to one level up instead of the .devcontainer folder.
+		"context": "..",
+		// Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
+		"dockerfile": "../Dockerfile.dev"
 	},
-
-	// Set *default* container specific settings.json values on container create.
-	"settings": {},
-
-
-	// Add the IDs of extensions you want installed when the container is created.
-	"extensions": [
-		"dbaeumer.vscode-eslint"
-	],
-
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
 	// Use 'forwardPorts' to make a list of ports inside the container available locally.
 	// "forwardPorts": [],
-
-	// Use 'postCreateCommand' to run commands after the container is created.
-	// "postCreateCommand": "yarn install",
-
-	// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	// Uncomment the next line to run commands after the container is created.
+	"postCreateCommand": "yarn && yarn build:extensions && yarn browser build",
+	// Configure tool-specific properties.
+	// "customizations": {},
+	// Uncomment to connect as an existing user other than the container default. More info: https://aka.ms/dev-containers-non-root.
 	"remoteUser": "node",
-
-	// Happens after updateContentCommand and once the dev container has been assigned to a user for the first time.
-	"postCreateCommand": "yarn",
-
 	"portsAttributes": {
-		"3000": { "label": "Theia Backend", "onAutoForward": "openBrowserOnce" },
-		"8080": { "label": "Trace Compass Server", "onAutoForward": "silent" }
+		"3000": {
+			"label": "Theia Backend",
+			"onAutoForward": "openBrowserOnce"
+		},
+		"8080": {
+			"label": "Trace Compass Server",
+			"onAutoForward": "silent"
+		}
 	},
-
 	// Runs each time the container is successfully started
 	// Starts the trace compass server. Downloads the server if not yet available.
 	"postStartCommand": "nohup bash -c 'yarn tracecompass-server:start &'"
-}
+}

README.md

@@ -56,67 +56,92 @@ Documentation on how to package Theia as a Desktop Product may be found [here](h
 
 ### Build
 
+#### Downloading dependencies
+
+To prepare the workspace the dependencies, plugins and the trace-compass server need to be downloaded.
+
+```sh
+yarn
+```
+
+```sh
+yarn download:plugins
+```
+
+```sh
+yarn tracecompass-server:download
+```
+
+#### Build all applications
+
+Build the sources and all three application (browser, docker and electron).
+
 For development and casual testing of Blueprint, one can build it in "dev" mode. This permits building Blueprint on systems with less resources, like a Raspberry Pi 4B with 4GB of RAM.
 
 ```sh
 # Build "dev" version of the Blueprint app. Its quicker, uses less resources, 
 # but the front end app is not "minified"
-yarn && yarn build:dev && yarn download:plugins
+yarn build:dev
 ```
 
 Production Blueprint applications:
 
 ```sh
 # Build production version of the Blueprint app
-yarn && yarn build && yarn download:plugins
+yarn build
+```
+
+#### Build & run electron application
+
+```sh
+yarn build:extensions
+yarn electron build
 ```
 
-### Package the Applications
+The electron app may be started with
+
+```sh
+yarn electron start
+```
+
+##### Package the electron application
 
 ATM we only produce packages for the Electron application.
 
 ```sh
+yarn build:extensions
 yarn package:applications
-# or
+# or (if the trace-compass server was already downloaded)
 yarn electron package
 ```
 
 The packaged application is located in `applications/electron/dist`.
 
-### Create a Preview Electron Electron Application (without packaging it)
+##### Create a Preview Electron Application (without packaging it)
 
 ```sh
+yarn build:extensions
+yarn package:applications:preview
+# or (if the trace-compass server was already downloaded)
 yarn electron package:preview
 ```
 
 The packaged application is located in `applications/electron/dist`.
 
-### Workspace and example files
-
-- To use the trace view, download and start the [TraceCompassServer](https://download.eclipse.org/tracecompass.incubator/trace-server/rcp/)
-- Example traces can be found here: [TraceCompassTutorialTraces](https://github.com/tuxology/tracevizlab/blob/master/labs/TraceCompassTutorialTraces.tgz)
-- An example workspace including a trace can be found [here](https://github.com/eclipsesource/cdtcloud-alpha/tree/master/example/workspace)
-- Clangd contexts also provides an example workspace, see [here](https://github.com/eclipse-cdt-cloud/clangd-contexts/tree/main/examples/clangd-workspace).
-
-### Running E2E Tests
-
-The E2E tests basic UI tests of the actual application.
-This is done based on the preview of the packaged application.
+#### Build & run browser application
 
 ```sh
-yarn electron package:preview
-yarn electron test
+yarn build:extensions
+yarn browser build
 ```
 
-### Docker based development
+The browser app may be started with
 
-1. Install the [Remote Dev extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) in VS Code
-2. Open this repository in VS Code
-3. In the notification that should appear: confirm to open this folder in the remote container instead
-4. Once VS Code is opened in the container and the `Configuring Dev Container` task is finished, run `yarn browser start` in the container's terminal to start the CDT Cloud blueprint backend.
-5. Once CDT Cloud blueprint is up, it should be running on 127.0.0.1:3000 and can be accessed from the host.
+```sh
+yarn browser start
+```
 
-Now you can make changes to the source code and rebuild with `yarn` or run `yarn watch` before the changes. After a browser refresh, your changes should get effective.
+The application is then available at <http://localhost:3000/>
 
 #### Build & run Docker image
 
@@ -132,15 +157,34 @@ To start the created image run:
 docker run -it -p 0.0.0.0:3000:3000 cdt-cloud-blueprint:latest
 ```
 
-### Running Browser app
+The application is then available at <http://localhost:3000/>
 
-The browser app may be started with
+### Docker based development
+
+1. Install the [Remote Dev extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) in VS Code
+2. Open this repository in VS Code
+3. In the notification that should appear: confirm to open this folder in the remote container instead
+4. Once VS Code is opened in the container and the `Configuring Dev Container` task is finished, run `yarn browser start` in the container's terminal to start the CDT Cloud blueprint backend.
+5. Once CDT Cloud blueprint is up, it should be running on 127.0.0.1:3000 and can be accessed from the host.
+
+Now you can make changes to the source code and rebuild with `yarn build:extensions && yarn browser build` or run `yarn watch` before the changes. After a browser refresh, your changes should get effective.
+
+#### Running E2E Tests
+
+The E2E tests basic UI tests of the actual application.
+This is done based on the preview of the packaged application.
 
 ```sh
-yarn browser start
+yarn electron package:preview
+yarn electron test
 ```
 
-and connect to <http://localhost:3000/>
+### Workspace and example files
+
+- To use the trace view, download and start the [TraceCompassServer](https://download.eclipse.org/tracecompass.incubator/trace-server/rcp/)
+- Example traces can be found here: [TraceCompassTutorialTraces](https://github.com/tuxology/tracevizlab/blob/master/labs/TraceCompassTutorialTraces.tgz)
+- An example workspace including a trace can be found [here](https://github.com/eclipsesource/cdtcloud-alpha/tree/master/example/workspace)
+- Clangd contexts also provides an example workspace, see [here](https://github.com/eclipse-cdt-cloud/clangd-contexts/tree/main/examples/clangd-workspace).
 
 ### Troubleshooting
 

package.json

@@ -58,8 +58,8 @@
     "clean": "lerna run clean && rimraf node_modules",
     "build": "yarn build:extensions && yarn build:applications",
     "build:dev": "yarn build:extensions && yarn build:applications:dev",
-    "build:applications": "yarn build:extensions && lerna run --scope=\"cdt-cloud-blueprint*app\" build:prod --concurrency 1",
-    "build:applications:dev": "yarn build:extensions && lerna run --scope=\"cdt-cloud-blueprint*app\" build --concurrency 1",
+    "build:applications": "lerna run --scope=\"cdt-cloud-blueprint*app\" build:prod --concurrency 1",
+    "build:applications:dev": "lerna run --scope=\"cdt-cloud-blueprint*app\" build --concurrency 1",
     "build:extensions": "lerna run --scope=\"cdt-cloud-blueprint*ext\" --scope=\"@eclipse-cdt-cloud/*\" build",
     "download:plugins": "theia download:plugins --rate-limit=15 --parallel=false --ignore-errors",
     "package:applications": "yarn tracecompass-server:download && lerna run --scope=\"cdt-cloud-blueprint*app\" package --concurrency 1",