Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

working on docs to make it a bit more useable #2907

Merged
merged 2 commits into from
Jan 22, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 37 additions & 8 deletions Docs/articles/Installation/DevKit.md
Original file line number Diff line number Diff line change
@@ -1,30 +1,59 @@
# 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`)
* Yasm (`apt install yasm`)
* 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:

<img src="https://raw.githubusercontent.com/CosmosOS/Cosmos/master/Docs/images/Dir.png" width="200">


### 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.
Expand Down
27 changes: 27 additions & 0 deletions Docs/articles/Installation/UserKit.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions Docs/articles/toc.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
## [Debug Commands](Debugger/DebugCommands.md)

# Installation
## [User Kit](Installation/UserKit.md)
## [Dev Kit](Installation/DevKit.md)
## [Running](Installation/Running.md)

Expand Down
50 changes: 50 additions & 0 deletions Docs/docfx.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand All @@ -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",
Expand Down
8 changes: 5 additions & 3 deletions Docs/index.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Welcome to the Official Cosmos Documentation</h1>

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

Expand All @@ -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)
24 changes: 0 additions & 24 deletions Docs/install.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
10 changes: 8 additions & 2 deletions Docs/toc.yml
Original file line number Diff line number Diff line change
@@ -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/
items:
- name: Cosmos
href: obj/api/cosmos
- name: X#
href: obj/api/xsharp
- name: IL2CPU
href: obj/api/il2cpu