stubbi/asm

ASM

A home for assembly.

ASM is a package registry and command-line tool for assembly projects. Build a project. Find a package. Check its target, source, and release evidence. The CLI itself is written in assembly.

Website · Quick start · Status · Why ASM · Security model

Why we are building this

Software should serve people exceptionally well and use resources with care. We are building a foundation that helps people and AI create better software and makes the results practical to share and assess. Our brand foundation defines this vision, story, and decision principles. The messaging guide shows how to apply them.

We expect AI to make useful assembly cheaper to write and maintain. If that happens, assembly needs an ecosystem that makes the results easy to use. Every project should not need to invent its own package format, target selection, and release checks.

Our working assumptions:

1. User experience and total cost matter. Software must work reliably, respond quickly, and use resources well. Development and maintenance count too.
2. AI can change the economics of assembly. We expect more useful implementations for more machines. We will measure the effort required to make them dependable.
3. Machine control can improve selected workloads. Instructions, layout, algorithms, and CPU features are all possible sources of improvement.
4. Cheaper generation may make more targets practical. We will measure the cost of specifications, tools, proofs, integration, and maintenance.
5. Generation requires verification. People and agents use the same checks. A proof must state its model, assumptions, and connection to the released bytes.
6. Performance claims must be reproducible. Publish the workload, baseline, hardware, tools, raw results, and regressions.

These are research assumptions, not established results. We will revise them when experiments disagree. ASM must remain useful when a compiler already produces the best implementation for a workload.

The product follows from those assumptions: one workflow for assembly projects, with explicit targets and inspectable evidence. Read the full motivation.

An early measured example

Our asmwc experiment compares complete assembly and Rust implementations of a word counter. On one Apple M3, default counting took 15.234 ms in assembly and 68.468 ms in Rust. Those are warm-cache medians for a 128 MiB text file, with 24 samples per implementation. The comparison includes differences in algorithms, input scheduling, and startup.

We checked the published record digests and recomputed the selected medians. We did not reproduce the macOS experiment during the ASM build. The evidence record includes the baseline, raw samples, slower cases, and limits. ASM needs to make this kind of evidence available beside the exact target artifact.

Quick start

The current CLI runs on Linux x86-64 and ARM64. Install ASM once with the bootstrap installer. Use asm self update for later updates from the hub.

Version 0.3.0 remains Linux-only. The native macOS port is qualification work for Apple Silicon and macOS 15 or later. Its native checks and publication of an attested release remain required before macOS becomes a supported download. Intel macOS is unsupported.

Install the command

The installer requires curl and GNU Coreutils in /usr/bin. Install GitHub CLI 2.93.0 or later at /usr/bin/gh before you start. The ASM installer does not use administrator access or a GitHub login.

curl -qfsS -m120 https://asm.build/install.sh | sh

The same command works on both supported hosts. The installer reads the operating system and CPU architecture with uname. It selects the matching executable before downloading it. An unsupported host stops installation before any files change.

The installer writes $HOME/.local/bin/asm. It checks the executable's size, digest, and signed release attestation before installation. The attestation connects the executable to the required release workflow. A different existing asm file remains unchanged.

Apply the PATH command shown by the installer. Then check the installed version:

asm version

Version 0.3.0 prints asm 0.3.0 (x86_64-linux) or asm 0.3.0 (aarch64-linux) for your host. Use asm self update for later updates.

<details> <summary>Set PATH for this terminal</summary>

Put the installation directory first in PATH for this terminal:

export PATH="$HOME/.local/bin:$PATH"

Add the same command to your shell configuration to keep this setting. Run asm version again.

</details>

<details> <summary>Inspect the installer first</summary>

You can read the installer without running it. To inspect a local copy, download it to a temporary file:

asm_installer=$(mktemp) &&
curl -qfsSL --proto '=https' --tlsv1.2 -m 120 https://asm.build/install.sh -o "$asm_installer" &&
cat "$asm_installer"

If the download succeeds, review the displayed script. After your review, run this separate command in the same terminal:

sh "$asm_installer"

Remove the temporary file after installation:

rm -f "$asm_installer"
unset asm_installer

</details>

<details> <summary>Use in scripts and CI</summary>

For scripts and CI, use the complete-download commands below. The script runs only if the download succeeds.

(
  installer=$(mktemp) || exit
  trap 'rm -f "$installer"' 0
  curl -q --proto '=https' --tlsv1.2 -fsSL --max-time 120 https://asm.build/install.sh -o "$installer" || exit
  sh "$installer"
)

Running it again accepts only the same release bytes with the required ownership and permissions. The installer does not change PATH or run the downloaded command.

</details>

The update contract explains the verification policy and supported installation paths.

Run your first project

Install GNU Binutils before building a project. On Debian or Ubuntu, the binutils package supplies /usr/bin/as and /usr/bin/ld. Source dependencies also need /usr/bin/gzip. asm doctor checks the project and registry tools.

Run these commands from the directory that will contain your new project:

asm doctor &&
asm new hello &&
cd hello &&
asm run &&
asm test

The program prints:

Hello from asm!

Your project contains an asm.toml manifest, src/main.s, and tests/main.s. asm run builds the project before it runs the program. asm test builds and runs the test program. A test succeeds when it exits with code zero.

The hello examples show complete projects for x86-64 and ARM64. Read the CLI source for x86-64 or ARM64 to follow the implementation. Each implementation includes native project, registry, dependency, and self-update commands.

Update ASM

Self-update supports only the direct, user-owned $HOME/.local/bin/asm file. Use your package manager for an installation that it owns.

Run the installed command:

asm self update

ASM selects its own stubbi/asm package from the hub. It verifies the signed release, source commit, target, size, and digest before replacing the installed command. The new command takes effect on its next invocation. The update does not execute the downloaded file.

Use asm self update X.Y.Z to select an exact newer version. Replace X.Y.Z with the required version. ASM refuses an older version. An equal version leaves the command unchanged without verifying the installed file again. This result does not establish registry freshness.

Use asm self update --json for machine-readable output. Use asm self --help for the command contract.

Updates are manual. The index has no independently signed expiry or revocation record. Read the security model for the trust boundary and remaining limits.

Build from source

The source build needs Git, GNU Make, and GNU Binutils. Registry commands also need curl and GNU sha256sum. These instructions describe the released Linux CLI. For the experimental Apple Silicon source build, read the macOS qualification guide.

git clone https://github.com/stubbi/asm.git &&
cd asm &&
make &&
make install PREFIX="$HOME/.local" &&
export PATH="$HOME/.local/bin:$PATH" &&
asm version

The source installer refuses to replace a different existing asm command. To replace that command deliberately, add REPLACE=1 to the installation command. make uninstall PREFIX="$HOME/.local" removes the command only when its bytes match this build.

make selects the native implementation from the build host. The source archive contains both implementations. Its root asm.toml describes the x86-64 reference project; use Make to build the CLI on ARM64.

To cross-assemble the ARM64 CLI on Linux x86-64, install AArch64 GNU cross-binutils and run:

make ARCH=aarch64 build/asm-aarch64-linux

This creates build/asm-aarch64-linux. Run it on Linux ARM64, or use QEMU for limited behavior checks. Read the ARM64 implementation notes for its instruction baseline, ABI, and test boundary.

The current release contains both executables, source, checksums, build metadata, and signed provenance. The bootstrap installer performs the binary installation checks.

Describe a project

[package]
name = "hello"
version = "0.1.0"

[build]
source = "src/main.s"
target = "x86_64-linux"

asm new writes your native host target into this manifest. The example above declares an x86-64 project; an ARM64 project uses aarch64-linux. The initial manifest format accepts these four string fields. It rejects unknown fields, duplicate fields, invalid paths, and unsupported build targets. It does not accept arbitrary build scripts. The build uses GNU assembler syntax and writes the program to build/app.

Find a package

asm search hello
asm info stubbi/hello
asm versions stubbi/hello
asm fetch stubbi/hello@0.3.0 --kind source

The client checks the downloaded size and SHA-256 digest. It refuses to overwrite an existing destination. Fetch does not extract or execute the artifact. Use asm --help for the current command syntax.

Use a source dependency

This example requires Linux x86-64 and uses the System V ABI. From a project directory, add an exact version:

asm add stubbi/math@0.3.0 --target x86_64-linux
asm lock

ASM records the selection in asm.lock. It checks and extracts the source under .asm/packages. The build makes that directory available to the assembler. Include the library explicitly in your source:

.include "stubbi/math/0.3.0/x86_64-linux/src/min.s"

Follow the complete package example on Linux x86-64 for a program that calls the function.

The library exports asm_u64_min. Its contract and tests describe the arguments, result, and register changes.

Commit asm.lock with your project. Use asm sync to restore its exact source artifacts on another machine with the same target. Use asm build --locked when a missing lock file must be an error. Builds check existing locked dependencies before assembly.

asm update owner/name@X.Y.Z selects an explicit replacement version. asm remove owner/name removes a selection and retains cached files. Version ranges and transitive dependencies are future work. A lock file checks declared packages; it does not sandbox other assembler inputs.

Install a program

asm install stubbi/hello@0.3.0

ASM selects a host executable and checks its size, digest, and ELF structure. It installs to $HOME/.local/bin/hello without running the program. An existing destination causes an error. Use --output PATH to choose another new file.

Status

ASM is an early alpha. The table below describes the implemented release boundary. The roadmap describes the complete service we intend to build.

The native CLI host and a package target are separate concepts. Either client can fetch a package for another target. Each client builds and runs local projects for its native host target. asm targets lists that build target. The RISC-V hello package does not imply a RISC-V CLI. The Apple Silicon macOS port has separate native qualification and release gates. Version 0.3.0 has no macOS executable in the published catalog. Intel macOS, Windows, and general cross-build commands remain unsupported.

The local registry benchmark measures the native x86-64 search implementation. At 4,096 records, median elapsed time decreased by approximately 19–21 times on the measured host. Small-catalog wall-time results were inconclusive, and some tail latencies increased. These results do not measure ARM64, network installation, or hosted search capacity.

Transitive dependency resolution, automatic public publication, account recovery, and isolated public build workers remain release gates. The current service does not claim feature parity with npm, PyPI, or crates.io.

The assembly server experiment includes published source, build instructions, and local HTTP and PostgreSQL tests. It is not deployed at asm.build.

Publish from source

A release record identifies a public source repository and an exact Git commit. Each artifact has its own target, kind, size, URL, and digest. A published version fixes its artifact digests. Clients reject different bytes.

The initial publication path uses a reviewed pull request. The registry specification gives the format and commands. asm publish validates actual artifact bytes and writes a local submission record. It does not upload files or reserve a package name. Follow the publishing guide to prepare archives and submit the record.

The CLI's project, registry, dependency, archive, publication, and self-update logic is assembly. It uses mature system tools for assembly, linking, HTTPS, SHA-256, gzip, and signature verification. Python handles registry operations and release automation. JavaScript supports the website.

Security evidence

Useful security evidence answers a specific question. ASM records metadata checks, artifact checks, provenance, formal proofs, and agent review separately. A missing result stays visible as missing.

Lean and Kraken can support proofs for suitable assembly routines. A proof must identify the theorem, instruction model, toolchain, assumptions, and artifact it covers. The public service also needs isolated workers and trusted verification rules.

Agents can propose implementations, tests, proof candidates, and reviews. They cannot grant a release a security status by opinion. Read the security design for the required gates and current limits.

Contribute

Read AGENTS.md, design.md, and the writing guide. The same contribution rules apply to people and agents. Follow the code of conduct in project discussions. The maintenance guide defines review, release, and incident procedures.

To run all local checks, install Python 3.11 or later and Node.js 18 or later. On Linux x86-64, release checks also need AArch64 and RISC-V GNU cross-binutils and QEMU user emulation. Then run:

make check

Tests cover user-visible behavior and rejection paths. CI runs the complete CLI contract suite on native x86-64 and ARM64 runners. Both jobs must pass before a release can proceed. Keep each commit focused. Include the reason for the change and the relevant validation in your pull request. Report a defect through GitHub Issues.

License

ASM uses AGPL-3.0-or-later. Changes to the platform should remain available to its users, including users of modified hosted versions. Starter code and reference examples use MIT. Packages retain the license declared for each version. Read the license scope, or run asm license.