Merge pull request #3 from shikaan/readme

feat: add a new readme with all associated resources

Author: shikaan

Makefile

@@ -2,38 +2,24 @@
 AS:=nasm
 ASFLAGS:=-f bin
 
+%.bin: %.s
+	sdk/build $<
+
 .PHONY: osle_test
 osle_test: osle fixtures/text.txt.bin test/fs.test.bin
-	dd if=/dev/zero of=osle.img bs=512 count=2880
-	dd if=osle.o of=osle.img bs=512 count=1 conv=notrunc
-	dd if=bin/snake.bin of=osle.img bs=512 seek=36 conv=notrunc
-	dd if=test/fs.test.bin of=osle.img bs=512 seek=72 conv=notrunc
-	dd if=fixtures/text.txt.bin of=osle.img bs=512 seek=108 conv=notrunc
-	dd if=bin/ed.bin of=osle.img bs=512 seek=144 conv=notrunc
-	dd if=bin/more.bin of=osle.img bs=512 seek=180 conv=notrunc
-	dd if=bin/rm.bin of=osle.img bs=512 seek=216 conv=notrunc
-	dd if=bin/mv.bin of=osle.img bs=512 seek=252 conv=notrunc
-	dd if=bin/help.bin of=osle.img bs=512 seek=288 conv=notrunc
+	sdk/pack test/fs.test.bin
+	sdk/pack fixtures/text.txt.bin
 
 .PHONY: osle
 osle: osle.o bin/snake.bin bin/ed.bin bin/more.bin bin/rm.bin bin/mv.bin bin/help.bin
 	dd if=/dev/zero of=osle.img bs=512 count=2880
 	dd if=osle.o of=osle.img bs=512 count=1 conv=notrunc
-	dd if=bin/snake.bin of=osle.img bs=512 seek=36 conv=notrunc
-	dd if=bin/ed.bin of=osle.img bs=512 seek=72 conv=notrunc
-	dd if=bin/more.bin of=osle.img bs=512 seek=108 conv=notrunc
-	dd if=bin/rm.bin of=osle.img bs=512 seek=144 conv=notrunc
-	dd if=bin/mv.bin of=osle.img bs=512 seek=180 conv=notrunc
-	dd if=bin/help.bin of=osle.img bs=512 seek=216 conv=notrunc
-
-%.bin: %.s
-	$(AS) $(ASFLAGS) -o $*.o $<
-	@filename=$(shell basename $@ .bin | cut -c -22) && \
-	(	printf "$$filename" | dd bs=22 conv=sync of=header.bin 2>/dev/null && \
-		filesize=$$(stat -c %s "$*.o" 2>/dev/null || stat -f %z "$*.o") && \
-		perl -e 'print pack("v", '$$filesize');' >> header.bin )
-	cat header.bin $*.o > $@
-	rm -f header.bin $*.o
+	sdk/pack bin/snake.bin
+	sdk/pack bin/ed.bin
+	sdk/pack bin/more.bin
+	sdk/pack bin/rm.bin
+	sdk/pack bin/mv.bin
+	sdk/pack bin/help.bin
 
 .PHONY: start
 start: osle

README.md

@@ -1,57 +1,122 @@
-OSle
----
+<p align="center">
+  <img width="256" src="./docs/logo.svg" alt="logo">
+</p>
 
-OSle is a tiny OS that can be run on x86 hardware.
+<p align="center">
+A tiny and mighty bootloader OS.
+</p>
 
-## tl;dr
 
-* tiny real-mode OS in 16 bits x86 assembly;
-* written as a bootloader. It's only 510 bytes in total;
-* has a shell, a file system, and process management;
-* runs [`userland software`](./bin/);
-* comes with an [SDK to write your own OSle software](./sdk/);
+<h4 align="center">
+  <a href="https://shikaan.github.io/OSle/">🚀 Try it out in the browser! 🚀</a>
+</h4>
 
-## Dependencies
 
-* [GNU make](https://www.gnu.org/software/make/)
-* [nasm](https://www.nasm.us)
-* [bochs](https://bochs.sourceforge.io)
+## 👀 Overview
 
-### MacOS
+OSle is a [real-mode](https://wiki.osdev.org/Real_Mode) OS that fits in a 
+bootloader. 
 
-Using Homebrew
+It's written in x86 assembly and, despite its tiny size (only 510 bytes), it 
+packs essential features like:
+
+- **Shell**: Run commands and builtins.
+- **File System**: Read, write, and find files on the system.
+- **Process Management**: Cooperatively spawn child processes.
+- **Userland Software**: Comes with [pre-built software](./bin/) and an 
+[SDK](./sdk/) to write your own.
+
+[Check out the online demo](https://shikaan.github.io/OSle) to see it in action.
+
+## 📚 Creating your first OSle program
+
+OSle includes a tiny [Software Development Kit (SDK)](./sdk/) that includes
+definitions and a toolchain to create your own OSle programs.
+
+Follow the [step-by-step tutorial](./tutorial/) to write your first program!
+
+## 🛠️ Development
+
+To develop OSle and OSle programs you will need the following tools:
+
+- [nasm](https://www.nasm.us)
+- [GNU make](https://www.gnu.org/software/make/) (usually preinstalled)
+- [bochs](https://bochs.sourceforge.io) (optional)
+
+<details>
+<summary>Installation instructions</summary>
+
+#### macOS
+
+Install dependencies using Homebrew:
 
 ```sh
 brew install nasm
 brew install bochs
 ```
 
-### Linux 
+#### Linux
 
-Using your local package manager, for example in Debian
+Install dependencies using your local package manager, e.g., on Debian:
 
 ```sh
 apt install nasm bochs
 ```
+</details>
 
-Please refer to the respective packages pages should you experience any problem.
+### Build and Run OSle locally
 
-## Run locally
+These recipes will compile OSle and use the [SDK](./sdk/) to compile and bundle
+all the pre-built programs. Using `start` will also run bochs right away.
 
 ```sh
+# build and run osle on bochs
 make start
+
+# or
+
+# build osle
+make osle
+# use QEMU to run it
+qemu-system-i386 -fda osle.img
 ```
 
-## Build locally
+### Build and Run your OSle program
 
 ```sh
-make boot.o
+# ensure you have a working OSle image at osle.img
+make osle
+
+# compile your source to generate my_file.bin
+sdk/build my_file.s
+
+# bundle my_file.bin into the osle.img image
+sdk/pack my_file.bin
+
+# run it!
+qemu-system-i386 -fda osle.img
 ```
 
-## Use it on a real device
+### Use OSle on a Real Device
+
+Write the built image to a device using `dd`:
 
-For example using `dd`
+> [!WARNING]  
+> The following action can damage your hardware. We take no responsibility for
+> any damage OSle might cause.
 
 ```sh
-sudo dd if=boot.o of=/dev/YOUR_DEVICE bs=512 count=1
-```
+# generate an OSle image at osle.img
+make osle
+
+# write it on a device
+sudo dd if=osle.img of=/dev/YOUR_DEVICE bs=512 count=1
+```
+
+## 🤝 Contributing
+
+Feel free to explore the [issues](https://github.com/shikaan/OSle/issues) and [pull requests](https://github.com/shikaan/OSle/pulls) to contribute or request features.
+
+## License
+
+[MIT](./LICENSE)

bin/help.s

@@ -43,7 +43,7 @@ str_print:
   ret
 
 VERSION:  db 0x0a, 0x0d
-          db "OSle: A tiny but mighty OS - https://github.com/shikaan/OSle"
+          db "OSle - https://github.com/shikaan/OSle"
           db 0x0a, 0x0d, 0
 
 BUILTINS: db 0x0a, 0x0d, "Builtins:", 0x0a, 0x0d