ExectOS Operating System

Contributings

Setting up XTchain

XTchain is a script-based compilation environment designed to streamline complex build processes across multiple platforms. This guide explains how to set up and use XTchain efficiently on your system. You will learn how to launch the XTchain environment, configure your terminal for convenience, and ensure that your development setup is ready for building projects like ExectOS.

Setting Up XTchain on Linux

Setting up XTchain on Linux is designed to be as straightforward and hassle-free as possible. Once you have downloaded and extracted the XTchain archive, there is virtually no additional configuration required to get started. Simply navigate to the extracted directory and launch the main executable script:

Building ExectOS

ExectOS must be compiled with the XTChain toolchain. Make sure you have already downloaded and installed XTchain and set up the environment before proceeding. Once this is done and the source code is ready, open a terminal and launch the XTChain Build Environment.

xtchain

Next, set your target architecture and build type. You can choose between:

Architecture: i686 (32-bit) or amd64 (64-bit)
Build type: DEBUG (for development and debugging) or RELEASE (for production)

Use the following commands:

Developing ExectOS

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©, VS Codium is essentially a telemetry-free, open-source version of VS Code.

ExectOS Coding Style

This document outlines our coding style guidelines. If you have suggestions for things that should be clarified better, contact with us. With a continuous stream of contributions and patches we would like the our code base to remain clean and easy to read and maintain.

General

Each source file should contain a header:

/**
 * PROJECT:         ExectOS
 * COPYRIGHT:       See COPYING.md in the top level directory
 * FILE:            path/to/source/file.c
 * DESCRIPTION:     Description of the purpose of the code in this file
 * DEVELOPERS:      Your Name <name@codingworkshop.eu.org>
 */

You should only add yourself to the developer list if you are making a significant contribution, which means you understand the purpose of the code in this file and you can provide support to anyone.

Submitting Patches

In order to review code better and use established lines of communication, we accept code in the form of Pull Requests on our Gitea 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’ 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.

Clean Room Guidelines

You sometimes run into a need to use the 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, and Directive (EU) 2016/943 of the European Parliament and any newer directives related to reverse engineering. As per Article 6 Decompilation 1. (a) 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

Contributing to ExectOS

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™ architecture.

Writing Documentation

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

Download Hugo v0.125.7 or newer.
Open a shell in the root of your repository and use below command to start server
```
hugo server -DF
```
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.

Working with GIT

The preferred method of contributing patches to ExectOS is via our self-hosted Gitea instance.

Initial Setup

First of all you will have to create an account on our Gitea 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:

Go to our Gitea instance and click on “Register” link in top, right corner.
Fill in your information.
Add your SSH key(s) for easier pushing via SSH instead of HTTPS.
Consider also enabling 2FA for improved security access and signing your commits with GPG.

Cloning Repositories

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.
Click on ‘Fork’ button, to create your own copy of the repository.

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: