How to Package Third-Party Software for HaikuPorts

HaikuPorts packages should be reproducible from a recipe, verified upstream source, declared dependencies, and reviewable Haiku-specific patches. The deliverable is not merely an HPKG that works on one machine; another builder must be able to create the same package in a clean environment and install/remove it without unmanaged files.

Research before creating a recipe

Search the HaikuPorts repository by project name, command, library provide, and old versions. Check open pull requests/issues so you do not duplicate a pending port. Read recipes for similar build systems in the same category, but verify every field against current policy.

Choose an upstream release archive from the project’s authoritative site. Record the stable HTTPS URL, cryptographic checksum, version, license, copyright holders, supported architectures, build system, runtime outputs, tests, and bundled dependencies. Avoid moving “latest” URLs that change bytes under the same name.

Confirm the license can be redistributed and that its exact identifier/text exists in Haiku’s packaging ecosystem. Do not guess “MIT” from a repository badge when individual files differ.

Set up HaikuPorter and HaikuPorts

Follow the current HaikuPorts wiki for cloning/configuring the matching haikuporter and haikuports repositories. Build on Haiku of the target architecture or the project’s supported environment. Keep the ports tree clean except your recipe/patches.

Place the recipe in the established category/package directory and name it with the upstream version according to current repository convention. Run HaikuPorter’s lint/check commands documented by the wiki before a full build.

Do not install missing build tools manually and then omit them from the recipe. A successful dirty host build is evidence of an undeclared dependency, not a finished port.

Write accurate metadata

Provide a concise SUMMARY, longer DESCRIPTION, HOMEPAGE, copyright/license fields, source URI and SHA-256 checksum, revision, and architecture status. Avoid marketing claims and line breaks/formats rejected by recipe policy.

Declare PROVIDES for the package itself and public commands, libraries, applications, or add-ons using Haiku’s typed resolvables. Declare REQUIRES for runtime libraries/services and BUILD_REQUIRES/command requirements for compilation tools as prescribed by the recipe format.

Split development headers/static files, documentation, tools, translations, or debug/source packages according to HaikuPorts conventions when appropriate. Each subpackage gets only its own files and dependencies. Do not make runtime users install an entire compiler stack.

Architecture status must be evidence-based. Mark unsupported/broken architectures honestly; do not claim x86 secondary/hybrid support because x86_64 built. Endianness, pointer width, and GCC2 ABI can expose separate failures.

Implement build and install phases

Use standard recipe helpers and directory variables instead of hardcoded /boot/system paths. Configure the project for the package prefix, compile with supported parallelism, and install into HaikuPorter’s staging/package directory—not the live system.

Patch only what Haiku needs: platform detection, API backend, path convention, missing standard feature, or build-system fix. Keep patches small, named, documented, and generated in the repository’s expected format. Prefer submitting generally useful fixes upstream and include the upstream issue/commit reference.

Never download dependencies during the build phase or write outside the controlled work/staging tree. Network-fetched build inputs defeat checksums and reproducibility. Avoid embedding the builder’s home path, current date, CPU flags, or Git state where upstream supports deterministic alternatives.

If tests require network, display, hardware, or unavailable services, separate them and document what is skipped. Do not delete a failing test merely to get an HPKG.

Build cleanly and inspect outputs

Run HaikuPorter with dependency resolution in the current documented manner, then repeat from a clean work directory. The second build must not rely on files left by the first. Save complete logs for failures.

Inspect each generated HPKG’s file list and metadata. Verify paths, executable permissions, application signature/resources, MIME registration, libraries/sonames, package provides/requires, license files, settings locations, and absence of build artifacts or host paths.

Use dependency inspection on executables/libraries and compare it with declared runtime requirements. A binary that launches on a developer system may be using an undeclared package already installed there.

Test installation lifecycle

Install the HPKG on a disposable/test Haiku system of each claimed architecture. Launch core functionality from Deskbar and Terminal where relevant. Test file open/save, network/media integration, locale, settings, and command help/version—not only process startup.

Upgrade from the previous recipe/package if one exists, then uninstall. Confirm package-owned files disappear, user data/settings follow policy, services/add-ons restart as documented, and no files were placed outside packagefs except declared writable files/scripts.

Test without development packages to prove runtime dependencies are complete. For libraries, compile/run a minimal consumer against the devel subpackage. For GUI apps, verify icon, signature, Deskbar entry, file types, and clean quit.

Submit a focused HaikuPorts change

Review the final diff: recipe, necessary patches, licenses/metadata, and no generated HPKG/work directories. Follow HaikuPorts’ current contribution workflow (the repository and wiki document its GitHub review process), not Haiku core’s Gerrit instructions.

The pull request explains upstream version/source, Haiku changes, tested architectures, build/test/install/uninstall commands, known limitations, and upstream patch status. Respond by updating the same branch, keep unrelated recipe formatting out, and rerun clean builds after review changes.

Once merged, watch builders/repository publication and install the repository-produced package. Local success is not final until automated infrastructure produces and clients can resolve it.

Related:

Sources: