From 1c842ef3d14de0c66104853785486e34acf74018 Mon Sep 17 00:00:00 2001 From: EnderIce2 Date: Sat, 8 Mar 2025 00:47:43 +0000 Subject: [PATCH] docs: update build instructions Signed-off-by: EnderIce2 --- .editorconfig | 5 +++ INSTALL.md | 72 ++++++++++++++++++++++++++++++++++++++++++ Makefile | 5 +++ README.md | 87 ++++++++------------------------------------------- 4 files changed, 95 insertions(+), 74 deletions(-) create mode 100644 INSTALL.md diff --git a/.editorconfig b/.editorconfig index 41a1382f..2e1ed055 100644 --- a/.editorconfig +++ b/.editorconfig @@ -19,3 +19,8 @@ indent_size = 2 [{CMakeLists.txt,*.cmake}] indent_size = 2 indent_style = space + +[*.md] +indent_style = space +indent_size = 4 +trim_trailing_whitespace = false diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..b72d9e6a --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,72 @@ +# ๐Ÿš€ Installation Guide + +This guide will help you install Fennix on your system. + +## ๐Ÿ› ๏ธ Preparing the Environment + +There are two ways to build the project: + +1. **๐Ÿณ Use Dev Container (Recommended)** + * This is the easiest way to prepare the environment for building the project. But firstly, you need to install [Docker](https://docs.docker.com/get-docker/) and [Visual Studio Code](https://code.visualstudio.com/). + * After installing Docker and Visual Studio Code, you can open the project in Visual Studio Code and click on the "Reopen in Container" button. + * This will open the project in a Dev Container with all the required tools installed. + * If you encounter errors while the Dev Container is building, ensure the following are correctly configured: + * `/tmp/.X11-unix` + * Environment variable `XAUTHORITY` + * `/run/user/1000/pulse/native` + * **Note:** These configurations are only necessary if you plan to use QEMU inside the container. +2. **๐Ÿ’ป Build the Project Locally** + * The instructions below will guide you through the process of building the project locally. + +**NOTE:** You MUST have `autoconf 2.69` and `automake 1.15.1` versions installed on your system. A complete list of dependencies can be found in the [.devcontainer/Dockerfile](.devcontainer/Dockerfile) file. + +Before building the project, you need to build the cross-compiler toolchain and QEMU. +You can do this by running the following command: + +```sh +make setup +``` + +This will clone, patch, and build the required tools for you. + +Alternatively, if you wish to skip building QEMU, you can run `make setup-no-qemu`. +However, in this case, you will need to manually specify the path to the QEMU binary in the `config.mk` file. + +## ๐Ÿ—๏ธ Building the Project + +To build the project, run: + +```sh +make build +``` + +This will build the kernel, userspace, and drivers. The resulting ISO image will be `Fennix.iso`. + +## ๐Ÿš€ Running the OS + +To run the OS, execute: + +```sh +make run +``` + +The `run` target will automatically build the project if it hasn't been built yet. + +## โš™๏ธ Additional Configuration + +You can customize the project by editing the `config.mk` file. + +## ๐Ÿงช Debugging + +If you use Visual Studio Code, you can press `F5` to start debugging the OS. +The configuration is already set up for you. + +Alternatively, you can run the following command to start debugging: + +```sh +make debug +``` + +This will start QEMU in debug mode, allowing you to connect to it using GDB. + +The GDB FIFO file is located at `/tmp/gdb-fennix`. diff --git a/Makefile b/Makefile index 15dbd7e4..057f97a6 100644 --- a/Makefile +++ b/Makefile @@ -111,6 +111,9 @@ setup: $(MAKE) prepare $(MAKE) tools +setup-no-qemu: + $(MAKE) --quiet -C tools ci + build: build_kernel build_bootloader build_userspace build_drivers build_image dump: @@ -313,6 +316,8 @@ endif vscode_debug: build_kernel build_userspace build_drivers build_image vscode_debug_only +debug: vscode_debug + qemu: qemu_vdisk clean_logs touch serial.log # x-terminal-emulator -e tail -f serial.log & diff --git a/README.md b/README.md index 46ee42da..3105b4a5 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@

- GitHub Repo stars + GitHub Repo stars GitHub Actions Workflow Status - GitHub commit activity + GitHub commit activity GitHub License

@@ -24,15 +24,15 @@ ## Features - ๐Ÿงฉ Flexible and modular - - You can easily choose the components you want to include in the kernel + - You can easily choose the components you want to include in the kernel - ๐ŸŽ›๏ธ Compatible with multiple platforms - - Supports i386, AMD64 and AArch64 platforms + - Supports i386, AMD64 and AArch64 platforms - ๐Ÿ“ฆ Support for different operating system binaries - - You can run Linux and Windows binaries + - You can run Linux and Windows binaries - ๐Ÿ–จ๏ธ Driver support - - Supports a variety of drivers for different hardware components + - Supports a variety of drivers for different hardware components - ๐Ÿ“– Detailed documentation - - The project is well-documented using Doxygen + - The project is well-documented using Doxygen > [!IMPORTANT] > Some features are still in development and may not be fully functional. @@ -43,75 +43,14 @@ You can download the development ISO image from the [Actions](https://github.com/EnderIce2/Fennix/actions/workflows/makefile.yml) tab on the GitHub repository. +### ๐Ÿ› ๏ธ Compile from Source -### ๐Ÿ› ๏ธ Prerequisites - -To build the project, you need to have the following tools installed: - -- `make` -- `gcc` -- `ld` -- ... and other standard Unix tools - - These can be installed using `build-essential` on Ubuntu or `base-devel` on Arch Linux -- `doxygen` (optional) - - To generate the documentation - -### ๐Ÿš€ Installation - -You can install the project by building it from source. - -#### Cloning the Repository - -First, clone the repository using Git: - -```sh -git clone https://github.com/EnderIce2/fennix.git -cd fennix -``` - -#### Preparing the Environment - -Before building the project, you need to build the cross-compiler toolchain and QEMU. You can do this by running the following command: - -```sh -make setup -``` - -This will clone, patch, and build the required tools for you. - -#### Building the Project - -To build the project, run: - -```sh -make build -``` - -This will build the kernel, userspace, and drivers. The iso image will be `Fennix.iso`. - -#### Running the OS - -You can run the OS using QEMU. First, build the project, then run: - -```sh -make run -``` - -#### Additional Configuration - -You can configure the project by editing the `config.mk` file. - -## ๐Ÿงช Debugging - -If you use Visual Studio Code, you can press `F5` to start debugging the OS. -The configuration is already set up for you. - -> [!TIP] -> Make sure you built the project at least once before debugging. +Check out the [installation guide](INSTALL.md) to compile the project from source. ## ๐Ÿ“š Documentation -The project documentation is generated using Doxygen. +The current documentation is available [here](https://fennix.enderice2.com/docs/index.html). + To generate the documentation, run: ```sh @@ -122,13 +61,13 @@ The documentation will be available in the `doxygen-doc/docs` directory. ## ๐Ÿ‘จโ€๐Ÿ’ป Contributing -Contributions are welcome! +Contributions are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines on how to contribute to this project. ### Contributors - + ## ๐Ÿ“ƒ License