Skyward-Build-System-(SBS).md

 SBS (*Skyward Build System*) is the build system that is used to compile boardcore's entrypoints, which are written for Miosix and need to be executed on a specific target board. It permits to group useful drivers in library and reuse the same group of files for different entrypoints.
 
-### How it Works
-Normally, to compile code made with Miosix for a specific board you would have to comment some lines in miosix/config and then execute `make` (see the [Miosix Guide](https://miosix.org/wiki/index.php?title=Quick_start)). 
-<br/>Since Boardcore uses a modified version of Miosix, a custom config/ folder was created without a specified target board in it.
+## Usage
 
-What SBS does is that it creates a Makefile for each entrypoint starting from the `Makefile.template`. The placeholders that are there are substituted with the values defined in `sbs.conf`, then the Makefile is moved to build/ and executes it.
+**Building**
+
+SBS's standard usage is building a board's firmware, which can be done with:
+```sh
+./sbs -b *boardname*
+```
 
-### Project Configuration
+You can also use the `-v` option (verbose). If you omit the  `-b` option all entrypoints will be compiled.
+
+**Other options**
+
+Prompting `./sbs --help` will print the options menu.
+
+## SBS.conf sections
+
+#### Project Configuration
 
 Whenever it is executed, SBS looks for a `sbs.conf` file in the current folder to know how to compile each entrypoint. The current folder could be the boardcore repository as well as another project which includes boardcore. For this reason, we have to define a `[PROJECT_CONF]` section with the following information, that will be valid for all entrypoints listed in the file:
 
-```
+```conf
 ENTRY_PATH:       entrypoints folder relative path, e.g. src/entrypoints
 TESTS_PATH:       tests folder relative path, e.g. src/tests
 SRC_PATH:         shared sources folder relative path, e.g. src/shared
@@ -20,22 +31,22 @@ PROJECT_SUBDIRS:  Optional subfolders which contains additional makefiles (eg: l
 PROJECT_LIBS:     Optional static libraries. (eg: libs/mxgui/mxgui.a)
 ```
 
-### SrcFiles
+#### SrcFiles
 
 The *srcfiles* are used for grouping together sources that refer to a common device/purpose,
 so that they can be referred to when building entrypoints by simply using `%name`. Note that SBS first imports the srcfiles from the sbs.conf inside the boardcore's folder, and then it will include any other srcfiles that are defined in higher level sbs.conf files.
 
-```
+```conf
 [name]
      Type: srcfiles
      Files: a '\n'-separated list of files
 ```
 
-### Boards and Tests
+#### Boards and Tests
 
 Sections of type `board` and `test` define how to compile the entrypoints.
 
-```
+```conf
  board:
      BoardId: which board to compile for
      BinName: name of the final binary (without extension!)
@@ -51,39 +62,101 @@ Sections of type `board` and `test` define how to compile the entrypoints.
      Main:    name of the main file (e.g. 'foo' -> TEST_PATH/foo.cpp)
 ```
 
-For example
 
-```
-#srcfiles
+## How it Works
+Normally, to compile code made with Miosix for a specific board you would have to comment some lines in miosix/config and then execute `make` (see the [Miosix Guide](https://miosix.org/wiki/index.php?title=Quick_start)). 
+<br/>Since Boardcore uses a modified version of Miosix, a custom config/ folder was created without a specified target board in it.
+
+What SBS does is that it creates a Makefile for each entrypoint starting from the `Makefile.template`. The placeholders that are there are substituted with the values defined in `sbs.conf`, then the Makefile is moved to build/ and executes it.
 
-[canbus]
-Type:       srcfiles
-Files:      src/shared/drivers/canbus/CanManager.cpp 
-            src/shared/drivers/canbus/CanBus.cpp 
-            src/shared/drivers/canbus/CanSocket.cpp 
-            src/shared/drivers/canbus/CanInterrupt.cpp 
+#### Standard MIOSIX build
 
-#boards
+- **Makefile**: main Makefile, used to compile the *main.cpp*. Lists the files to compile (`SRC:=`), the libraries to include (`INCLUDE:=`) and the directories to include (`INCLUDE_DIRS:=`).
+- **miosix/Makefile**: Makefile for the kernel sources.
+- **miosix/config/Makefile.inc**: specifies compiler flags, the target board and all board-specific configurations (Clock speed, linker script location, XRAM etc...).
 
-[discovery-canbus-test]
-Type:       board
-BoardId:    stm32f429zi_stm32f4discovery
-BinName:    discovery-canbus-test
-Include:    %canbus %shared
-Defines:    
-Main:       canbus-test
+```mermaid
+graph TD;
 
-```
+subgraph miosix-kernel
+Makefile -- execute --> miosixMakefile
+Makefile -- include --> configMakefile.inc
 
-### Building
+subgraph miosix
+miosixMakefile[Makefile]
 
-SBS's standard usage is building a board's firmware, which can be done with:
+subgraph config
+configMakefile.inc[Makefile.inc]
+end
+
+end
+
+end
 ```
-./sbs -b *boardname*
+
+**Build Sequence**
+
+1. Choose target board modifying Makefile.inc
+2. Choose sources, defines and includes modifying Makefile
+3. Compile with `make` from the main folder
+
+#### SBS Build
+
+The SBS build works as follows: from your project folder, you execute  `python3 <BOARDCORE_FOLDER>/sbs` (e.g. using a script). SBS will then search for an sbs.conf in the directory from which it has been executed. From there, it will get the paths and configurations for all the entrypoints, importing the srcfiles also from the boardcore/sbs.conf (to reuse source groups that come from boardcore). Then, for each entrypoint, it fills in the Makefile.template creating a standard MIOSIX Makefile for each entrypoint. Each Makefile is then executed to compile a binary.
+
+```mermaid
+graph TD;
+
+subgraph "Project Folder"
+sbs.sh
+sbs.conf
+subgraph "build"
+buildBOARD1[BOARD1]
+buildBOARD2[BOARD2]
+build...[...]
+end
+subgraph "bin"
+binBOARD1[BOARD1.bin]
+binBOARD2[BOARD2.bin]
+bin...[...]
+end
+end
+
+sbs.sh -- 1. execute --> boardcoresbs.py
+boardcoresbs.py -- 2. read --> sbs.conf
+boardcoresbs.py -- 3. import srcfiles --> boardcoresbs.conf
+boardcoresbs.py -- 4. read template --> Makefile.template
+Makefile.template -- 5. create makefile --> buildBOARD1
+buildBOARD1 -- 6. make --> binBOARD1
+Makefile.template -- 5. create makefile --> buildBOARD2
+buildBOARD2 -- 6. make --> binBOARD2
+
+subgraph "skyward-boardcore"
+boardcoresbs.conf[sbs.conf]
+boardcoresbs.py[sbs]
+Makefile.template
+end
 ```
 
-You can also use the `-v` option (verbose). If you omit the  `-b` option all entrypoints will be compiled.
+## Making a new SBS project
+
+*Make a new project that includes SBS*
+
+1. include skyward-boardcore as submodule of your project.
+
+2. create a `sbs.conf` in your project directory, specifying where is the boardcore submodule (e.g. libs/skyward-boardcore) and where are the sources (shared, entrypoints and tests).
 
-### Other options
+3. a typical file structure is
 
-Prompting `./sbs --help` will print the options menu.
\ No newline at end of file
+   ```
+   YourProject/
+    |_ src/
+    |   |_ shared/
+    |   |_ entrypoints/
+    |   |_ tests/
+    |_ libs/
+    |   |_ boardcore/
+    |_ sbs.conf
+    |_ bin/      <-- binaries will be generated here
+    |_ build/    <-- Makefiles will be generated here
+   ```
\ No newline at end of file