CHAOS

Directly jump to corresponding main section:

• Prerequisites
• Usage
• External links
• Troubleshooting
• Bonus

Prerequisites

• Windows: >= 10 (with build >= 19041)

  • Git
  • enable WSL2 feature
  • Container engine : at least one
    • Docker Desktop + BuildKit + activate the WSL2 Backend for Docker Desktop
    • (preferred) Podman Engine(CLI) or Desktop
  • IDE: at least one
    • VisualStudio Code

• Ubuntu Linux: every LTS >= 18.04

  • Git
  • Container engine : at least one
    • DockerCE/EE + BuildKit
    • (preferred) Podman Engine(CLI) or Desktop
  • IDE: at least one
    • VisualStudio Code + specific Podman's IDE configuration
  • (optional) MicroK8s : Kubernetes for Ubuntu
  • (optional) Kubectl : Kubernetes CLI

see here or there for more info about the Open Containers Initiative (OCI).

Usage

Directly jump to corresponding sub-section:

1. Clone
2. Prepare
3. Build
   • Docker
   • OCI - Podman
4. Configure
   1. VSCode

1. Clone CHAOS

simply clone CHAOS repo into your local dev directory :

[user@hostname]$ git -C /your/local/dev/directory clone https://github.com/LABSIM/CHAOS.git

2. Prepare the environment

first of all, dir into your freshly cloned CHAOS root :

[user@hostname]$ cd /your/local/dev/directory/CHAOS/

export secret info (personal access token) to enable git 2FA from a container ! For further informations, see here

[user@hostname]$ echo 'your_super_secret_github_username' > /your/local/secret/path/github_username.txt
[user@hostname]$ echo 'your_super_secret_github_token' > /your/local/secret/path/github_token.txt

or...

PS> Write-Output "your_super_secret_github_username" | Out-File -append -encoding ASCII "C:\your\local\secret\path\github_username.txt"
PS> Write-Output "your_super_secret_github_token" | Out-File -append -encoding ASCII "C:\your\local\secret\path\github_token.txt"

then, we'll lauch the build stage for our container <chaos-target>:<chaos-version>

furthermore, private github tokens are temporary loaded during the build stage via the secret mount mechanism, more informations here

3. Build the container

depending on your container engine, available <chaos-target> & build procedure may be subject to some minor changes.

by convention, we advise :

• <chaos-section> == CHAOS high-level section name containing multiple target foreach project
• <chaos-target> == CHAOS specific build target name
• <chaos-version> == CHAOS build version, a good rule of thumbs should be that it matched the intended GAIA Simulation Software Ecosystem (SSE) version, see under

actually, the default GAIA SSE is configured to be the v.2.0.1 with features dev,sf,sb, but they can be configured through theses additionnal args in any of the folowwing container engine :

--build-arg GAIA_TARGET_ECOSYSTEM=<gaia-sse-version>
--build-arg GAIA_ENABLE_FEATURE=<gaia-sse-feature-A>,<gaia-sse-feature-B>,<gaia-sse-feature-N>

for a complete list of available each <gaia-sse-version> & <gaia-sse-feature>, see the LABSIM private GAIA repository here

3.1. Docker stack

MAY be required

the build log may be too heavy for the default builder driver so, if required, run the following command to increase the log builder setting :

[user@hostname]$ docker buildx create --driver docker-container --driver-opt env.BUILDKIT_STEP_LOG_MAX_SIZE=1000000000 --bootstrap --use

start by running the following command

[user@hostname]$ docker build --no-cache --load --secret id=GITHUB_USERNAME,src=your/local/secret/path/github_username.txt --secret id=GITHUB_TOKEN,src=your/local/secret/path/github_token.txt --file distro/<chaos-section>/docker/Dockerfile --target <chaos-target> --tag <chaos-target>:<chaos-version> .

available <chaos-target> for each <chaos-section> are :

1. LABSIM section (docker multi-stage build) :
   • labsim-base-gcc-bookworm target : a Debian Bookworm Linux distro with a GNU GCC compiler environment whithout SSE
   • labsim-devcontainer-gcc-bookworm target : a Debian Bookworm Linux distro with a GNU GCC compiler environment shipped with the desired SSE
   • labsim-base-llvm-bookworm target : a Debian Bookworm Linux distro with a LLVM compiler environment whithout SSE
   • labsim-devcontainer-llvm-bookworm target : a Debian Bookworm Linux distro with a LLVM compiler environment shipped with the desired SSE
2. SCHEME-GATEWAY section (docker multi-stage build) :
   • scheme-gateway-gcc-bookworm target : a Debian Bookworm Linux distro with a GNU GCC compiler environment whithout SSE
   • scheme-gateway-devcontainer-gcc-bookworm target : a Debian Bookworm Linux distro with a GNU GCC compiler environment shipped with the desired SSE

so now you should have a <chaos-target>:<chaos-version> container loaded into your local registry & ready to run ! Launch it with the following :

[user@hostname]$ docker run --rm -it <chaos-target>:<chaos-version>

& check the GAIA configuration, if any, with :

[user@hostname]$ gaia

don't forget to exit our running container :

[user@hostname]$ exit

3.2. Podman stack

[user@hostname]$ podman build --format oci --isolation rootless --no-cache --load --secret id=GITHUB_USERNAME,src=your/local/secret/path/github_username.txt --secret id=GITHUB_TOKEN,src=your/local/secret/path/github_token.txt --file distro/<chaos-section>/oci/<chaos-target>/Containerfile --tag <chaos-target>:<chaos-version> .

available <chaos-target> for each <chaos-section> are :

1. LABSIM section :
   • labsim-base-gcc-bookworm target : a Debian Bookworm Linux distro with a GNU GCC compiler environment whithout SSE
   • labsim-devcontainer-gcc-bookworm target : a Debian Bookworm Linux distro with a GNU GCC compiler environment shipped with the desired SSE
   • labsim-base-llvm-bookworm target : a Debian Bookworm Linux distro with a LLVM compiler environment whithout SSE
   • labsim-devcontainer-llvm-bookworm target : a Debian Bookworm Linux distro with a LLVM compiler environment shipped with the desired SSE

so now you should have a <chaos-target>:<chaos-version> container loaded into your local registry & ready to run ! Launch it with the following :

[user@hostname]$ podman run --rm -it <chaos-target>:<chaos-version>

& check the GAIA configuration, if any, with :

[user@hostname]$ gaia

don't forget to exit our running container :

[user@hostname]$ exit

4. Configure your preferred IDE

4.1. VSCode

Then, if you want to dev from the inside of our freshly build container, do :

1. Open VSCode, File > Open Folder... > Navigate to CHAOS dir > [Enter]
2. Install the following extensions (shortcut: [Ctrl]+[Shift]+[X]) :
   • Docker : ms-azuretools.vscode-docker
   • Kubernetes : ms-kubernetes-tools.vscode-kubernetes-tools
   • Remote dev : ms-vscode-remote.vscode-remote-extensionpack
   • BONUS! Material Theme : Equinusocio.vsc-material-theme
3. Press [F1] & type Remote-Containers: Rebuild & Reopen in Container, select the desired target, [Enter]
4. Open the worskspace when prompted to. Should pop in the lower right corner
5. Happy Coding !

Iff. using an LLVM based devcontainer see here about how to configure an integrated lldb debugger or, if you are a lazy one, as I am, simply install the CodeLLDB package from marketplace. But, be advise that it ship it's own LLDB binary so it will squeeze the devcontainer built-in...

HACK : If an error message poped up, well... It seems that the cpptool extension is buggy from inside a container, so we must force/install it from package :

• press [F1] & type Extensions: Install from VSIX..., [Enter]
• navigate to /labsim/dev/ directory, then select the cpptools-linux.vsix
• reload extensions as prosposed

External links

• development containers specification, see here

• devcontainer.json format details, see here

• VSCode devcontainer documentation, see here

Troubleshooting

Bug/Problem	Advice
- Win10 - suuuuuper slow internet speed	1. run a powershell as admin 2. run this command 3. reboot host 4. clean & purge docker data

Bonus

Command	Description
docker rmi -f $(docker images -a -q)	clean all local images
docker image ls	list all local images
docker run --rm -it {container}:{tag}	run interactive shell
docker stats	see running container stats from shell
docker system prune --all --force --volumes	! CAUTION ! full cleanup

License

See COPYING file