-
- | - -HyperCPU is a set of programs, created to work with my own simple ISA. -Project was created for fun, but took a lot of time, and i learned a lot in process. - - | -
+ + What is it? + | + Roadmap + | + Installation + | + Usage + | + Contributing + | + Authors + | + License +
+ +
+
+ 
+
+## What is it?
+
+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 toolkit includes:
+* **hCPU emulator**;
+* **hASM assembler**;
+* **hASM disassembler**.
+
+>[!WARNING]
+> HyperCPU supports Linux systems only. Do not even try to build it under Windows.
+
+## Roadmap
+
+You can find the project roadmap [here](ROADMAP.md).
+
+## Installation
+
+At the moment of writing this text, HyperCPU installation is done by building the whole project from source codes. Maybe one day HyperCPU will start distributing release tarballs for much easier installation, but who knows.
+
+### Building from source codes
+
+HyperCPU requires these tools and libraries:
+
+* C++ compiler with C++23 standard support (i. e. `gcc` >= `14`);
+* `clang` >= `19`;
+* `cmake`, `ninja` - build systems;
+* `re2` - regular expressions parser;
+* `libfmt` - formatting library;
+* `googletest` - required for building tests in Release build profile;
+* `python3`, `python3-pip`, `sphinx` and `sphinx-rtd-theme` (should be installed through `pip` or your system package manager) - required for building a documentation.
+
+There are a few options (definitions) that can be used with `cmake`:
+* `CMAKE_BUILD_TYPE`:`STRING` - project build profile (`Release` or `Debug`), should be always specified;
+* `HCPU_SANITIZERS_ENABLED`:`BOOL` - HyperCPU sanitizers (enabled by default); use `-DHCPU_SANITIZERS_ENABLED:BOOL=OFF` to disable them.
+
+After installing dependencies, open the terminal and run these commands:
+
+```bash
+git clone https://github.com/HyperWinX/HyperCPU --recursive
+cd HyperCPU
+cmake -S. -Bbuild -G "Ninja" -DCMAKE_BUILD_TYPE=Release
+ninja -C build default -j$(nproc)
+```
+
+That's all. The compiled binaries should be located in `build` directory.
+
+Run `cd docs && make html` to build a documentation. After that go to `docs/_build/html` directory, open `index.html` and start reading.
+
+## Usage
+
+```
+Usage: hcasm [--help] [--version] [-o VAR] [-c] [-v VAR] source
+
+Positional arguments:
+ source source file to be assembled [required]
+
+Optional arguments:
+ -h, --help shows help message and exits
+ -v, --version prints version information and exits
+ -o name of the binary file
+ -c compile to object file
+ -v set verbosity level. possible modes:
+ - debug
+ - info
+ - warning
+ - error [nargs=0..1] [default: "warning"]
+
+Usage: hcemul [--help] [--version] [-v VAR] binary
+
+Positional arguments:
+ binary binary file to execute [required]
+
+Optional arguments:
+ -h, --help shows help message and exits
+ -v, --version prints version information and exits
+ -v set verbosity level. possible modes:
+ - debug
+ - info
+ - warning
+ - error [nargs=0..1] [default: "debug"]
+```
+
+## Contributing
+
+HyperCPU is in active development, and we will be happy to hear any feedback from you. Do not hesitate to report bugs or suggest any ideas using "Issues" page.
+
+>[!IMPORTANT]
+>Please send your pull requests to `dev` repository branch (not `master`).
+
+Thank you for your interest in HyperCPU.
+
+## Authors
+
+* [HyperWin](https://github.com/HyperWinX) (2024 - present time) - idea, code, documentation.
+* [Ivan Movchan](https://github.com/ivan-movchan) (2025 - present time) - artwork.
+
+## License
+
+HyperCPU is a free software licensed under [GNU General Public License 3.0](LICENSE).
\ No newline at end of file
diff --git a/roadmap.md b/ROADMAP.md
similarity index 100%
rename from roadmap.md
rename to ROADMAP.md
diff --git a/examples/hello_world.s b/examples/hello_world.s
new file mode 100644
index 00000000..acee77d2
--- /dev/null
+++ b/examples/hello_world.s
@@ -0,0 +1,16 @@
+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;
\ No newline at end of file
diff --git a/git/logo.png b/images/logo.png
similarity index 100%
rename from git/logo.png
rename to images/logo.png
diff --git a/git/logo_dark.png b/images/logo_dark.png
similarity index 100%
rename from git/logo_dark.png
rename to images/logo_dark.png
diff --git a/images/screenshot.png b/images/screenshot.png
new file mode 100644
index 00000000..0af2b7d8
Binary files /dev/null and b/images/screenshot.png differ
-