const std = @import("std");

const Build = std.Build;

const LazyPath = Build.LazyPath;

const internals = @import("build-internals");

pub const Target = internals.Target;

pub const Chip = internals.Chip;

pub const HardwareAbstractionLayer = internals.HardwareAbstractionLayer;

pub const Board = internals.Board;

pub const BinaryFormat = internals.BinaryFormat;

pub const MemoryRegion = internals.MemoryRegion;

const regz = @import("tools/regz");

// If more ports are available, the error "error: evaluation exceeded 1000 backwards branches" may occur.

// In such cases, consider increasing the argument value for @setEvalBranchQuota().

const port_list: []const struct {

name: [:0]const u8,

dep_name: [:0]const u8,

} = &.{

.{ .name = "esp", .dep_name = "port/espressif/esp" },

.{ .name = "gd32", .dep_name = "port/gigadevice/gd32" },

.{ .name = "atsam", .dep_name = "port/microchip/atsam" },

.{ .name = "avr", .dep_name = "port/microchip/avr" },

.{ .name = "nrf5x", .dep_name = "port/nordic/nrf5x" },

.{ .name = "lpc", .dep_name = "port/nxp/lpc" },

.{ .name = "rp2xxx", .dep_name = "port/raspberrypi/rp2xxx" },

.{ .name = "stm32", .dep_name = "port/stmicro/stm32" },

.{ .name = "ch32v", .dep_name = "port/wch/ch32v" },

};

const exe_targets: []const std.Target.Query = &.{

.{ .cpu_arch = .aarch64, .os_tag = .macos },

.{ .cpu_arch = .aarch64, .os_tag = .linux },

.{ .cpu_arch = .aarch64, .os_tag = .windows },

.{ .cpu_arch = .x86_64, .os_tag = .macos },

.{ .cpu_arch = .x86_64, .os_tag = .linux, .abi = .musl },

.{ .cpu_arch = .x86_64, .os_tag = .windows },

};

pub fn build(b: *Build) void {

const optimize = b.standardOptimizeOption(.{});

const generate_linker_script_exe = b.addExecutable(.{

.name = "generate_linker_script",

.root_source_file = b.path("tools/generate_linker_script.zig"),

.target = b.host,

.optimize = optimize,

});

generate_linker_script_exe.root_module.addImport(

"build-internals",

b.dependency("build-internals", .{}).module("build-internals"),

);

b.installArtifact(generate_linker_script_exe);

const boxzer_dep = b.dependency("boxzer", .{});

const boxzer_exe = boxzer_dep.artifact("boxzer");

const boxzer_run = b.addRunArtifact(boxzer_exe);

if (b.args) |args|

boxzer_run.addArgs(args);

const package_step = b.step("package", "Package monorepo using boxzer");

package_step.dependOn(&boxzer_run.step);

generate_release_steps(b);

}

fn generate_release_steps(b: *Build) void {

const release_regz_step = b.step("release-regz", "Generate the release binaries for regz");

const release_uf2_step = b.step("release-uf2", "Generate the release binaries for uf2");

for (exe_targets) |t| {

const release_target = b.resolveTargetQuery(t);

const regz_dep = b.dependency("tools/regz", .{

.optimize = .ReleaseSafe,

.target = release_target,

});

const regz_artifact = regz_dep.artifact("regz");

const regz_target_output = b.addInstallArtifact(regz_artifact, .{

.dest_dir = .{

.override = .{

.custom = t.zigTriple(b.allocator) catch unreachable,

},

},

});

release_regz_step.dependOn(&regz_target_output.step);

}

for (exe_targets) |t| {

const release_target = b.resolveTargetQuery(t);

const uf2_dep = b.dependency("tools/uf2", .{

.optimize = .ReleaseSafe,

.target = release_target,

});

const uf2_artifact = uf2_dep.artifact("elf2uf2");

const uf2_target_output = b.addInstallArtifact(uf2_artifact, .{

.dest_dir = .{

.override = .{

.custom = t.zigTriple(b.allocator) catch unreachable,

},

},

});

release_uf2_step.dependOn(&uf2_target_output.step);

}

}

pub const PortSelect = blk: {

var fields: []const std.builtin.Type.StructField = &.{};

for (port_list) |port| {

fields = fields ++ [_]std.builtin.Type.StructField{.{

.name = port.name,

.type = bool,

.default_value = @as(*const anyopaque, @ptrCast(&false)),

.is_comptime = false,

.alignment = @alignOf(bool),

}};

}

break :blk @Type(.{

.Struct = .{

.layout = .auto,

.fields = fields,

.decls = &.{},

.is_tuple = false,

},

});

};

// Don't know if this is required but it doesn't hurt either.

// Helps in case there are multiple microzig instances including the same ports (eg: examples).

pub const PortCache = blk: {

var fields: []const std.builtin.Type.StructField = &.{};

for (port_list) |port| {

const typ = ?(custom_lazy_import(port.dep_name) orelse struct {});

fields = fields ++ [_]std.builtin.Type.StructField{.{

.name = port.name,

.type = typ,

.default_value = @as(*const anyopaque, @ptrCast(&@as(typ, null))),

.is_comptime = false,

.alignment = @alignOf(typ),

}};

}

break :blk @Type(.{

.Struct = .{

.layout = .auto,

.fields = fields,

.decls = &.{},

.is_tuple = false,

},

});

};

var port_cache: PortCache = .{};

/// The MicroZig build system.

///

/// # Example usage:

/// ```zig

/// const std = @import("std");

/// const microzig = @import("microzig");

///

/// const MicroBuild = microzig.MicroBuild(.{

/// .rp2xxx = true,

/// });

///

/// pub fn build(b: *std.Build) void {

/// const optimize = b.standardOptimizeOption(.{});

///

/// const mz_dep = b.dependency("microzig", .{});

/// const mb = MicroBuild.init(b, mz_dep) orelse return;

///

/// const fw = mb.add_firmware(.{

/// .name = "test",

/// .root_source_file = b.path("src/main.zig"),

/// .target = mb.ports.rp2xxx.boards.raspberrypi.pico,

/// .optimize = optimize,

/// });

/// mb.install_firmware(fw, .{});

/// }

/// ```

pub fn MicroBuild(port_select: PortSelect) type {

return struct {

const SelectedPorts = blk: {

var fields: []const std.builtin.Type.StructField = &.{};

for (port_list) |port| {

if (@field(port_select, port.name)) {

const typ = custom_lazy_import(port.dep_name) orelse struct {};

fields = fields ++ [_]std.builtin.Type.StructField{.{

.name = port.name,

.type = typ,

.default_value = null,

.is_comptime = false,

.alignment = @alignOf(typ),

}};

}

}

break :blk @Type(.{

.Struct = .{

.layout = .auto,

.fields = fields,

.decls = &.{},

.is_tuple = false,

},

});

};

const Self = @This();

builder: *Build,

dep: *Build.Dependency,

core_dep: *Build.Dependency,

drivers_dep: *Build.Dependency,

/// Contains all the ports you selected.

ports: SelectedPorts,

const InitReturnType = blk: {

@setEvalBranchQuota(2000);

var ok = true;

for (port_list) |port| {

if (@field(port_select, port.name)) {

ok = ok and custom_lazy_import(port.dep_name) != null;

}

}

if (ok) {

break :blk *Self;

} else {

break :blk noreturn;

}

};

/// Initializes the microzig build system. Returns null when there are ports

/// that haven't been fetched yet (it uses lazy dependencies internally).

pub fn init(b: *Build, dep: *Build.Dependency) ?InitReturnType {

if (InitReturnType == noreturn) {

inline for (port_list) |port| {

if (@field(port_select, port.name)) {

_ = dep.builder.lazyDependency(port.dep_name, .{});

}

}

return null;

}

var ports: SelectedPorts = undefined;

inline for (port_list) |port| {

if (@field(port_select, port.name)) {

@field(ports, port.name) = if (@field(port_cache, port.name)) |cached_port| cached_port else blk: {

const port_dep = dep.builder.lazyDependency(port.dep_name, .{}).?;

const instance = custom_lazy_import(port.dep_name).?.init(port_dep);

@field(port_cache, port.name) = instance;

break :blk instance;

};

}

}

const mb = b.allocator.create(Self) catch @panic("out of memory");

mb.* = .{

.builder = b,

.dep = dep,

.core_dep = dep.builder.dependency("core", .{}),

.drivers_dep = dep.builder.dependency("drivers", .{}),

.ports = ports,

};

return mb;

}

/// Configuration options for the `add_firmware` function.

pub const CreateFirmwareOptions = struct {

/// The name of the firmware file.

name: []const u8,

/// The MicroZig target that the firmware is built for. Either a board or a chip.

target: *const Target,

/// The optimization level that should be used. Usually `ReleaseSmall` or `Debug` is a good choice.

/// Also using `std.Build.standardOptimizeOption` is a good idea.

optimize: std.builtin.OptimizeMode,

/// The root source file for the application. This is your `src/main.zig` file.

root_source_file: LazyPath,

/// Imports for the application.

imports: []const Build.Module.Import = &.{},

/// If set, overrides the `single_threaded` property of the target.

single_threaded: ?bool = null,

/// If set, overrides the `bundle_compiler_rt` property of the target.

bundle_compiler_rt: ?bool = null,

/// If set, overrides the `hal` property of the target.

hal: ?HardwareAbstractionLayer = null,

/// If set, overrides the `board` property of the target.

board: ?Board = null,

/// If set, overrides the `linker_script` property of the target.

linker_script: ?LazyPath = null,

/// Strips stack trace info from final executable.

strip: bool = false,

/// Enables the following build options for the firmware executable

/// to support stripping unused symbols in all modes (not just Release):

/// exe.link_gc_sections = true;

/// exe.link_data_sections = true;

/// exe.link_function_sections = true;

strip_unused_symbols: bool = true,

/// Additional patches the user may apply to the generated register

/// code. This does not override the chip's existing patches.

patches: []const regz.patch.Patch = &.{},

};

fn serialize_patches(b: *Build, patches: []const regz.patch.Patch) []const u8 {

var buf = std.ArrayList(u8).init(b.allocator);

for (patches) |patch| {

std.json.stringify(patch, .{}, buf.writer()) catch @panic("OOM");

buf.writer().writeByte('\n') catch @panic("OOM");

}

return buf.toOwnedSlice() catch @panic("OOM");

}

/// Creates a new firmware for a given target.

pub fn add_firmware(mb: *Self, options: CreateFirmwareOptions) *Firmware {

const b = mb.dep.builder;

const target = options.target;

const zig_target = b.resolveTargetQuery(target.chip.cpu);

const cpu = Cpu.init(zig_target.result);

// TODO: let the user override which ram section to use the stack on,

// for now just using the first ram section in the memory region list

const first_ram = blk: {

for (target.chip.memory_regions) |region| {

if (region.kind == .ram)

break :blk region;

} else @panic("no ram memory region found for setting the end-of-stack address");

};

const maybe_hal = options.hal orelse target.hal;

const maybe_board = options.board orelse target.board;

const config = b.addOptions();

config.addOption(bool, "has_hal", maybe_hal != null);

config.addOption(bool, "has_board", maybe_board != null);

config.addOption([]const u8, "cpu_name", zig_target.result.cpu.model.name);

config.addOption([]const u8, "chip_name", target.chip.name);

config.addOption(usize, "end_of_stack", first_ram.offset + first_ram.length);

const core_mod = b.createModule(.{

.root_source_file = mb.core_dep.path("src/microzig.zig"),

.imports = &.{

.{

.name = "config",

.module = config.createModule(),

},

.{

.name = "drivers",

.module = mb.drivers_dep.module("drivers"),

},

},

});

const cpu_mod = if (target.chip.cpu_module_file) |root_source_file|

b.createModule(.{

.root_source_file = root_source_file,

})

else

cpu.create_module(b, mb.core_dep);

cpu_mod.addImport("microzig", core_mod);

core_mod.addImport("cpu", cpu_mod);

const regz_exe = b.dependency("tools/regz", .{ .optimize = .ReleaseSafe }).artifact("regz");

const chip_source = switch (target.chip.register_definition) {

.atdf, .svd => |file| blk: {

const regz_run = b.addRunArtifact(regz_exe);

regz_run.addArg("--microzig");

regz_run.addArg("--format");

regz_run.addArg(@tagName(target.chip.register_definition));

regz_run.addArg("--output_path"); // Write to a file

const zig_file = regz_run.addOutputFileArg("chip.zig");

var patches = std.ArrayList(regz.patch.Patch).init(b.allocator);

// From chip definition

patches.appendSlice(target.chip.patches) catch @panic("OOM");

// From user invoking `add_firmware`

patches.appendSlice(options.patches) catch @panic("OOM");

if (patches.items.len > 0) {

// write patches to file

const patch_ndjson = serialize_patches(b, patches.items);

const write_file_step = b.addWriteFiles();

const patch_file = write_file_step.add("patch.ndjson", patch_ndjson);

regz_run.addArg("--patch_path");

regz_run.addFileArg(patch_file);

}

regz_run.addFileArg(file);

break :blk zig_file;

},

.zig => |src| src,

};

const chip_mod = b.createModule(.{

.root_source_file = chip_source,

});

chip_mod.addImport("microzig", core_mod);

core_mod.addImport("chip", chip_mod);

if (maybe_hal) |hal| {

const hal_mod = b.createModule(.{

.root_source_file = hal.root_source_file,

.imports = hal.imports,

});

hal_mod.addImport("microzig", core_mod);

core_mod.addImport("hal", hal_mod);

}

if (maybe_board) |board| {

const board_mod = b.createModule(.{

.root_source_file = board.root_source_file,

.imports = board.imports,

});

board_mod.addImport("microzig", core_mod);

core_mod.addImport("board", board_mod);

}

const app_mod = mb.builder.createModule(.{

.root_source_file = options.root_source_file,

.imports = options.imports,

});

app_mod.addImport("microzig", core_mod);

core_mod.addImport("app", app_mod);

const fw = mb.builder.allocator.create(Firmware) catch @panic("out of memory");

fw.* = .{

.mb = mb,

.core_mod = core_mod,

.artifact = mb.builder.addExecutable(.{

.name = options.name,

.optimize = options.optimize,

.target = zig_target,

.linkage = .static,

.root_source_file = mb.core_dep.path("src/start.zig"),

.strip = options.strip,

}),

.app_mod = app_mod,

.target = target,

.emitted_files = Firmware.EmittedFiles.init(mb.builder.allocator),

};

fw.artifact.bundle_compiler_rt = options.bundle_compiler_rt orelse fw.target.bundle_compiler_rt;

fw.artifact.link_gc_sections = options.strip_unused_symbols;

fw.artifact.link_function_sections = options.strip_unused_symbols;

fw.artifact.link_data_sections = options.strip_unused_symbols;

fw.artifact.root_module.addImport("microzig", core_mod);

fw.artifact.root_module.addImport("app", app_mod);

// If not specified then generate the linker script

const linker_script = options.linker_script orelse target.linker_script orelse blk: {

const GenerateLinkerScriptArgs = @import("tools/generate_linker_script.zig").Args;

const generate_linker_script_exe = mb.dep.artifact("generate_linker_script");

const generate_linker_script_args: GenerateLinkerScriptArgs = .{

.cpu_name = zig_target.result.cpu.model.name,

.cpu_arch = zig_target.result.cpu.arch,

.chip_name = target.chip.name,

.memory_regions = target.chip.memory_regions,

};

const args_str = std.json.stringifyAlloc(

b.allocator,

generate_linker_script_args,

.{},

) catch @panic("out of memory");

const generate_linker_script_run = b.addRunArtifact(generate_linker_script_exe);

generate_linker_script_run.addArg(args_str);

break :blk generate_linker_script_run.addOutputFileArg("linker.ld");

};

fw.artifact.setLinkerScript(linker_script);

return fw;

}

/// Configuration options for firmware installation.

pub const InstallFirmwareOptions = struct {

format: ?BinaryFormat = null,

};

/// Adds a new dependency to the `install` step that will install the `firmware` into the folder `$prefix/firmware`.

pub fn install_firmware(mb: *Self, fw: *Firmware, options: InstallFirmwareOptions) void {

std.debug.assert(mb == fw.mb);

const install_step = add_install_firmware(mb, fw, options);

mb.builder.getInstallStep().dependOn(&install_step.step);

}

/// Creates a new `std.Build.Step.InstallFile` instance that will install the given firmware to `$prefix/firmware`.

///

/// **NOTE:** This does not actually install the firmware yet. You have to add the returned step as a dependency to another step.

/// If you want to just install the firmware, use `installFirmware` instead!

pub fn add_install_firmware(mb: *Self, fw: *Firmware, options: InstallFirmwareOptions) *Build.Step.InstallFile {

std.debug.assert(mb == fw.mb);

const format = options.format orelse fw.target.preferred_binary_format orelse .elf;

const basename = mb.builder.fmt("{s}{s}", .{

fw.artifact.name,

format.get_extension(),

});

return mb.builder.addInstallFileWithDir(fw.get_emitted_bin(format), .{ .custom = "firmware" }, basename);

}

/// Declaration of a firmware build.

pub const Firmware = struct {

pub const EmittedFiles = std.AutoHashMap(BinaryFormat, LazyPath);

mb: *Self,

/// The artifact that is built by MicroZig.

artifact: *Build.Step.Compile,

/// The app module that is built by Zig.

app_mod: *Build.Module,

// The @import("microzig") module

core_mod: *Build.Module,

/// The target to which the firmware is built.

target: *const Target,

emitted_elf: ?LazyPath = null,

emitted_files: EmittedFiles,

/// Returns the emitted ELF file for this firmware. This is useful if you need debug information

/// or want to use a debugger like Segger, ST-Link or similar.

///

/// **NOTE:** This is similar, but not equivalent to `std.Build.Step.Compile.getEmittedBin`. The call on the compile step does

/// not include post processing of the ELF files necessary by certain targets.

pub fn get_emitted_elf(fw: *Firmware) LazyPath {

if (fw.emitted_elf == null) {

const raw_elf = fw.artifact.getEmittedBin();

fw.emitted_elf = if (fw.target.patch_elf) |patch_elf|

patch_elf(fw.target.dep, raw_elf)

else

raw_elf;

}

return fw.emitted_elf.?;

}

/// Returns the emitted binary for this firmware. The file is either in the preferred file format for

/// the target or in `format` if not null.

///

/// **NOTE:** The file returned here is the same file that will be installed.

pub fn get_emitted_bin(fw: *Firmware, format: ?BinaryFormat) LazyPath {

const resolved_format = format orelse fw.target.preferred_binary_format orelse .elf;

const result = fw.emitted_files.getOrPut(resolved_format) catch @panic("out of memory");

if (!result.found_existing) {

const elf_file = fw.get_emitted_elf();

const basename = fw.mb.builder.fmt("{s}{s}", .{

fw.artifact.name,

resolved_format.get_extension(),

});

result.value_ptr.* = switch (resolved_format) {

.elf => elf_file,

.bin => blk: {

const objcopy = fw.mb.builder.addObjCopy(elf_file, .{

.basename = basename,

.format = .bin,

});

break :blk objcopy.getOutput();

},

.hex => blk: {

const objcopy = fw.mb.builder.addObjCopy(elf_file, .{

.basename = basename,

.format = .hex,

});

break :blk objcopy.getOutput();

},

.uf2 => |family_id| blk: {

const uf2_exe = fw.mb.dep.builder.dependency("tools/uf2", .{ .optimize = .ReleaseSafe }).artifact("elf2uf2");

const convert = fw.mb.builder.addRunArtifact(uf2_exe);

convert.addArg("--family-id");

convert.addArg(@tagName(family_id));

convert.addArg("--elf-path");

convert.addFileArg(elf_file);

convert.addArg("--output-path");

break :blk convert.addOutputFileArg(basename);

},

.dfu => @panic("DFU is not implemented yet. See https://github.com/ZigEmbeddedGroup/microzig/issues/145 for more details!"),

.esp => @panic("ESP firmware image is not implemented yet. See https://github.com/ZigEmbeddedGroup/microzig/issues/146 for more details!"),

.custom => |generator| generator.convert(fw.target.dep, elf_file),

};

}

return result.value_ptr.*;

}

/// Configuration options for the `add_app_import` function.

pub const AppDependencyOptions = struct {

depend_on_microzig: bool = false,

};

/// Adds an import to your application.

pub fn add_app_import(fw: *Firmware, name: []const u8, module: *Build.Module, options: AppDependencyOptions) void {

if (options.depend_on_microzig) {

module.addImport("microzig", fw.core_mod);

}

fw.app_mod.addImport(name, module);

}

/// Adds an include path to the firmware.

pub fn add_include_path(fw: *Firmware, path: LazyPath) void {

fw.artifact.addIncludePath(path);

}

/// Adds a system include path to the firmware.

pub fn add_system_include_path(fw: *Firmware, path: LazyPath) void {

fw.artifact.addSystemIncludePath(path);

}

/// Adds a c source file to the firmware.

pub fn add_c_source_file(fw: *Firmware, source: Build.Module.CSourceFile) void {

fw.artifact.addCSourceFile(source);

}

/// Adds options to your application.

pub fn add_options(fw: *Firmware, module_name: []const u8, options: *Build.Step.Options) void {

fw.app_mod.addOptions(module_name, options);

}

/// Adds an object file to the firmware.

pub fn add_object_file(fw: *Firmware, source: LazyPath) void {

fw.artifact.addObjectFile(source);

}

};

};

}

const Cpu = enum {

avr5,

cortex_m,

riscv32,

// TODO: to be verified

pub fn init(target: std.Target) Cpu {

if (std.mem.eql(u8, target.cpu.model.name, "avr5")) {

return .avr5;

} else if (std.mem.startsWith(u8, target.cpu.model.name, "cortex_m")) {

return .cortex_m;

} else if (target.cpu.arch.isRISCV() and target.ptrBitWidth() == 32) {

return .riscv32;

}

@panic("unrecognized cpu configuration");

}

pub fn create_module(cpu: Cpu, b: *Build, core_dep: *Build.Dependency) *Build.Module {

return b.createModule(.{

.root_source_file = switch (cpu) {

.avr5 => core_dep.path("src/cpus/avr5.zig"),

.cortex_m => core_dep.path("src/cpus/cortex_m.zig"),

.riscv32 => core_dep.path("src/cpus/riscv32.zig"),

},

});

}

};

pub inline fn custom_lazy_import(

comptime dep_name: []const u8,

) ?type {

const build_runner = @import("root");

const deps = build_runner.dependencies;

const pkg_hash = custom_find_import_pkg_hash_or_fatal(dep_name);

inline for (@typeInfo(deps.packages).Struct.decls) |decl| {

if (comptime std.mem.eql(u8, decl.name, pkg_hash)) {

const pkg = @field(deps.packages, decl.name);

const available = !@hasDecl(pkg, "available") or pkg.available;

if (!available) {

return null;

}

return if (@hasDecl(pkg, "build_zig"))

pkg.build_zig

else

@compileError("dependency '" ++ dep_name ++ "' does not have a build.zig");

}

}

comptime unreachable; // Bad @dependencies source

}

inline fn custom_find_import_pkg_hash_or_fatal(comptime dep_name: []const u8) []const u8 {

@setEvalBranchQuota(2000);

const build_runner = @import("root");

const deps = build_runner.dependencies;

const pkg_deps = comptime for (@typeInfo(deps.packages).Struct.decls) |decl| {

const pkg_hash = decl.name;

const pkg = @field(deps.packages, pkg_hash);

if (@hasDecl(pkg, "build_zig") and pkg.build_zig == @This()) break pkg.deps;

} else deps.root_deps;

comptime for (pkg_deps) |dep| {

if (std.mem.eql(u8, dep[0], dep_name)) return dep[1];

};

@panic("dependency not found");

}