HyperCPU - the hyper toolkit for custom hyper ISA

What is it? | Roadmap | Installation | Usage | Contributing | Authors | License

Important

HyperCPU is almost ready for use! Wait for 1.0 release to try it out or build the project locally, test and report found issues.

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.

Installation

At the moment of writing this text, HyperCPU installation is done by building the whole project from source code. 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 or 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:

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 (2024 - present time) - idea, code, documentation.
• Ivan Movchan (2025 - present time) - artwork.

License

HyperCPU is a free software licensed under GNU General Public License 3.0.