Generate docs for libs, update docs build process

.gitea/workflows/docs.yaml

@@ -15,7 +15,7 @@ jobs:
       - name: Install software
         run: |
           sudo apt-get update
-          sudo apt-get install -y doxygen make rsync
+          sudo apt-get install -y doxygen make rsync clang clang-tools
 
       - name: Set up python3
         uses: actions/setup-python@v5
@@ -28,7 +28,7 @@ jobs:
           pip install mkdocs mkdocs-material pymdown-extensions
 
       - name: Build
-        run: make docs
+        run: ./aux/docs.sh
 
       - name: Deploy
         env:

Makefile

@@ -3,7 +3,6 @@ platform ?= amd64
 include make/apps.mk
 include make/kernel.mk
 include make/dist.mk
-include make/docs.mk
 include make/libmsl.mk
 include make/liballoc.mk
 include make/libterminal.mk

aux/compiledb.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+set -x
+
+make -B all_compiledb_kernel
+make -B all_compiledb_liballoc
+make -B all_compiledb_libmsl
+make -B all_compiledb_libprocess
+make -B all_compiledb_libterminal
+make -B all_compiledb_libstring

aux/docs.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+
+set -x
+
+./aux/compiledb.sh
+
+make -B docs_liballoc
+make -B docs_libmsl
+make -B docs_libprocess
+make -B docs_libstring
+make -B docs_libterminal
+
+mkdocs build

docs/building_kernel.md

@@ -14,31 +14,18 @@ This article describes, how to build the kernel, how the build system works and
 
 cd into root of MOP3 source tree.
 
-Build the kernel:
+Run:
 ```
-make -B all_kernel buildtype=<debug|release>
+./aux/devel.sh
 ```
 
-Build essential system applications:
+This script does everything for you - builds the kernel, userspace apps, necessary libraries and such.
+The buildsystem is quite compilcated, so it probably requires it's own article.
+
+For debugging you can do:
 ```
-make -B all_apps
+./aux/devel.sh debug
 ```
 
-Prepare the ramdisk:
+This will build with `buildtype=debug` as opposed to `buildtype=release`. You now can view symbols inside
-```
+of gdb or objdump.
-make -B all_dist
-```
-
-Build ISO image:
-```
-./aux/limine_iso_amd64.sh
-```
-
-Now you have an ISO image, which can be run my QEMU or you can burn it onto a CD.
-
-For the convenience of the developer, there's a magic "do all" script located in `aux`:
-```
-./aux/devel.sh # optionally "./aux/devel.sh debug" for debugging
-```
-
-It does all the previous steps, just packed into a single script.

docs/processes_overview.md

@@ -2,24 +2,15 @@
 
 ## What is a process?
 
-A process is a structure defined to represent an internal state of a user application's environment. This includes
+A process represents a piece of executing code, has it's own stack and CPU state. Think of it as a "task". There are no
-the necessary stacks, code, data and other resources. A process (usually) has it's own address, but in certain
+kernel processes, only userspace processes.
-circumstances may share it with another process.
 
-## Only processes vs. processes-threads model
+A process must be a member of a broader process group or procgroup for short.
 
-### Overview
+## Procgroups
 
-MOP3 doesn't have a process-thread separation. Ususally in operating systems you'd have a "process", which consists
+A procgroup owns things like memory, kernel resources and such. Processes work within the scope of a procgroup. Once all
-of multiple worker threads. For eg. a single-threaded application is a process, which consists of one worker. In MOP3
+procgroup's members die, the procgroup is considered unreachable and thus cleaned up.
-we do things a little differently. We only have processes, but some processes may work within the same pool of (generally speaking)
-"resources", such as a shared address space, shared memory allocations, mutexes and so on. An application then consists of
-not threads, but processes, which are loosely tied together via shared data.
-
-#### Processes-threads model diagram
-![Processes-threads model](assets/images/processes-threads.png)
-#### Only processes model diagram
-![Only processes model](assets/images/only-processes.png)
 
 ## Scheduling
 

init/init.c

@@ -18,7 +18,10 @@ void app_proc (void) {
     mutex_lock (MUTEX);
 
     for (int i = 0; i < 3; i++)
-      test (letter);
+      terminal_print (&letter, 1);
+
+    for (volatile int i = 0; i < 1000*1000; i++)
+      ;
 
     mutex_unlock (MUTEX);
   }
@@ -38,10 +41,11 @@ void app_main (void) {
   for (;;) {
     mutex_lock (MUTEX);
 
-    for (int i = 0; i < 3; i++) {
+    for (int i = 0; i < 3; i++)
-      terminal_print ("hello\n", 6);
+      terminal_print (&letter, 1);
-    }
+    
-    /* test (letter); */
+    for (volatile int i = 0; i < 1000*1000; i++)
+      ;
 
     mutex_unlock (MUTEX);
   }

liballoc/.gitignore

@@ -1 +1,3 @@
 *.o
+*.json
+docs/

liballoc/Makefile

@@ -25,4 +25,9 @@ clean:
 format:
 	clang-format -i $$(git ls-files '*.c' '*.h')
 
+docs:
+	clang-doc --format=md --output docs -p . $$(git ls-files '*.h')
+	mkdir -p ../docs/libs/liballoc
+	cp ./docs/GlobalNamespace/*.md ../docs/libs/liballoc
+
 .PHONY: all clean format

libmsl/.gitignore

@@ -0,0 +1,2 @@
+*.json
+docs/

libmsl/Makefile

@@ -25,4 +25,9 @@ clean:
 format:
 	clang-format -i $$(git ls-files '*.c' '*.h')
 
+docs:
+	clang-doc --format=md --output docs -p . $$(git ls-files '*.h')
+	mkdir -p ../docs/libs/libmsl
+	cp ./docs/GlobalNamespace/*.md ../docs/libs/libmsl
+
 .PHONY: all clean format

libprocess/.gitignore

@@ -1 +1,3 @@
 *.o
+*.json
+docs/

libprocess/Makefile

@@ -25,4 +25,9 @@ clean:
 format:
 	clang-format -i $$(git ls-files '*.c' '*.h')
 
+docs:
+	clang-doc --format=md --output docs -p . $$(git ls-files '*.h')
+	mkdir -p ../docs/libs/libprocess
+	cp ./docs/GlobalNamespace/*.md ../docs/libs/libprocess
+
 .PHONY: all clean format

libstring/.gitignore

@@ -1 +1,3 @@
 *.o
+*.json
+docs/

libstring/Makefile

@@ -25,4 +25,9 @@ clean:
 format:
 	clang-format -i $$(git ls-files '*.c' '*.h')
 
+docs:
+	clang-doc --format=md --output docs -p . $$(git ls-files '*.h')
+	mkdir -o ../docs/libs/libstring
+	cp ./docs/GlobalNamespace/*.md ../docs/libs/libstring
+
 .PHONY: all clean format

libterminal/.gitignore

@@ -1 +1,3 @@
 *.o
+*.json
+docs/

libterminal/Makefile

@@ -25,4 +25,9 @@ clean:
 format:
 	clang-format -i $$(git ls-files '*.c' '*.h')
 
+docs:
+	clang-doc --format=md --output docs -p . $$(git ls-files '*.h')
+	mkdir -p ../docs/libs/libterminal
+	cp ./docs/GlobalNamespace/*.md ../docs/libs/libterminal
+
 .PHONY: all clean format

make/docs.mk

@@ -1,4 +0,0 @@
-docs:
-	mkdocs build
-
-.PHONY: docs

make/liballoc.mk

@@ -1,10 +1,16 @@
 all_liballoc:
 	make -C liballoc platform=$(platform) all
 
+all_compiledb_liballoc:
+	bear --output liballoc/compile_commands.json -- make -C liballoc platform=$(platform) all
+
 clean_liballoc:
 	make -C liballoc platform=$(platform) clean
 
 format_liballoc:
 	make -C liballoc platform=$(platform) format
 
-.PHONY: all_liballoc clean_liballoc format_liballoc
+docs_liballoc:
+	make -C liballoc platform=$(platform) docs
+
+.PHONY: all_liballoc clean_liballoc format_liballoc docs_liballoc

make/libmsl.mk

@@ -1,10 +1,16 @@
 all_libmsl:
 	make -C libmsl platform=$(platform) all
 
+all_compiledb_libmsl:
+	bear --output libmsl/compile_commands.json -- make -C libmsl platform=$(platform) all
+
 clean_libmsl:
 	make -C libmsl platform=$(platform) clean
 
 format_libmsl:
 	make -C libmsl platform=$(platform) format
 
-.PHONY: all_libmsl clean_libmsl format_libmsl
+docs_libmsl:
+	make -C libmsl platform=$(platform) docs
+
+.PHONY: all_libmsl clean_libmsl format_libmsl docs_libmsl

make/libprocess.mk

@@ -1,10 +1,16 @@
 all_libprocess:
 	make -C libprocess platform=$(platform) all
 
+all_compiledb_libprocess:
+	bear --output libprocess/compile_commands.json -- make -C libprocess platform=$(platform) all
+
 clean_libprocess:
 	make -C libprocess platform=$(platform) clean
 
 format_libprocess:
 	make -C libprocess platform=$(platform) format
 
-.PHONY: all_libprocess clean_libprocess format_libprocess
+docs_libprocess:
+	make -C libprocess platform=$(platform) docs
+
+.PHONY: all_libprocess clean_libprocess format_libprocess docs_libprocess

make/libstring.mk

@@ -1,10 +1,16 @@
 all_libstring:
 	make -C libstring platform=$(platform) all
 
+all_compiledb_libstring:
+	bear --output libstring/compile_commands.json -- make -C libstring platform=$(platform) all
+
 clean_libstring:
 	make -C libstring platform=$(platform) clean
 
 format_libstring:
 	make -C libstring platform=$(platform) format
 
-.PHONY: all_libstring clean_libstring format_libstring
+docs_libstring:
+	make -C libstring platform=$(platform) docs
+
+.PHONY: all_libstring clean_libstring format_libstring docs_libstring

make/libterminal.mk

@@ -1,10 +1,16 @@
 all_libterminal:
 	make -C libterminal platform=$(platform) all
 
+all_compiledb_libterminal:
+	bear --output libterminal/compile_commands.json -- make -C libterminal platform=$(platform) all
+
 clean_libterminal:
 	make -C libterminal platform=$(platform) clean
 
 format_libterminal:
 	make -C libterminal platform=$(platform) format
 
-.PHONY: all_libterminal clean_libterminal format_libterminal
+docs_libterminal:
+	make -C libterminal platform=$(platform) docs
+
+.PHONY: all_libterminal clean_libterminal format_libterminal docs_libterminal