Netwide Assembly rules for Bazel

Ruleset and toolchain for assembling Netwide Assembly (nasm) sources in Bazel.

This is an early release, and is provided without assurances. Contributions, feedback, and bug reports are welcome.

Getting Started

Add the following snippet to your MODULE.bazel file:

bazel_dep(name = "rules_nasm", version = "{SEE_RELEASES}")

register_toolchains(
    "@rules_nasm//nasm/toolchain",
)

See the release notes for getting started with the latest version.

Note that toolchain registration can be updated to point to a custom toolchain if users wish to have full control over the version of nasm used in different configurations. See nasm_toolchain for more details on defining toolchains.

Supported platforms

The following platforms are currently supported:

Linux x86_64
MacOS x86_64
Windows x86_64

Known Issues

Bugs, known issues, and planned features are documented in Issues. Additional issue reports are welcome.

rules_nasm

Bazel rules for Netwide Assembly (nasm).

Rules

Functions

nasm_library

load("@rules_nasm//nasm:defs.bzl", "nasm_library")

nasm_library(name, srcs, hdrs, copts, includes, preincs)

Assemble an nasm source for use as a C++ dependency.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	The assembly source file. Must have an extension of .asm, .nasm, .s.	List of labels	optional	`[]`
hdrs	Other assembly sources which may be included by `src`. Must have an extension of .asm, .nasm, .s, .i, .inc.	List of labels	optional	`[]`
copts	Additional compilation flags to `nasm`.	List of strings	optional	`[]`
includes	Directories which will be added to the search path for include files.	List of strings	optional	`[]`
preincs	Assembly sources which will be included and processed before the source file. Sources will be included in the order listed. Must have an extension of .asm, .nasm, .s, .i, .inc.	List of labels	optional	`[]`

nasm_toolchain

load("@rules_nasm//nasm:defs.bzl", "nasm_toolchain")

nasm_toolchain(name, copts, nasm)

A toolchain for configuring nasm rules.

A toolchain can be defined by adding a snippet like the following somewhere in a BUILD.bazel file within your workspace.

load("@rules_nasm//nasm:nasm_toolchain.bzl", "nasm_toolchain")

nasm_toolchain(
    name = "nasm_toolchain",
    copts = select({
        "@rules_nasm//nasm/toolchain:elf64": ["-felf64"],
        "@rules_nasm//nasm/toolchain:win64": ["-fwin64"],
        "@rules_nasm//nasm/toolchain:macho64": ["-fmacho64"],
        "//conditions:default": [],
    }),
    nasm = "@nasm",
    visibility = ["//visibility:public"],
)

toolchain(
    name = "toolchain",
    toolchain = ":nasm_toolchain",
    toolchain_type = "@rules_nasm//nasm:toolchain_type",
    visibility = ["//visibility:public"],
)

Once the toolchain is defined, it will need to be registered in the MODULE.bazel file.

register_toolchains("//:toolchain")

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
copts	Default arguments to pass to the `nasm` executable.	List of strings	optional	`[]`
nasm	The `nasm` executable.	Label	required

nasm_cc_binary

load("@rules_nasm//nasm:defs.bzl", "nasm_cc_binary")

nasm_cc_binary(*, name, srcs, hdrs, preincs, includes, **kwargs)

Assemble a source file as an executable.

Assembles an nasm source file as an executable binary. The assembled object file will be linked against the C standard library, meaning that it must define a starting function with the label expected by system libraries, can reference C standard library functions, and must not export labels which conflict with the C standard library.

(Standalone binaries which are not linked to standard libraries are planned for a future release.)

NB: The mangling of function labels is defined by the ABI of the target platform. Some degree of portability can be ensured by using a macro to define global labels, and deduce the target platform by inspecting the target binary format.

PARAMETERS

Name	Description	Default Value
name	A unique name for this target.	none
srcs	The assembly source files.	none
hdrs	Other assembly sources which may be included by `srcs`.	`None`
preincs	Assembly sources which will be included and processed before the source file. Sources will be included in the order listed.	`None`
includes	Directories which will be added to the search path for include files.	`None`
kwargs	Additional keyword arguments passed to the `cc_binary` rule.	none

nasm_cc_library

load("@rules_nasm//nasm:defs.bzl", "nasm_cc_library")

nasm_cc_library(*, name, srcs, hdrs, preincs, includes, **kwargs)

Assemble an nasm source for use as a C++ dependency.

Assembled object files should be usable as C compilation units. Rather than create a CcInfo object directly, we pass the assembled object file as the src to a cc_library rule, which creates a corresponding provider, and captures any additional dependencies.

PARAMETERS

Name	Description	Default Value
name	A unique name for this target.	none
srcs	The assembly source files.	none
hdrs	Other assembly sources which may be included by `srcs`.	`None`
preincs	Assembly sources which will be included and processed before the source file. Sources will be included in the order listed.	`None`
includes	Directories which will be added to the search path for include files.	`None`
kwargs	Additional keyword arguments passed to the `cc_library` rule.	none

nasm_cc_test

load("@rules_nasm//nasm:defs.bzl", "nasm_cc_test")

nasm_cc_test(*, name, srcs, size, hdrs, preincs, includes, **kwargs)

Assemble and execute a test assembly program.

PARAMETERS

Name	Description	Default Value
name	A unique name for this target.	none
srcs	The assembly source files.	none
size	The "heaviness" of a test target. See Bazel reference for details.	`None`
hdrs	Other assembly sources which may be included by `srcs`.	`None`
preincs	Assembly sources which will be included and processed before the source file. Sources will be included in the order listed.	`None`
includes	Directories which will be added to the search path for include files.	`None`
kwargs	Additional keyword arguments passed to the `cc_test` rule.	none