Update and improve documentation (#1256)

mosa · Jan 27, 2025 · 295584e · 295584e
1 parent 66d6d8a
commit 295584e
Show file tree

Hide file tree

Showing 31 changed files with 331 additions and 310 deletions.
diff --git a/Source/Docs/a-dive-into-baremetal.rst b/Source/Docs/a-dive-into-baremetal.rst
@@ -198,7 +198,7 @@ good example of this is the ``PCService``, or even the aforementioned ``DeviceSe
 fulfills the purpose of handling power management, like shutting down or rebooting the system. This service must be
 queryable at any point in time, whenever the user wishes to shut down or reboot their PC. Similarly (but more so
 to the end user), the ``DeviceService`` allows querying any initialized device driver in the system. This is
-particularly useful if you want to, say, get all ``IGraphicsDevice``s in the system, or even get a very specific device
+particularly useful if you want to, say, get all ``IGraphicsDevice`` devices in the system, or even get a very specific device
 like a ``StandardKeyboard``.
 
 Either way, here, we initialize a total of **5 new services**, all of which most likely need no introduction now. But,

diff --git a/Source/Docs/compiler-design.rst b/Source/Docs/compiler-design.rst
@@ -1,5 +1,5 @@
 ###############
-Compiler Design
+Compiler design
 ###############
 
 The MOSA Compiler framework is designed around two pipelines, each with multiple stages, and a type system.

diff --git a/Source/Docs/compiler-optimizations.rst b/Source/Docs/compiler-optimizations.rst
@@ -1,5 +1,5 @@
 ######################
-Compiler Optimizations
+Compiler optimizations
 ######################
 
 Optimizations

diff --git a/Source/Docs/compiler-transformations.rst b/Source/Docs/compiler-transformations.rst
@@ -1,5 +1,5 @@
 ########################
-Compiler Transformations
+Compiler transformations
 ########################
 
 The MOSA compiler uses a database of transformations to represent specific types of optimizations. These transformation

diff --git a/Source/Docs/contents.txt b/Source/Docs/contents.txt
@@ -13,6 +13,7 @@
    :maxdepth: 1
 
    getting-started
+   usb-flash-drive-installation
    demos
 
 .. toctree::
@@ -26,6 +27,15 @@
    tool-explorer
    tool-debugger
 
+.. toctree::
+   :caption: Utilities
+   :hidden:
+   :maxdepth: 1
+
+   unit-tests
+   create-core-library
+   source-code-generator
+
 .. toctree::
    :caption: Settings
    :hidden:
@@ -59,14 +69,6 @@
 
    runtime-tables
 
-.. toctree::
-   :caption: Advanced
-   :hidden:
-   :maxdepth: 1
-
-   unit-tests
-   usb-flash-drive-installation
-
 .. toctree::
    :caption: Contribute
    :hidden:

diff --git a/Source/Docs/create-core-library.rst b/Source/Docs/create-core-library.rst
@@ -0,0 +1,56 @@
+###################
+Create core library
+###################
+
+To implement its own core library, MOSA generates a "dummy" one that includes all the public APIs but without the actual implementation code. The **Create core library** utility takes care of doing that work. To clone the official .NET core library repository, it requires ``git``. Here are the available command line arguments for the utility:
+
+.. csv-table::
+   :header: "Short name","Long name","Description"
+   :widths: 100, 100, 50
+
+    -o,\-\-output,Sets the output directory.
+    -c,\-\-copy-files,"If enabled, only copies and patches the source files and stops."
+
+To run the utility, simply execute the following command on any platform:
+
+.. code-block:: bash
+
+	dotnet bin/Mosa.Utility.CreateCoreLib.dll -o Output
+
+The process can take between a few seconds to a few minutes depending on the speed of your internet connection and PC. At the end, you should get a ``System.Runtime.dll`` file at the directory where you executed the utility. At the end, you should get a console output that looks like this:
+
+.. code-block:: text
+
+  Cloning .NET runtime GitHub repository...
+  Cloning into 'runtime'...
+  remote: Enumerating objects: 65953, done.
+  remote: Counting objects: 100% (65953/65953), done.
+  remote: Compressing objects: 100% (42248/42248), done.
+  Receiving objects: 100% (65953/65953), 88.04 MiB | 9.16 MiB/s, done.
+  remote: Total 65953 (delta 25898), reused 34761 (delta 20956), pack-reused 0 (from 0)
+  Resolving deltas: 100% (25898/25898), done.
+  Updating files: 100% (58901/58901), done.
+  Parsing input files...
+  Patching System.DirectoryServices.manual.cs...
+  Patching System.Net.Http.Json.cs...
+  Patching System.Net.Http.WinHttpHandler.cs...
+  Patching System.Configuration.ConfigurationManager.cs...
+  Patching System.Data.Common.cs...
+  Compiling source files...
+  Decompiling assembly...
+  Removing project file...
+  Removing Properties folder...
+  Patching System.Collections.Generic/PriorityQueue.cs...
+  Patching System.Collections.Generic/PriorityQueue.cs...
+  Patching System/Nullable.cs...
+  Patching System/ReadOnlySpan.cs...
+  Patching System.Runtime.InteropServices/Marshal.cs...
+  Patching System.Runtime.InteropServices/MemoryMarshal.cs...
+  Patching System.Runtime.CompilerServices/Unsafe.cs...
+  Patching System.Numerics/Vector.cs...
+  Patching System.Runtime.Intrinsics/Vector64.cs...
+  Patching System.Runtime.Intrinsics/Vector128.cs...
+  Patching System.Runtime.Intrinsics/Vector256.cs...
+  Patching System.Runtime.Intrinsics/Vector512.cs...
+  Patching System.Threading/Volatile.cs...
+  Patching System.Threading/Interlocked.cs...
diff --git a/Source/Docs/demos.rst b/Source/Docs/demos.rst
@@ -12,7 +12,7 @@ CoolWorld
 
 It's MOSA's flagship demo. It can boot into either console mode (containing a shell with a few basic commands) or
 graphical mode (which makes use of the GPU and some other features offered by MOSA). You can boot into console mode by
-inserting the `-bootoptions coolworldui=consolemode` command line option when starting the MOSA launcher.
+inserting the ``-bootoptions coolworldui=consolemode`` command line option when starting the MOSA launcher.
 
 Console mode:
 

diff --git a/Source/Docs/faq.rst b/Source/Docs/faq.rst
@@ -45,4 +45,4 @@ Are Cosmos and MOSA working together?
 Recently, there have been talks to integrate the MOSA compiler into Cosmos, thus potentially being able to implement
 more features in the MOSA compiler while also providing more stability and performance for Cosmos. While nothing has
 come out of this yet, you can express your opinion on this in our Discord in #cosmos-integration and in the Cosmos
-Discord in #mosa-cosmos-crossdev.
+Discord in #dev-mosa-cosmos.
diff --git a/Source/Docs/get-involved.rst b/Source/Docs/get-involved.rst
@@ -1,5 +1,5 @@
 ############
-Get Involved
+Get involved
 ############
 
 We need your help!
@@ -35,5 +35,5 @@ contributions if you:
 Please be careful with any contribution you make regarding to patents, other open source licenses and any potential
 restrictions. We can only accept contributions compatible with the
 `New BSD License <http://en.wikipedia.org/wiki/BSD_licenses>`__. MIT license is a compatible license, while GNU licenses
-are incomparable. Read more about our :doc:`license` policy.
+are incomparable. Read more about our :doc:`license<license>` policy.
 
diff --git a/Source/Docs/getting-started.rst b/Source/Docs/getting-started.rst
@@ -1,5 +1,5 @@
 ***************
-Getting Started
+Getting started
 ***************
 
 Prerequisites
@@ -20,12 +20,12 @@ On Linux, the following prerequisites are necessary:
 * `Git <https://git-scm.com/>`__ (only if you want to clone and build manually)
 * `QEMU <https://www.qemu.org/>`__
 
-If you're using Ubuntu 22.04, you can use the following commands to quickly set everything up:
+If you're using Ubuntu 24.04, you can use the following commands to quickly set everything up:
 
 .. code-block:: bash
 
 	# Register Microsoft package repository
-	wget -q https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
+	wget -q https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
 	sudo dpkg -i packages-microsoft-prod.deb
 
 	# Install the .NET Core SDK

diff --git a/Source/Docs/images/ventoy2disk-gui.png b/Source/Docs/images/ventoy2disk-gui.png
diff --git a/Source/Docs/introduction.rst b/Source/Docs/introduction.rst
@@ -46,4 +46,4 @@ The MOSA compiler seeks to provide high quality code generation using the follow
 - Block Reordering
 - Greedy Register Allocation
 
-For an exhaustive list, see :doc:`Compiler Optimizations<compiler-optimizations>` which also gives a description of each of these optimizations.
+For an exhaustive list, see :doc:`compiler-optimizations` which also gives a description of each of these optimizations.
diff --git a/Source/Docs/optimization-options.rst b/Source/Docs/optimization-options.rst
@@ -1,7 +1,7 @@
 ####################
-Optimization Options
+Optimization options
 ####################
 
 Here are the available optimization options for the MOSA compiler:
 
-.. image:: images/mosa-optimization-options.png
+.. image:: images/mosa-optimization-options.png
diff --git a/Source/Docs/project-structure.rst b/Source/Docs/project-structure.rst
@@ -1,5 +1,5 @@
 #################
-Project Structure
+Project structure
 #################
 
 MOSA has a lot of projects, which can seem daunting at first. This page will exclusively cover all the types of projects

diff --git a/Source/Docs/runtime-tables.rst b/Source/Docs/runtime-tables.rst
@@ -1,5 +1,5 @@
 ###################
-MOSA Runtime Tables
+MOSA runtime tables
 ###################
 
 This diagram represents the internal runtime tables within the MOSA virtual machine:
@@ -12,15 +12,15 @@ Table Definitions
 .. csv-table::
    :header: "Internal String Object"
    :widths: 200
-	
+
 	Pointer to Method Table
 	String Length
 	Unicode String
 
 .. csv-table::
    :header: "Assembly Table"
    :widths: 200
-	
+
 	Number of Assemblies
 	Pointer to Assembly 1..N
 
@@ -61,7 +61,7 @@ Table Definitions
 
 	Number of Fields
 	Pointer to Field Definition 1..N
-	
+
 .. csv-table::
    :header: "Field Definition"
    :widths: 200
@@ -72,14 +72,14 @@ Table Definitions
 	Pointer to Field Type
 	Address
 	Offset / Size
-	
+
 .. csv-table::
    :header: "Properties Table"
    :widths: 200
 
 	Number of Properties
 	Pointer to Property Definition 1..N
-	
+
 .. csv-table::
    :header: "Property Definition"
    :widths: 200
@@ -90,7 +90,7 @@ Table Definitions
 	Pointer to Property Type
 	Pointer to Getter Method Definition
 	Pointer to Setter Method Defiinition
-		
+
 .. csv-table::
    :header: "Method Lookup Table"
    :widths: 200
@@ -99,14 +99,14 @@ Table Definitions
 	Pointer to Method (Starting Address)
 	Method Size
 	Pointer to Method Definition
-	
+
 .. csv-table::
    :header: "Protected Region Table"
    :widths: 200
 
 	Number of Regions
 	Pointer to Protected Region Definition 1..N
-	
+
 .. csv-table::
    :header: "Protected Region Definition"
    :widths: 200
@@ -116,22 +116,22 @@ Table Definitions
 	Region Handler
 	Exception Handler Type
 	Pointer to Exception Type
-	
+
 .. csv-table::
    :header: "Interface Slot Table"
    :widths: 200
-	
+
 	Number of Interface Method Tables
 	Pointer to Interface Method Table 1..N
-	
+
 .. csv-table::
    :header: "Interface Method Table"
    :widths: 200
-	
+
 	Pointer to Interface Type
 	Number of Methods
 	Pointer to Method Definition 1..N
-	
+
 .. csv-table::
    :header: "Method Definition"
    :widths: 200
@@ -146,7 +146,7 @@ Table Definitions
 	Pointer to Method GC Data
 	Number of Parameters
 	Pointer to Parameter Definition 1..N
-	
+
 .. csv-table::
    :header: "Property Definition"
    :widths: 200
@@ -155,14 +155,14 @@ Table Definitions
 	Pointer to Custom Attributes
 	Parameter Attributes
 	Pointer to Parameter Type
-	
+
 .. csv-table::
    :header: "Custom Attributes Table"
    :widths: 200
 
 	Number of Attributes
 	Pointer to Custom Attribute 1..N
-	
+
 .. csv-table::
    :header: "Custom Attribute"
    :widths: 200
@@ -171,31 +171,31 @@ Table Definitions
 	Pointer to Constructor Method
 	Number of Arguments
 	Pointer to Argument 1..N
-	
+
 .. csv-table::
    :header: "Custom Attribute Argument"
    :widths: 200
-	
+
 	Pointer to Argumentame
 	Is Argument a Field
 	Pointer to Argument Type
 	Argument Size
 	Argument
-	
+
 .. csv-table::
    :header: "Method GC Data"
    :widths: 200
 
 	Pointer to SafePoint Table
 	Pointer to Method GC Stack Data
-	
+
 .. csv-table::
    :header: "Method GC Stack Data"
    :widths: 200
-	
+
 	Number of Method GC Stack Entries
 	Pointer to Method GC Stack Entry 1..N
-	
+
 .. csv-table::
    :header: "Method GC Stack Entry"
    :widths: 200
@@ -205,11 +205,11 @@ Table Definitions
 	Live Ranges 1..N
 	. Address Offset
 	. Address Range
-	
+
 .. csv-table::
    :header: "Method SafePoint Table"
    :widths: 200
-	
+
 	Number of SafePoints
 	SafePoint 1..N
 	. Address Offset