asm GitHub

AN OPEN SOURCE PROJECT

Packages for
assembly.

Build assembly projects with the target and interface spelled out.

The assembly CLI runs on Linux x86-64, Linux ARM64, and Apple Silicon macOS 15 or later.

Install Asm Browse packages
EARLY ALPHANative Linux and macOS CLI · exact package versions
Native host / assembly

YOUR FIRST PROJECT

01
01

Create a project

asm new hello
02

Build the program

cd hello
asm build
03

Run it

asm runHello from asm!
Install Asm and native build tools before you start.
Read the example source: Linux x86-64 · Linux ARM64
01 Assembly at the core
02 Targets before assumptions
03 Evidence with a scope

GET STARTED

Install Asm.

The installer selects a published executable for your operating system and CPU. Install it for your user account, then run the first-project commands above.

Version 0.6.0 supports Linux x86-64, Linux ARM64, and Apple Silicon macOS 15 or later. Intel macOS is unsupported.

The installer supports Linux ARM64 and macOS 15 or later on ARM64 and Linux x86_64. It selects the matching build on your machine. On Linux, it uses curl and GNU Coreutils in /usr/bin. Install GitHub CLI at /usr/bin/gh. On macOS, it uses system tools, including Perl and /usr/bin/shasum. Install GitHub CLI at /opt/homebrew/bin/gh. The installation requires a local APFS volume with ownership enabled. Use GitHub CLI 2.93.0 or later before you start.

INSTALL Asm 0.6.0
curl -qfsS -m120 https://asm.build/install.sh | sh
Linux ARM64 and macOS 15 or later on ARM64 and Linux x86_64Read the installer ↗

The Asm installer does not use sudo or a GitHub login. It checks the exact file and its signed release attestation. It installs to $HOME/.local/bin/asm and preserves a different existing asm file.

Apply the PATH command shown by the installer. Then run asm version. For later updates, run asm self update.

Set PATH for this terminal

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.

Inspect the installer first

Download the script to a temporary file:

DOWNLOAD FOR REVIEW
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
Use in scripts and CI

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

INSTALL FROM FILE
(
  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.

Build from source

Install Git, Make, and Python 3.11 or later. Linux needs GNU binutils; macOS needs Xcode Command Line Tools. These commands install Asm for your user account.

BUILD FROM SOURCE
# Linux or Apple Silicon macOS · native build tools
git clone https://github.com/stubbi/asm.git &&
cd asm &&
make &&
make install PREFIX="$HOME/.local" &&
export PATH="$HOME/.local/bin:$PATH" &&
asm version
Native assembly CLIBuild instructions

The installer refuses to replace a different command. The PATH change applies to this terminal.

Linux projects need GNU binutils. macOS projects need Xcode Command Line Tools. Registry commands use curl, SHA-256 tools, and gzip from the host.

Read the installation guide

PACKAGE REGISTRY

Inspect a package.

Read the source, check the target, and inspect the release records. This catalog uses the published registry index.

Open the index

Package names and versions come from the registry records.

You can also browse the CLI source and the hello examples for x86-64 and ARM64 on GitHub.

A checksum checks file integrity. Review the source and evidence before you run a package.

THE PACKAGE MODEL

The target is part
of the package.

A useful assembly routine should be easy to reuse. Its package must state which machine it supports and how other code can call it.

DESIGN DIRECTION
01

A machine contract.

Architecture, instruction-set requirements, operating system, and object format describe where the code can run.

archISAOSformat
02

An interface contract.

The application binary interface (ABI) defines calls and data layout. Packages also state symbol names, memory ownership, and register use.

ABIsymbolsownership
03

A record of the build.

Declared tools, pinned inputs, and recorded outputs give consumers something concrete to reproduce and review.

toolchaininputsdigests
Read the package design

THE VERIFICATION MODEL

Show the evidence.

Each security claim must name the version, target, and assumptions it covers. Consumers need access to its reports and artifacts.

Read the security model

Hosted proof and analysis services are planned.
Each release lists its current checks.

01

Provenance

Who published the package, which source produced it, and which build process was used.

Identity + origin
02

Scanning

Reports from named tools, with their versions, findings, and coverage available for review.

Tool + ruleset + findings
03

Testing

Recorded results for defined inputs and targets, including boundary cases and ABI behavior.

Cases + environment + results
04

Scoped proofs

Specific properties, explicit assumptions, and machine-checkable artifacts where the tooling supports them.

Property + assumptions + checker

WHY Asm

Make the useful
work reusable.

Software should work well for its users and cost less to run. Assembly can give developers direct control over how a machine does that work.

Our working assumption is that AI-assisted development may make assembly practical for more projects. It may also reduce the cost of ports. Both claims need evidence.

Generated code still needs review and verification. Performance claims need reproducible measurements, including results that show no improvement. Asm is building the shared package, release, and evidence tools for that work.

Read the project motivation

A measured example

An asmwc experiment measured default counting on a 128 MiB text file. On Apple M3 with macOS 15.6.1, median time was 15.234 ms for optimized assembly and 68.468 ms for native Rust. Each implementation had 24 samples with a warm file cache. The comparison includes algorithm, I/O, and startup differences. Asm checked the published records; we have not reproduced the experiment.

Read the experiment and its limits

BUILT IN THE OPEN

What comes next.

The current release covers local projects and exact dependencies. Planned work includes hosted publication, dependency resolution, more hosts, and hosted verification.

Full roadmap
  1. NOW
    01

    CLI foundation

    A native assembly executable, local project commands, and a format for package records.

  2. NOW
    02

    Exact dependencies

    Locked versions, checked source files, native executable installs, and reproducible release artifacts.

  3. PLANNED
    03

    Registry operations

    Authenticated publication, ownership controls, account recovery, and dependency range resolution.

  4. RESEARCH
    04

    Deeper assurance

    Clients for more hosts, isolated analysis, and scoped proof checks for supported routines.

CONTRIBUTE

There’s a lot
left to build.

Explore the repository Bring an idea or an issue