xt-sys/website
2
1
Fork 0
Code Issues Pull Requests Actions Activity

Import ExectOS Web Site
All checks were successful
Builds / ExectOS WebSite (push) Successful in 15s
Details

Browse Source 
Reviewed-on: #1
Reviewed-by: Piotr Likoski <likoski@noreply.codingworkshop.git>
Co-authored-by: Rafal Kupiec <belliash@codingworkshop.eu.org>
Co-committed-by: Rafal Kupiec <belliash@codingworkshop.eu.org>
This commit is contained in:
Rafal Kupiec
2024-06-18 23:00:02 +02:00
committed by CodingWorkshop Signing Team
parent 83270c38d4
commit 3e1a7c1932
49 changed files with 1096 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
content/contributing/building-exectos.md Normal file
View File

@@ -0,0 +1,58 @@
+++
title = 'Building ExectOS'
date = 2024-06-18T16:37:24+02:00
+++
ExectOS must be compiled with the XTChain toolchain. Make sure you have already [downloaded](/download) and installed it.
Once this is done and the source code is ready, open a terminal and launch the XTChain Build Environment.
```
xtchain
```
Then, set your target build architecture and the build type and configure the project. Choose `i686` or `amd64` depending
on the architecture you wish to target. The build type can be either `DEBUG` for debugging purposes or `RELEASE` for
a production build.
```
charch [i686|amd64]
chbuild [DEBUG|RELEASE]
./configure.sh
```
After the sources are configured, navigate to the build directory and compile the source code.
```
cd build
xbuild
```
Afterwards, you will find the binaries in `build/output/binaries` directory. Apart from that, depending on build type, you
can also find a debug symbols in PDB format in `build/output/symbols` folder and precompiled libraries that can be used to
link other software using XTDK in `build/output/library`
## Creating Qemu Disk Image
If you want to build a disk image that is ready to use with Qemu, you can use the following command:
```
xbuild diskimg
```
This will create a disk image that you can boot within a Qemu Virtual Machine, or convert to other format for use within
other hypervisor, like VirtualBox.
## Testing with Qemu
After successfully compiling ExectOS, you can test it using Qemu with either hardware virtualization (KVM) or software
emulation (TCG). To start Qemu with KVM, use the `testkvm` target, and for TCG emulation, use the `testtcg` target. These
targets are provided for convenience and you can run these commands from your build directory.
```
xbuild testkvm # For KVM hardware virtualization
```
or
```
xbuild testtcg # For TCG software emulation
```
These commands will automatically configure Qemu with the appropriate settings for ExectOS and start the virtual machine.
In addition to Qemu, you can also use Bochs for emulation. Bochs is an IA-32 (x86) PC emulator that provides a different
emulation environment. To launch Bochs with the ExectOS image, run the following command:
```
xbuild bochsvm
```
This will start the Bochs emulator with ExectOS loaded, allowing you to test the system in an environment that may offer
different debugging capabilities compared to Qemu.
Remember that the performance and debugging features will vary depending on whether you use KVM, TCG, or Bochs. KVM
requires that your host machine supports hardware virtualization, while TCG is a pure software emulator which works on
systems without hardware virtualization. Bochs provides a rich set of debugging features, which can be useful when
troubleshooting complex issues.

36
content/contributing/clean-room-guidelines.md Normal file
View File

@@ -0,0 +1,36 @@
+++
title = 'Clean Room Guidelines'
date = 2024-06-17T23:11:23+02:00
+++
You sometimes run into a need to use the [clean-room design](http://en.wikipedia.org/wiki/Clean_room_design) techniques
to work around the problem without infringing on any copyrights. While you attempt at reverse engineering, all
corresponding contributions should follow
[Council Directive 91/250/EEC](https://eur-lex.europa.eu/legal-content/EN/ALL/?uri=celex%3A31991L0250), and
[Directive (EU) 2016/943](https://eur-lex.europa.eu/eli/dir/2016/943/oj) of the European Parliament and any newer
directives related to reverse engineering. As per
[Article 6 Decompilation 1. (a)](https://eur-lex.europa.eu/legal-content/EN/ALL/?uri=celex%3A31991L0250) you must own
a legal copy/license of the software before doing any attempts at reverse engineering. The software must be officially
deprecated and/or obsolete. If you live outside of the European Union, you should follow similar rules described in legal
acts issued by the local authorities if they conform to the EU law. This especially means, that
#### You are allowed to:
* **Decompile for Interoperability**: According to the directives, decompilation is permissible when it's necessary to
achieve interoperability with other software. This means you can reverse engineer parts of the software to understand
the underlying interfaces.
* **Own a Legal Copy**: You must own a legal copy or license of the software you wish to reverse engineer. This ensures
that your starting point is within legal bounds.
* **Work with Obsolete Software**: The software you reverse engineer should be obsolete or no longer maintained by the
manufacturer. This typically applies to software that is no longer receiving updates or support.
#### You are NOT allowed to:
* **Infringe Copyrights**: You must not reproduce code or utilize proprietary algorithms from the software without
permission, as this would infringe on the copyright.
* **Break Protection Measures**: You are not permitted to crack or bypass any form of copy protection or digital rights
management that the software employs.
* **Commercially Exploit the Work**: You should not use the knowledge gained from reverse engineering for commercial
exploitation or to create direct competitors, unless you have specific agreements that allow for such activities.
* **Reveal Trade Secrets**: It is generally illegal to uncover and reveal trade secrets through the process of reverse
engineering.
Remember, laws and regulations vary by jurisdiction and change over time, so it's crucial to stay updated on the current
laws.

6
content/contributing/coding-style.md Normal file
View File

@@ -0,0 +1,6 @@
+++
title = 'ExectOS Coding Style'
date = 2024-06-18T00:20:07+02:00
+++
At the moment of writing this article, no coding style was established. You should check how existing code looks like and
follow its current formatting.

30
content/contributing/contributing-to-exectos.md Normal file
View File

@@ -0,0 +1,30 @@
+++
title = 'Contributing to ExectOS'
date = 2024-06-17T22:35:51+02:00
+++
The ExectOS project and CodingWorkshop Team always seek new contributors from all skill levels. No matter if you are
a developer, tester, designer, or techwriter, your contributions are always appreciated.
### Software Developers
We are always looking for people proficient in C and/or Assembly, especially familiar with tools such as Bochs, Qemu,
or VirtualBox. Writing an Operating System is not a beginner's task. In fact, writing an Operating System is usually
considered the most difficult programming task. Join the exclusive ranks of people knowing OSDev concepts, and yet
smaller ranks of people knowing the secrets of NT&trade; architecture.
### Testers
No software is usable if it is found to be unstable. Writing an Operating System, is yet more complex task. Tester role
is responsible for assisting the development process by running [builds](/download) and providing a feedback. All and any
information about issues you encountered during this process can be
[reported](https://git.codingworkshop.eu.org/xt-sys/exectos/issues). The more detailed report is, the easier it will be
to fix it. At least basic knowledge in collecting information from a crash, like backtraces and knowledge of using
debugger will help you. When submitting issues, take care that the bug report is not a duplicate of an already existing,
open issue. You should always follow the template specified for issues in our Gitea.
### Technical Writers
As a team, we focus mostly on OS development. We are looking for some creative people to update and write documentation,
post content to this website as well as social media accounts to promote ExectOS. New web site design ideas and bug fixes
are as well welcome.
### Community Managers
The ExectOS community keeps in touch via [Discord](/contact-us). Community Manager role is responsible to keep people
involved, keep discussions going and moderate.

38
content/contributing/developing-exectos.md Normal file
View File

@@ -0,0 +1,38 @@
+++
title = 'Developing ExectOS'
date = 2024-06-18T16:36:47+02:00
+++
We leave you free to choose your working environment, but we also recommend working with VS Code, or VS Codium. Both are
free to use, open-source IDEs, compatible with Windows, Linux, and macOS operating systems. They falls under the same
category as Atom, Sublime, and Text Wrangler, but they also has more advanced features. While the first one is am original
code editor from the Microsoft&copy;, VS Codium is essentially a telemetry-free, open-source version of VS Code.
### Recommended Extensions
* **[Clangd](https://open-vsx.org/extension/llvm-vs-code-extensions/vscode-clangd)**: helps developers write,
understand and improve C/C++ code by providing code completion, compile errors and warnings, hover information and
inlay hints, include management, code formatting and more.
* **[CMake](https://open-vsx.org/extension/twxs/cmake)**: extension provides support for CMake in Visual Studio Code.
* **[Codeium](https://open-vsx.org/extension/Codeium/codeium)**: modern coding superpower, a free code acceleration
toolkit built on cutting edge AI technology. Currently, Codeium provides autocomplete, chat, and search capabilities
in 70+ languages, with lightning fast speeds and state-of-the-art suggestion quality.
* **[GNU Assembler Language Support](https://open-vsx.org/extension/basdp/language-gas-x86)**: extension provides
language support for x86 and x86_64 assembly language in AT&T dialect.
* **[Markdown Preview Enhanced](https://open-vsx.org/extension/shd101wyy/markdown-preview-enhanced)**: extension that
provides many useful functionalities such as automatic scroll sync, math typesetting, mermaid, PlantUML, pandoc,
PDF export, code chunk, presentation writer, etc.
### Getting Started with VS Code
Opening a project in Visual Studio Code is straightforward, especially that you can find `ExectOS.code-workspace` file
in project's GIT repository. Once you checkout the source code, you can open the workspace file directly from the command
line:
```
code ExectOS.code-workspace
```
Alternatively, you can start VS Code and use the menu options:
* Open Visual Studio Code.
* Go to File > Open Workspace from File...
* Navigate to the directory containing your cloned repository.
* Select the ExectOS.code-workspace file and click Open.
VS Code will load everything defined in the workspace file, including folder structure and settings specific to the
ExectOS project. You're now ready to start working on the project.

52
content/contributing/submitting-patches.md Normal file
View File

@@ -0,0 +1,52 @@
+++
title = 'Submitting Patches'
date = 2024-06-17T23:47:42+02:00
+++
In order to review code better and use established lines of communication, we accept code in the form of Pull Requests
on our [Gitea](https://git.codingworkshop.eu.org/xt-sys/exectos/pulls) instance. The process may seem a little bit
complicated at first, but it will become very natural. It is important for us, to make sure the author and email settings
for your GIT are configured correctly. You should follow our '[Working with GIT](/contributing/working-with-git)' document,
but the key point is to use your real name and valid e-mail address. This is not just for developers to show a stronger
commitment and establish trust, but also helps discourage irresponsible programmers from submitting unacceptable code.
You will need a Gitea account which must also use your real name. You should be precise; having the names match helps in
identifying commits.
### Patch Guidelines
In order to make your patches as easy to check as possible, try to keep them small, clear, and atomic:
* Include only closely related changes in one commit.
* Don't implement extra things that no one uses.
* Try to limit each merge request to only a few commits.
* Limit a commit to changing a single file or component.
Above rules make the Pull Request easier to review.
### Commit Message
### Quality Check
It never hurts to check through your changes one last time. Take a while, to look at each line of the patch and make sure
there are no unintentional or unrelated changes. Also make sure that the layout of your code conforms to our
[coding style](/contributing/coding-style).
### Sending Pull Request
After checking in your local changes, you can submit a Pull Request on Gitea to get your changes upstream. This requires
you to be working on a Gitea fork. You should make up a temporary branch name for your changes. That branch will be deleted
once the merge request is merged, so it's better to avoid using the master branch directly.
### Managing Pull Request
After you've submitted your merge request, a reviewer will be assigned to it, if someone is responsible for that area of
the code. You can also assign a reviewer yourself if you know who the right person is. If a reviewer gives some feedback
or a critique, carefully think about what they say and fix your patch before resubmitting. When updating your changes, you
can simply push the fixes as a new commit on top of your Pull Request. This is prefferred way, as allows us to compare
code before and after your fixes. All commits can be squashed by a reviewer upon merge.
If your Pull Request remains in the queue for several weeks without being committed and without feedback, you can ask for
further suggestions on our [Discord](/contact-us) server. If you have patches rejected multiple times, don't be discouraged.
You might consider finding a mentor willing to pre-review your changes before you submit them again.
### Reviewing Pull Request
If you are asked to review a merge request, and find things that need to be improved, you should add a comment to the merge
request from the Gitea interface. You can also fix things up yourself and push updated commits to the original branch, once
submitter explicitly give you access to his GIT repository. If you think that the merge request is good to go in, you
should mark it approved. As a rule, a merge request won't be committed until all reviewers have approved it. If you have
been assigned as a reviewer but you feel that you cannot meaningfully review the changes, feel free to unassign yourself.

53
content/contributing/working-with-git.md Normal file
View File

@@ -0,0 +1,53 @@
+++
title = 'Working with GIT'
date = 2024-06-17T17:31:15+02:00
+++
The preferred method of contributing patches to ExectOS is via our self-hosted [Gitea](https://git.codingworkshop.eu.org)
instance.
### Initial Setup
First of all you will have to create an account on our [Gitea](https://git.codingworkshop.eu.org) instance. Do note that
you can also use your existing GitHub or GitLab account via OAuth. Creating new account on our Gitea is pretty straight
forward, anyway:
1. Go to our Gitea instance and click on "[Register](https://git.codingworkshop.eu.org/user/sign_up)" link in top,
right corner.
2. Fill in your information.
3. Add your SSH key(s) for easier pushing via SSH instead of HTTPS.
4. Consider also enabling 2FA for improved security access and signing your commits with GPG.
### Cloning Repositories
1. Go to Gitea's frontage after you’ve signed in and search for the repository you want to clone. Click on its name to
open it.
2. Click on 'Fork' button, to create your own copy of the repository.
3. Either clone your fork of it, with
```
git clone ssh://git@git.codingworkshop.eu.org:8822/<username>/<repository>.git .
```
or if you already cloned the repo you can add your fork as remote, with
```
git remote add <my_fork> ssh://git@git.codingworkshop.eu.org:8822/<username>/<repository>.git
```
### Proper GIT Setup
ExectOS uses GIT for Source Code Management (SCM) and GIT uses a username to associate commits with an identity. The GIT
username is not the same as your Gitea username. You can change the name that is associated with your GIT commits. The new
name you set will be visible in any future commits you push to Gitea from the command line. In order to accept your
patches, we require you to provide your real name and valid e-mail address. This can be done with the following commands:
```
git config --global user.name "<your real name>"
git config --global user.email "<your email>"
```
Above command will update username and email globally, for every repository on your computer. Alternatively, these changes
can be introduced for a single repository, by changing the current working directory to the local repository where you want
to configure the name that is associated with your GIT commits and issueing the following commands:
```
git config user.name "<your real name>"
git config user.email "<your email>"
```
### Keeping Forks Updated
You should always ensure that you have the latest version of the repository you want to work on before starting your work to
avoid duplicating work and merge conflicts. You can do so with:
```
git pull <remote> master --rebase
```

36
content/contributing/writing-documentation.md Normal file
View File

@@ -0,0 +1,36 @@
+++
title = 'Writing Documentation'
date = 2024-06-17T18:08:34+02:00
+++
Our documentation is integrated with this website and it is stored in GIT repository. This website is powered by the Hugo
Static Site Generator. All pages are created as simple Markdown files and everyone is free to submit Pull Requests to
enhance the website. This article will help you better understand the proper guidelines for submitting documentation.
### Guidelines
* **Use standard English**: Use standard United States (U.S.) English throughout all technical publications.
* **Write in active-voice**: Active voice sentences clarify the performer of an action and are easier to understand than
passive-voice sentences.
* **Use present simple tense**: Users read documentation to perform tasks or gather information. For users, these
activities take place in their present, so the present tense is appropriate in most cases.
* **Write in second person**: Users are more engaged with documentation when you use second person (that is, you address
the user as "you").
* **Use appropriate mood**: For procedures, use imperative mood.
* **Avoid ambiguous titles**: Each title should include a clear description of the page’s subject.
* **Write objectively**: Do not use humor, jargon, exclamation marks, idioms, metaphors, and other colloquialisms.
* **Write positively**: Write in a positive tone. Positive sentences improve readability.
* **Avoid personification**: Avoid the adverbs such as "probably", "hopefully", "basically", and so on.
* **Do not use contractions**: Generally, do not contract the words.
* **Use spelling and grammar checking tools**: Run text through spelling and grammar checking tools, if available.
### Testing Documentation
1. [Download](https://gohugo.io/) Hugo v0.125.7 or newer.
2. Open a shell in the root of your repository and use below command to start server
```
hugo server -DF
```
3. Open `http://localhost:1313/` in your browser to access the website and check the results.
### Submitting Patches
We welcome patches for both documentation and the website. We use the GNU Free Documentation License 1.3 or later for all
documentation and website content. Contributions using other licenses are unlikely to be accepted. Patches should be
contributed via our [Gitea instance](https://git.codingworkshop.eu.org/xt-sys/website).