Update Contributing docs

docs/contributing/building/building.md

@@ -32,23 +32,13 @@
 
 3. **Clone** [tracee repository](https://github.com/aquasecurity/tracee/)
 
-    ```console
-    git clone [email protected]:aquasecurity/tracee
-    ```
-
-    ```text
-    Cloning into 'tracee'...
-    remote: Enumerating objects: 13251, done.
-    remote: Counting objects: 100% (555/555), done.
-    remote: Compressing objects: 100% (240/240), done.
-    remote: Total 13251 (delta 343), reused 369 (delta 280), pack-reused 12696
-    Receiving objects: 100% (13251/13251), 11.75 MiB | 8.62 MiB/s, done.
-    Resolving deltas: 100% (8105/8105), done.
+    ```bash
+    git clone [https://github.com/aquasecurity/tracee/](https://github.com/aquasecurity/tracee/)
     ```
 
 4. All makefiles have a **help** target to give you needed instructions
 
-    ```console
+    ```bash
     make help
     ```
 
@@ -95,61 +85,22 @@
 
 5. Build **all** targets at once
 
-    ```console
+    ```bash
     make all
     ```
 
-    ```text
-    Submodule 'libbpf' (https://github.com/libbpf/libbpf.git) registered for path '3rdparty/libbpf'
-    Cloning into '/home/rafaeldtinoco/tracee/3rdparty/libbpf'...
-    mkdir -p dist/signatures
-    GOOS=linux CC=clang GOARCH=amd64 CGO_CFLAGS= CGO_LDFLAGS= go build \
-        --buildmode=plugin \
-        -o dist/signatures/builtin.so \
-        signatures/golang/export.go signatures/golang/kubernetes_api_connection.go signatures/golang/stdio_over_socket.go
-    ```
-
 6. Build a **static binary** by setting `STATIC=1`
 
-    ```console
+    ```bash
     STATIC=1 make all
     ```
 
-    ```text
-    CC="clang" \
-        CFLAGS=""-fPIC"" \
-        LD_FLAGS="" \
-        make \
-        -C ./3rdparty/libbpf/src \
-        BUILD_STATIC_ONLY=1 \
-        DESTDIR=/home/rafaeldtinoco/tracee/dist/libbpf \
-        OBJDIR=/home/rafaeldtinoco/tracee/dist/libbpf/obj \
-        INCLUDEDIR= LIBDIR= UAPIDIR= prefix= libdir= \
-        install install_uapi_headers
-    ...
-    ```
-
 7. Build a **static binary** with [BTFHUB Support](https://github.com/aquasecurity/btfhub)
 
-    ```console
+    ```bash
     BTFHUB=1 STATIC=1 make all
     ```
 
-    ```text
-    Cloning into '/home/rafaeldtinoco/tracee/3rdparty/btfhub'...
-    remote: Enumerating objects: 205, done.
-    remote: Counting objects: 100% (16/16), done.
-    remote: Compressing objects: 100% (12/12), done.
-    remote: Total 205 (delta 4), reused 10 (delta 3), pack-reused 189
-    Receiving objects: 100% (205/205), 10.59 MiB | 7.56 MiB/s, done.
-    Resolving deltas: 100% (73/73), done.
-    Cloning into '/home/rafaeldtinoco/tracee/3rdparty/btfhub-archive'...
-    remote: Enumerating objects: 1993, done.
-    remote: Counting objects: 100% (28/28), done.
-    remote: Compressing objects: 100% (23/23), done.
-    Receiving objects:  15% (301/1993), 154.97 MiB | 15.72 MiB/s
-    ```
-
     !!! Note
         BTFHUB support will embed several very small files (BTF files) into your
         final binary. Those files will allow **tracee** binary to be executed
@@ -166,17 +117,6 @@
 
 8. Build a **debugable binary** with DWARF generation by setting `DEBUG=1`
 
-    ```console
+    ```bash
     DEBUG=1 make
     ```
-
-    ```text
-    GOOS=linux CC=clang GOARCH=amd64 CGO_CFLAGS="-I/home/gg/code/tracee/dist/libbpf" CGO_LDFLAGS="-lelf  -lz  /home/gg/code/tracee/dist/libbpf/libbpf.a" go build \
-        -tags core,ebpf \
-        -ldflags=" \
-             -extldflags \"\" \
-             -X main.version=\"v0.8.0-107-g121efeb\" \
-            " \
-        -v -o dist/tracee \
-       ./cmd/tracee
-    ```

docs/contributing/building/environment.md

@@ -14,72 +14,44 @@
     If you want to build tracee on your local machine
     [read this](./building.md).
 
+## Quick steps
 
-## Quick steps (**impatient readers**)
+1. Build tracee environment:
 
-!!! Example
-
-    * Build and execute **tracee**:
-
-        ```console
-        make -f builder/Makefile.tracee-make alpine-prepare
-        make -f builder/Makefile.tracee-make alpine-shell
-        ```
-
-        and inside the container:
-
-        ```console
-        make clean
-        make tracee
-        sudo ./dist/tracee \
-            -o option:parse-arguments \
-            --scope comm=bash \
-            --scope follow
-        ```
-
-    Now, in your host's bash shell, execute a command. You will see all events
-    (except scheduler ones) being printed, in "table format", to stdout.
-
-    * Build and execute **tracee**:
-
-        ```console
-        make -f builder/Makefile.tracee-make alpine-prepare
-        make -f builder/Makefile.tracee-make alpine-shell
-        ```
+    ```bash
+    make -f builder/Makefile.tracee-make alpine-prepare
+    make -f builder/Makefile.tracee-make alpine-shell
+    ```
 
-        and inside the container:
+2. Build and execute tracee:
 
-        ```console
-        make clean
-        make all
-        sudo ./dist/tracee \
-            -o format:json \
-            -o option:parse-arguments \
-            --scope comm=bash \
-            --scope follow 
-        ```
-
-    Now, in your host's bash shell, execute: `sudo strace /bin/ls` and observe
-    tracee warning you about a possible risk (with its Anti-Debugging signature).
+    ```bash
+    make clean
+    make tracee
+    sudo ./dist/tracee \
+        -o option:parse-arguments \
+        --scope comm=bash \
+        --scope follow
+    ```
 
-Now, for **more patient readers** ...
+Now, in your host's bash shell, execute a command. You will see all events
+(except scheduler ones) being printed, in "table format", to stdout.
 
 ## How to build and use the environment
 
 In order to have a controlled building environment for tracee, tracee provides
-a `Makefile.tracee-make` file that allows you to create and use a docker
-container environment to build & test **tracee**. 
+a `Makefile.tracee-make` file that allows you to create and use a docker container environment to build & test **tracee**.
+
+There are Two different environments that are maintained for building tracee:
 
-Two different environments are maintained for building tracee:
+* **Alpine**
+* **Ubuntu**
 
-* Alpine
-* Ubuntu
+The reason for that is that **Alpine Linux** is based in the [musl](https://en.wikipedia.org/wiki/Musl) C standard library.
 
-The reason for that is that **Alpine Linux** is based in the
-[musl](https://en.wikipedia.org/wiki/Musl) C standard library, while the
-**Ubuntu Linux** uses [glibc](https://en.wikipedia.org/wiki/Glibc). By
-supporting both building environments we can always be sure that the project
-builds (and executes) correctly in both environments.
+while the **Ubuntu Linux** uses [glibc](https://en.wikipedia.org/wiki/Glibc).
+
+By supporting both building environments we can always be sure that the project builds (and executes) correctly in both environments.
 
 !!! Attention
     Locally created containers, called `alpine-tracee-make` or
@@ -91,81 +63,94 @@ builds (and executes) correctly in both environments.
 
 * To create an **alpine-tracee-make** container:
 
-    ```console
+    ```bash
     make -f builder/Makefile.tracee-make alpine-prepare
     ```
 
 * To create an **ubuntu-tracee-make** container:
 
-    ```console
+    ```bash
     make -f builder/Makefile.tracee-make ubuntu-prepare
     ```
 
 ### Executing a builder environment
 
 * To execute an **alpine-tracee-make** shell:
 
-    ```console
+    ```bash
     make -f builder/Makefile.tracee-make alpine-shell
     ```
 
 * To execute an **ubuntu-tracee-make** shell:
 
-    ```console
+    ```bash
     make -f builder/Makefile.tracee-make ubuntu-shell
     ```
 
 ### Using build environment as a **make** replacement
 
-Instead of executing a builder shell, you may use `alpine-tracee-make`, or
-`ubuntu-tracee-make`, as a replacement for the `make` command:
+Instead of executing a builder shell, you may use `alpine-make`, or
+`ubuntu-make`, as a replacement for the `make` command:
 
-```console
-make -f builder/Makefile.tracee-make ubuntu-prepare
-make -f builder/Makefile.tracee-make ubuntu-make ARG="help"
-make -f builder/Makefile.tracee-make ubuntu-make ARG="clean"
-make -f builder/Makefile.tracee-make ubuntu-make ARG="bpf"
-make -f builder/Makefile.tracee-make ubuntu-make ARG="tracee"
-make -f builder/Makefile.tracee-make ubuntu-make ARG="all"
-```
+1. Create builder environment as described:
+    [Creating a builder environment](#creating-a-builder-environment)
+2. Compile tracee using `ubuntu-make`
 
-And, after the compilation, run the commands directly in your host:
+    * Build tracee binary:
 
-```console
-sudo ./dist/tracee \
-    -o option:parse-arguments \
-    --scope comm=bash \
-    --scope follow
-```
+        ```bash
+        make -f builder/Makefile.tracee-make ubuntu-make ARG="tracee"
+        ```
 
-> **Note**: the generated binary must be compatible to your host (depending on
-> glibc version, for example).
+    * Show help for make file:
 
-If you don't want to depend on host's libraries versions, or if you are using
-the `alpine-tracee-make` container as a replacement for `make`, and your host
-is not an **Alpine Linux**, then you may set `STATIC=1` variable so you can run
-compiled binaries in your host:
+        ```bash
+        make -f builder/Makefile.tracee-make ubuntu-make ARG="help"
+        ```
 
-```console
-make -f builder/Makefile.tracee-make alpine-prepare
-make -f builder/Makefile.tracee-make alpine-make ARG="help"
-STATIC=1 make -f builder/Makefile.tracee-make alpine-make ARG="all"
-```
+    * Remove tracee binary
 
-and execute the static binary from your host:
+        ```bash
+        make -f builder/Makefile.tracee-make ubuntu-make ARG="clean"
+        ```
 
-```console
-ldd dist/tracee
-```
+    * Build binaries for all
 
-```text
-not a dynamic executable
-```
+        ```bash
+        make -f builder/Makefile.tracee-make ubuntu-make ARG="all"
+        ```
 
-!!! Attention
-    compiling **tracee-rules** with STATIC=1 won't allow you to use golang based
-    signatures:
-    > ```text
-    > 2021/12/13 13:27:21 error opening plugin /tracee/dist/signatures/builtin.so:
-    > plugin.Open("/tracee/dist/signatures/builtin.so"): Dynamic loading not supported
-    > ```
+3. Run tracee binary
+
+    ```bash
+    sudo ./dist/tracee
+    ```
+
+> **Note**: the generated binary must be compatible to your host (depending on glibc version).
+
+If you don't want to depend on host's libraries versions, or your host is not an **Alpine Linux** or you are using the `alpine-make` container as a replacement for `make`, then it's necessary  to set `STATIC` variable to `1` so you can run compiled binaries in your host machine:
+
+1. Compile tracee
+
+    ```bash
+    make -f builder/Makefile.tracee-make alpine-prepare
+    STATIC=1 make -f builder/Makefile.tracee-make alpine-make ARG="all"
+    ```
+
+2. Verify the executable is static
+
+    * Note: ldd print the shared libraries required by an executable file
+
+    ```bash
+    ldd dist/tracee
+    ```
+
+    ```text
+    not a dynamic executable
+    ```
+
+3. Execute the static binary from your host
+
+    ```bash
+    sudo ./dist/tracee
+    ```