[wiki] Update toolchain description

.gitignore

@@ -70,3 +70,6 @@ sysroot
 
 # pcap files
 *.pcap
+
+# python env
+mimiker-env/

Dockerfile

@@ -2,28 +2,20 @@ FROM debian:bullseye-backports
 
 WORKDIR /root
 
-RUN apt-get -q update && apt-get upgrade -y
-RUN apt-get install -y --no-install-recommends -t bullseye-backports \
-      git make ccache cpio curl gnupg universal-ctags cscope socat patch \
-      gperf quilt bmake byacc python3-pip device-tree-compiler tmux \
-      libmpfr6 libfdt1 libpython3.9 libsdl2-2.0-0 libglib2.0-0 libpixman-1-0
-RUN apt-key adv --fetch-keys https://apt.llvm.org/llvm-snapshot.gpg.key
-RUN echo "deb http://apt.llvm.org/bullseye/ llvm-toolchain-bullseye-14 main" > \
-      /etc/apt/sources.list.d/llvm-14.list && apt-get update
-RUN apt-get install -y --no-install-recommends -t bullseye-backports \
-      clang-14 clang-format-14 llvm-14 lld-14
-# patch & quilt required by lua and programs in contrib/
-# gperf required by libterminfo
-# socat & tmux required by launch
+COPY packages.txt .
+RUN apt-get -q update && apt-get upgrade -y && \
+  apt-get install -y --no-install-recommends -t bullseye-backports $(cat packages.txt) && \
+  apt-key adv --fetch-keys https://apt.llvm.org/llvm-snapshot.gpg.key && \
+  echo "deb http://apt.llvm.org/bullseye/ llvm-toolchain-bullseye-14 main" > \
+        /etc/apt/sources.list.d/llvm-14.list && apt-get update && \
+  apt-get install -y --no-install-recommends -t bullseye-backports \
+        clang-14 clang-format-14 llvm-14 lld-14
+
 COPY requirements.txt .
-RUN pip3 install setuptools wheel && pip3 install -r requirements.txt
-RUN curl -O https://mimiker.ii.uni.wroc.pl/download/mipsel-mimiker-elf_latest_amd64.deb && \
-    dpkg -i mipsel-mimiker-elf_latest_amd64.deb && rm -f mipsel-mimiker-elf_latest_amd64.deb
-RUN curl -O https://mimiker.ii.uni.wroc.pl/download/aarch64-mimiker-elf_latest_amd64.deb && \
-    dpkg -i aarch64-mimiker-elf_latest_amd64.deb && rm -f aarch64-mimiker-elf_latest_amd64.deb
-RUN curl -O https://mimiker.ii.uni.wroc.pl/download/riscv32-mimiker-elf_latest_amd64.deb && \
-    dpkg -i riscv32-mimiker-elf_latest_amd64.deb && rm -f riscv32-mimiker-elf_latest_amd64.deb
-RUN curl -O https://mimiker.ii.uni.wroc.pl/download/riscv64-mimiker-elf_latest_amd64.deb && \
-    dpkg -i riscv64-mimiker-elf_latest_amd64.deb && rm -f riscv64-mimiker-elf_latest_amd64.deb
-RUN curl -O https://mimiker.ii.uni.wroc.pl/download/qemu-mimiker_latest_amd64.deb && \
-    dpkg -i qemu-mimiker_latest_amd64.deb && rm -f qemu-mimiker_latest_amd64.deb
+RUN pip3 install setuptools wheel && pip3 install -r requirements.txt && \
+  curl -O https://mimiker.ii.uni.wroc.pl/download/mipsel-mimiker-elf_latest_amd64.deb && \
+  curl -O https://mimiker.ii.uni.wroc.pl/download/aarch64-mimiker-elf_latest_amd64.deb && \
+  curl -O https://mimiker.ii.uni.wroc.pl/download/riscv32-mimiker-elf_latest_amd64.deb && \
+  curl -O https://mimiker.ii.uni.wroc.pl/download/riscv64-mimiker-elf_latest_amd64.deb && \
+  curl -O https://mimiker.ii.uni.wroc.pl/download/qemu-mimiker_latest_amd64.deb && \
+  apt-get install -y ./*.deb && rm -f *.deb

install-tools.sh

@@ -0,0 +1,89 @@
+#!/bin/bash
+nocolor='\033[0m'
+col_red='\033[0;31m'
+col_orange='\033[0;33m'
+col_blue='\033[0;34m'
+
+function fatal() {
+    echo -e "${col_red}ERROR${nocolor}: "$1
+    exit 1
+}
+
+function warn() {
+    echo -e "${col_orange}WARN${nocolor}: "$1
+}
+
+function info() {
+    echo -e "${col_blue}INFO${nocolor}: "$1
+}
+
+function ask() {
+    read -p "Do you want to proceed? (Y/n) " choice
+    case $choice in
+        [yY] ) return;;
+        [nN] ) echo exiting...;
+            exit 1;;
+        * ) echo invalid response. Assuming NO.;
+            exit 1;;
+    esac
+}
+
+# all checks before script is run
+[ "`id -u`" -eq 0 ] && fatal "You are running as root... it is not supported"
+[ -f /etc/apt/sources.list.d/llvm.list ] && warn 'You already have llvm sources.list. The script will override it.' && ask
+[ -f requirements.txt ] || fatal 'Python requirements not found. Are you in the Mimiker directory?'
+[ -f /usr/bin/apt ] || fatal '/usr/bin/apt is missing; is your distro debian based?'
+[ -f /usr/bin/sudo ] || fatal 'sudo is missing; (run `su -c "apt install sudo"`)'
+
+DEBS=packages.txt
+
+info "Install required packages"
+info "Upgrade privileges to root user"
+info "Install packages from base repository"
+
+sudo -u root sh -c "apt-get update -q && apt install $(< ${DEBS})"
+
+info "Drop privileges to $USER"
+
+read -p "Do you want to create python virtual env for Mimiker? (Y/n) " choice
+case $choice in
+    [yY] )
+        python3 -m venv mimiker-env
+        source mimiker-env/bin/activate
+        info "Python venv 'mimiker-env' created"
+        ;;
+esac
+
+info "Install python dependencies"
+pip3 install -r requirements.txt
+
+CODENAME=$(lsb_release -sc 2>/dev/null)
+
+if ! [ "$CODENAME" == "bullseye" ]; then
+    fatal "Your distribution '$CODENAME' is not supported"
+fi
+
+LLVM_VERSION=14
+DEBS_LLVM="clang-${LLVM_VERSION} clang-format-${LLVM_VERSION} llvm-${LLVM_VERSION} lld-${LLVM_VERSION}"
+
+info "Prepare sources.list for llvm && install llvm-${LLVM_VERSION}"
+LLVM_REPO="deb http://apt.llvm.org/${CODENAME}/ llvm-toolchain-${CODENAME}-${LLVM_VERSION} main"
+sudo -u root sh -c "apt-key adv --fetch-keys https://apt.llvm.org/llvm-snapshot.gpg.key && echo ${LLVM_REPO} > /etc/apt/sources.list.d/llvm.list && apt-get update -q && apt-get install ${DEBS_LLVM}"
+
+WORKDIR=$(mktemp -d)
+info "${WORKDIR} created"
+info "Download prebuild toolchain"
+
+curl -o $WORKDIR/mipsel-mimiker-elf_latest_amd64.deb https://mimiker.ii.uni.wroc.pl/download/mipsel-mimiker-elf_latest_amd64.deb
+curl -o $WORKDIR/aarch64-mimiker-elf_latest_amd64.deb https://mimiker.ii.uni.wroc.pl/download/aarch64-mimiker-elf_latest_amd64.deb
+curl -o $WORKDIR/riscv32-mimiker-elf_latest_amd64.deb https://mimiker.ii.uni.wroc.pl/download/riscv32-mimiker-elf_latest_amd64.deb
+curl -o $WORKDIR/riscv64-mimiker-elf_latest_amd64.deb https://mimiker.ii.uni.wroc.pl/download/riscv64-mimiker-elf_latest_amd64.deb
+curl -o $WORKDIR/qemu-mimiker_latest_amd64.deb https://mimiker.ii.uni.wroc.pl/download/qemu-mimiker_latest_amd64.deb
+
+info "Install toolchain"
+sudo -u root sh -c "apt-get install $WORKDIR/*.deb"
+
+info "Cleanup $WORKDIR"
+rm -r $WORKDIR
+
+exit 0

packages.txt

@@ -0,0 +1 @@
+git make ccache cpio curl gnupg universal-ctags cscope socat patch gperf quilt byacc python3 python3-pip python3-virtualenv device-tree-compiler tmux lsb-release

wiki/docs/building.md

@@ -22,4 +22,7 @@ they are run, add `VERBOSE=1` to the command line.
 **Important!** It's recommended to issue `make distclean` command after each
 modification to `config.mk` file.
 
+**Important!** Before building Mimker for different board you have to run
+`make distclean` with `BOARD` argument set to previous board.
+
 [1]: toolchain.md

wiki/docs/toolchain.md

@@ -1,30 +1,50 @@
 Toolchain
 ---
 
-To build Mimiker you will need a toolchain, i.e. compiler, linker, ELF tools and
-debugger. The default option is to choose quite recent _LLVM toolchain_ (check
-version in [tools.mk][6]), i.e. `clang`, `lld`, `llvm` from [apt.llvm.org][7],
-and [gdb-multiarch][8]. However you'll need to reconfigure [launch][9] script to
-use same `gdb-multiarch` binary for each target architecture, look for `gdb`
-section and find `binary` key. 
+To build and run Mimiker you will need a toolchain, i.e. compiler, linker, ELF
+tools, emulator and debugger. The default option is to choose quite recent
+_LLVM toolchain_ (check version in [tools.mk][6]), i.e. `clang`, `lld`, `llvm`
+from [apt.llvm.org][7] and [QEmu][11].
 
-You need to install patched version of [QEmu][11] as well. Our version solves
-several issues not patched in the mainstream version – please refer to our list
-of [patches][10]. Prebuild package for Debian x86-64 can be found [here][5].
+NOTE:
+If you plan to run Mimiker on MIPS you need to install patched version of QEmu
+as well. Our version solves several issues not patched in the mainstream version
+– please refer to our list of [patches][10]. Prebuild package for Debian x86-64
+can be found [here][5].
 
-The other (deprecated) method is to use a custom pre-build _GNU toolchain_,
-i.e. `gcc`, `binutils` and `gdb`. We prepared packages for Debian x86-64 based
-system, each for different target architecture: supports [MIPS][1],
-[AArch64][2], RISC-V [32-bit][3] and [64-bit][4].
+## Requiremnts
+You can find all needed software in a [Dockerfile][12]. There is also a script
+[install-tools.sh][13] that will automatically install all needed software on
+Debian system.
+
+You also need to install python requirements. E.g. with command:
+```
+pip3 install -r requirements.txt
+```
+
+#### A comment about dependencies from Dockerfile
+```
+# patch & quilt required by lua and programs in contrib/
+# gperf required by libterminfo
+# socat & tmux required by launch
+```
+
+## Deprecated toolchain
+The other method is to use a custom pre-build _GNU toolchain_, i.e. `gcc`,
+`binutils` and `gdb`. We prepared packages for Debian x86-64 based system, each
+for different target architecture: supports [MIPS][1], [AArch64][2],
+RISC-V [32-bit][3] and [64-bit][4].
 
 [1]: http://mimiker.ii.uni.wroc.pl/download/mipsel-mimiker-elf_latest_amd64.deb
 [2]: http://mimiker.ii.uni.wroc.pl/download/aarch64-mimiker-elf_latest_amd64.deb
 [3]: http://mimiker.ii.uni.wroc.pl/download/riscv32-mimiker-elf_latest_amd64.deb
 [4]: http://mimiker.ii.uni.wroc.pl/download/riscv64-mimiker-elf_latest_amd64.deb
 [5]: http://mimiker.ii.uni.wroc.pl/download/qemu-mimiker_latest_amd64.deb
-[6]: build/tools.mk
+[6]: ../blob/master/build/tools.mk
 [7]: https://apt.llvm.org/
 [8]: https://packages.debian.org/sid/gdb-multiarch
-[9]: launch#L50
-[10]: toolchain/qemu-mimiker/patches
+[9]: ../blob/master/launch
+[10]: ../blob/master/toolchain/qemu-mimiker/patches
 [11]: https://www.qemu.org/
+[12]: ../blob/master/Dockerfile
+[14]: ../blob/master/install-tools.sh