# asm (stubbi/asm)

> Asm is a package registry and command-line tool for assembly projects. You create a project, use shared packages, and publish releases with their source and verification results.

- GitHub: https://github.com/stubbi/asm
- GitHub.Locker page: https://github.locker/stubbi/asm
- Stars: 326
- Language: Assembly
- License: AGPL-3.0
- Last push: 2026-11-05

## Questions and answers

Written by GitHub.Locker from the README and the repository; check the README below for details.

**Is this a new programming language?**

No. Assembly stays the language. Asm adds a shared package ecosystem on top, with named packages, explicit machine targets, and repeatable builds.

**How do I get it running?**

Install GitHub CLI 2.93.0 or later, run the installer, apply the PATH command it shows, and then check the version it reports.

**What do I need installed first?**

On Linux you need GitHub CLI, curl, GNU Coreutils, and GNU Binutils for the assembler and linker. On Apple Silicon macOS you need GitHub CLI at /opt/homebrew/bin/gh and Xcode Command Line Tools.

**What is the catch?**

It is an early alpha. Transitive dependencies, self-service publication, account recovery, and hosted formal verification are still planned, and cross-target native-library linking is unsupported.

**Which machines does it run on?**

Linux x86-64, Linux ARM64, and Apple Silicon Macs on macOS 15 or later. Windows is not listed in the README.

**Can one project target several machines?**

Yes. A project can hold several named target implementations, and asm build --target riscv64-linux builds a separate Linux artifact without running it.

**Why would anyone write assembly today?**

The README argues that as code gets cheaper to write, running it costs more. Assembly gives direct control over instructions, memory layout, and CPU features, which AI could make practical for much more software.

**How do I create a project and run its tests?**

Install Binutils or Xcode Command Line Tools, then create a new project. asm build links the executable into build/app, asm run executes it, and asm test runs tests/main.s, where a zero exit code passes.

**Can I install a package's program directly?**

Yes. On Linux x86-64 or ARM64, installing a package puts the matching executable in $HOME/.local/bin, and Asm tracks it in a local inventory. Use --output to pick another path.


---

## README (checked against GitHub 2026-11-06)

Source: https://github.com/stubbi/asm/blob/main/README.md

# asm

**A home for assembly.**

Asm is a package registry and command-line tool for assembly projects.
Create a project, use packages, and share releases with their source and verification results.

[Website](https://asm.build) · [Quick start](#quick-start) · [Status](#status) · [Why Asm](docs/why-asm.md) · [Security model](docs/specs/security.md)

## A new era for software

Programming languages made software practical for people to write and maintain.
AI opens up a different approach: generate implementations for the machine, and judge them by the experience they deliver.

The priorities are familiar: software that works, responds quickly, and protects its users.
As code becomes cheaper to produce, the cost of running it matters more.
Memory, compute, and energy use affect both the experience and the cost of delivering it.

Assembly gives direct control over instructions, memory layout, and CPU features.
AI could make that control practical for a much wider range of software.
Each implementation still needs a way to reach the people and projects that can use it.

Asm brings assembly into a shared package ecosystem: named packages, explicit machine targets, repeatable builds, and evidence tied to each release.
The goal is to make efficient, dependable software practical to distribute and reuse.

[More on the technical reasoning](docs/why-asm.md).

## Quick start

Asm 0.6.0 supports **Linux x86-64, Linux ARM64, and Apple Silicon with macOS 15 or later**.

### Install the command

Install [GitHub CLI 2.93.0 or later](https://cli.github.com/) before running the installer.

| System | Required tools |
| --- | --- |
| Linux | GitHub CLI at `/usr/bin/gh`, curl, and GNU Coreutils in `/usr/bin`. |
| Apple Silicon macOS | GitHub CLI at `/opt/homebrew/bin/gh`; other tools are supplied by macOS. |

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

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

```sh
asm version
```

On Apple Silicon, the output is `asm 0.6.0 (aarch64-macos)`.

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

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

Add this command to your shell configuration to keep the setting.

</details>

[Installer source](https://asm.build/install.sh) · [Installation requirements](docs/self-update.md) · [macOS filesystem and signing requirements](docs/macos.md)

### Run your first project

Install GNU Binutils on Linux, or Xcode Command Line Tools on macOS with `xcode-select --install`.
On Debian or Ubuntu, the `binutils` package supplies the assembler and linker.

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

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

The program prints:

```text
Hello from asm!
```

The project contains `asm.toml`, `src/main.s`, and `tests/main.s`.
Assembly source is text; `asm build` assembles and links it into the executable `build/app`.
`asm run` also runs that executable.
`asm test` builds and runs `tests/main.s`; a zero exit code passes the test.

### Update Asm

For an installation made with the installer:

```sh
asm self update
```

For an installation managed by another package manager, use that manager to update Asm.

## Projects and packages

### Describe a project

`asm.toml` names the project, its source file, and its target:

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

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

`asm new` sets the target for your machine.
Linux ARM64 uses `aarch64-linux`; Apple Silicon macOS uses `aarch64-macos`.

Asm 0.6.0 also accepts one project with several `[target.<id>]` implementations.
Each target has its own source, test, and optional native-library fields.
The [hello](examples/hello/README.md) and [math](examples/math/README.md) projects keep these inputs under `targets/<id>/`.
`asm build --target riscv64-linux` builds a separate Linux artifact.
`asm test --target riscv64-linux --no-run` builds its test without executing it.
Target-specific dependency selections share one v2 lock.
See the [multi-target project contract](docs/multi-target-projects.md) for tools, commands, and platform limits.

### Find a package

```sh
asm search hello
asm info stubbi/hello
asm versions stubbi/hello
asm fetch stubbi/hello@0.6.0 --target x86_64-linux --kind source
```

This downloads the Linux x86-64 source archive and checks its size and SHA-256 digest.
Use `asm --help` for command options.

### Use a source dependency

This example requires Linux x86-64 and gzip at `/usr/bin/gzip`.
From a project directory:

```sh
asm add stubbi/math@0.6.0 --target x86_64-linux
asm lock
```

Include the library in your source:

```asm
.include "stubbi/math/0.6.0/x86_64-linux/targets/x86_64-linux/src/min.s"
```

The [complete example](docs/use-a-package.md) calls `asm_u64_min` and explains its calling convention.

Commit `asm.lock` with your project.
`asm sync` restores the recorded dependencies.
`asm build --locked` requires the lock file and checks dependencies before assembly.

### Install a program

On Linux x86-64 or ARM64:

```sh
asm install stubbi/hello@0.6.0
```

This installs the matching executable at `$HOME/.local/bin/hello`.
Use `--output PATH` to choose another destination.
The destination must be a new file.
Asm records both default and custom destinations in its local inventory.
One package identity has at most one managed installation.

Inspect and manage recorded programs:

```sh
asm installed
asm upgrade stubbi/hello
asm uninstall stubbi/hello
```

`upgrade` selects the highest available host version from the recorded registry.
Use `owner/name@version` to select an exact version.
`update` and `remove` continue to manage project source dependencies.

Published 0.4.0 binaries do not include these management commands.
Updating Asm does not adopt earlier installations; programs without an inventory record remain unmanaged.
See the [installed-program contract](docs/installed-programs.md) for file checks, recovery, and limits.

## Status

Asm is an early alpha.

| Area | Available today |
| --- | --- |
| Native CLI | Linux x86-64, Linux ARM64, and Apple Silicon macOS 15+. |
| Projects | Create, inspect, build, run, test, and clean; select native or standalone Linux implementations. |
| Packages | Search, inspect versions, download source, install executables, list installations, upgrade, and uninstall. |
| Dependencies | Exact direct source dependencies, with target-specific selections in a shared lock file. |
| Registry | Package search, target filters, release records, and verification results. |
| Publication | Source archives and release records submitted through reviewed pull requests. |
| Artifact checks | Metadata, size, SHA-256, archive structure, and executable format. |
| CLI updates | Manual updates with signed release provenance. |

Asm 0.6.0 adds named target implementations, standalone Linux cross builds, and target-specific dependency locks.
The [release notes](docs/releases/0.6.0.md) describe the commands, artifact scope, and limits.

Projects select the native host by default.
Explicit standalone Linux builds produce separate artifacts without executing them.
Cross-target native-library linking remains unsupported.
Packages can provide separate artifacts for other targets, including RISC-V Linux.

Transitive dependencies, self-service publication, account recovery, isolated public build workers, and hosted formal verification are planned.
The [roadmap](docs/roadmap.md) tracks that work.

## Publish from source

A package release records its source repository, exact Git commit, target, and artifact digests.
`asm publish` checks the release files and prepares a local submission record.
Publication proceeds through a pull request to the registry.

Follow the [publishing guide](registry/README.md) for the commands and submission process.

## Build with an AI

The [Asm development skill](skills/asm-build/SKILL.md) guides requirements, target selection, package reuse, tests, and bounded performance work.
The [MCP setup guide](docs/agents.md) connects AI clients to read-only discovery, planning, and measurement-comparison tools.
The AI uses its authorized workspace tools to build and execute software.

Hosted registry and MCP deployment remain under qualification.
The [hosted registry contract](docs/hosted-registry.md) records the implementation scope and remaining recovery, security, and runtime gates.

## Security evidence

Package records distinguish artifact checks, build provenance, formal proofs, and agent reviews.
Each result applies to a particular check and artifact.
Missing results appear as missing.

The [security model](docs/specs/security.md) explains the checks, trust boundaries, and planned verification services.

## Build from source

Install Git, Make, and Python 3.11 or later.
Linux also requires GNU Binutils, curl, GNU Coreutils, and gzip.
Apple Silicon macOS requires Xcode Command Line Tools.

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

`make` selects the native implementation for your machine.
The root `asm.toml` describes the Linux x86-64 reference build.
The [ARM64 notes](cli/aarch64/README.md) cover cross-assembly; the [macOS guide](docs/macos.md) covers Apple Silicon builds.

## Contribute

Start with [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).
The [repository layout](CONTRIBUTING.md#repository-layout) explains the source, licenses, experiments, and retained measurements.
Follow the [design guide](design.md), [writing guide](docs/writing.md), and [code of conduct](CODE_OF_CONDUCT.md).

The CLI uses assembly for project and package logic, with system tools for assembly, linking, transport, and cryptographic checks.
Python handles registry operations, release automation, and the separate MCP protocol adapter; JavaScript supports the website.
The hosted registry runtime foundation uses assembly with mature protocol and database libraries.
The [bundled-verifier migration](docs/trusted-distribution.md) uses Go for the Sigstore and TUF adapter.

On Linux, run `make check` from the repository root.
On macOS, run `make test`.
The [contribution guide](CONTRIBUTING.md) lists test prerequisites, including cross-toolchains.
Include the reason for your change and its validation in the pull request.
Report defects through [GitHub Issues](https://github.com/stubbi/asm/issues).

## License

Asm uses [AGPL-3.0-or-later](LICENSE).
Starter code and reference examples use MIT.
Packages retain the license declared for each version.
See the [license scope](LICENSING.md), or run `asm license`.