diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..c1eedf9 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,6 @@ +.git +.github +vendor +.var +.cache +www.pid diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..94a04c2 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,44 @@ +name: Build and test + +on: + push: + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + hack: + runs-on: ubuntu-24.04 + timeout-minutes: 20 + env: + COMPOSE_PROJECT_NAME: hack-dev-ci + PORT: 18080 + steps: + - uses: actions/checkout@v7.0.1 + - name: Match the workspace owner + run: echo "HACK_UID=$(id -u)" >> "$GITHUB_ENV" + - name: Validate Compose and build the image + run: | + docker compose config --quiet + docker compose build --pull + - name: Install dependencies and check Hack + run: | + docker compose run --rm --no-deps hack-dev-ubuntu sh -eu -c ' + composer install --prefer-dist --no-progress + composer validate --no-check-publish + composer check-platform-reqs + composer test + composer lint + composer typecheck + ' + - name: Check the HTTP endpoint + run: | + docker compose up -d --wait --wait-timeout 240 + test "$(curl --fail --silent http://127.0.0.1:18080/hello.hack)" = 'Hello World!' + - name: Show logs and clean up + if: always() + run: | + docker compose logs --no-color + docker compose down diff --git a/.gitignore b/.gitignore index bc77797..eff5e0a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ vendor/ www.pid -Dockerfile -.var/ \ No newline at end of file +.var/ +.cache/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..4304eef --- /dev/null +++ b/Dockerfile @@ -0,0 +1,48 @@ +# syntax=docker/dockerfile:1 +# HHVM's last published distro package requires Ubuntu 20.04 libraries. +FROM ubuntu:20.04 + +ARG TARGETARCH +ARG COMPOSER_VERSION=2.11.1 +ARG COMPOSER_SHA256=6f1b891e1d4927d62740276c540fb490e47689e19e102c49e8da849794882f8c + +ENV HHVM_DISABLE_NUMA=true \ + HHVM_DISABLE_PERSONALITY=true \ + COMPOSER_NO_INTERACTION=1 + +RUN test "$TARGETARCH" = amd64 \ + && apt-get update \ + && DEBIAN_FRONTEND=noninteractive apt-get upgrade -y \ + && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ + ca-certificates curl git lsof php-cli php-curl php-mbstring php-xml unzip \ + && rm -rf /var/lib/apt/lists/* + +# dl.hhvm.com's HTTPS certificate has expired. Verify the frozen package by +# its published SHA-256 instead of disabling TLS verification for downloads. +RUN curl -fL --retry 3 \ + http://dl.hhvm.com/ubuntu/pool/main/h/hhvm/hhvm_4.172.1-1~focal_amd64.deb \ + -o /tmp/hhvm.deb \ + && echo 'ee567aa0f7eee3c00a73e9265fdd3998c9b3c40b60028c236ed93933abe67763 /tmp/hhvm.deb' | sha256sum -c - \ + && apt-get update \ + && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends /tmp/hhvm.deb \ + && rm -rf /tmp/hhvm.deb /var/lib/apt/lists/* + +ARG HACK_UID=1000 +RUN curl -fL --retry 3 "https://getcomposer.org/download/${COMPOSER_VERSION}/composer.phar" \ + -o /usr/local/bin/composer \ + && echo "${COMPOSER_SHA256} /usr/local/bin/composer" | sha256sum -c - \ + && chmod +x /usr/local/bin/composer \ + && useradd --create-home --uid "$HACK_UID" --shell /bin/bash hack \ + && mkdir /app \ + && chown hack:hack /app + +COPY docker/entrypoint.sh /usr/local/bin/docker-entrypoint +COPY docker/hhvm.ini /etc/hhvm/php.ini +RUN chmod +x /usr/local/bin/docker-entrypoint + +WORKDIR /app +COPY --chown=hack:hack . /app +USER hack +EXPOSE 8080 +ENTRYPOINT ["docker-entrypoint"] +CMD ["hhvm", "-m", "server", "-p", "8080", "-d", "hhvm.server.source_root=/app/src"] diff --git a/README.md b/README.md index e6e5601..a34053b 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,148 @@ -# What is this? -A way to get [HHVM](https://hhvm.com/) working on arm64. +# Docker Hack development environment -# How to use -This requires use of [Colima](https://github.com/abiosoft/colima) and an up to date version of [QEMU](https://www.qemu.org/) in order to work. Rosetta does not currently support [some x86_64 instruction](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment) execution which HHVM uses. +A Docker-based [HHVM](https://hhvm.com/) development image, including Composer, +the Hack typechecker and linter, and HackTest. The image is built from the tracked +Dockerfile; source and dependencies are mounted at `/app` during development. +## Version limits + +Verified against upstream package indexes on November 3, 2026: + +| Component | Version | +| --- | --- | +| HHVM | 4.172.1 (last published Ubuntu package) | +| Ubuntu | 20.04, with all available public package updates | +| PHP (runs Composer only) | Ubuntu's 7.4 package, with available public updates | +| Composer | 2.11.1 | +| HSL | 4.108.1 | +| hhvm-autoload | 3.3.2 | +| hh-clilib | 2.6.0 | +| HackTest | 2.4.0 | +| FBExpect | 2.9.1 | + +These are the latest available packages for this environment, **not a currently +maintained runtime stack**. HHVM [ended official releases](https://hhvm.com/blog/2023/10/27/oss-update.html). +The newer [HHVM 4.172.3 source tag](https://github.com/facebook/hhvm/tree/HHVM-4.172.3) +has no corresponding official Ubuntu package or Docker image. Later security +fixes [require compiling HHVM from source](https://hhvm.com/blog/2023/07/25/security-update.html). +Ubuntu 20.04's normal support has ended, and several Hack tools are marked +abandoned. This setup is for local development; rebuilding it does not make +those unsupported components current or suitable for public deployment. + +The packaged HHVM binary depends on Ubuntu 20.04 libraries, so simply changing +the base image to a newer Ubuntu release will not work. Its download is pinned +by SHA-256 because `dl.hhvm.com` currently has an expired HTTPS certificate; +Composer downloads continue to use HTTPS and are also checksum-verified. + +HHAST was removed because even its last release (4.168.3) rejects HHVM 4.172's +syntax-tree schema. `composer lint` uses HHVM's built-in `hh_client --lint` +instead. This checks Hack diagnostics; HHAST-specific style rules are no longer +available. `HHVM_DISABLE_PERSONALITY=true` lets the typechecker work with Docker's +default seccomp profile without changing container security settings. + +## Start the environment + +Install Docker Engine/Desktop and Docker Compose v2 or newer. On x86-64 Linux +or an Intel Mac, use your normal Docker context. On Apple Silicon, use a full +x86-64 QEMU VM with Colima. Setting `platform: linux/amd64` alone is not enough: +the CLI tools can work under Docker Desktop's translation while the HTTP server +still crashes. This build's full test suite, including HTTP, is verified on +native x86-64 Linux in CI; the full Colima VM path has not been revalidated here. + +```sh +brew install docker docker-compose qemu colima ``` -brew install docker -brew install qemu -brew install colima + +For an existing Homebrew installation, first run +`brew update && brew upgrade docker docker-compose qemu colima`, then start the VM: + +```sh +colima start --profile hack-dev --vm-type qemu --arch x86_64 \ + --cpu 4 --cpu-type max --memory 16 --network-address +docker context use colima-hack-dev +``` + +If Homebrew's Compose plugin is not found, follow the plugin setup printed by +`brew info docker-compose`. Use a separate Colima profile so other VMs are not +reconfigured. Stop this VM with `colima stop --profile hack-dev` when finished. + +```sh git clone https://github.com/justdan6/docker-hack-dev.git cd docker-hack-dev +# On Linux, match the bind-mounted directory's owner: +# export HACK_UID=$(id -u) +docker compose build --pull +docker compose up -d --wait --wait-timeout 240 +``` + +Open . The expected response is `Hello World!`. +Changes in `src/` are picked up without rebuilding the image. Composer installs +the committed lockfile before the server starts and stops startup on failure. +The service runs as the `hack` user, and the port is bound to localhost. +Set `PORT=8081` before `docker compose up` to use a different host port. -colima start --arch x86_64 --cpu 4 --cpu-type "max" --memory 16 --network-address -docker compose up +## Update and rebuild + +After pulling updated repository files: + +```sh +git pull --ff-only +docker compose build --pull --no-cache +docker compose up -d --force-recreate --wait --wait-timeout 240 +docker compose exec hack-dev-ubuntu composer test +``` + +`--pull` refreshes the Ubuntu base image; `--no-cache` reruns package installation +to pick up available OS updates. `up --force-recreate` replaces the running +container with the rebuilt image. The bind-mounted source and `vendor/` remain +on your host. No volume deletion is needed. + +To look for future Hack library updates, then regenerate and commit the lockfile: + +```sh +docker compose run --rm --no-deps hack-dev-ubuntu composer outdated --direct +docker compose run --rm --no-deps hack-dev-ubuntu composer update --with-all-dependencies ``` -Go to http://localhost:8080/hello.hack +Composer itself is pinned in `Dockerfile`. To update it later, change +`COMPOSER_VERSION` and `COMPOSER_SHA256` together using the checksum from the +[official downloads page](https://getcomposer.org/download/), then rebuild. +Update Docker Desktop through its updater, or update Docker Engine and the +Compose plugin through your OS package manager. + +## Validate the build + +```sh +docker compose run --rm --no-deps hack-dev-ubuntu composer install --prefer-dist +docker compose run --rm --no-deps hack-dev-ubuntu composer validate --no-check-publish +docker compose run --rm --no-deps hack-dev-ubuntu composer check-platform-reqs +docker compose run --rm --no-deps hack-dev-ubuntu composer test +docker compose run --rm --no-deps hack-dev-ubuntu composer lint +docker compose run --rm --no-deps hack-dev-ubuntu composer typecheck +curl --fail http://localhost:8080/hello.hack +``` + +GitHub Actions runs the build, dependency checks, tests, lint, typecheck, and +HTTP smoke test on x86-64 Linux for pushes and pull requests. + +Inspect failures with `docker compose logs --tail=100`; stop the environment +with `docker compose down`. If APT reports invalid signatures during a build, +also check that Docker's VM has free disk space. +If a macOS bind mount fails with `operation not permitted`, grant Docker Desktop +access to the checkout's directory in macOS privacy/file-sharing settings, or +move the checkout into a directory Docker can already access. + +## Publish the rebuilt image + +Building locally does not update Docker Hub. If you maintain +`justdanz/hack-dev-ubuntu`, publish the tested image explicitly: + +```sh +docker login +docker compose push hack-dev-ubuntu +``` -Any changes in /src will be picked up by [HHVM](https://docs.hhvm.com/hhvm/). +To publish under a different Docker Hub account, change `image:` in +`compose.yaml` before building and pushing. This repository does not push images +automatically. Compose normally builds from source (`pull_policy: build`), so +`docker compose pull` alone is not the update workflow for this checkout. diff --git a/compose.yaml b/compose.yaml index 522f030..5e80802 100644 --- a/compose.yaml +++ b/compose.yaml @@ -1,13 +1,21 @@ services: hack-dev-ubuntu: - image: justdanz/hack-dev-ubuntu # justdanz/hack-dev-debian + image: justdanz/hack-dev-ubuntu:latest + platform: linux/amd64 + build: + context: . + args: + HACK_UID: ${HACK_UID:-1000} + pull_policy: build + init: true + working_dir: /app volumes: - ./:/app ports: - - "8080:8080" - command: - - /bin/sh - - -c - - | - composer install - hhvm -m server -p 8080 -d hhvm.server.source_root=/app/src + - "127.0.0.1:${PORT:-8080}:8080" + healthcheck: + test: ["CMD", "curl", "--fail", "--silent", "http://127.0.0.1:8080/hello.hack"] + interval: 10s + timeout: 5s + retries: 6 + start_period: 120s diff --git a/composer.json b/composer.json index 8179a98..f9c3919 100644 --- a/composer.json +++ b/composer.json @@ -1,8 +1,9 @@ { "require": { - "hhvm/hsl": "^4.108", - "hhvm/hhvm-autoload": "^3.3", - "facebook/hh-clilib": "^2.6" + "hhvm": "~4.172.1", + "hhvm/hsl": "^4.108.1", + "hhvm/hhvm-autoload": "^3.3.2", + "facebook/hh-clilib": "^2.6.0" }, "config": { "allow-plugins": { @@ -10,8 +11,12 @@ } }, "require-dev": { - "hhvm/hhast": "^4.168", - "hhvm/hacktest": "^2.4", - "facebook/fbexpect": "^2.9" + "hhvm/hacktest": "^2.4.0", + "facebook/fbexpect": "^2.9.1" + }, + "scripts": { + "test": "vendor/bin/hacktest tests/", + "lint": "php scripts/lint.php", + "typecheck": "hh_client check" } } diff --git a/composer.lock b/composer.lock index 1e5e3a1..92e3965 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "b3093c04695f0ed348d24df77fb93405", + "content-hash": "e8b9b5705ec7de45c42c9b74273cedc2", "packages": [ { "name": "facebook/hh-clilib", @@ -46,7 +46,9 @@ "issues": "https://github.com/hhvm/hh-clilib/issues", "source": "https://github.com/hhvm/hh-clilib/tree/v2.6.0" }, - "time": "2020-12-14T21:29:15+00:00" + "abandoned": true, + "time": "2020-12-14T21:29:15+00:00", + "published-time": "2020-12-14T21:30:04+00:00" }, { "name": "hhvm/hhvm-autoload", @@ -83,8 +85,8 @@ "Facebook\\AutoloadMap\\ComposerPlugin" ], "branch-alias": { - "dev-master": "3.x-dev", "dev-main": "3.x-dev", + "dev-master": "3.x-dev", "dev-CI_current_pull_request": "3.x-dev" } }, @@ -102,7 +104,8 @@ "source": "https://github.com/hhvm/hhvm-autoload/tree/v3.3.2" }, "abandoned": true, - "time": "2022-05-30T18:49:17+00:00" + "time": "2022-05-30T18:49:17+00:00", + "published-time": "2022-05-30T19:31:40+00:00" }, { "name": "hhvm/hsl", @@ -143,7 +146,8 @@ "issues": "https://github.com/hhvm/hsl/issues", "source": "https://github.com/hhvm/hsl/tree/v4.108.1" }, - "time": "2021-05-04T14:32:06+00:00" + "time": "2021-05-04T14:32:06+00:00", + "published-time": "2021-05-04T14:33:58+00:00" }, { "name": "hhvm/hsl-experimental", @@ -187,7 +191,8 @@ "source": "https://github.com/hhvm/hsl-experimental/tree/v4.108.0" }, "abandoned": true, - "time": "2021-05-04T18:41:22+00:00" + "time": "2021-05-04T18:41:22+00:00", + "published-time": "2021-05-04T18:42:19+00:00" }, { "name": "hhvm/type-assert", @@ -233,7 +238,8 @@ "source": "https://github.com/hhvm/type-assert/tree/v4.2.2" }, "abandoned": true, - "time": "2021-09-13T15:44:05+00:00" + "time": "2021-09-13T15:44:05+00:00", + "published-time": "2021-09-13T15:50:05+00:00" } ], "packages-dev": [ @@ -277,7 +283,8 @@ "source": "https://github.com/hhvm/difflib/tree/v1.3.0" }, "abandoned": true, - "time": "2021-09-27T22:08:35+00:00" + "time": "2021-09-27T22:08:35+00:00", + "published-time": "2021-11-17T21:42:00+00:00" }, { "name": "facebook/fbexpect", @@ -313,7 +320,8 @@ "source": "https://github.com/hhvm/fbexpect/tree/v2.9.1" }, "abandoned": true, - "time": "2022-06-06T19:39:09+00:00" + "time": "2022-06-06T19:39:09+00:00", + "published-time": "2022-06-06T19:41:18+00:00" }, { "name": "hhvm/hacktest", @@ -346,8 +354,8 @@ "type": "library", "extra": { "branch-alias": { - "dev-master": "2.x-dev", "dev-main": "2.x-dev", + "dev-master": "2.x-dev", "dev-CI_current_pull_request": "2.x-dev" } }, @@ -360,65 +368,19 @@ "issues": "https://github.com/hhvm/hacktest/issues", "source": "https://github.com/hhvm/hacktest/tree/v2.4.0" }, - "time": "2022-06-06T18:42:25+00:00" - }, - { - "name": "hhvm/hhast", - "version": "v4.168.2", - "source": { - "type": "git", - "url": "https://github.com/hhvm/hhast.git", - "reference": "01f7fed70d675643b200e8661e07eaed781592af" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/hhvm/hhast/zipball/01f7fed70d675643b200e8661e07eaed781592af", - "reference": "01f7fed70d675643b200e8661e07eaed781592af", - "shasum": "" - }, - "require": { - "facebook/difflib": "^1.0.0", - "facebook/hh-clilib": "^2.5.0rc1", - "hhvm": "^4.168.2", - "hhvm/type-assert": "^4.2.2" - }, - "require-dev": { - "facebook/fbexpect": "^2.8.1", - "facebook/hack-codegen": "^4.0", - "hhvm/hacktest": "^2.3.0", - "hhvm/hhvm-autoload": "^2.0.4|^3.0" - }, - "bin": [ - "bin/hhast-lint", - "bin/hhast-lint.hack", - "bin/hhast-migrate", - "bin/hhast-migrate.hack" - ], - "type": "library", - "extra": { - "branch-alias": { - "dev-master": "4.x-dev", - "dev-main": "4.x-dev" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "description": "A mutable AST library for Hack with linting and code migrations", - "support": { - "issues": "https://github.com/hhvm/hhast/issues", - "source": "https://github.com/hhvm/hhast/tree/v4.168.2" - }, - "time": "2023-01-25T18:12:29+00:00" + "abandoned": true, + "time": "2022-06-06T18:42:25+00:00", + "published-time": "2022-06-06T18:43:04+00:00" } ], "aliases": [], "minimum-stability": "stable", - "stability-flags": [], + "stability-flags": {}, "prefer-stable": false, "prefer-lowest": false, - "platform": [], - "platform-dev": [], - "plugin-api-version": "2.6.0" + "platform": { + "hhvm": "~4.172.1" + }, + "platform-dev": {}, + "plugin-api-version": "2.11.0" } diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh new file mode 100644 index 0000000..4e4ad83 --- /dev/null +++ b/docker/entrypoint.sh @@ -0,0 +1,10 @@ +#!/bin/sh +set -eu + +# Install the committed dependency versions before starting the dev server. +# Other commands (including composer update) run directly. +if [ "${1:-}" = hhvm ] && [ "${2:-}" = -m ] && [ "${3:-}" = server ]; then + composer install --prefer-dist --no-progress +fi + +exec "$@" diff --git a/docker/hhvm.ini b/docker/hhvm.ini new file mode 100644 index 0000000..c53c0a0 --- /dev/null +++ b/docker/hhvm.ini @@ -0,0 +1,6 @@ +hhvm.log.level = Warning +hhvm.log.always_log_unhandled_exceptions = true +hhvm.log.use_log_file = false +hhvm.server.type = proxygen +hhvm.server.ip = 0.0.0.0 +hhvm.server.default_document = hello.hack diff --git a/hhast-lint.json b/hhast-lint.json deleted file mode 100644 index 29b8c70..0000000 --- a/hhast-lint.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "roots": [ "bin/", "src/", "tests/" ], - "builtinLinters": "all" -} diff --git a/scripts/lint.php b/scripts/lint.php new file mode 100644 index 0000000..45c3e19 --- /dev/null +++ b/scripts/lint.php @@ -0,0 +1,42 @@ +isFile() && $file->getExtension() === 'hack') { + $files[] = $file->getPathname(); + } + } +} +sort($files); +if (!$files) { + fwrite(STDERR, "No Hack source files found.\n"); + exit(1); +} + +exec('hh_client --lint --json '.implode(' ', array_map('escapeshellarg', $files)), $output, $status); +if ($status !== 0) { + fwrite(STDERR, implode("\n", $output)."\n"); + exit($status); +} + +try { + $result = json_decode(implode("\n", $output), true, 512, JSON_THROW_ON_ERROR); +} catch (JsonException $exception) { + fwrite(STDERR, 'Invalid linter output: '.$exception->getMessage()."\n"); + exit(1); +} +if (!isset($result['errors']) || !is_array($result['errors'])) { + fwrite(STDERR, "Linter output is missing the errors array.\n"); + exit(1); +} +if ($result['errors']) { + fwrite(STDERR, json_encode($result['errors'], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES)."\n"); + exit(1); +} +printf("No lint errors (%d files checked).\n", count($files)); diff --git a/src/hello.hack b/src/hello.hack index 102549b..55fe41f 100644 --- a/src/hello.hack +++ b/src/hello.hack @@ -2,5 +2,7 @@ use namespace HH\Lib\IO; <<__EntryPoint>> async function main(): Awaitable { + require_once(__DIR__.'/../vendor/autoload.hack'); + Facebook\AutoloadMap\initialize(); await IO\request_output()->writeAllAsync("Hello World!\n"); -} \ No newline at end of file +} diff --git a/src/square_vec.hack b/src/square_vec.hack new file mode 100644 index 0000000..61a14a6 --- /dev/null +++ b/src/square_vec.hack @@ -0,0 +1,5 @@ +use namespace HH\Lib\Vec; + +function square_vec(vec $values): vec { + return Vec\map($values, $value ==> $value * $value); +} diff --git a/tests/MyTest.hack b/tests/MyTest.hack index 7f55aa6..8e9ad54 100644 --- a/tests/MyTest.hack +++ b/tests/MyTest.hack @@ -13,4 +13,4 @@ final class MyTest extends HackTest { public function testSquares(vec $in, vec $expected_output): void { expect(square_vec($in))->toBeSame($expected_output); } -} \ No newline at end of file +}