|
| 1 | +# HashLink – Copilot Agent Instructions |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +HashLink is a virtual machine for the [Haxe](https://haxe.org) programming language. It can either execute `.hl` bytecode produced by the Haxe compiler (using the `hl` binary), or compile Haxe code to C for standalone native execution (HLC mode, requiring all dependent libraries but not the `hl` binary). This repository contains: |
| 6 | + |
| 7 | +- The HashLink VM (`hl` binary) and runtime library (`libhl.so`) |
| 8 | +- Optional native extension libraries (cross-platform: `fmt.hdll`, `sdl.hdll`, `ssl.hdll`, `openal.hdll`, `uv.hdll`, `mysql.hdll`, `sqlite.hdll`, `heaps.hdll`, `ui.hdll`; platform-specific: `mesa.hdll` on Linux game servers, `directx.hdll`/`dx12.hdll`/`dx12debug.hdll` on Windows) |
| 9 | +- Source code of the HashLink core library (hl/libhl) in `src/` and native extension library implementations in `libs/` |
| 10 | +- Test programs in `other/tests/` |
| 11 | +- CMake build support alongside the classic `Makefile` |
| 12 | + |
| 13 | +## Building HashLink on Linux |
| 14 | + |
| 15 | +### Install system dependencies |
| 16 | + |
| 17 | +```bash |
| 18 | +sudo apt-get update -y |
| 19 | +sudo apt-get install --no-install-recommends -y \ |
| 20 | + libmbedtls-dev \ |
| 21 | + libopenal-dev \ |
| 22 | + libpng-dev \ |
| 23 | + libsdl2-dev \ |
| 24 | + libturbojpeg-dev \ |
| 25 | + libuv1-dev \ |
| 26 | + libvorbis-dev \ |
| 27 | + libsqlite3-dev |
| 28 | +``` |
| 29 | + |
| 30 | +### Build and install |
| 31 | + |
| 32 | +```bash |
| 33 | +make |
| 34 | +sudo make install |
| 35 | +sudo ldconfig |
| 36 | +``` |
| 37 | + |
| 38 | +This installs the `hl` binary to `/usr/local/bin` and `libhl.so` plus the `.hdll` extension libraries to `/usr/local/lib`. |
| 39 | + |
| 40 | +## Compiling and Running a Haxe Program |
| 41 | + |
| 42 | +Haxe source files are compiled to HashLink bytecode with the Haxe compiler, then executed with `hl`: |
| 43 | + |
| 44 | +```bash |
| 45 | +# Compile a Haxe program to HashLink bytecode |
| 46 | +haxe --hl program.hl -cp <source-dir> -m <MainClass> |
| 47 | + |
| 48 | +# Run the bytecode |
| 49 | +hl program.hl |
| 50 | +``` |
| 51 | + |
| 52 | +Example using the test program included in the repository: |
| 53 | + |
| 54 | +```bash |
| 55 | +haxe --hl hello.hl -cp other/tests -m HelloWorld |
| 56 | +hl hello.hl |
| 57 | +``` |
| 58 | + |
| 59 | +## Running Tests |
| 60 | + |
| 61 | +The main test in the build workflow: |
| 62 | + |
| 63 | +```bash |
| 64 | +haxe -hl hello.hl -cp other/tests -main HelloWorld -D interp |
| 65 | +hl hello.hl |
| 66 | +``` |
| 67 | + |
| 68 | +To test the C output path: |
| 69 | + |
| 70 | +```bash |
| 71 | +haxe -hl src/_main.c -cp other/tests -main HelloWorld |
| 72 | +make hlc |
| 73 | +./hlc |
| 74 | +``` |
| 75 | + |
| 76 | +HashLink is mostly tested as part of the Haxe tests over at https://github.com/HaxeFoundation/haxe/tree/development/tests. There are several test suites: |
| 77 | + |
| 78 | +- `unit/` - General Unit tests |
| 79 | +- `misc/hl` - Tests expected to produce failures/warnings or assert specific stdout/stderr output |
| 80 | +- `sys/` - Tests specific to the `std/sys` package |
| 81 | +- `threads/` - Thread-related tests, generally for `std/sys/thread` package |
| 82 | + |
| 83 | +> **Note:** The latest Haxe nightly generally requires git versions of haxelibs rather than the released ones. For example: |
| 84 | +> ```bash |
| 85 | +> haxelib git utest https://github.com/haxe-utest/utest.git |
| 86 | +> ``` |
| 87 | +
|
| 88 | +## Key Source Files and Directories |
| 89 | +
|
| 90 | +| Path | Description | |
| 91 | +|------|-------------| |
| 92 | +| `src/` | Source code of the HashLink core library (hl/libhl): JIT compiler, GC, module loader, debugger | |
| 93 | +| `src/hl.h` | Main public header for embedding HashLink | |
| 94 | +| `libs/` | Native extension libraries (fmt, sdl, ssl, openal, uv, mysql, sqlite, heaps, mesa, ui, directx, etc.) | |
| 95 | +| `include/` | Vendored third-party headers (pcre2, mbedtls, sdl, etc.) | |
| 96 | +| `other/tests/` | Haxe test programs | |
| 97 | +| `other/haxelib/` | HashLink haxelib package sources | |
| 98 | +| `Makefile` | Primary build file for Linux/macOS | |
| 99 | +| `CMakeLists.txt` | CMake build file (cross-platform) | |
| 100 | +
|
| 101 | +## Code Style and Conventions |
| 102 | +
|
| 103 | +- The VM and libraries are written in **C11** (`-std=c11`). |
| 104 | +- Use `${CC}` for C compilation; `${CXX}` for C++ (only in the `heaps` library). |
| 105 | +- Follow the existing pattern of adding new native functions via `HL_PRIM` macros defined in `src/hl.h`. |
| 106 | +- New native libraries should be placed under `libs/<name>/` and expose a `DEFINE_PRIM` table. |
0 commit comments