diff options
| -rw-r--r-- | BUILD.md | 73 | ||||
| -rw-r--r-- | CHANGELOG.md | 1 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 167 | ||||
| -rw-r--r-- | README.md | 115 |
4 files changed, 293 insertions, 63 deletions
diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 0000000..2e9c87d --- /dev/null +++ b/BUILD.md @@ -0,0 +1,73 @@ +## Requirements + +1. Compiler toolset chose in the toolchain file + * GCC cross compiler toolchain (arch-elf-tool - i686-elf-g++ for compiler) + + To build and install from source refer to the [documentation](https://gcc.gnu.org/install) + + * Clang cross compiler toolchain + Clang support cross compile out the box. + + You can download *clang* from your package manager. + + Using *apt*: + + ```bash + apt-get update && apt-get install clang + ``` + + Using *pacman*: + + ```bash + pacman -Sy clang + ``` + + Or build from source consider the [documentation](https://clang.llvm.org/get_started.html) + +2. Nasm compiler (for x86 only) + + To download from package manager. + + Using *apt* + + ```bash + apt-get update && apt-get install nasm + ``` + + Using *pacman* + + ```bash + pacman -Sy nasm + ``` + +3. Grub bootloader (only it is currently supported) + + It is reccommended to build grub from source configured target as chose +architecture. + + To build grub from source refer to the [documentation](https://www.gnu.org/software/grub/manual/grub/html_node/Obtaining-and-Building-GRUB.html) + +## Kernel configuration +You can configure kernel using cmake -D option. All cmake options build-in are supported + +### Options +Not yet available options + +## Build instructions + +### On your host environment +``` +cmake -DCMAKE_TOOLCHAIN_FILE=<FILE> -D<OPTION>=<VALUE> -B build +cmake --build build +# Create iso file using *grub-mkrescue* +# Assume GRUB configured and built to a chose architecture +mkdir -p iso/os +cp build/Objective iso/os +grub-mkrescue -o build/kernel.iso iso +``` + +After you can create virtual machine or using emulator to run kernel. +For qemu and x86 architecture: +```bash +qemu-system-i386 -cdrom build/kernel.iso +``` diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5e9b10f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1 @@ +## No recent releases diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a488123 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,167 @@ +## Table of content + +- [I have a question](#i-have-a-question) +- [I want to contribute](#i-want-to-contribute) +- [Style guide](#style-guide) +- [Git branching workflow](#git-branching-workflow) +- [Sending a patch](#sending-a-patch) + * [Gerrit](#gerrit) + * [Github](#github) + * [Email](#email) +- [Suggesting enhancement](#suggesting-enhancement) +- [Reporting a bug](#reporting-a-bug) +- [Commit message](#commit-message) +- [Discussion lists](#discussion-lists) + +## I have a question +**Before to ask a question, ensure that information already has in markdown files** + +It is best to search for existing issue on github or topic in discussion list. +In case you have a suitable issue/topic and still need clarification, write your +question there. + +If you then still feel the need to ask a question and need clarification, we recommend the following: + +- Open issue/topic. +- Provide as much context as you can about what you are running into. + +We will then take care of the issue an soon as possible. + +## I want to contribute +You need to find an idea firstly. Look through open issues, discussions and bugs lists or [TODO.md](TODO.md) file. +Try to build a project from `develop` or `release` branch and debug kernel to +find some bugs. [BUILD.md](BUILD.md) file contains instruction to build a source +code. As a non expert coder is is a hugely useful way to contribute to a +project. + +When you find or already have ideas, not to rush write a code. + +Ask yourself these questions firstly: + +- What is the kind of problem i am trying to solve? +- What are the exact semantics/behaviours? +- How it affect on others system components and kernel at all? +- It is enough at this level of details? Or need dive deep? + +And publish your thoughts in corresponding discussions or +bugs list to except waste a time to write irrelevant code. + +**Push the patch directly if it solve an obvious problem.** + +See [suggesting enhancement](#suggesting-enhancement) or [reporting a bug](#reporting-a-bug) section. + +Once solution is reached, write a code and push patch to review. +See [style guide](#style-guide) and [sending a patch](#sending-a-patch) sections. + +## Style guide +Use google code style (unfinished section) + +## Git branching workflow +This model branching is based on [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) +except standalone `feature` branch intend to request to create a new feature +branch and no release branches (they are replaced by tags in `main` branch). +Bug branches are similar to feature branches in workflow, but purposes are +differ. `email` branch indent to receive patches from email and used by gerrit +instance when pushing to review. + +## Sending a patch +**`CMakeCache.txt` file must is attached to the commit** + +Before to submit a patch, please read its whole. Make sure there are no unintended changes and fix them. +Trailing whitespaces, empty commits, test code, bad words and etc. must be deleted. + +Pay attention to a commits count. Stick to following rule: the less the better. +One commit is most preferable. Two and more commits must be divided by particular patches. +Important to send a good readable patch using comments, appropriate variable and +functions names, break the code into semantic parts and etc. + +Choose the proper branch to merge. Standalone `bug` and `feature` branches using to create a not +present issue in repository. Specific feature or `bugfix*` refer to a present +issue. `email`, `main` and `develop` branches are autonomics, and used not for to submit a changes. + +Make sure that the patch includes tests to check updates work properly. Try to +accomplish greatest code coverage. + +Supply a patch with following information; Do not format your description like +you are filling out a form. + +- Name of topic in discussions or bugs list +- What patch does in a short paragraph. +- Which branch the patch is against. +- Which subsystem and module have touched. +- Describe the effect your patch has on performance, if any. +- Include documentation on how to use a new function with examples. + +You can submit updates three ways: gerrit instance, Github PR or email. Gerrit +is most prefer method. Github and email are less desirable. All links you can +find in [README.md](README.md) file in link section. + +All received patches are send to a gerrit instance and reviewed. Verification run by +CI/CD server. Stages ran on the server: kernel configuration, source code building and tests execution. If no error while stages running, verification passed. +Patch might be returned if verification or code review not passed. CI/CD +provides a link to a executed pipeline where you can get acquainted with +detailed log on a patch page. Or get a feedback if code review is failed. + +Apply required changes and resubmit the patch to gerrit to resume review +process. Resubmit the patch from github or email is not allowed now. + +## Suggesting enhancement +Step following points to submit a good enhancement suggestion: + +- Use a clear and descriptive title for the issue to identify the suggestion. +- Provide a step-by-step description of the suggested enhancement in as many details as possible. +- Describe the current behavior and explain which behavior you expected to see instead and why. At this point you can also tell which alternatives is losing. +- Explain why this enhancement would be useful to most CONTRIBUTING.md users. You may also want to point out the other projects that solved it better and which could serve as inspiration. + +Create a new topic in discussions list or add your thoughts if topic is already +created. **Please be kind and patient to all community members.** + +Enhancement suggestions are tracked in discussion lists. + +## Reporting a bug +When you spot the problem, it is a good practice to report this. I'm trying to +provide description how to report a bug in a right way, that help me to fix a +error pretty soon. + +Before submitting a bug report determine if your bug is a bug and not a error +on your side e.g. using incompatible tools/versions. Ensure that the report has +a fully information to not a chase you up for more details. Get a much useful +information into your message as you can. The developer will need to reproduce +your problem before try and fix it. Do not just say "It is broken" or "It +crashed". + +Attach the following information: + +- Version of the kernel. +- Explain the behavior you would expect and the actual behaviour. +- Exactly what steps did you take to trigger the bug? +- `CMakeCache.txt` file content. +- If possible provide an exact example that demonstrates your problem. This +could be a code snippet or display content from emulator or something else. +Create the minimum working example that demonstrates your problem. Remove +anything that is unnecessary as this might introduce different problems or +obscure the issue. + +Also check to see if the problem has been reported before. This could mean +searching for resolved problems as well as unresolved ones. + +If you find your bug already reported, but you can provide more information on +the problem, then add this to the discussion as it will help the developer solve +it. + +You can use bugs mailing list or github issues to report a bug. + +## Commit message +Use the following [format](https://wiki.openstack.org/wiki/GitCommitMessages) to +write a pretty commit message. Descriptive and structured message is better to +allow to build a representation of changes in mind. Do not use short messages +consists of a only header. Developer is not to try a solve puzzles if a good message +is not provides. + +## Email lists +There are three email list current. `Discussions list` needs to share a +enhancements with others developers. `Bugs list` uses to publish findings bugs. +And last list is `patches` to send source code changes. + +Anyone can to write and read someone list without an invitation. +Any activity is welcome :) @@ -1,63 +1,52 @@ -## Objective Operating System - -## Install dependencies - -#### Ubuntu - -```sh -sudo apt update -y -sudo apt -y install build-essential binutils nasm xorriso grub-common qemu-system-i386 mtools -``` - -You need to build GCC cross compiler for i686 or x86_64 supports x32 architecture/s to compile from sources. -Also required gcc and stdc++ libraries. -Refer to GCC documentation for detailed information - <https://gcc.gnu.org/install/> - -## Build and run - -Before build the project set some variables - DEBUG and LIBS_PATH. -These variables may pass through *make* command `make *variables* *rule*`, or usage environment variables `export *name*=*value*`. - -#### Variables - -1. DEBUG. Not takes value. If defineŠ², the debug version of the project will be build, otherwise the release version. Responsible for the debug version of the project to test OS via GDB. -2. LIBS_PATH. Takes the path to the required libraries. Now gcc library is required, supplied with the compiled. - -#### Ubuntu - -Build and run release version -```sh -make all -``` - -Build and run debug version -```sh -make DEBUG=* all -``` -or -```sh -export DEBUG=* -make all -``` - -## Docs - -- [Link on collection of articles "How startup app without OS"][1] -- [The GNU GRUB manual][2] -- [Executable and linkable format ELF][3] -- [NASM documentation][4] -- [Article about creatiing a simple OS][5] -- [Multiboot specification][6] -- [GCC compiler documentation][7] -- [Using NASM in a Hello World kernel][8] -- [Video memory ports x86][9] - -[1]:https://habr.com/ru/companies/neobit/articles/173263/ -[2]:https://www.gnu.org/software/grub/manual/grub/grub.pdf -[3]:https://www.cs.cmu.edu/afs/cs/academic/class/15213-f00/docs/elf.pdf -[4]:https://www.nasm.us/xdoc/2.16.01/nasmdoc.pdf -[5]:https://wiki.osdev.org/Bare_Bones#Writing_a_kernel_in_C.2B.2B -[6]:https://www.gnu.org/software/grub/manual/multiboot/multiboot.pdf -[7]:https://gcc.gnu.org/onlinedocs/gcc.pdf -[8]:https://wiki.osdev.org/Bare_Bones_with_NASM -[9]:https://stackoverflow.com/questions/17367618/address-of-video-memory +# Objective Kernel Project + +## Table of Contents + +- [Description](#Description) +- [Build](#Build) +- [Contributing](#Contributing) +- [Community](#Community) +- [Links](#Links) + +## Description +Objective Kernel is a project of operation system kernel which is based on the +principle: *Everything represents in objects*. + +Object is abstraction to interact with further objects. Such object has type +including some data set to exist instance of this object type, properties and +events sets. For instance, some objects can have the persistence property means +to memory current object state. + +Property is a operation with like or unlike object type. For instance, addition of +two numbers/number and variable, transaction following ACID, persistence or +partial persistence. + +Event is reacting on some changes in system: a field object's changing or a signal +from connected device. + +Kernel also support the objected-oriented methods: inheritance, encapsulation +and polymorphism. + +This helps to construct physical and mathematical models systems where each +object interact with others objects using properties and events. + +## Build +Consider the [BUILD.md](BUILD.md) file to get the build guideline and +options for kernel configuration. + +## Contributing +Ways and terms to participant in project development described in [CONTRIBUTING.md](CONTRIBUTING.md) +file + +## Community +[Discussions mailing list](https://groups.io/g/objective-project-discussions) +[Github issues](https://github.com/ObjectiveOS/objective/issues) + +## Links +* [github](https://github.com/ObjectiveOS/objective) +* [cgit](http://git-ddns-to-devserv.duckdns.org/) +* [gerrit](https://gerrit-ddns-to-devserv.duckdns.org) +* [GoCD](https://gocd-ddns-to-devserv.duckdns.org) +* [Mailing list (discussions)](https://groups.io/g/objective-project-discussions) +* [Mailing list (bugs)](https://groups.io/g/objective-project-bugs) +* [Mailing list (patches)](https://groups.io/g/objective-project-kernel-patches) |