Project logo, README and code examples updates

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# HyperCPU Contributing Guidelines
+
+This file describes the contributing guidelines of the project.
+
+If you are going to work with code, we strongly recommend reading [Coding style](#coding-style) section at the end of file.
+
+## Project collaborators
+
+Clone repository locally and create a new branch from `master` with some senseful name.
+
+> [!TIP]
+> Ask yourself: what are you going to do? What feature are you going to implement (or what bug are you going to fix)?
+> 
+> **Examples of BAD branch names:** `r0ego03rg750yt3w4p37w8ypt98bo4wy49wyeuys9o49suebs9o84y3p47304p34bt3tb5o94ba0843twp`, `vasyapupkinwashere`.
+>
+> **Examples of GOOD branch names:** `fix-zero-division-error`, `implement-windows-support`.
+
+Do your work on that branch, but **do not** touch others. Every push to any branch except `master` starts a CI workflow with minimal tests.
+
+When you are ready, make a pull request (PR) to `master` branch. When the PR gets created, you have to track following checks: `CodeQL`, `Codacy`, main CI workflow that runs extended tests, and the job that builds the project on multiple platforms.
+
+If MentatBot tells you what can be improved, it is better that you improve it :)
+
+When all CI jobs finish successfully, just wait for project owner to review and approve your work and, finally, merge your PR.
+
+Voila! Your changes have been merged and accepted to the project.
+
+## Contributors
+
+The same stuff as for project collaborators, except that you also have to fork the repository and work there. You will probably have to disable GitHub Actions or connect the self-hosted runner (no guarantee that HyperCPU workflows will execute successfully on custom runner).
+
+## Coding style
+
+### Identifiers
+
+Use *PascalCase* for namespaces, class names and functions; *snake_case* for local variables and class fields.
+
+### Tabs
+
+2 spaces long.
+
+### Whitespaces
+
+A single space should be between operators, and no spaces should be between parenthesis and arguments.
+
+```cpp
+namespace HyperCPU {
+  ...
+}
+
+class CPU {
+  private:
+    bool is_hypercpu_cool = true;
+}
+
+void HyperCPU::CPU::CPU() {
+  int magic_number = 0xDEADBEEF;
+  std::exit(1337 * 42);
+}
+```

README.md

@@ -1,36 +1,16 @@
 <div align="center">
-     <picture>
-          <source media="(prefers-color-scheme: dark)" srcset="images/logo_dark.png">
-          <source media="(prefers-color-scheme: light)" srcset="images/logo.png">
-          <img alt="HyperCPU" src="images/logo.png">
-     </picture>
+    <img alt="HyperCPU" src="images/logo.png">
+    <h1>HyperCPU</h1>
+    <p>
+        <a href="https://github.com/HyperWinX/HyperCPU/issues"><img src="https://img.shields.io/github/issues/HyperWinX/HyperCPU" alt="GitHub opened issues"></a>
+        <img src="https://img.shields.io/badge/version-0.5.2-red" alt="Version">
+        <img src="https://img.shields.io/github/actions/workflow/status/HyperWinX/HyperCPU/testing.yml?branch=dev" alt="CI status">
+        <img src="https://img.shields.io/badge/status-in_development-red" alt="Status">
+        <img src="https://img.shields.io/github/license/HyperWinX/HyperCPU" alt="License">
+        <img src="https://img.shields.io/github/stars/HyperWinX/HyperCPU?color=lime" alt="Stars">
+    </p>
 </div>
 
-<h4 align="center">HyperCPU — the <i>hyper</i> toolkit for custom <i>hyper</i> ISA</h4>
-
-<p align="center">
-     <a href="https://github.com/HyperWinX/HyperCPU/issues">
-     <img src="https://img.shields.io/github/issues/HyperWinX/HyperCPU"
-          alt="GitHub opened issues"></a>
-     <img src="https://img.shields.io/badge/version-0.5.2-red"
-          alt="Version">
-     <img src="https://img.shields.io/github/actions/workflow/status/HyperWinX/HyperCPU/testing.yml?branch=dev"
-          alt="CI status">
-     <img src="https://img.shields.io/badge/status-in_development-red"
-          alt="Status">
-     <img src="https://img.shields.io/github/license/HyperWinX/HyperCPU"
-          alt="License">
-     <img src="https://img.shields.io/github/stars/HyperWinX/HyperCPU?color=lime"
-          alt="Stars">
-</p>
-
->[!IMPORTANT]
-> HyperCPU is almost ready for use! Wait for 1.0 release to try it out or build the project yourself, test it and report issues.
-
-<img alt="HyperCPU screenshot" src="images/screenshot.png">
-
-### What is this
-
 HyperCPU is a set of programs created to work with my own simple ISA (instruction set architecture). The project was created for fun, but it took a lot of time (and nerves), and I learned a lot while working on it.
 
 HyperCPU project includes:
@@ -40,10 +20,15 @@ HyperCPU project includes:
 
 See [ROADMAP.md](ROADMAP.md) for project ideas and tasks.
 
+>[!IMPORTANT]
+> HyperCPU is almost ready for use! Wait for 1.0 release to try it out or build the project yourself, test it and report issues.
+
+<img alt="HyperCPU screenshot" src="images/screenshot.png">
+
 ### Installation
 
 >[!WARNING]
-> HyperCPU supports 64-bit GNU/Linux systems only. It is known to be successfully built and running on `amd64` and `aarch64` architectures.
+> HyperCPU supports GNU/Linux systems only. It is known to be successfully built on `x86_32`, `x86_64` and `ARMv8` architectures.
 >
 > HyperCPU fails to build and/or work properly under \*BSD systems ­— please do not ask us for support of these systems. Windows support is also not planned.
 
@@ -55,37 +40,41 @@ Pre-compiled binaries are currently not available. Sorry.
 
 Building HyperCPU requires these dependencies to be installed:
 
-* **C++20 compilers:** GCC 12+, Clang 14+.
-* **Build system:** Bazel.
-
-Generating the documentation in HTML format requires Python 3 and a few modules (`python3-sphinx`, `python3-sphinx-rtd-theme`) to be installed.
+* GCC `>=12` or Clang `>=14`;
+* GNU make (required for documentation).
+* Bazel `>=8.2.1` (recommended using Bazelisk for installation).
+* Python `>=3.6` with additional modules:
+    * `conan` (should be installed with `--break-system-packages` flag);
+    * `sphinx` and `sphinx-rtd-theme` (required for documentation).
 
-After installing dependencies run these commands in the terminal:
+After installing dependencies build the project by executing these commands:
 
 ```bash
-git clone --recursive https://github.com/HyperCPU-Project/HyperCPU
+git clone --recursive https://github.com/HyperCPU-Project/HyperCPU # Clone the repository.
 cd HyperCPU
-bazel build //src/... --config=linux-opt
-cd docs
-make html
+conan profile detect && conan install . --build=cmake --build=missing # Download and compile dependencies.
+bazel build //src/... --config=linux-opt # Build the project.
+ln -s bazel-bin/src/Assembler/hcasm hcasm # Make symlink to hcasm.
+ln -s bazel-bin/src/Emulator hcemul # Make symlink to hcemul.
 ```
 
-The compiled binaries should be located in `bazel-out` directory, and the generated documentation should be located in `docs/_build/html` directory. After building the project open `index.html` file and start reading the documentation.
+Building documentation should not be hard too:
 
-To run the resulting binaries without searching for them in `bazel-out`, use `bazel run`.
 ```
-bazel run //src/Assembler:hcasm -- <args>
-bazel run //src/Emulator:hcemul -- <args>
+cd docs
+make html
 ```
 
-Check out [examples](examples) folder for interesting code examples that will help you better understand the syntax of hASM and the power of HyperCPU.
+After building documentation open `docs/_build/html/index.html` and start reading.
 
 ### Usage
 
+Check out [examples](examples) folder for interesting code examples that will help you better understand the syntax of hASM and the power of HyperCPU.
+
 #### `hcasm` (hASM assembler)
 
 ```bash
-$ ./hcasm [-h] [--help] [--version] [-o VAR] [-c] [-V VAR] source
+$ ./hcasm [-h | --help] [--version] [-o VAR] [-c] [-V VAR] source
 ```
 
 * `source` — source code file to be compiled.
@@ -98,33 +87,27 @@ $ ./hcasm [-h] [--help] [--version] [-o VAR] [-c] [-V VAR] source
 #### `hcemul` (hCPU emulator)
 
 ```bash
-$ ./hcemul [-h] [--help] [--version] [-v VAR] [-m VAR] [--memory VAR] binary
+$ ./hcemul [-h | --help] [--version] [-v VAR] [-m | --memory VAR] binary
 ```
 
 * `binary` — binary file to be executed.
 * `-h`, `--help` — display help message and exit.
 * `--version` — display program version and exit.
 * `-v VAR` — specify verbosity level (`debug`, `info`, `warning`, `error`). Default value is `warning`.
-* `-m`, `--memory` — specify max. memory amount to be used. Postfixes are supported. Default value is `8K`.
+* `-m` (`--memory`) `VAR` — specify max. memory amount to be used. Postfixes are supported. Default value is `8K`.
 
 ### Contributing
 
-We will be happy to hear any feedback from you. Do not hesitate to report bugs or suggest any ideas using "Issues" page.
-
-Want to contribute to the project? Read [CONTRIBUTION.md](CONTRIBUTION.md) firstly.
-
-Thank you for your interest in HyperCPU.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contributing guidelines.
 
 ### Authors
 
-* **[HyperWin](https://github.com/HyperWinX) (2024 - present time)** — HyperCPU Project founder, lead developer and documentation author.
-* **[Ivan Movchan](https://github.com/ivan-movchan) (2025 - present time)** — beta tester, artist and just a contributor.
-* **[AshFungor](https://github.com/AshFungor) (2025 - present time)** — good contributor:)
+HyperCPU is brought to you by these wonderful people:
 
-### License
-
-HyperCPU is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+* **[HyperWin](https://github.com/HyperWinX)** — project founder, lead developer and documentation author.
+* **[Ivan Movchan](https://github.com/ivan-movchan)** — project artist, tester, code examples author and just a contributor.
+* **[AshFungor](https://github.com/AshFungor)** — just a good contributor :)
 
-This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+### License
 
-You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
+HyperCPU is free software released under the terms of the [GNU General Public License v3.0](LICENSE).

ROADMAP.md

@@ -1,6 +1,6 @@
 # HyperCPU Roadmap
 
-This document describes the roadmap of the project (some kind of TODO-list).
+This file describes the roadmap of the project (some kind of TODO-list).
 
 ### *Release 1.0*
 

examples/compare.s

@@ -0,0 +1,49 @@
+/*
+ * This program compares 2 values in x0 and x1 registers and displays a message depending on the result of comparison.
+ *
+ * Written by Ivan Movchan <ivan.movchan.07@gmail.com> in 2025.
+ */
+
+str_equal:
+  .b8 "x0 = x1\n";
+  .b8 0u0;
+
+str_greater:
+  .b8 "x0 > x1\n";
+  .b8 0u0;
+
+str_less:
+  .b8 "x0 < x1\n";
+  .b8 0u0;
+
+.attr(entry) main:
+  mov x0, 0u42;
+  mov x1, 0x13;
+  cmp x0, x1;
+  jme is_equal;
+  jmgr is_greater;
+  jml is_less;
+
+is_equal:
+  mov x3, str_equal;
+  jmp print;
+
+is_greater:
+  mov x3, str_greater;
+  jmp print;
+
+is_less:
+  mov x3, str_less;
+  jmp print;
+
+print:
+  mov xlll0, 0u0;
+  mov xlll2, [x3];
+  cmp xlll2, 0u0;
+  jme print_end;
+  write xlll0, xlll2;
+  inc x3;
+  jmp print;
+
+print_end:
+  halt;

examples/escape-sequences.s

@@ -0,0 +1,42 @@
+/*
+ * This program demonstrates how HyperCPU can handle ANSI escape sequences [1].
+ * They can be used for displaying a colorful text or moving a cursor.
+ * String literals are used — see hello-world.s for details.
+ *
+ * Written by Ivan Movchan <ivan.movchan.07@gmail.com> in 2025.
+ *
+ * [1] https://en.wikipedia.org/wiki/ANSI_escape_code
+ */
+
+data:
+  .b8 "\e[1;37m";
+  .b8 "#       #                                          #######  ########  #       #\n";
+  .b8 "#       #                                         #       # #       # #       #\n";
+  .b8 "#       # #       # ########   #######  # ######  #         #       # #       #\n";
+  .b8 "#       # #       # #       # #       # ##      # #         #       # #       #\n";
+  .b8 "######### #       # #       # #       # #         #         ########  #       #\n";
+  .b8 "#       # #       # #       # ########  #         #         #         #       #\n";
+  .b8 "#       # #       # #       # #         #         #         #         #       #\n";
+  .b8 "#       # #       # #       # #       # #         #       # #         #       #\n";
+  .b8 "#       #  ######## ########   #######  #          #######  #          ####### \n";
+  .b8 "                  # #\n";
+  .b8 "                  # #\n";
+  .b8 "          #       # #\n";
+  .b8 "           #######  #\n\n";
+  .b8 "                      https://hypercpu-project.github.io/                      \n";
+  .b8 "\e[0m";
+  .b8 0u0;
+
+.attr(entry) main:
+  mov x1, data;
+
+print:
+  mov xlll2, [x1];
+  cmp xlll2, 0u0;
+  jme print_end;
+  write xlll0, xlll2;
+  inc x1;
+  jmp print;
+
+print_end:
+  halt;

examples/hello-world-legacy.s

@@ -0,0 +1,25 @@
+/*
+ * This is a simple "Hello World" program written in HyperCPU assembly (hASM).
+ * It writes a string to the console char by char, then writes a newline byte (0x10) and halts CPU.
+ *
+ * If you are interested in more modern (and simple?) way of displaying text in console, see hello-world.s.
+ *
+ * Written by Ivan Movchan <ivan.movchan.07@gmail.com> in 2025.
+ */
+
+main:
+  write xlll0, 'H';
+  write xlll0, 'e';
+  write xlll0, 'l';
+  write xlll0, 'l';
+  write xlll0, 'o';
+  write xlll0, ',';
+  write xlll0, ' ';
+  write xlll0, 'w';
+  write xlll0, 'o';
+  write xlll0, 'r';
+  write xlll0, 'l';
+  write xlll0, 'd';
+  write xlll0, '!';
+  write xlll0, 0u10;
+  halt;

examples/hello-world.s

@@ -0,0 +1,26 @@
+/*
+ * This is another simple "Hello World" program written in HyperCPU assembly (hASM).
+ * It writes a null-terminated string to the console using string literals and a little loop, then halts CPU.
+ *
+ * Before 0.4.5 version you could have to write a string char by char — see hello-world-legacy.s for details.
+ *
+ * Written by Ivan Movchan <ivan.movchan.07@gmail.com> in 2025.
+ */
+
+data:
+  .b8 "Hello, world!\n";
+  .b8 0u0;
+
+.attr(entry) main:      // Program entry point.
+  mov x1, data;
+
+print:
+  mov xlll2, [x1];
+  cmp xlll2, 0u0;     // Is NULL (0u0)?
+  jme print_end;      // Yes — go to finish.
+  write xlll0, xlll2; // No — write data to console.
+  inc x1;
+  jmp print;
+
+print_end:
+  halt;