From 5a0879eb62f408a88f659f7d1e6eafe54967546f Mon Sep 17 00:00:00 2001 From: Andrea Di Dio Date: Mon, 22 Jul 2024 15:25:01 +0200 Subject: [PATCH 1/8] lab1: You Got Framed --- .gitignore | 1 + 1 file changed, 1 insertion(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bee8a64 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +__pycache__ From d6728f184d4b35a9aecdd29428e8bc09f254b154 Mon Sep 17 00:00:00 2001 From: maxgallup Date: Sat, 31 Aug 2024 14:39:48 +0000 Subject: [PATCH 2/8] feat: added devcontainer support --- .devcontainer/Dockerfile | 34 +++++++++++ .devcontainer/custom/.bashrc | 56 ++++++++++++++++++ .devcontainer/devcontainer.json | 22 +++++++ .gitignore | 4 ++ jos.out | 100 -------------------------------- jos.out.mcorefork | 100 -------------------------------- 6 files changed, 116 insertions(+), 200 deletions(-) create mode 100644 .devcontainer/Dockerfile create mode 100644 .devcontainer/custom/.bashrc create mode 100644 .devcontainer/devcontainer.json create mode 100644 .gitignore delete mode 100644 jos.out delete mode 100644 jos.out.mcorefork diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000..74ea443 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,34 @@ +FROM ubuntu:22.04 + +ARG DEBIAN_FRONTEND=noninteractive + +RUN apt update && apt upgrade -y + +RUN apt update --fix-missing && apt install -y \ + sudo \ + build-essential \ + curl \ + git \ + make \ + python3 \ + python-is-python3 \ + wget + +RUN apt update --fix-missing && apt install -y \ + clang \ + llvm \ + lld \ + gdb \ + qemu-system + + +# Add custom user "dev" with sudo permissions +RUN useradd dev -u 1000 -m -s /bin/bash && \ + echo "dev ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers +USER dev + + +# Terminal prompt customizations +COPY custom/.bashrc /home/dev/.bashrc +RUN sudo chown dev:dev /home/dev/.bashrc + diff --git a/.devcontainer/custom/.bashrc b/.devcontainer/custom/.bashrc new file mode 100644 index 0000000..647d491 --- /dev/null +++ b/.devcontainer/custom/.bashrc @@ -0,0 +1,56 @@ +# customized PS1 prompt to indicate we are in a container +PS1="\W \e[01;31m$\e[m " + +# If not running interactively, don't do anything +case $- in + *i*) ;; + *) return;; +esac + +# don't put duplicate lines or lines starting with space in the history. +# See bash(1) for more options +HISTCONTROL=ignoreboth + +# append to the history file, don't overwrite it +shopt -s histappend + +# for setting history length see HISTSIZE and HISTFILESIZE in bash(1) +HISTSIZE=1000 +HISTFILESIZE=2000 + +# custom +alias l="ls -lah" +alias ..="cd .." + +# git aliases +alias gs="git status" +alias gc="git commit -m " +alias ga="git add " +alias gp="git push" +alias gpl="git pull" +alias gl="git log --pretty=oneline" + +# check the window size after each command and, if necessary +# update the values of LINES and COLUMNS. +shopt -s checkwinsize + +# make less more friendly for non-text input files, see lesspipe(1) +[ -x /usr/bin/lesspipe ] && eval "$(SHELL=/bin/sh lesspipe)" + + +# Alias definitions in bash_aliases +if [ -f ~/work/scripts/.bash_aliases ]; then + . ~/work/scripts/.bash_aliases +fi + +# enable programmable completion features (you don't need to enable +# this, if it's already enabled in /etc/bash.bashrc and /etc/profile +# sources /etc/bash.bashrc). +if ! shopt -oq posix; then + if [ -f /usr/share/bash-completion/bash_completion ]; then + . /usr/share/bash-completion/bash_completion + elif [ -f /etc/bash_completion ]; then + . /etc/bash_completion + fi +fi + diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..6c919f1 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,22 @@ +{ + "name": "aos-dev", + + "build": { + "dockerfile": "Dockerfile" + }, + + "customizations": { + "vscode": { + "extensions": [ + "streetsidesoftware.code-spell-checker", + ] + } + }, + "capAdd": ["SYS_PTRACE"], + "securityOpt": [ "seccomp=unconfined" ], + + // If you need more ports forwarded, add them here + "forwardPorts": [ + ], + +} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..238843a --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +obj +*__pycache__ +.gdbrc* +*jos* \ No newline at end of file diff --git a/jos.out b/jos.out deleted file mode 100644 index 3eb3792..0000000 --- a/jos.out +++ /dev/null @@ -1,100 +0,0 @@ -+ ld obj/kernel/kernel -+ mk obj/kernel/kernel.img -*** -*** Now run 'make gdb'. -*** -c[?7lSeaBIOS (version 1.15.0-1) - - -iPXE (https://ipxe.org) 00:03.0 CA00 PCI2.10 PnP PMM+07F8B4A0+07ECB4A0 CA00 -Press Ctrl-B to configure iPXE (PCI 00:03.0)... - - -Booting from Hard Disk... - -[LAB 2] check_ptbl_flags() succeeded! -[LAB 2] check_wx() succeeded! -[LAB 2] check_nx() succeeded! -[LAB 2] check_4k_paging() succeeded! -[LAB 2] check_free_list_order() succeeded! -[LAB 2] check_memory_layout() succeeded! -[LAB 2] check_buddy_consistency() succeeded! -[LAB 2] check_vas() succeeded! -I/O APIC with base=0xfec00000 -SMP: setting IMCR to switch from PIC mode to symmetric I/O mode -[PID 0] New task with PID 1 -LOAD vaddr=0x800020 memsz=4062 offset=352 filesz=4062 flags=[r-x] -LOAD vaddr=0x801000 memsz=716 offset=8192 filesz=716 flags=[r--] -LOAD vaddr=0x802000 memsz=8 offset=12288 filesz=8 flags=[rw-] -LOAD vaddr=0x200000 memsz=104 offset=12304 filesz=104 flags=[rw-] -[PID 1] New task with PID 2 -[PID 1] New task with PID 3 -[PID 1] New task with PID 4 -[PID 1] New task with PID 5 -[PID 1] New task with PID 6 -[PID 1] New task with PID 7 -[PID 1] New task with PID 8 -[PID 1] New task with PID 9 -[PID 9] Running on CPU 0 -[PID 9] Exiting gracefully -[PID 1] New task with PID 10 -[PID 1] New task with PID 11 -[PID 1] New task with PID 12 -[PID 1] New task with PID 13 -[PID 1] New task with PID 14 -[PID 1] New task with PID 15 -[PID 1] New task with PID 16 -[PID 1] New task with PID 17 -[PID 1] Running on CPU 0 -[PID 1] Exiting gracefully -[PID 1] Freed task with PID 9 -[PID 1] Freed task with PID 1 -[PID 17] Running on CPU 0 -[PID 17] Exiting gracefully -[PID 17] Freed task with PID 17 -[PID 16] Running on CPU 0 -[PID 16] Exiting gracefully -[PID 16] Freed task with PID 16 -[PID 15] Running on CPU 0 -[PID 15] Exiting gracefully -[PID 15] Freed task with PID 15 -[PID 13] Running on CPU 0 -[PID 13] Exiting gracefully -[PID 13] Freed task with PID 13 -[PID 14] Running on CPU 0 -[PID 14] Exiting gracefully -[PID 14] Freed task with PID 14 -[PID 12] Running on CPU 0 -[PID 12] Exiting gracefully -[PID 12] Freed task with PID 12 -[PID 11] Running on CPU 0 -[PID 11] Exiting gracefully -[PID 11] Freed task with PID 11 -[PID 10] Running on CPU 0 -[PID 10] Exiting gracefully -[PID 10] Freed task with PID 10 -[PID 8] Running on CPU 0 -[PID 8] Exiting gracefully -[PID 8] Freed task with PID 8 -[PID 7] Running on CPU 0 -[PID 7] Exiting gracefully -[PID 7] Freed task with PID 7 -[PID 6] Running on CPU 0 -[PID 6] Exiting gracefully -[PID 6] Freed task with PID 6 -[PID 5] Running on CPU 0 -[PID 5] Exiting gracefully -[PID 5] Freed task with PID 5 -[PID 3] Running on CPU 0 -[PID 3] Exiting gracefully -[PID 3] Freed task with PID 3 -[PID 4] Running on CPU 0 -[PID 4] Exiting gracefully -[PID 4] Freed task with PID 4 -[PID 2] Running on CPU 0 -[PID 2] Exiting gracefully -[PID 2] Freed task with PID 2 -Destroyed the only task - nothing more to do! -Welcome to the OpenLSD kernel monitor! -Type 'help' for a list of commands. -qemu-system-x86_64: terminating on signal 15 from pid 57442 (make) diff --git a/jos.out.mcorefork b/jos.out.mcorefork deleted file mode 100644 index 3eb3792..0000000 --- a/jos.out.mcorefork +++ /dev/null @@ -1,100 +0,0 @@ -+ ld obj/kernel/kernel -+ mk obj/kernel/kernel.img -*** -*** Now run 'make gdb'. -*** -c[?7lSeaBIOS (version 1.15.0-1) - - -iPXE (https://ipxe.org) 00:03.0 CA00 PCI2.10 PnP PMM+07F8B4A0+07ECB4A0 CA00 -Press Ctrl-B to configure iPXE (PCI 00:03.0)... - - -Booting from Hard Disk... - -[LAB 2] check_ptbl_flags() succeeded! -[LAB 2] check_wx() succeeded! -[LAB 2] check_nx() succeeded! -[LAB 2] check_4k_paging() succeeded! -[LAB 2] check_free_list_order() succeeded! -[LAB 2] check_memory_layout() succeeded! -[LAB 2] check_buddy_consistency() succeeded! -[LAB 2] check_vas() succeeded! -I/O APIC with base=0xfec00000 -SMP: setting IMCR to switch from PIC mode to symmetric I/O mode -[PID 0] New task with PID 1 -LOAD vaddr=0x800020 memsz=4062 offset=352 filesz=4062 flags=[r-x] -LOAD vaddr=0x801000 memsz=716 offset=8192 filesz=716 flags=[r--] -LOAD vaddr=0x802000 memsz=8 offset=12288 filesz=8 flags=[rw-] -LOAD vaddr=0x200000 memsz=104 offset=12304 filesz=104 flags=[rw-] -[PID 1] New task with PID 2 -[PID 1] New task with PID 3 -[PID 1] New task with PID 4 -[PID 1] New task with PID 5 -[PID 1] New task with PID 6 -[PID 1] New task with PID 7 -[PID 1] New task with PID 8 -[PID 1] New task with PID 9 -[PID 9] Running on CPU 0 -[PID 9] Exiting gracefully -[PID 1] New task with PID 10 -[PID 1] New task with PID 11 -[PID 1] New task with PID 12 -[PID 1] New task with PID 13 -[PID 1] New task with PID 14 -[PID 1] New task with PID 15 -[PID 1] New task with PID 16 -[PID 1] New task with PID 17 -[PID 1] Running on CPU 0 -[PID 1] Exiting gracefully -[PID 1] Freed task with PID 9 -[PID 1] Freed task with PID 1 -[PID 17] Running on CPU 0 -[PID 17] Exiting gracefully -[PID 17] Freed task with PID 17 -[PID 16] Running on CPU 0 -[PID 16] Exiting gracefully -[PID 16] Freed task with PID 16 -[PID 15] Running on CPU 0 -[PID 15] Exiting gracefully -[PID 15] Freed task with PID 15 -[PID 13] Running on CPU 0 -[PID 13] Exiting gracefully -[PID 13] Freed task with PID 13 -[PID 14] Running on CPU 0 -[PID 14] Exiting gracefully -[PID 14] Freed task with PID 14 -[PID 12] Running on CPU 0 -[PID 12] Exiting gracefully -[PID 12] Freed task with PID 12 -[PID 11] Running on CPU 0 -[PID 11] Exiting gracefully -[PID 11] Freed task with PID 11 -[PID 10] Running on CPU 0 -[PID 10] Exiting gracefully -[PID 10] Freed task with PID 10 -[PID 8] Running on CPU 0 -[PID 8] Exiting gracefully -[PID 8] Freed task with PID 8 -[PID 7] Running on CPU 0 -[PID 7] Exiting gracefully -[PID 7] Freed task with PID 7 -[PID 6] Running on CPU 0 -[PID 6] Exiting gracefully -[PID 6] Freed task with PID 6 -[PID 5] Running on CPU 0 -[PID 5] Exiting gracefully -[PID 5] Freed task with PID 5 -[PID 3] Running on CPU 0 -[PID 3] Exiting gracefully -[PID 3] Freed task with PID 3 -[PID 4] Running on CPU 0 -[PID 4] Exiting gracefully -[PID 4] Freed task with PID 4 -[PID 2] Running on CPU 0 -[PID 2] Exiting gracefully -[PID 2] Freed task with PID 2 -Destroyed the only task - nothing more to do! -Welcome to the OpenLSD kernel monitor! -Type 'help' for a list of commands. -qemu-system-x86_64: terminating on signal 15 from pid 57442 (make) From c4fc0b5ceaeb52cd60faf8381d7abf84e3689d25 Mon Sep 17 00:00:00 2001 From: maxgallup Date: Sat, 31 Aug 2024 14:49:28 +0000 Subject: [PATCH 3/8] chore: edited readme --- README | 1 - README.md | 4 ++++ 2 files changed, 4 insertions(+), 1 deletion(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index fa6cf65..0000000 --- a/README +++ /dev/null @@ -1 +0,0 @@ -Welcome to the OpenLSD framework. diff --git a/README.md b/README.md new file mode 100644 index 0000000..695a4f6 --- /dev/null +++ b/README.md @@ -0,0 +1,4 @@ +Welcome to the OpenLSD framework. + +# Usage with VSCode and Docker +VSCode ships an extension called [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) which allows you to open a repository inside of a Docker container that has all necessary development tools installed. This isolates your development environment from your host machine. Simply install the extension, then run the _"Dev Containers: Rebuild and Reopen inside Container"_ command from VSCode's command palette. It will take a while to build the container, however after that it will be cached and can be opened quickly. From fb02f82bc81e49aab3306db079c5cfc0677f52ef Mon Sep 17 00:00:00 2001 From: maxgallup Date: Sat, 31 Aug 2024 14:50:55 +0000 Subject: [PATCH 4/8] fix: adapted gitignore --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 238843a..5b53307 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ +__pycache__ obj -*__pycache__ .gdbrc* *jos* \ No newline at end of file From 031a3a5f5b3524732051f44f6590db5b23d693bd Mon Sep 17 00:00:00 2001 From: maxgallup Date: Tue, 17 Sep 2024 16:42:44 +0200 Subject: [PATCH 5/8] feat: added gef --- .devcontainer/Dockerfile | 5 +++++ .gitignore | 1 + 2 files changed, 6 insertions(+) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 74ea443..c2ef2ed 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -28,7 +28,12 @@ RUN useradd dev -u 1000 -m -s /bin/bash && \ USER dev +# Install GEF for sanity & its dependencies +RUN sudo apt install -y file && bash -c "$(wget https://gef.blah.cat/sh -O -)" + # Terminal prompt customizations +COPY custom/gu /usr/local/bin/gu COPY custom/.bashrc /home/dev/.bashrc +RUN sudo chown dev:dev /usr/local/bin/gu RUN sudo chown dev:dev /home/dev/.bashrc diff --git a/.gitignore b/.gitignore index 5b53307..2238615 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +.vscode __pycache__ obj .gdbrc* From 00725f6c20bee926adf3cb966abaf0b2699e05f8 Mon Sep 17 00:00:00 2001 From: maxgallup Date: Tue, 15 Oct 2024 14:17:31 +0200 Subject: [PATCH 6/8] fix: cleanup --- .devcontainer/Dockerfile | 10 +--------- .devcontainer/devcontainer.json | 9 ++++++--- 2 files changed, 7 insertions(+), 12 deletions(-) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index c2ef2ed..0b9755e 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -21,19 +21,11 @@ RUN apt update --fix-missing && apt install -y \ gdb \ qemu-system - # Add custom user "dev" with sudo permissions RUN useradd dev -u 1000 -m -s /bin/bash && \ echo "dev ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers USER dev - -# Install GEF for sanity & its dependencies -RUN sudo apt install -y file && bash -c "$(wget https://gef.blah.cat/sh -O -)" - # Terminal prompt customizations -COPY custom/gu /usr/local/bin/gu -COPY custom/.bashrc /home/dev/.bashrc -RUN sudo chown dev:dev /usr/local/bin/gu -RUN sudo chown dev:dev /home/dev/.bashrc +COPY --chown=dev:dev custom/.bashrc /home/dev/.bashrc diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 6c919f1..2b86a39 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -9,14 +9,17 @@ "vscode": { "extensions": [ "streetsidesoftware.code-spell-checker", + "ms-vscode.cpptools", ] } }, "capAdd": ["SYS_PTRACE"], "securityOpt": [ "seccomp=unconfined" ], - // If you need more ports forwarded, add them here - "forwardPorts": [ - ], + // If you need more ports forwarded, add them here. + "forwardPorts": [], + // Optionally, uncomment this for the container to use + // the network interface of the host (typically not necessary). + // "runArgs": [ "--network=host" ], } From 1e128298f1134bddec155e0f61d0f6f52fb5aa61 Mon Sep 17 00:00:00 2001 From: maxgallup Date: Tue, 15 Oct 2024 15:45:45 +0200 Subject: [PATCH 7/8] feat: updated readme + docker only support --- .devcontainer/docker.sh | 91 +++++++++++++++++++++++++++++++++++++++++ Makefile | 16 ++++++++ README.md | 25 +++++++++-- 3 files changed, 129 insertions(+), 3 deletions(-) create mode 100755 .devcontainer/docker.sh diff --git a/.devcontainer/docker.sh b/.devcontainer/docker.sh new file mode 100755 index 0000000..fd1e1c2 --- /dev/null +++ b/.devcontainer/docker.sh @@ -0,0 +1,91 @@ +#!/bin/bash + +IMAGE_NAME="aos-dev" +CONTAINER_NAME="aos-dev-container" +CONTAINER_ENTRY="/usr/bin/bash" +WORK_DIR="/home/dev/work" + +PROJECT_ROOT="$(pwd)" + +# function contianer_run() { +# sudo docker run -w $WORK_DIR --rm --hostname dev -it -v $PROJECT_ROOT:$WORK_DIR:z $IMAGE_NAME $CONTAINER_ENTRY +# } + +function container_stop() { + sudo docker stop $CONTAINER_NAME || echo "container already stopped" +} + +function clean() { + container_stop + sudo docker rm $CONTAINER_NAME || echo "container already removed" + sudo docker image rm $IMAGE_NAME || echo "image already removed" +} + +function container_start() { + if [ -z "$(sudo docker ps -a | grep $CONTAINER_NAME)" ]; then + echo ">> creating dev container" + + sudo docker run -w $WORK_DIR --hostname dev -it --name $CONTAINER_NAME \ + --net=host \ + --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \ + -v $PROJECT_ROOT:$WORK_DIR:z \ + $IMAGE_NAME $CONTAINER_ENTRY + + else + echo ">> found existing dev container" + sudo docker start $CONTAINER_NAME + sudo docker exec -it $CONTAINER_NAME $CONTAINER_ENTRY + + # if [ -z "$(sudo docker ps -a | grep $CONTAINER_NAME | grep "Up")" ]; then + # else + # fi + + + # echo "container exists already" + # sudo docker run -w $WORK_DIR --hostname dev -it \ + # --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \ + # -v $PROJECT_ROOT:$WORK_DIR:z \ + # $IMAGE_NAME $CONTAINER_ENTRY + fi +} + + +function image_build() { + if [ -z "$(sudo docker images | grep $IMAGE_NAME)" ]; then + echo ">> building image: $IMAGE_NAME" + sudo docker build -t $IMAGE_NAME .devcontainer/ + fi +} + + +function print_usage() { + echo "Usage ./docker.sh [container-start/stop | image-build | clean]" +} + + + +function main() { + if ! command -v docker 2>&1 >/dev/null; then + echo "Could not find docker. Please install it https://docs.docker.com/engine/install/" + exit 1 + fi + + if [ -z "$1" ]; then + print_usage + elif [ "$1" = "container-start" ]; then + container_start + elif [ "$1" = "container-stop" ]; then + container_stop + elif [ "$1" = "clean" ]; then + clean + elif [ "$1" = "image-build" ]; then + image_build + else + print_usage + fi + +} + + +main $@ + diff --git a/Makefile b/Makefile index 573aacd..f5ae672 100644 --- a/Makefile +++ b/Makefile @@ -348,6 +348,22 @@ run-%-nox: prep-% pre-qemu run-%: prep-% pre-qemu $(QEMU) $(QEMUOPTS) + + + + +docker: + @.devcontainer/docker.sh image-build + @.devcontainer/docker.sh container-start + +docker-stop: + @.devcontainer/docker.sh container-stop + +docker-clean: + @.devcontainer/docker.sh clean + + + # This magic automatically generates makefile dependencies # for header files included from C source files we compile, # and keeps those dependencies up-to-date every time we recompile. diff --git a/README.md b/README.md index 695a4f6..9af7359 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,23 @@ -Welcome to the OpenLSD framework. -# Usage with VSCode and Docker -VSCode ships an extension called [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) which allows you to open a repository inside of a Docker container that has all necessary development tools installed. This isolates your development environment from your host machine. Simply install the extension, then run the _"Dev Containers: Rebuild and Reopen inside Container"_ command from VSCode's command palette. It will take a while to build the container, however after that it will be cached and can be opened quickly. + +# Getting Started + +In order to get all necessary dependencies installed for this project we recommend to get started with following one of the supported methods below. + + +## With VSCode + Docker +VSCode ships an extension called [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) which allows you to open a repository inside of a Docker container that has all necessary development tools installed. This isolates your development environment from your host machine. Simply install the extension, then run the _"Dev Containers: Rebuild and Reopen inside Container"_ command from VSCode's command palette (Ctrl+P). It will take a while to build the container, however after that it will be cached and can be opened quickly. + +Note, that VSCode installs a development environment inside the container itself and lets you use a shell inside the container. This will obviously be different from the shell on you native machine, so feel free to add anything to the [Dockerfile](.devcontainer/Dockerfile) to suite your needs. Since we are running the project inside a docker container, we don't need to be worried about polluting our host's system with various versions of clang. After opening in the devcontainer environment, run `make grade` to verify that everything works. + + +## With Docker only + +We also provide the following Makefile target to start an interactive shell with all dependencies installed, without using VSCode. Simply run `make docker` which will build and start a shell inside the container (Ctrl + D) to exit. Then use `make grade` to verify everything is working + + +## With Devbox (Nix) + +[Devbox](https://www.jetify.com/devbox) is a wrapper built on top of the nix package manager and can make reproducibility very easy. This option has the benefit of keeping your host's development environment. If you have devbox installed, simply run `devbox shell` and all dependencies will be resolved. Then run `make grade` to verify everything works. + + From 1a00ed3bcccf406ed24fd378882eb92f882f4857 Mon Sep 17 00:00:00 2001 From: maxgallup Date: Tue, 15 Oct 2024 15:52:12 +0200 Subject: [PATCH 8/8] fix: updated readme --- README.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9af7359..f7f5620 100644 --- a/README.md +++ b/README.md @@ -5,18 +5,22 @@ In order to get all necessary dependencies installed for this project we recommend to get started with following one of the supported methods below. -## With VSCode + Docker -VSCode ships an extension called [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) which allows you to open a repository inside of a Docker container that has all necessary development tools installed. This isolates your development environment from your host machine. Simply install the extension, then run the _"Dev Containers: Rebuild and Reopen inside Container"_ command from VSCode's command palette (Ctrl+P). It will take a while to build the container, however after that it will be cached and can be opened quickly. +## With Docker only +*This method requires `docker`.* -Note, that VSCode installs a development environment inside the container itself and lets you use a shell inside the container. This will obviously be different from the shell on you native machine, so feel free to add anything to the [Dockerfile](.devcontainer/Dockerfile) to suite your needs. Since we are running the project inside a docker container, we don't need to be worried about polluting our host's system with various versions of clang. After opening in the devcontainer environment, run `make grade` to verify that everything works. +We provide the following Makefile target to start an interactive shell with all dependencies installed. Simply run `make docker` which will build and start a shell inside the container. This will mount the root of the project into the container so all of the files on your host will be inside the container as well. Then use `make grade` to verify everything works. -## With Docker only +## With VSCode + Docker +*This method requires `docker` and `VSVode`.* + +VSCode ships an extension called [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) which allows you to open a repository inside of a Docker container that has all necessary development tools installed. This isolates your development environment from your host machine. Simply install the extension, then run the _"Dev Containers: Rebuild and Reopen inside Container"_ command from VSCode's command palette (Ctrl+P). It will take a while to build the container, however after that it will be cached and can be opened quickly. -We also provide the following Makefile target to start an interactive shell with all dependencies installed, without using VSCode. Simply run `make docker` which will build and start a shell inside the container (Ctrl + D) to exit. Then use `make grade` to verify everything is working +Note, that VSCode installs a development environment inside the container itself and lets you use a shell inside the container. This will obviously be different from the shell on you native machine, so feel free to add anything to the [Dockerfile](.devcontainer/Dockerfile) to suite your needs. Since we are running the project inside a docker container, we don't need to be worried about polluting our host's system with various versions of clang. After opening in the devcontainer environment, run `make grade` to verify that everything works. ## With Devbox (Nix) +*This method requires `devbox`.* [Devbox](https://www.jetify.com/devbox) is a wrapper built on top of the nix package manager and can make reproducibility very easy. This option has the benefit of keeping your host's development environment. If you have devbox installed, simply run `devbox shell` and all dependencies will be resolved. Then run `make grade` to verify everything works.