MacPorts Base

repository·master·Indexed 21 days ago

https://github.com/macports/macports-base

Source code and documentation for the MacPorts command-line client, a package management system for macOS. Includes technical details on the vendored BLAKE3 C implementation (v1.8.4), configuration via macports.conf, and command references for port management such as activate, deactivate, archive, archivefetch, bump, cat, clean, and shell navigation.

Tokens
38.8K
Snippets
183
Records
215
Agent score
77%

What's inside macports-base

  1. Overview of the BLAKE3 C Implementation

    master
    This directory contains a vendored subset of the BLAKE3 reference C implementation (version 1.8.4). It provides the core BLAKE3 hashing functionality with support for various CPU backends including ARM NEON and x86-64 (SSE2, SSE4.1, AVX2, and AVX-512) via assembly and portable C implementations. The implementation is designed to be integrated into the pextlib use case within MacPorts.
  2. How BLAKE3 build integration works

    master
    The build system uses an autoconf-generated config.h file to manage feature flags (such as BLAKE3_NO_SSE2, BLAKE3_NO_SSE41, etc.). Instead of modifying the upstream headers directly, these defines are injected into the vendored sources using the compiler's -include flag. This ensures the src/ directory remains pristine.
  3. Create and sign release tarballs

    master

    Release tarballs are .tar.bz2 and .tar.gz archives of the base repository, named MacPorts-<version>.tar.{bz2,gz}.

    Use the top-level Makefile to generate tarballs and checksums. You can automatically sign them with a detached GPG signature using DISTGPGID or generate a signify(1) signature for selfupdate over HTTP using DISTKEY.

    Commands:

    • Basic generation: make dist DISTVER=<version>
    • With GPG signature: make dist DISTVER=<version> DISTGPGID=<email_or_hex_id>
    • With signify signature: make dist DISTVER=<version> DISTKEY=<path_to_secret_key>
    # Generate tarballs with GPG signature
    make dist DISTVER=2.0.0 DISTGPGID=<handle>@macports.org
    
    # Generate tarballs with signify signature
    make dist DISTVER=2.0.0 DISTKEY=/path/to/macports/macports-base-2024.sec
  4. Create and sign release packages (pkg/dmg)

    master

    MacPorts releases include .pkg (flat packages for macOS 10.6+) or .dmg (disk images) installers.

    Workflow:

    1. Build: Use the port command to build the package. The Portfile must be updated with the new version and checksums.
    2. Sign: Use productsign with a Developer ID Installer certificate.
    3. Notarize: For macOS 10.14 Mojave and later, submit the .pkg via xcrun notarytool or xcrun altool.
    4. Staple: After successful notarization, use xcrun stapler staple.
    5. Checksum: Generate MD5, SHA1, RIPEMD160, and SHA256 checksums using openssl.

    Validation Checklist:

    • Linking: Use otool -L to ensure binaries/libraries (like daemondo or Tcl dylibs) do not link against anything outside a vanilla macOS installation + developer tools.
    • Architecture: Use file to confirm binaries are universal (e.g., Mach-O universal binary with 2 architectures).
    • Tcl Invocation: Ensure scripts in ${destroot}/opt/local/bin use #!/opt/local/bin/port-tclsh to use the bundled interpreter.
    • UX: Verify the .dmg mounts in Finder and the .pkg launches Installer.app correctly.
    # Build packages
    sudo port -d pkg MacPorts
    sudo port -d dmg MacPorts
    
    # Sign package
    productsign --sign "Developer ID Installer: John Doe" unsigned/MacPorts-2.0.0-10.7-Lion.pkg MacPorts-2.0.0-10.7-Lion.pkg
    
    # Notarize (macOS 10.14+)
    xcrun notarytool submit MacPorts-2.0.0-10.14-Mojave.pkg \
        --apple-id <your-apple-id> --keychain-profile "notarytool" \
        --wait
    
    # Staple
    xcrun stapler staple MacPorts-2.5.4-10.14-Mojave.pkg
    
    # Generate checksums
    for type in -md5 -sha1 -ripemd160 -sha256; do
      openssl dgst $type MacPorts-2.0.0-*.{pkg,dmg} >> MacPorts-2.0.0.chk.txt
    done
  5. Tag a MacPorts release

    master

    Releases must be tagged to ensure replicability. Use annotated, GPG-signed tags (-a -s).

    Tagging Conventions:

    • Beta: v2.0.0-beta2
    • Release Candidate: v2.0.0-rc1
    • Final Release: v2.0.0
    • Point Release: v2.0.1

    Steps:

    1. Tag the macports-base repository.
    2. Create a corresponding archive tag in the macports-ports repository to provide a compatible set of ports.

    Example Workflow:

    # Tagging base
    git tag -a -s v2.0.0 release-2.0
    git push origin v2.0.0
    
    # Tagging ports archive
    git clone macports/macports-ports macports-ports
    cd macports-ports
    git tag -a -s v2.0.0-archive origin/master
    git push origin v2.0.0-archive
    git tag -a -s v2.0.0 release-2.0
    git push origin v2.0.0
  6. Prepare code for a MacPorts release

    master

    Before tagging a release, perform the following code updates:

    1. Update ChangeLog: Update the ChangeLog file in both master and the release branch.
    2. Update Versioning: Update config/macports_version with the target release number. This file is used by the port command and the selfupdate procedure.
    3. Maintain Compatibility: Preserve config/mp_version and config/dp_version at fixed values (1.800 and 1.710 respectively) if backwards compatibility for old installations is required.
    4. Regenerate Scripts: Run ./autogen.sh to update the autoconf configure script, as it reads from mp_version.
    5. Regenerate Man Pages: Clean and rebuild man pages to ensure the new version number is reflected in the output.

    Ensure all changes are merged between the release branch and master as necessary.

    ./autogen.sh
    ./standard_configure.sh
    make -C doc/ clean all \
        ASCIIDOC=/opt/local/bin/asciidoc \
        XSLTPROC=/opt/local/bin/xsltproc \
        DOCBOOK_XSL=/opt/local/share/xsl/docbook-xsl-nons/manpages/docbook.xsl
  7. How to update the vendored BLAKE3 sources

    master

    If you need to update the BLAKE3 implementation to a newer version, follow these steps:

    1. Replace the contents of src/ with the new upstream files from the c/ directory of the official BLAKE3 repository.
    2. Verify that the existing files in patches/ still apply cleanly to the new source; modify them if necessary.
    3. Update the version number at the top of the README.md file.
  8. View the command synopsis for the port command

    master
    Use the port usage command to display a brief summary of all possible options for the port command. This output shows the canonical order in which the port command expects arguments and flags, mirroring the SYNOPSIS section of the man port(1) manpage.
    port usage
  9. Create a MacPorts release branch

    master

    For each major release (e.g., 1.9.x, 2.0.x), create a dedicated git branch. This branch will host all alpha, beta, release candidates, and point releases. Only the macports-base repository is branched; the ports tree is handled separately.

    To create the branch from master:

    1. Choose the git revision (usually origin/master).
    2. Create and push the branch (e.g., release-2.0).

    Note: Once master begins development for the next major version, increase its version in config/macports_version by setting the patch-level to 99 (e.g., 2.0.99) to differentiate it from the release branch.

    git branch release-2.0 origin/master
    git push origin release-2.0
  10. Make release available via selfupdate

    master

    To enable users to receive the new version via selfupdate, you must update the config/RELEASE_URL file in the macports-base repository with the new release tag. This file is used by the mprsyncup job to distribute the code via rsync.

    You may also need to purge the CDN cache for distfiles.macports.org/MacPorts/RELEASE_URL to ensure the update propagates quickly.

  11. Use daemondo to run and manage daemons

    master

    daemondo is a wrapper program designed to run daemons on macOS. It acts as an adapter between launchd and traditional rc.d style scripts.

    It provides the following lifecycle management:

    • Start: Executes a specified command on launch.
    • Stop: Stops the daemon when daemondo receives SIGTERM or when a specific --stop-cmd is provided.
    • Restart: Restarts the daemon on SIGHUP or when specific system events occur (network changes, power state changes, or notifications).
    • Monitoring: In its primary mode, it tracks the daemon's process ID (PID) and will exit if the daemon process dies.

    Operational Modes:

    1. Asynchronous (PID Tracking): If no --stop-cmd is provided, daemondo executes the --start-cmd asynchronously and tracks the resulting PID. It uses this PID to signal the daemon for stops/restarts.
    2. Synchronous (Command-based): If --stop-cmd is provided, both start and stop commands are issued synchronously. In this mode, daemondo does not track a PID but relies on the provided commands to control the daemon.
    usage: daemondo [-hv] [--version]
                         --start-cmd prog args... ;
                         [--stop-cmd prog arg... ;]
                         [--restart-cmd prog arg... ;]
                         [--restart-wakeup]
                         [--restart-netchange]
                         [--restart-config regex... ;]
                         [--restart-dist-notify names... ;
                         [--restart-darwin-notify names... ;]