From bdc683604ec4d565a106772482f1ed54efcd3a46 Mon Sep 17 00:00:00 2001 From: zarlo <5899@zarlo.dev> Date: Wed, 17 Jan 2024 03:18:57 +0000 Subject: [PATCH] work on the docs --- Docs/articles/Installation/DevKit.md | 45 +++++++++++++++++++----- Docs/articles/Installation/UserKit.md | 27 +++++++++++++++ Docs/articles/toc.md | 1 + Docs/docfx.json | 50 +++++++++++++++++++++++++++ Docs/index.md | 8 +++-- Docs/install.md | 24 ------------- Docs/toc.yml | 10 ++++-- 7 files changed, 128 insertions(+), 37 deletions(-) create mode 100644 Docs/articles/Installation/UserKit.md diff --git a/Docs/articles/Installation/DevKit.md b/Docs/articles/Installation/DevKit.md index 800c047387..cf229af0d9 100644 --- a/Docs/articles/Installation/DevKit.md +++ b/Docs/articles/Installation/DevKit.md @@ -1,15 +1,25 @@ # Dev Kit Installation -### Prerequisites for Windows +## Windows + +### Prerequisites * (Free) source code of Development Kit from [Cosmos on GitHub](https://github.com/CosmosOS/Cosmos) * You must clone the repository using Git. For a detailed walkthrough, [see here](https://help.github.com/articles/fork-a-repo/). * (Free) [Visual Studio 2022 Community](https://visualstudio.microsoft.com/vs/) * (Free) [InnoSetup](http://www.jrsoftware.org/isdl.php#qsp) * This is required to build the setup kit which is used to build and install the Visual Studio integration libaries for Cosmos. - * During install it will ask you about optional components to install. Be sure you check "Install Inno Setup Preprocessor". + * During install it will ask you about optional components to install. Be sure you check "Install Inno Setup Preprocessor". + +### Installation + +* Look in the downloaded sources and run **install-VS2022.bat** with admin privileges (UAC will ask for permission), needed for install in system directories. +* When the installation is complete, Visual Studio will automatically open and you may begin programming with your new, modified copy of Cosmos. + -### Prerequisites for Linux +## Linux + +### Prerequisites * .NET SDK (6+): [Download .NET SDK](https://learn.microsoft.com/en-us/dotnet/core/install/linux) * Make (`apt install make`) @@ -17,14 +27,33 @@ * Xorriso (`apt install xorriso`) * QEMU or any other virtual machine. See [Running](https://cosmosos.github.io/articles/Installation/Running.html) for more information. -### Installation on Windows -* Look in the downloaded sources and run **install-VS2022.bat** with admin privileges (UAC will ask for permission), needed for install in system directories. -* When the installation is complete, Visual Studio will automatically open and you may begin programming with your new, modified copy of Cosmos. - -### Installation on Linux +### Installation Run `make` to build Cosmos. Cosmos will clone all the required repos, build itself, and install it and it's nuget packages to the system automatically. +## notes / FAQ + +### custom cosmos repos + +if you are using custom cosmos repos you will need to clone them all manually as the installer script will pull from https://github.com/CosmosOS/ + +A tree diagram of the source should look like the following: + + + + +### get stuck pulling the git repos + +check if git is installed and in your path as we use git to pull the repos + +### i just updated and my project is sill using the old version + +you may need to clear you nuget cache try ``dotnet clean`` to clear the project level cache + +### the project templates are not showing in visual studio + +if you have more then 1 version of visual studio installed this can bug this follow "dotnet Project Templates" should fix it + ### dotnet Project Templates If you are using linux or prefer not using Visual Studio for your projects, you can install the dotnet project template using `dotnet new --install ./source/templates/csharp/` assuming you are currently in the Cosmos base directory. After installing the template use `dotnet new cosmosCSKernel -n {name}` to create a new Cosmos Kernel project. diff --git a/Docs/articles/Installation/UserKit.md b/Docs/articles/Installation/UserKit.md new file mode 100644 index 0000000000..f562c413b1 --- /dev/null +++ b/Docs/articles/Installation/UserKit.md @@ -0,0 +1,27 @@ +# Installation + +for DevKit / linux see [DevKit](DevKit.md) + +### Prerequisites + + +* **Visual Studio 2022** - [Download](https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx) +* **Visual Studio 2022 Workload: .NET Desktop** - .NET Desktop development +* **.NET 6.0** - [Download](https://www.microsoft.com/en-us/download/details.aspx?id=53321) +* **VMware Player or Workstation** VMware Player is free, so that is recommended instead - [Download](https://www.vmware.com/uk/products/workstation-player/workstation-player-evaluation.html) +* **Microsoft Visual C++ 2010 Redistributable** - [Download](https://www.microsoft.com/en-us/download/details.aspx?id=26999) + +### Installing Cosmos + +First, you need to choose between the User Kit and the Dev Kit. It is recommended that new users start with the User Kit but only move later to the Dev Kit if you need the latest features and want to contribute back to the main project. +The Dev Kit is the live source against which the Cosmos Team develops directly. The Dev Kit has the latest and greatest features, but at various times has known issues, and sometimes may not even build. Thus to use the Dev Kit be sure to join our support channels and inquire about the current status before using the Dev Kit or updating it. + +The User Kit is a snapshot stable version of Cosmos including a premade installer. The UserKit however is often quite a bit out of date compared to the DevKit and is only occasionally updated. The User Kit is a great easy way to get familiar with Cosmos, but active developers should transition to the Dev Kit after becoming very familiar with the UserKit, and expect some bugs here and there. + +### User Kit + +1. Download [the latest release of Cosmos](http://github.com/CosmosOS/Cosmos/releases/latest) (download the **exe** file) +2. Wait for the download to complete then run the installer. Allow it to run as admin. Make sure **VS2022 is NOT running** when you do this. +3. Click "Next" then "Install" +4. Wait for the install to progress. **Tip:** At the end the installer may look like it has stalled, but it is still doing something in the background. WAIT for the "Finish" button to become available. +5. Cosmos should now be installed. Follow other tutorials to find out how to create your first OS. \ No newline at end of file diff --git a/Docs/articles/toc.md b/Docs/articles/toc.md index 29b0d623d8..62545c5039 100644 --- a/Docs/articles/toc.md +++ b/Docs/articles/toc.md @@ -8,6 +8,7 @@ ## [Debug Commands](Debugger/DebugCommands.md) # Installation +## [User Kit](Installation/UserKit.md) ## [Dev Kit](Installation/DevKit.md) ## [Running](Installation/Running.md) diff --git a/Docs/docfx.json b/Docs/docfx.json index 459137ad82..c95c3649ae 100644 --- a/Docs/docfx.json +++ b/Docs/docfx.json @@ -14,6 +14,42 @@ } ], "dest": "obj/api" + }, + { + "src": [ + { + "files": [ + "source/Cosmos.Core/Cosmos.Core.csproj", + "source/Cosmos.Core_Asm/Cosmos.Core_Asm.csproj", + "source/Cosmos.HAL2/Cosmos.HAL2.csproj", + "source/Cosmos.System2/Cosmos.System2.csproj", + "source/Cosmos.Debug.Kernel/Cosmos.Debug.Kernel.csproj", + ], + "exclude": [ + "**/bin/**", + "**/obj/**" + ], + "src": "../" + } + ], + "dest": "obj/api/cosmos" + }, + { + "src": [ + { + "files": [ + "source/Cosmos.Core_Plugs/Cosmos.Core_Plugs.csproj", + "source/Cosmos.HAL2/Cosmos.HAL2.csproj", + "source/Cosmos.System2_Plugs/Cosmos.System2_Plugs.csproj" + ], + "exclude": [ + "**/bin/**", + "**/obj/**" + ], + "src": "../" + } + ], + "dest": "obj/api/plugs" } ], "build": { @@ -25,6 +61,20 @@ "src": "obj/api", "dest": "api" }, + { + "files": [ + "**/*.yml" + ], + "src": "obj/api/cosmos", + "dest": "api/cosmos" + }, + { + "files": [ + "**/*.yml" + ], + "src": "obj/api/plugs", + "dest": "api/plugs" + }, { "files": [ "**/*.md", diff --git a/Docs/index.md b/Docs/index.md index 57bad9d8a1..984999e929 100644 --- a/Docs/index.md +++ b/Docs/index.md @@ -1,8 +1,8 @@ # Welcome to the Official Cosmos Documentation -If you're new to Cosmos, welcome! Before you get stuck in the API documentation, we highly recommend you visit the website linked at the bottom. +If you're new to Cosmos, welcome! Before you get stuck in the API documentation, we highly recommend you visit the website linked below. -The Articles section of this website includes some articles which have been written many years ago for websites such as www.codeproject.com and are kept for archival purposes. These discuss elements such as the Cosmos Virtual File System. We prefer newcomers who want to develop their own operating systems to read the API documentation while we update these articles to comply with the current Cosmos project. +The Articles section of this website includes some articles which have been written over years ago for websites such as www.codeproject.com and are mostly kept for archival purposes. These discuss elements such as the Cosmos Virtual File System. We prefer newcomers who want to develop their own operating systems to read the API documentation while we update these articles to comply with the current Cosmos project. For projects using the VFS directly, we recommend you use System.IO methods where possible. This is because these were written before much progress was made making .NET assemblies usable @@ -17,4 +17,6 @@ If you need a translation for this documentation, click [here](https://cosmosos- You can find the latest and previous build statuses on [AppVeyor](https://ci.appveyor.com/project/CosmosOS/cosmos) [![Build status](https://ci.appveyor.com/api/projects/status/kust7g5dlnykhkaf/branch/master?svg=true)](https://ci.appveyor.com/project/CosmosOS/cosmos/branch/master) -[![Join the chat at (https://discord.com/invite/kwtBwv6jhD](https://img.shields.io/discord/833970409337913344)](https://discord.com/invite/kwtBwv6jhD) +[![Join the chat at (https://discord.com/invite/kwtBwv6jhD](https://img.shields.io/discord/833970409337913344)](https://discord.com/invite/kwtBwv6jhD) + +xref link [https://cosmosos.github.io/xrefmap.yml](https://cosmosos.github.io/xrefmap.yml) diff --git a/Docs/install.md b/Docs/install.md index d65bbdee3d..dd93d577b5 100644 --- a/Docs/install.md +++ b/Docs/install.md @@ -1,28 +1,4 @@ -# Installation -### Prerequisites - - -* **Visual Studio 2022** - [Download](https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx) -* **Visual Studio 2022 Workload: .NET Desktop** - .NET Desktop development -* **.NET 6.0** - [Download](https://www.microsoft.com/en-us/download/details.aspx?id=53321) -* **VMware Player or Workstation** VMware Player is free, so that is recommended instead - [Download](https://www.vmware.com/uk/products/workstation-player/workstation-player-evaluation.html) -* **Microsoft Visual C++ 2010 Redistributable** - [Download](https://www.microsoft.com/en-us/download/details.aspx?id=26999) - -### Installing Cosmos - -First, you need to choose between the User Kit and the Dev Kit. It is recommended that new users start with the User Kit but only move later to the Dev Kit if you need the latest features and want to contribute back to the main project. -The Dev Kit is the live source against which the Cosmos Team develops directly. The Dev Kit has the latest and greatest features, but at various times has known issues, and sometimes may not even build. Thus to use the Dev Kit be sure to join our support channels and inquire about the current status before using the Dev Kit or updating it. - -The User Kit is a snapshot stable version of Cosmos including a premade installer. The UserKit however is often quite a bit out of date compared to the DevKit and is only occasionally updated. The User Kit is a great easy way to get familiar with Cosmos, but active developers should transition to the Dev Kit after becoming very familiar with the UserKit, and expect some bugs here and there. - -### User Kit - -1. Download [the latest release of Cosmos](http://github.com/CosmosOS/Cosmos/releases/latest) (download the **exe** file) -2. Wait for the download to complete then run the installer. Allow it to run as admin. Make sure **VS2022 is NOT running** when you do this. -3. Click "Next" then "Install" -4. Wait for the install to progress. **Tip:** At the end the installer may look like it has stalled, but it is still doing something in the background. WAIT for the "Finish" button to become available. -5. Cosmos should now be installed. Follow other tutorials to find out how to create your first OS. ### Dev Kit diff --git a/Docs/toc.yml b/Docs/toc.yml index 82f9363bcd..a55f5e4794 100644 --- a/Docs/toc.yml +++ b/Docs/toc.yml @@ -1,11 +1,17 @@ - name: Home href: index.md - name: Install - href: install.md + href: articles/Installation/UserKit.md - name: Cosmos Website href: https://gocosmos.org - name: Articles href: articles/ homepage: articles/GettingStarted.md - name: API Documentation - href: obj/api/ \ No newline at end of file + items: + - name: Cosmos + href: obj/api/cosmos + - name: X# + href: obj/api/xsharp + - name: IL2CPU + href: obj/api/il2cpu \ No newline at end of file