build(release): package MIInfer v0.2.0 baseline

CMakeLists.txt

@@ -6,6 +6,41 @@ project(MIInfer VERSION 0.2.0 LANGUAGES CXX)
 
 include(GNUInstallDirs)
 include(FetchContent)
+include(CTest)
+
+option(MIINFER_BUILD_BENCHMARKS "Include benchmark executables in the default build" OFF)
+option(MIINFER_BUILD_RESEARCH_TOOLS "Include historical and forensic tools in the default build" OFF)
+option(MIINFER_BUILD_TESTS "Include test executables in the default build and register CTest tests" ${BUILD_TESTING})
+set(BUILD_TESTING "${MIINFER_BUILD_TESTS}")
+if(MIINFER_BUILD_TESTS)
+    enable_testing()
+endif()
+set(MIINFER_RELEASE_TEST_TARGETS
+    miinfer-host-test
+    miinfer-openai-api-test
+    miinfer-m12-gdn-oracle
+    miinfer-model-loader-test
+    miinfer-qwen3-primitives-host-test
+    miinfer-qwen3-layer0-test
+    miinfer-qwen3-kv-cache-test
+    miinfer-qwen3-forward-test
+    miinfer-qwen3-tokenizer-test
+    miinfer-kquant-wave-test
+    miinfer-hip-smoke
+    miinfer-fp16-gemv-test
+    miinfer-q4-q8-gemv-test
+    miinfer-q4-q8-dot4-probe
+    miinfer-model-gpu-test
+    miinfer-qwen3-primitives-test
+    miinfer-qwen35-conv-batch-test
+    miinfer-qwen3-layer0-gpu-test
+    miinfer-qwen3-kv-cache-gpu-test
+    miinfer-qwen3-quant-kv-attention-test
+    miinfer-qwen3-cached-attention-determinism-gpu-test
+    miinfer-qwen3-forward-gpu-test
+    miinfer-qwen3-decode-gpu-test
+    miinfer-qwen3-decode-sequence-gpu-test
+)
 
 FetchContent_Declare(nlohmann_json
     URL https://github.com/nlohmann/json/releases/download/v3.11.3/json.tar.xz
@@ -596,8 +631,46 @@ if(MIINFER_ENABLE_HIP)
 
 endif()
 
-include(CTest)
-if(BUILD_TESTING)
+# Keep non-product executable targets available for explicit development builds,
+# but do not make research programs a prerequisite of the normal release build.
+get_property(MIINFER_EXECUTABLE_TARGETS DIRECTORY PROPERTY BUILDSYSTEM_TARGETS)
+foreach(MIINFER_TARGET IN LISTS MIINFER_EXECUTABLE_TARGETS)
+    get_target_property(MIINFER_TARGET_TYPE "${MIINFER_TARGET}" TYPE)
+    if(NOT MIINFER_TARGET_TYPE STREQUAL "EXECUTABLE")
+        continue()
+    endif()
+
+    get_target_property(MIINFER_TARGET_SOURCES "${MIINFER_TARGET}" SOURCES)
+    set(MIINFER_EXCLUDE_FROM_ALL FALSE)
+    foreach(MIINFER_SOURCE IN LISTS MIINFER_TARGET_SOURCES)
+        if(MIINFER_SOURCE MATCHES "^bench/"
+           AND NOT MIINFER_TARGET STREQUAL "miinfer-m12-gdn-oracle"
+           AND NOT MIINFER_BUILD_BENCHMARKS)
+            set(MIINFER_EXCLUDE_FROM_ALL TRUE)
+        elseif(MIINFER_SOURCE MATCHES "^tools/"
+               AND NOT MIINFER_TARGET STREQUAL "miinfer"
+               AND NOT MIINFER_BUILD_RESEARCH_TOOLS)
+            set(MIINFER_EXCLUDE_FROM_ALL TRUE)
+        elseif(MIINFER_SOURCE MATCHES "^tests/"
+               AND NOT MIINFER_TARGET STREQUAL "miinfer-device-info"
+               AND (NOT MIINFER_BUILD_TESTS
+                    OR NOT MIINFER_TARGET IN_LIST MIINFER_RELEASE_TEST_TARGETS))
+            set(MIINFER_EXCLUDE_FROM_ALL TRUE)
+        endif()
+    endforeach()
+
+    if(MIINFER_TARGET STREQUAL "miinfer-m12-gdn-oracle"
+       AND NOT MIINFER_BUILD_TESTS
+       AND NOT MIINFER_BUILD_BENCHMARKS)
+        set(MIINFER_EXCLUDE_FROM_ALL TRUE)
+    endif()
+
+    if(MIINFER_EXCLUDE_FROM_ALL)
+        set_property(TARGET "${MIINFER_TARGET}" PROPERTY EXCLUDE_FROM_ALL TRUE)
+    endif()
+endforeach()
+
+if(MIINFER_BUILD_TESTS)
     add_test(NAME host-only COMMAND miinfer-host-test)
     set_tests_properties(host-only PROPERTIES LABELS "host-only")
     add_test(NAME openai-api-host COMMAND miinfer-openai-api-test)
@@ -655,23 +728,13 @@ if(BUILD_TESTING)
     endif()
 endif()
 
+install(FILES README.md LICENSE DESTINATION "${CMAKE_INSTALL_DOCDIR}")
 install(FILES
-    README.md
-    LICENSE
-    docs/current-state.md
+    docs/cli-product-contract.md
     docs/hardware.md
-    DESTINATION "${CMAKE_INSTALL_DOCDIR}"
+    docs/release.md
+    DESTINATION "${CMAKE_INSTALL_DOCDIR}/docs"
 )
-install(FILES
-    developer-guide.md
-    AGENTS.md
-    DESTINATION "${CMAKE_INSTALL_DOCDIR}"
-)
-install(DIRECTORY docs/ DESTINATION "${CMAKE_INSTALL_DOCDIR}/docs"
-        FILES_MATCHING PATTERN "*.md")
-install(DIRECTORY experiments/ DESTINATION "${CMAKE_INSTALL_DOCDIR}/experiments"
-        FILES_MATCHING PATTERN "*.md")
-install(FILES bench/README.md DESTINATION "${CMAKE_INSTALL_DOCDIR}/bench")
 install(PROGRAMS install.sh DESTINATION ".")
 if(MIINFER_ENABLE_HIP)
     install(TARGETS miinfer miinfer-device-info
@@ -684,6 +747,17 @@ set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "MI50/gfx906 LLM inference runtime")
 set(CPACK_PACKAGE_VERSION "${PROJECT_VERSION}")
 set(CPACK_PACKAGE_FILE_NAME
     "miinfer-${PROJECT_VERSION}-${MIINFER_TARGET_ARCH}-${CMAKE_SYSTEM_NAME}")
+set(MIINFER_RELEASE_PACKAGE_ARCHIVE
+    "${CMAKE_BINARY_DIR}/${CPACK_PACKAGE_FILE_NAME}.tar.gz")
 set(CPACK_PACKAGE_DIRECTORY "${CMAKE_BINARY_DIR}")
 set(CPACK_GENERATOR "TGZ")
 include(CPack)
+
+if(MIINFER_BUILD_TESTS)
+    add_test(NAME package-archive-smoke
+        COMMAND bash "${CMAKE_SOURCE_DIR}/scripts/test-package.sh"
+            "${MIINFER_RELEASE_PACKAGE_ARCHIVE}")
+    set_tests_properties(package-archive-smoke PROPERTIES
+        LABELS "package-host"
+        SKIP_REGULAR_EXPRESSION "^SKIP: package archive")
+endif()

README.md

@@ -7,11 +7,12 @@ knowledge of kernel presets.
 
 ## Install and start
 
-On a supported Linux/MI50 system, install the release archive and add its
-binary directory to `PATH`:
+On a supported Linux/MI50 system, download and extract the release archive,
+run its installer, then add the installed binary directory to `PATH`:
 
 ```bash
-./install.sh miinfer-0.2.0-gfx906-Linux.tar.gz
+tar -xzf miinfer-0.2.0-gfx906-Linux.tar.gz
+./miinfer-0.2.0-gfx906-Linux/install.sh miinfer-0.2.0-gfx906-Linux.tar.gz
 export PATH="$HOME/.local/miinfer/bin:$PATH"
 miinfer doctor --model ~/models/Qwen3.8-27B-Q4_K_M.gguf
 miinfer chat ~/models/Qwen3.8-27B-Q4_K_M.gguf
@@ -48,23 +49,18 @@ support `--json` where applicable.
 
 ## Qualification
 
-The V2-0045 MI50 qualification measured MIInfer ahead of pinned mx-llama.cpp
-and upstream llama.cpp in all nine tested prefill/decode cells. The claim is
+The MI50 qualification measured MIInfer ahead of pinned mx-llama.cpp and
+upstream llama.cpp in all nine tested prefill/decode cells. The claim is
 specific to the qualified model, hardware, and workload matrix. Decode used
 forced-token model-forward replay, not HTTP generation throughput; the
 multi-turn serving workload passed with prefix reuse but was not compared
-against the other runtimes. See the
-[qualification record](experiments/V2-0045-definitive-competitive-qualification.md)
-and [current state](docs/current-state-of-the-art.md).
+against the other runtimes. See [release notes and qualification scope](docs/release.md).
 
 The P8192 prefill lead over mx is narrow. The isolated attention kernel remains
 slower, but attention research is deferred because the complete qualified
 runtime wins the measured system-level matrix.
 
-## Development
-
-MIInfer remains specialized for gfx906 and Qwen3.8-27B-Q4_K_M. Build and
-benchmark methodology lives in [`bench/README.md`](bench/README.md) and
-[`docs/benchmarking.md`](docs/benchmarking.md). Historical kernel research and
-milestone notes are retained in [`developer-guide.md`](developer-guide.md);
-they are not required for normal CLI use.
+For source builds, installation details, hardware support, and the public CLI
+contract, see [`docs/release.md`](docs/release.md),
+[`docs/hardware.md`](docs/hardware.md), and
+[`docs/cli-product-contract.md`](docs/cli-product-contract.md).

developer-guide.md

@@ -35,6 +35,23 @@ optimization.
 The milestone notes below are historical snapshots; they do not supersede
 this current status.
 
+## Current CMake build graph
+
+The default release build includes the runtime, device probe, and release test
+targets. Research benchmarks and historical/forensic tools are excluded from
+the default build and can be enabled explicitly:
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
+  -DMIINFER_BUILD_BENCHMARKS=ON \
+  -DMIINFER_BUILD_RESEARCH_TOOLS=ON
+cmake --build build
+```
+
+Use `-DMIINFER_BUILD_TESTS=OFF` only when test executables are not needed.
+Normal release packaging uses the options' defaults; see
+[`docs/release.md`](docs/release.md).
+
 ## M17 local appliance quick start
 
 From a release archive on a supported MI50/gfx906 Linux machine:

docs/release.md

@@ -0,0 +1,68 @@
+# Release and installation
+
+MIInfer releases target Linux on one AMD Instinct MI50 32 GB (`gfx906`) and
+require a compatible ROCm/HIP runtime on the host. The archive contains the
+MIInfer executables, installer, license, and user-facing documentation; it
+does not contain the model or ROCm libraries.
+
+## Install a release archive
+
+Download `miinfer-<version>-gfx906-Linux.tar.gz` from the project release
+distribution, then install it into the default user prefix:
+
+```bash
+tar -xzf miinfer-<version>-gfx906-Linux.tar.gz
+./miinfer-<version>-gfx906-Linux/install.sh \
+  miinfer-<version>-gfx906-Linux.tar.gz
+export PATH="$HOME/.local/miinfer/bin:$PATH"
+miinfer doctor --model ~/models/Qwen3.8-27B-Q4_K_M.gguf
+miinfer chat ~/models/Qwen3.8-27B-Q4_K_M.gguf
+```
+
+The installer accepts an optional destination prefix. Re-running it overlays
+the archive files at that prefix, which supports replacing an existing
+installation. User configuration is stored separately under
+`~/.config/miinfer`; model files are never copied into the installation.
+
+## Build a release archive from source
+
+With the supported HIP/ROCm development toolchain installed:
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+cmake --build build --target package
+scripts/test-package.sh build/miinfer-0.2.0-gfx906-Linux.tar.gz
+```
+
+The package name is derived from the CMake project version, target
+architecture, and operating system. `miinfer --version` reports that version,
+the source commit, dirty state, compiler, and target architecture. Normal
+release builds omit research benchmarks and forensic tools. Developers can
+include them in the default build with
+`-DMIINFER_BUILD_BENCHMARKS=ON -DMIINFER_BUILD_RESEARCH_TOOLS=ON`; release
+tests are enabled by default and can be controlled with
+`-DMIINFER_BUILD_TESTS=OFF`.
+
+## Qualified performance scope
+
+The qualified model is Qwen3.8-27B-Q4_K_M on one MI50. These are the measured
+V2-0045 medians; prefill is prompt processing and decode is forced-token
+model-forward replay, not HTTP generation throughput.
+
+| Workload | MIInfer | mx-llama.cpp | upstream llama.cpp |
+| --- | ---: | ---: | ---: |
+| P512 prefill | 2.180 s | 2.279 s | 2.566 s |
+| P1024 prefill | 4.368 s | 4.576 s | 5.173 s |
+| P2048 prefill | 8.839 s | 9.195 s | 10.416 s |
+| P4096 prefill | 18.045 s | 18.576 s | 21.068 s |
+| P8192 prefill | 37.634 s | 37.982 s | 42.978 s |
+| P64 decode, TG128 | 33.81 ms/token | 38.47 ms/token | 41.43 ms/token |
+| P512 decode, TG128 | 34.07 ms/token | 38.54 ms/token | 41.41 ms/token |
+| P2048 decode, TG128 | 34.50 ms/token | 39.31 ms/token | 41.99 ms/token |
+| P8192 decode, TG128 | 36.88 ms/token | 42.77 ms/token | 43.45 ms/token |
+
+This is a runtime benchmark claim for the tested setup, not a promise of
+equivalent end-to-end HTTP throughput on other hardware, models, or software
+versions. The real multi-turn MIInfer serving workload passed with prefix
+reuse; it was not competitively measured against the other runtimes.