Skip to content

Commit 1a1c58c

Browse files
BoryaGamesBoryaGames
committed
Improve documentation
1 parent bfbe3b4 commit 1a1c58c

File tree

7 files changed

+340
-3
lines changed

7 files changed

+340
-3
lines changed

‎content/docs/en/advanced/app-file-structure.mdx‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: App File Structure
3+
description: How app files work on the inside.
4+
---
5+
6+
![App File Structure](/app_file_structure.png)
7+
8+
First `62 80 62 80` bytes (red color) is **CatCore Magic Signature** - kernel, apps, kexts all start from these bytes.
9+
10+
Next `02` byte (green color) is **File Type**, where `02` means it's an** .app** (**Application File**).
11+
12+
Next `01` byte (yellow color) is **Application Type**. Check table below to know all the application types (they also are available in `CatCore.ProcessType` variable, except the `CatCore.ProcessType.APP`):
13+
14+
| Number | Type |
15+
|--------|------------|
16+
| 0 | DUMMY |
17+
| 1 | KERNEL |
18+
| 3 | JAVASCRIPT |
19+
| 4 | PYTHON |
20+
| 5 | PHP |
21+
| 6 | RUBY |
22+
23+
Next `01` byte (dark blue color) is **Application Flags** (bitfield). Check table below to know all the bitfield flags:
24+
25+
| Flag | Name | Description |
26+
|---------|--------|------------------------|
27+
| 1 \<< 0 | SIGNED | Application is signed. |
28+
29+
If application has `SIGNED` flag, next 256 bytes (purple color) is a **Signature**.
30+
31+
Everything else after that (light blue color) is an **Application Manifest**, which is reversed Base64 of a JSON object. JSON object **doesn't** have a strict structure, the only requirement is `code` property, containing the application code itself.

‎content/docs/en/advanced/meta.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"title": "Advanced",
3+
"icon": "Atom",
4+
"pages": ["app-file-structure"],
5+
"defaultOpen": true
6+
}

‎content/docs/en/first-os.mdx‎

Lines changed: 168 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,171 @@ title: First OS
33
description: How to make and boot your first OS.
44
---
55

6-
# Work in progress.
6+
import { File, Folder, Files } from "fumadocs-ui/components/files";
7+
import { Terminal, AppWindow } from "lucide-react";
8+
9+
Let's make your first OS, by the end of this guide you will have the following file structure:
10+
11+
<Files>
12+
<Folder name="src" defaultOpen>
13+
<Folder name="overlay-fs" defaultOpen>
14+
<Folder name="system" defaultOpen>
15+
<File name="system.js" />
16+
<File name="logo.png" />
17+
</Folder>
18+
</Folder>
19+
<Folder name="apps" defaultOpen />
20+
<File name="system.json" />
21+
</Folder>
22+
</Files>
23+
24+
Start by creating all the folders (but `src/apps` is optional!), and then let's make `src/system.json` file (which is, actually, optional too):
25+
26+
```json
27+
{
28+
"name": "ExampleOS",
29+
"version": "v0.0.1",
30+
"logo": "/system/logo.png",
31+
"loading": "circle"
32+
}
33+
```
34+
35+
<Accordions>
36+
<Accordion title="name" id="systemjson-name">
37+
It's the name of your OS as a string, which will be the name of your executable, app window and as a `CatCore.systemName` variable inside your code. It's recommended to set this value, but the default is `"System"`.
38+
</Accordion>
39+
<Accordion title="version" id="systemjson-version">
40+
It's the version of your OS as a string starting from `v`, which will be available as `CatCore.systemVersion` variable inside your code. It's recommended to set this value. If it's not starting from `v`, it will be automatically added (`0.0.1` --> `v0.0.1`).
41+
</Accordion>
42+
<Accordion title="logo" id="systemjson-logo">
43+
Optional logo of your OS at boot screen and app icon. Must be a string of a **CatCore path** (check example with `overlay-fs` above).
44+
</Accordion>
45+
<Accordion title="loading" id="systemjson-loading">
46+
Sets boot screen loader style. Must be `"circle"` or `"bar"`, defaults to `"circle"`.
47+
Circle is similar to Windows 11 boot and bar is similar to iOS/MacOS boot.
48+
This choice is decorative, but bar can have a progress percentage (how much % of the bar is filled), giving more information to the user.
49+
</Accordion>
50+
</Accordions>
51+
52+
Once you have made the folders, `system.json` (or decided to skip it) and logo file (optional), you need to create a file for your OS code.
53+
54+
OS code file must be in `/system` mount, named `system` or `sys`, and have any supported language extension. Currently supported languages: **JavaScript**, **Python**, **PHP**, **Ruby**, but this list will increase in future updates.
55+
56+
Once you have created the file, paste this example code:
57+
58+
<Tabs groupId="oslanguage" items={["JavaScript", "Python", "PHP", "Ruby"]} persist>
59+
<Tab value="JavaScript">
60+
```javascript
61+
CatCore.loadProgress();
62+
```
63+
</Tab>
64+
<Tab value="Python">
65+
```python
66+
CatCore.loadProgress()
67+
```
68+
</Tab>
69+
<Tab value="PHP">
70+
```php
71+
<?php
72+
$CatCore->loadProgress();
73+
?>
74+
```
75+
</Tab>
76+
<Tab value="Ruby">
77+
```ruby
78+
CatCore.loadProgress()
79+
```
80+
</Tab>
81+
</Tabs>
82+
83+
Next, compile your first OS and open it. After some waiting, you should have a black screen - congratulations with your first OS! 🎉
84+
85+
<Callout title="Troubleshooting">
86+
If you have some issues and do not get a black screen, press `Ctrl + Shift + F8` inside your OS, even while it's booting. There's a great chance a **logs panel** will open up containing enough information to fix problems. If you still can't get your first OS to work, contact CatCore support using [Discord](https://discord.gg/AU5PBWxeVN) or [GitHub](https://github.com/CatCoreV).
87+
</Callout>
88+
89+
For future development, you may use some IDE that can speed up your OS development. I recommend **VSCode**, as it's the only one tested with **CatCore**. To use IDE integration, just open `os-compiler` folder in your IDE and if your IDE supports it, it will automatically pick-up all the needed files. You might need to compile at least 1 time for IDE integration to work properly. If you're using **JavaScript**, your IDE might not like top-level `await`, even though it's supported - we can't fix this issue, so you'll have to just add an async wrapper.
90+
91+
And lastly, you should learn how to control the bootscreen:
92+
93+
<Tabs groupId="oslanguage" items={["JavaScript", "Python", "PHP", "Ruby"]} persist>
94+
<Tab value="JavaScript">
95+
```javascript
96+
// Loop from 1% to 100%
97+
for (var i = 1; i <= 100; i++) {
98+
// Set the loading progress
99+
CatCore.loadProgress(i);
100+
// Wait 0.1 seconds
101+
await CatCore.delay(0.1 *CatCore.SECOND);
102+
}
103+
104+
// Without an argument, it completely ends the boot and hides the boot screen
105+
CatCore.loadProgress();
106+
```
107+
</Tab>
108+
<Tab value="Python">
109+
```python
110+
import asyncio
111+
112+
async def main():
113+
# Loop from 1% to 100%
114+
for i in range(1, 101):
115+
# Set the loading progress
116+
CatCore.loadProgress(i)
117+
# Wait 0.1 seconds
118+
await CatCore.delay(0.1 *CatCore.SECOND)
119+
120+
# Without an argument, it completely ends the boot and hides the boot screen
121+
CatCore.loadProgress()
122+
123+
asyncio.run(main())
124+
```
125+
</Tab>
126+
<Tab value="PHP">
127+
```php
128+
<?php
129+
// Loop from 1% to 100%
130+
for (var i = 1; i <= 100; i++) {
131+
// Set the loading progress
132+
$CatCore->loadProgress(i);
133+
// Wait 0.1 seconds
134+
await $CatCore->delay(0.1 *CatCore.SECOND);
135+
}
136+
137+
// Without an argument, it completely ends the boot and hides the boot screen
138+
$CatCore->loadProgress();
139+
?>
140+
```
141+
</Tab>
142+
<Tab value="Ruby">
143+
```ruby
144+
# Loop from 1% to 100%
145+
(1..100).each do |i|
146+
# Set the loading progress
147+
CatCore.loadProgress(i)
148+
# Wait 0.1 seconds
149+
await CatCore.delay(0.1 *CatCore::SECOND)
150+
end
151+
152+
# Without an argument, it completely ends the boot and hides the boot screen
153+
CatCore.loadProgress()
154+
```
155+
</Tab>
156+
</Tabs>
157+
158+
<Callout title="Did not understand?">
159+
If you have trouble understanding the code, you probably **should** learn English (words like **delay** or **load progress**) or your programming language (like `for` or `await`).
160+
In JavaScript, top-level `await` is allowed, even if your IDE does not think that.
161+
If you're a Ruby developer, you might not know about `await`, as Ruby does not have that keyword, so you'll have to learn it like in other languages. Simple explanation of `await` is just to **wait** for that function to finish, even if it takes a long time in the background.
162+
</Callout>
163+
164+
Now, that you have basic understanding of CatCore, you can make a **text-based terminal OS**, a **graphical OS**, or even both at the same time, and it's **your** choice, so choose what you want to start with:
165+
166+
<Cards>
167+
<Card href="/en/docs/text-mode" icon={<Terminal />} title="Text mode">
168+
I choose to learn how to interact with CatCore's **text mode** and make a text-based terminal OS.
169+
</Card>
170+
<Card href="/en/docs/gui/window" icon={<AppWindow />} title="Graphical mode">
171+
I choose to start learning GUI (Graphical User Interface) and start making a basic window.
172+
</Card>
173+
</Cards>

‎content/docs/en/getting-started.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,9 @@ First I would recommend to learn about all the compiler buttons:
8080
New **Quick** mode allows you to use cache of previous compilation to highly speed up the next one.
8181
Since you just opened the compiler, it's **locked**, but once you'll do a compilation, it will unlock.
8282
Note that if you change any setting (like the kernel version, architecture or target), quick compilation will lock again.
83-
> Quick compilation is useful, but it also keeps old files in `/data` mount, which can break your OS in some rare cases, but that's your OS issue, which you probably **should** fix if it happens!
83+
<Callout title="Quick compilation">
84+
Quick compilation is useful, but it also keeps old files in `/data` mount, which can break your OS in some rare cases, but that's your OS issue, which you probably **should** fix if it happens!
85+
</Callout>
8486
</Accordion>
8587
<Accordion title="Bottom bar" id="bottom-bar">
8688
Bottom bar contains a status of the compilation, like **Ready!**, which displays what is currently happening.

‎content/docs/en/meta.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"pages": ["getting-started", "first-os"]
2+
"pages": ["getting-started", "first-os", "text-mode", "advanced"]
33
}

‎content/docs/en/text-mode.mdx‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: Text Mode
3+
description: How to use text mode.
4+
---
5+
6+
First, let's start by just outputting some text:
7+
8+
<Tabs groupId="oslanguage" items={["JavaScript", "Python", "PHP", "Ruby"]} persist>
9+
<Tab value="JavaScript">
10+
```javascript
11+
CatCore.text("Hello, World!");
12+
```
13+
</Tab>
14+
<Tab value="Python">
15+
```python
16+
CatCore.text("Hello, World!")
17+
```
18+
</Tab>
19+
<Tab value="PHP">
20+
```php
21+
<?php
22+
$CatCore->text("Hello, World!");
23+
?>
24+
```
25+
</Tab>
26+
<Tab value="Ruby">
27+
```ruby
28+
CatCore.text("Hello, World!")
29+
```
30+
</Tab>
31+
</Tabs>
32+
33+
This was easy! And for multi-line texts just use `\n` or anything else you would normally.
34+
35+
You might want to **customize** this text. Here's an example of one of text's properties:
36+
37+
<Tabs groupId="oslanguage" items={["JavaScript", "Python", "PHP", "Ruby"]} persist>
38+
<Tab value="JavaScript">
39+
```javascript
40+
// Set value
41+
CatCore.textOffset(16);
42+
43+
// Read value
44+
var offset = CatCore.textOffset();
45+
```
46+
</Tab>
47+
<Tab value="Python">
48+
```python
49+
# Set value
50+
CatCore.textOffset(16)
51+
52+
# Read value
53+
offset = CatCore.textOffset()
54+
```
55+
</Tab>
56+
<Tab value="PHP">
57+
```php
58+
<?php
59+
// Set value
60+
$CatCore->textOffset(16);
61+
62+
// Read value
63+
$offset = $CatCore->textOffset();
64+
?>
65+
```
66+
</Tab>
67+
<Tab value="Ruby">
68+
```ruby
69+
# Set value
70+
CatCore.textOffset(16)
71+
72+
# Read value
73+
offset = CatCore.textOffset()
74+
```
75+
</Tab>
76+
</Tabs>
77+
78+
This is just an example, here's the list of every single one, use them just as an example above:
79+
80+
<Accordions>
81+
<Accordion title="textOffset" id="textmode-offset">
82+
It's a number - amount of pixels from top-left corner to the start of the text, defaults to `10`.
83+
</Accordion>
84+
<Accordion title="textFont" id="textmode-font">
85+
It's a string - font name your text will use. User must have it installed in their host OS, if using an app.
86+
</Accordion>
87+
<Accordion title="textSize" id="textmode-size">
88+
It's a number - size of the text, defaults to `13`.
89+
</Accordion>
90+
<Accordion title="textColor" id="textmode-color">
91+
It's a color of the text, defaults to `white`.
92+
</Accordion>
93+
<Accordion title="backgroundColor" id="textmode-background">
94+
It's a color of the background, defaults to `black`.
95+
</Accordion>
96+
</Accordions>
97+
98+
## ANSI
99+
100+
There's also one more function `CatCore.enableANSI`, which is a boolean. It controls whetever `CatCore.text` should parse and render ANSI escape sequences. Here's an example for you:
101+
102+
<Tabs groupId="oslanguage" items={["JavaScript", "Python", "PHP", "Ruby"]} persist>
103+
<Tab value="JavaScript">
104+
```javascript
105+
CatCore.enableANSI(true);
106+
CatCore.text("This is \x1b[1mBOLD\x1b[0m!");
107+
```
108+
</Tab>
109+
<Tab value="Python">
110+
```python
111+
CatCore.enableANSI(True)
112+
CatCore.text("This is \x1b[1mBOLD\x1b[0m!")
113+
```
114+
</Tab>
115+
<Tab value="PHP">
116+
```php
117+
<?php
118+
$CatCore->enableANSI(true);
119+
$CatCore->text("This is \x1b[1mBOLD\x1b[0m!");
120+
?>
121+
```
122+
</Tab>
123+
<Tab value="Ruby">
124+
```ruby
125+
CatCore.enableANSI(true)
126+
CatCore.text("This is \x1b[1mBOLD\x1b[0m!")
127+
```
128+
</Tab>
129+
</Tabs>
130+
131+
CatCore understands a lot of ANSI escape sequences: bold, dim/faint, italic, underline, inverted, striketrough, background and foreground colors (in 8/16/256/RGB color modes).

‎public/app_file_structure.png‎

108 KB
Loading

0 commit comments

Comments
 (0)