// SPDX-License-Identifier: GPL-3.0-or-later
import Foundation
import CryptoKit
import Darwin
enum CMOCLaunchMode: String, Codable, CaseIterable, Sendable { case quickload, disk }
enum CMOCDiskBootMode: String, Codable, CaseIterable, Sendable { case none, program, custom }
/// Commands typed at a Disk BASIC prompt after mounting a development disk in FD0.
enum DevelopmentDiskProgram: Sendable {
case basic(String), binary(String)
var bootCommand: String {
switch self {
case .basic(let name): return "RUN\"\(name)\""
case .binary(let name): return "LOADM\"\(name)\":EXEC"
}
}
func instructions(dos: Bool) -> String {
let manual: String
switch self {
case .basic(let name): manual = "type LOAD\"\(name)\", then type RUN on the next line."
case .binary: manual = "type \(bootCommand)."
}
return "Mount the disk in FD0. At the Disk BASIC prompt, " + manual
+ (dos ? " You can also type DOS to start the program." : "")
}
}
enum CMOCBuildAction: String, CaseIterable, Sendable { case build, rebuild, clean, disk, custom }
struct CMOCBuildConfiguration: Codable, Equatable, Sendable {
var name: String
var makeArguments: [String] = []
init(name: String, makeArguments: [String] = []) { self.name = name; self.makeArguments = makeArguments }
enum CodingKeys: CodingKey { case name, makeArguments }
init(from decoder: Decoder) throws {
let c = try decoder.container(keyedBy: CodingKeys.self)
name = try c.decode(String.self, forKey: .name)
makeArguments = try c.decodeIfPresent([String].self, forKey: .makeArguments) ?? []
}
}
/// An explicitly configured build recipe, represented as a grouped GNU Make rule.
/// Commands are user-owned Makefile recipes, executed only by Build.
struct CMOCGeneratedResource: Codable, Equatable, Sendable {
var outputs: [String]
var inputs: [String]
var command: String
init(outputs: [String] = [], inputs: [String] = [], command: String = "") {
self.outputs = outputs; self.inputs = inputs; self.command = command
}
}
struct CMOCLibraryProject: Codable, Equatable, Sendable {
var directory: String
var target: String
var archive: String
init(directory: String = "", target: String = "all", archive: String = "") {
self.directory = directory; self.target = target; self.archive = archive
}
}
struct CMOCMakefileSettings: Codable, Equatable, Sendable {
static let marker = "# Generated by VCC Plus — edit Project Settings to regenerate."
var sources: [String] = ["main.c"]
var includePaths: [String] = []
var libraries: [String] = ["decbfile"]
var libraryPaths: [String] = []
var defines: [String] = []
var compilerOptions: [String] = []
var linkerOptions: [String] = []
var limit: String? = nil
var libraryProjects: [CMOCLibraryProject] = []
var generatedResources: [CMOCGeneratedResource] = []
var executable = "main.bin"
var origin = "2800"
var stackSpace = 2048
var releaseOptimization = "-O2"
var diskImage: String? = nil
var diskFiles: [String] = []
var diskBootLoader: String? = nil
var diskBootMode: CMOCDiskBootMode = .none
init() {}
enum CodingKeys: CodingKey { case sources, includePaths, libraries, libraryPaths, defines, compilerOptions, linkerOptions, limit, libraryProjects, generatedResources, executable, origin, stackSpace, releaseOptimization, diskImage, diskFiles, diskBootLoader, diskBootMode }
init(from decoder: Decoder) throws {
self.init(); let c = try decoder.container(keyedBy: CodingKeys.self)
sources = try c.decodeIfPresent([String].self, forKey: .sources) ?? sources
includePaths = try c.decodeIfPresent([String].self, forKey: .includePaths) ?? []
libraries = try c.decodeIfPresent([String].self, forKey: .libraries) ?? libraries
libraryPaths = try c.decodeIfPresent([String].self, forKey: .libraryPaths) ?? []
defines = try c.decodeIfPresent([String].self, forKey: .defines) ?? []
compilerOptions = try c.decodeIfPresent([String].self, forKey: .compilerOptions) ?? []
linkerOptions = try c.decodeIfPresent([String].self, forKey: .linkerOptions) ?? []
limit = try c.decodeIfPresent(String.self, forKey: .limit)
libraryProjects = try c.decodeIfPresent([CMOCLibraryProject].self, forKey: .libraryProjects) ?? []
generatedResources = try c.decodeIfPresent([CMOCGeneratedResource].self, forKey: .generatedResources) ?? []
executable = try c.decodeIfPresent(String.self, forKey: .executable) ?? executable
origin = try c.decodeIfPresent(String.self, forKey: .origin) ?? origin
stackSpace = try c.decodeIfPresent(Int.self, forKey: .stackSpace) ?? stackSpace
releaseOptimization = try c.decodeIfPresent(String.self, forKey: .releaseOptimization) ?? releaseOptimization
diskImage = try c.decodeIfPresent(String.self, forKey: .diskImage)
diskFiles = try c.decodeIfPresent([String].self, forKey: .diskFiles) ?? []
diskBootLoader = try c.decodeIfPresent(String.self, forKey: .diskBootLoader)
diskBootMode = try c.decodeIfPresent(CMOCDiskBootMode.self, forKey: .diskBootMode) ?? (diskBootLoader == nil ? .none : .custom)
}
/// Pierre Sarrazin's public-domain autostart.c 0.1.2, copied from
/// third_party/examples/coco-letters/autostart.c. This embedded helper is public
/// domain, separately from the GPL generator. It is emitted only under obj/.
static let dosBootLoaderSource = #"""
// autostart.c - Program to be run by the Disk Basic DOS command.
// By Pierre Sarrazin
// This file is in the public domain.
//
// Reference: Roger Schrag, "A Special Use For The DOS Command",
// The Rainbow, November 1984, p.140.
//
// To compile: cmoc --dos autostart.c
// To install on CoCo disk image: install-coco-boot-loader some-image.dsk autostart.bin
// To run on CoCo: type DOS and to automatically run *.BAS.
//
// Version history:
// 0.1.0 2016-01-16 Use of legacy.h discontinued.
// 0.1.1 2018-04-03 Adapted to CMOC 0.1.51 (const).
// 0.1.2 2018-08-04 Basic line now forced to be uppercase.
#include
#define ENDFLG 0x00 // STOP/END FLAG: POSITIVE=STOP, NEG=END
#define CINBFL 0x70 // CONSOLE IN BUFFER FLAG: 00=NOT EMPTY, $FF=EMPTY
#define RVEC4 0x016a // RAM hook: CONSOLE IN
byte oldHookInstr;
word oldHookAddr;
const char *basicLineReader;
void feedKeyboard()
{
word preservedX;
asm("stx", preservedX);
* (byte *) CINBFL = 0; // console in buffer now not empty
char nextBasicByte = (char) toupper(*basicLineReader);
++basicLineReader;
if (nextBasicByte == 0) // if finished returning Basic line
{
* (byte *) RVEC4 = oldHookInstr;
* (word *) (RVEC4 + 1) = oldHookAddr;
nextBasicByte = '\r'; // return "Enter" to cause execution of Basic line
}
asm {
lda nextBasicByte
ldx preservedX
tfr u,s // discard stack frame
leas 4,s // discard previous stack frame ptr and return addr
rts // return to caller of CONSOLE IN
}
}
int main()
{
* (byte *) ENDFLG = - * (byte *) ENDFLG; // why?
basicLineReader =
#ifndef COMMAND
"RUN\"*.BAS\""
#else
COMMAND
#endif
;
// Install function feedKeyboard() as CONSOLE IN routine.
//
oldHookInstr = * (byte *) RVEC4;
oldHookAddr = * (word *) (RVEC4 + 1);
* (byte *) RVEC4 = 0x7e; // JMP instruction
* (void **) (RVEC4 + 1) = (void *) feedKeyboard;
* (word *) 0x2600 = 0; // overwrite "OS" marker with two null bytes
asm("jmp", "$ac7c"); // go interpret a Basic line (which is read from console)
return 0; // avoids compiler error
}
"""#
var programBootCommand: String { DevelopmentDiskProgram.binary((executable as NSString).lastPathComponent.uppercased()).bootCommand }
func generateMakefile(makefileName: String = "Makefile") throws -> String {
// Generated recipes use simple Make-safe project-relative names. Imported
// Makefiles remain free to implement more elaborate escaping and layouts.
func path(_ value: String) throws {
try CMOCProject.validateRelativePath(value)
guard value.allSatisfy({ $0.isASCII && ($0.isLetter || $0.isNumber || "_./-".contains($0)) }), !value.hasPrefix("-") else {
throw CMOCBuildError.message("Generated Makefile paths must use letters, numbers, underscores, dots, dashes and slashes: \(value)")
}
}
guard !sources.isEmpty, Set(sources.map { $0.lowercased() }).count == sources.count, sources.allSatisfy({ $0.hasSuffix(".c") }),
["-O0", "-O1", "-O2"].contains(releaseOptimization), (64...32768).contains(stackSpace),
UInt16(origin.hasPrefix("0x") ? String(origin.dropFirst(2)) : origin, radix: 16) != nil else {
throw CMOCBuildError.message("Choose distinct C sources, a hexadecimal load address, and a supported optimization/stack setting.")
}
func checkedArgument(_ argument: String) throws {
guard !argument.isEmpty, argument.utf8.count <= 8192, !argument.contains("\0"),
!argument.contains("\n"), !argument.contains("\r") else {
throw CMOCBuildError.message("Compiler options and definitions must each occupy one nonempty line.")
}
}
for definition in defines {
try checkedArgument(definition)
let name = definition.prefix(while: { $0 != "=" })
guard let first = name.first, first.isASCII && (first.isLetter || first == "_"),
name.allSatisfy({ $0.isASCII && ($0.isLetter || $0.isNumber || $0 == "_") }) else {
throw CMOCBuildError.message("Use C macro definitions such as MAX_WORD_LEN=5 or DISPLAY_NAME=\"My Game\".")
}
}
for option in compilerOptions + linkerOptions {
try checkedArgument(option)
guard option.hasPrefix("-"), option != "-", option != "--" else {
throw CMOCBuildError.message("Additional compiler/linker arguments must be options beginning with '-'.")
}
}
if let limit, UInt16(limit.hasPrefix("0x") ? String(limit.dropFirst(2)) : limit, radix: 16) == nil {
throw CMOCBuildError.message("The optional memory limit must be a hexadecimal address, such as 7F80.")
}
func shellArgument(_ token: String) -> String {
// GNU Make define blocks retain # and backslashes. Double dollars for
// Make expansion, then single-quote each argv token for the shell.
"'" + token.replacingOccurrences(of: "$", with: "$$").replacingOccurrences(of: "'", with: "'\"'\"'") + "'"
}
let generatedOutputs = generatedResources.flatMap(\.outputs)
guard Set(generatedOutputs.map { $0.lowercased() }).count == generatedOutputs.count else { throw CMOCBuildError.message("A generated resource may have only one producing recipe.") }
try path(makefileName)
for value in sources + includePaths + libraryPaths + [executable] + [diskImage, diskBootLoader].compactMap({ $0 }) + diskFiles + generatedOutputs + generatedResources.flatMap(\.inputs) { try path(value) }
let reserved = Set([makefileName.lowercased(), CMOCProject.configurationFilename.lowercased()])
let executableKey = executable.lowercased(), diskKey = diskImage?.lowercased()
let sourcesAndInputs = Set((sources + generatedResources.flatMap(\.inputs)).map { $0.lowercased() })
guard !reserved.contains(executableKey), !sourcesAndInputs.contains(executableKey),
diskKey != executableKey,
diskKey.map({ !reserved.contains($0) && !sourcesAndInputs.contains($0) }) ?? true,
!sources.contains(where: { $0.lowercased().hasPrefix("obj/") }),
!generatedOutputs.contains(where: { reserved.contains($0.lowercased()) || $0.lowercased() == executableKey || $0.lowercased() == diskKey }) else {
throw CMOCBuildError.message("Build outputs must not replace source files, Makefile, project settings or one another. The obj directory is reserved for compiler products.")
}
if diskImage != nil {
var diskNames = Set()
for file in [executable] + diskFiles {
let name = (file as NSString).lastPathComponent.uppercased()
let parts = name.split(separator: ".", omittingEmptySubsequences: false)
guard (1...2).contains(parts.count), (1...8).contains(parts[0].count),
(parts.count == 1 || (1...3).contains(parts[1].count)),
parts.allSatisfy({ $0.allSatisfy({ $0.isASCII && ($0.isLetter || $0.isNumber || "_-".contains($0)) }) }),
diskNames.insert(name).inserted else {
throw CMOCBuildError.message("Disk files need unique 8.3 names (ignoring case), including the executable: \(name)")
}
}
}
for library in libraries {
guard !library.isEmpty, library.allSatisfy({ $0.isASCII && ($0.isLetter || $0.isNumber || "_-".contains($0)) }) else { throw CMOCBuildError.message("Invalid library name: \(library)") }
}
for library in libraryProjects { try path(library.directory); try path(library.archive); try path(library.target) }
for recipe in generatedResources {
guard !recipe.outputs.isEmpty, !recipe.command.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
!recipe.command.contains("\0"), recipe.command.utf8.count <= 32768 else { throw CMOCBuildError.message("Each generated resource needs output files and a command.") }
}
let automaticLoader = "obj/vcc-dos-boot/loader.bin"
var loader: String?
switch diskBootMode {
case .none: loader = nil
case .custom:
guard let diskBootLoader else { throw CMOCBuildError.message("Choose a custom DOS bootloader binary, or select None.") }
loader = diskBootLoader
case .program:
guard diskImage != nil, UInt16(origin.hasPrefix("0x") ? String(origin.dropFirst(2)) : origin, radix: 16)! >= 0x2800 else {
throw CMOCBuildError.message("Automatic DOS boot requires a disk image and a program load address of $2800 or higher.")
}
guard !(sources + diskFiles + generatedOutputs + generatedResources.flatMap(\.inputs) + [executable, diskImage!]).contains(where: {
$0.lowercased() == "obj/vcc-dos-boot" || $0.lowercased().hasPrefix("obj/vcc-dos-boot/")
}) else { throw CMOCBuildError.message("obj/vcc-dos-boot is reserved for the automatic DOS bootloader.") }
loader = automaticLoader
}
let objects = sources.map { "obj/" + String($0.dropLast(2)) + ".o" }
let archives = libraryProjects.map(\.archive)
let includeFlags = includePaths.map { "-I" + $0 }.joined(separator: " ")
let libraryFlags = (libraryPaths.map { "-L" + $0 } + libraries.map { "-l" + $0 }).joined(separator: " ")
let compatibility = libraries.contains("vcccompat") ? "export VCC_CMOC_COMPAT = 1\n" : ""
var text = """
\(Self.marker)
# Ordinary GNU Make; no VCC Plus project parser is required to build it.
CMOC ?= cmoc
PERL ?= perl
WRITECOCOFILE ?= writecocofile
INSTALL_LOADER ?= install-coco-boot-loader
VCC_CONFIGURATION ?= Debug
ifeq ($(VCC_CONFIGURATION),Release)
OPTIM ?= \(releaseOptimization)
else
OPTIM ?= -O0
DEBUG_FRAME ?= -fno-omit-frame-pointer
endif
define VCC_DEFINES
\(defines.map { shellArgument("-D" + $0) }.joined(separator: " "))
endef
define VCC_COMPILER_OPTIONS
\(compilerOptions.map(shellArgument).joined(separator: " "))
endef
define VCC_LINKER_OPTIONS
\(linkerOptions.map(shellArgument).joined(separator: " "))
endef
\(compatibility)CPPFLAGS += \(includeFlags) $(VCC_DEFINES)
CFLAGS += --coco --intermediate --deps --stack-space=\(stackSpace) $(OPTIM) $(DEBUG_FRAME) $(VCC_COMPILER_OPTIONS)
LDFLAGS += --coco --intermediate --org=\(origin) \(limit.map { "--limit=" + $0 } ?? "") $(VCC_LINKER_OPTIONS)
LDLIBS += \(libraryFlags)
OBJECTS := \(objects.joined(separator: " "))
.PHONY: all build clean disk libraries
all: build
build: \(executable)
\(executable): $(OBJECTS) \(archives.joined(separator: " ")) \(makefileName)
\t@mkdir -p $(dir $@)
\t"$(CMOC)" $(LDFLAGS) -o $@ $(OBJECTS) \(archives.joined(separator: " ")) $(LDLIBS)
"""
// Explicit rules preserve directory identity for equal basenames in different folders.
// Generated headers/resources precede compilation on the first build; .d files
// then provide exact per-translation-unit header dependencies.
for (source, object) in zip(sources, objects) {
text += "\(object): \(source) \(makefileName) \(generatedOutputs.joined(separator: " "))\n"
text += "\t@mkdir -p $(dir $@)\n"
text += "\t\"$(CMOC)\" $(CPPFLAGS) $(CFLAGS) --intdir=$(dir $@) -c -o $@ $<\n\n"
}
for recipe in generatedResources {
text += recipe.outputs.joined(separator: " ") + " &: " + recipe.inputs.joined(separator: " ") + " \(makefileName)\n"
let directories = Set(recipe.outputs.map { ($0 as NSString).deletingLastPathComponent }.filter { !$0.isEmpty }).sorted()
if !directories.isEmpty { text += "\t@mkdir -p " + directories.joined(separator: " ") + "\n" }
for line in recipe.command.split(separator: "\n", omittingEmptySubsequences: false) { text += "\t" + line + "\n" }
for output in recipe.outputs { text += "\ttest -f " + output + "\n" }
text += "\n"
}
for (index, library) in libraryProjects.enumerated() {
let refresh = "vcc-library-\(index)"
text += ".PHONY: \(refresh)\n\(refresh):\n"
// Run the submake as the archive recipe so GNU Make restats the
// archive before deciding whether its dependents need relinking.
text += "\(library.archive): \(refresh)\n\t$(MAKE) -C \(library.directory) \(library.target)\n\ttest -f $@\n\n"
}
if diskBootMode == .program {
// No Make-time shell/file evaluation: emit/compile the helper only as
// an ordinary target recipe. Its code must end before the user program.
let define = "-DCOMMAND=\"" + programBootCommand.replacingOccurrences(of: "\"", with: "\\\"") + "\""
text += "# DOS helper: Pierre Sarrazin, autostart.c 0.1.2, public domain.\n"
text += "\(automaticLoader): \(makefileName)\n\t@mkdir -p $(dir $@)\n"
text += "\t@printf '%s\\n' " + Self.dosBootLoaderSource.components(separatedBy: "\n").map(shellArgument).joined(separator: " ") + " > obj/vcc-dos-boot/loader.c\n"
text += "\t\"$(CMOC)\" --dos -O0 --limit=2800 -o $@ " + shellArgument(define) + " obj/vcc-dos-boot/loader.c\n\n"
}
if let diskImage {
text += "disk: \(diskImage)\n\(diskImage): \(executable) \(diskFiles.joined(separator: " ")) \(loader ?? "") \(makefileName)\n"
text += "\t@mkdir -p $(dir $@)\n"
// Disk BASIC geometry; writecocofile initializes the directory/granule state
// from a blank 0xFF image, as used by the upstream CoCo Letters workflow.
text += "\t$(PERL) -e 'print chr(255) x (35*18*256)' > $@\n"
if let loader { text += "\t$(INSTALL_LOADER) $@ \(loader)\n" }
for file in [executable] + diskFiles { text += "\t$(WRITECOCOFILE) $@ \(file)\n" }
} else { text += "disk:\n\t@echo 'No disk image configured'; exit 1\n" }
text += "\nclean:\n\trm -rf obj\n\trm -f \(executable) \((executable as NSString).deletingPathExtension).map \((executable as NSString).deletingPathExtension).link \(diskImage ?? "") \(generatedOutputs.joined(separator: " "))\n"
for library in libraryProjects { text += "\t$(MAKE) -C \(library.directory) clean\n" }
text += "\n-include $(OBJECTS:.o=.d)\n"
return text
}
}
/// Portable bindings for libraries supplied by the current app installation.
struct CMOCBundledLibraryBinding: Codable, Equatable, Sendable {
var library = "decbfile"
var minimumVersion = ""
var directoryVariable = ""
var linkVariable = ""
init(library: String = "decbfile", minimumVersion: String = "", directoryVariable: String = "", linkVariable: String = "") {
self.library = library; self.minimumVersion = minimumVersion
self.directoryVariable = directoryVariable; self.linkVariable = linkVariable
}
enum CodingKeys: CodingKey { case library, minimumVersion, directoryVariable, linkVariable }
init(from decoder: Decoder) throws {
let c = try decoder.container(keyedBy: CodingKeys.self)
library = try c.decode(String.self, forKey: .library)
minimumVersion = try c.decodeIfPresent(String.self, forKey: .minimumVersion) ?? ""
directoryVariable = try c.decodeIfPresent(String.self, forKey: .directoryVariable) ?? ""
linkVariable = try c.decodeIfPresent(String.self, forKey: .linkVariable) ?? ""
}
}
struct CMOCBundledLibrary: Identifiable, Sendable {
var id: String
var version: String
var license: String
var files: [String: String]
var available: Bool
static func catalog(at runtime: URL) throws -> [Self] {
guard let record = try JSONSerialization.jsonObject(with: Data(contentsOf: runtime.appendingPathComponent("manifest.json"))) as? [String: Any] else {
throw CMOCBuildError.message("The bundled library manifest is unreadable.")
}
var entries = record["libraries"] as? [String: [String: Any]] ?? [:]
if let disk = record["decbfile"] as? [String: Any] {
entries["decbfile"] = ["version": disk["version"] ?? "", "license": disk["license"] ?? "", "filesSHA256": [
"share/cmoc/lib/libdecbfile.a": disk["archiveSHA256"] as? String ?? "",
"share/cmoc/include/decbfile.h": disk["headerSHA256"] as? String ?? ""]]
}
let standalone = record["standaloneDisk"] as? [String: Any]
entries["dskcon-standalone"] = ["version": standalone?["cmocVersion"] ?? record["cmoc"] ?? "", "license": "Contains Disk BASIC-derived code; see Licenses & Notices",
"filesSHA256": standalone?["filesSHA256"] ?? [String: String]()]
return entries.keys.sorted().map { name in
let item = entries[name]!, files = item["filesSHA256"] as? [String: String] ?? [:]
let archive = "share/cmoc/lib/lib\(name).a"
return Self(id: name, version: item["version"] as? String ?? "", license: item["license"] as? String ?? "",
files: files, available: files[archive] != nil && FileManager.default.fileExists(atPath: runtime.appendingPathComponent(archive).path))
}
}
static func version(_ text: String) -> [Int]? {
let pieces = text.split(separator: ".", omittingEmptySubsequences: false)
guard !pieces.isEmpty, pieces.count <= 8, pieces.allSatisfy({ !$0.isEmpty && $0.count <= 8 && $0.allSatisfy({ $0.isASCII && $0.isNumber }) }) else { return nil }
return pieces.compactMap { Int($0) }
}
static func atLeast(_ installed: String, _ required: String) -> Bool {
guard let a = version(installed), let b = version(required) else { return false }
for i in 0.. y }
}
return true
}
static let stagingDirectory = ".vccplus-libraries"
static func validate(_ bindings: [CMOCBundledLibraryBinding], configurations: [CMOCBuildConfiguration]) throws {
guard bindings.count <= 32, Set(bindings.map(\.library)).count == bindings.count else { throw CMOCBuildError.message("Select each bundled library once (up to 32).") }
var directories = Set(), links = Set()
let reserved = Set(["MAKE", "MAKEFLAGS", "MFLAGS", "GNUMAKEFLAGS", "MAKELEVEL", "SHELL", "VCC_TOOLCHAIN"])
for b in bindings {
guard !b.library.isEmpty, b.library.count <= 80, b.library.allSatisfy({ $0.isASCII && ($0.isLetter || $0.isNumber || "_-".contains($0)) }),
b.minimumVersion.isEmpty || version(b.minimumVersion) != nil,
!b.directoryVariable.isEmpty || !b.linkVariable.isEmpty else { throw CMOCBuildError.message("Choose a library, a valid optional minimum version, and a directory or linker variable.") }
for v in [b.directoryVariable, b.linkVariable] where !v.isEmpty {
guard v.count <= 80, let first = v.first, first.isASCII && (first.isLetter || first == "_"),
v.allSatisfy({ $0.isASCII && ($0.isLetter || $0.isNumber || $0 == "_") }), !reserved.contains(v),
!configurations.flatMap(\.makeArguments).contains(where: { $0.prefix(while: { $0 != "=" }) == v }) else {
throw CMOCBuildError.message("Library variables must be ordinary Make names, used only here and not also in configuration arguments: \(v)")
}
}
if !b.directoryVariable.isEmpty, !directories.insert(b.directoryVariable).inserted { throw CMOCBuildError.message("Each library directory needs a distinct Make variable.") }
if !b.linkVariable.isEmpty { links.insert(b.linkVariable) }
}
guard directories.isDisjoint(with: links) else { throw CMOCBuildError.message("A Make variable cannot be both a library directory and linker flags.") }
}
/// Copy verified archives/headers into a space-free isolated workspace. Never
/// point writable Make recipes into the installed application's bundle.
static func stage(_ bindings: [CMOCBundledLibraryBinding], runtime: URL, workspace: URL) throws -> [String: Data] {
let manager = FileManager.default, root = workspace.appendingPathComponent(stagingDirectory)
guard !bindings.isEmpty else { return [:] }
let catalog = try catalog(at: runtime)
var payload: [String: Data] = [:], rules = "# Generated bundled-library bindings; original Makefile is unchanged.\n"
for b in bindings {
guard let library = catalog.first(where: { $0.id == b.library }), library.available else { throw CMOCBuildError.message("Bundled library \(b.library) is not installed in this app.") }
guard b.minimumVersion.isEmpty || atLeast(library.version, b.minimumVersion) else { throw CMOCBuildError.message("\(b.library) requires version \(b.minimumVersion) or newer; this app includes \(library.version).") }
let destination = root.appendingPathComponent(b.library)
for (relative, hash) in library.files {
try CMOCProject.validateRelativePath(relative)
guard relative == "share/cmoc/lib/lib\(b.library).a" || relative.hasPrefix("share/cmoc/include/") || relative.hasPrefix("LICENSES/") else { throw CMOCBuildError.message("Unsupported library manifest path: \(relative)") }
let source = runtime.appendingPathComponent(relative)
guard try source.resourceValues(forKeys: [.isSymbolicLinkKey]).isSymbolicLink != true else { throw CMOCBuildError.message("Bundled library files must not be links.") }
let data = try Data(contentsOf: source)
guard CMOCProject.sha256(data) == hash else { throw CMOCBuildError.message("Bundled library \(b.library) failed its integrity check. Reinstall the app.") }
let headerPrefix = b.library == "vcccompat" ? "share/cmoc/include/vcc/compat/" : "share/cmoc/include/"
let filename = relative.hasPrefix(headerPrefix) ? String(relative.dropFirst(headerPrefix.count)) : source.lastPathComponent
let path = stagingDirectory + "/" + b.library + "/" + filename
guard payload[path] == nil else { throw CMOCBuildError.message("Duplicate bundled library filename.") }
payload[path] = data
}
if b.library == "vcccompat" { rules += "export VCC_CMOC_COMPAT = 1\n" }
if !b.linkVariable.isEmpty { rules += "override \(b.linkVariable) += -L\(destination.path) -l\(b.library)\n" }
payload[stagingDirectory + "/" + b.library + "/VCC-LIBRARY.txt"] = Data("\(b.library) \(library.version)\n\(library.license)\n".utf8)
}
// Retain bundled third-party notices with the frozen build products.
for (path, bytes) in try CMOCProject.files(in: runtime.appendingPathComponent("LICENSES")) {
payload[stagingDirectory + "/LICENSES/" + path] = bytes
}
payload[stagingDirectory + "/bindings.mk"] = Data(rules.utf8)
for (path, bytes) in payload {
let url = workspace.appendingPathComponent(path)
try manager.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
if (try? Data(contentsOf: url)) != bytes { try bytes.write(to: url, options: .atomic) }
}
return payload
}
}
/// Optional UI metadata. The user's ordinary Makefile remains the build authority.
struct CMOCProjectConfiguration: Codable, Equatable, Sendable {
var entrySource = "main.c"
var makefile = "Makefile"
// An empty override delegates goal selection to Make itself.
var buildTarget = ""
var cleanTarget = "clean"
var diskTarget: String? = nil
var binary: String? = "main.bin"
var diskImage: String? = nil
/// Optional build-produced placement manifest for packed/banked programs.
var debugManifest: String? = nil
/// Additional build-produced floppy images reviewed for owned disk exchange.
/// These are outputs, not source inputs or arbitrary files to mount.
var playtestDisks: [String] = []
/// Concrete additional delivery files; outputDirectories are never export permissions.
var exportOutputs: [String] = []
var launchMode: CMOCLaunchMode = .quickload
var launchCommands: [String] = []
var configurations = [CMOCBuildConfiguration(name: "Debug"), CMOCBuildConfiguration(name: "Release", makeArguments: ["VCC_CONFIGURATION=Release"])]
var jobs = 1
var bundledLibraries: [CMOCBundledLibraryBinding] = []
/// Explicit sibling folders needed by a custom Makefile, such as ../tools.
/// They are copied beside the isolated project, never inferred from recipes.
var buildSupportDirectories: [String] = []
/// Explicit non-source inputs, pre-generated inputs, and disposable output roots.
var resourceInputs: [String] = []
var generatedInputs: [String] = []
var outputDirectories: [String] = []
var makefileSettings: CMOCMakefileSettings? = nil
init() {}
enum CodingKeys: CodingKey { case entrySource, makefile, buildTarget, cleanTarget, diskTarget, binary, diskImage, debugManifest, playtestDisks, exportOutputs, launchMode, launchCommands, configurations, jobs, makefileSettings, bundledLibraries, buildSupportDirectories, resourceInputs, generatedInputs, outputDirectories }
init(from decoder: Decoder) throws {
self.init()
let c = try decoder.container(keyedBy: CodingKeys.self)
entrySource = try c.decodeIfPresent(String.self, forKey: .entrySource) ?? entrySource
makefile = try c.decodeIfPresent(String.self, forKey: .makefile) ?? makefile
buildTarget = try c.decodeIfPresent(String.self, forKey: .buildTarget) ?? buildTarget
cleanTarget = try c.decodeIfPresent(String.self, forKey: .cleanTarget) ?? cleanTarget
diskTarget = try c.decodeIfPresent(String.self, forKey: .diskTarget)
if c.contains(.binary) { binary = try c.decodeIfPresent(String.self, forKey: .binary) }
diskImage = try c.decodeIfPresent(String.self, forKey: .diskImage)
debugManifest = try c.decodeIfPresent(String.self, forKey: .debugManifest)
playtestDisks = try c.decodeIfPresent([String].self, forKey: .playtestDisks) ?? []
exportOutputs = try c.decodeIfPresent([String].self, forKey: .exportOutputs) ?? []
launchMode = try c.decodeIfPresent(CMOCLaunchMode.self, forKey: .launchMode) ?? launchMode
launchCommands = try c.decodeIfPresent([String].self, forKey: .launchCommands) ?? []
configurations = try c.decodeIfPresent([CMOCBuildConfiguration].self, forKey: .configurations) ?? configurations
jobs = try c.decodeIfPresent(Int.self, forKey: .jobs) ?? jobs
makefileSettings = try c.decodeIfPresent(CMOCMakefileSettings.self, forKey: .makefileSettings)
bundledLibraries = try c.decodeIfPresent([CMOCBundledLibraryBinding].self, forKey: .bundledLibraries) ?? []
buildSupportDirectories = try c.decodeIfPresent([String].self, forKey: .buildSupportDirectories) ?? []
resourceInputs = try c.decodeIfPresent([String].self, forKey: .resourceInputs) ?? []
generatedInputs = try c.decodeIfPresent([String].self, forKey: .generatedInputs) ?? []
outputDirectories = try c.decodeIfPresent([String].self, forKey: .outputDirectories) ?? []
}
func encode(to encoder: Encoder) throws {
var c = encoder.container(keyedBy: CodingKeys.self)
try c.encode(entrySource, forKey: .entrySource); try c.encode(makefile, forKey: .makefile)
try c.encode(buildTarget, forKey: .buildTarget); try c.encode(cleanTarget, forKey: .cleanTarget)
try c.encodeIfPresent(diskTarget, forKey: .diskTarget)
if let binary { try c.encode(binary, forKey: .binary) } else { try c.encodeNil(forKey: .binary) }
try c.encodeIfPresent(diskImage, forKey: .diskImage); try c.encode(launchMode, forKey: .launchMode)
try c.encodeIfPresent(debugManifest, forKey: .debugManifest)
if !playtestDisks.isEmpty { try c.encode(playtestDisks, forKey: .playtestDisks) }
if !exportOutputs.isEmpty { try c.encode(exportOutputs, forKey: .exportOutputs) }
try c.encode(launchCommands, forKey: .launchCommands); try c.encode(configurations, forKey: .configurations)
try c.encode(jobs, forKey: .jobs); try c.encodeIfPresent(makefileSettings, forKey: .makefileSettings)
if !bundledLibraries.isEmpty { try c.encode(bundledLibraries, forKey: .bundledLibraries) }
if !buildSupportDirectories.isEmpty { try c.encode(buildSupportDirectories, forKey: .buildSupportDirectories) }
if !resourceInputs.isEmpty { try c.encode(resourceInputs, forKey: .resourceInputs) }
if !generatedInputs.isEmpty { try c.encode(generatedInputs, forKey: .generatedInputs) }
if !outputDirectories.isEmpty { try c.encode(outputDirectories, forKey: .outputDirectories) }
}
func validated() throws -> Self {
for path in [entrySource, makefile] + [binary, diskImage, debugManifest].compactMap({ $0 }) { try CMOCProject.validateRelativePath(path) }
let declarations = resourceInputs + generatedInputs + outputDirectories
guard declarations.count <= 4096,
Set(declarations.map { $0.lowercased() }).count == declarations.count else {
throw CMOCBuildError.message("Project input/output declarations must have at most 4096 distinct, unambiguous paths.")
}
for path in declarations {
try CMOCProject.validateRelativePath(path)
guard !path.split(separator: "/").contains(where: { [".git", ".hg", ".svn"].contains($0.lowercased()) }) else {
throw CMOCBuildError.message("Version-control internals cannot be declared as project inputs or outputs.")
}
}
guard playtestDisks.count <= 8,
Set(playtestDisks.map { $0.lowercased() }).count == playtestDisks.count else {
throw CMOCBuildError.message("Declare at most eight distinct additional playtest disks.")
}
let otherRoles = [entrySource, makefile, CMOCProject.configurationFilename] +
[binary, diskImage, debugManifest].compactMap { $0 } + resourceInputs + generatedInputs +
(makefileSettings?.sources ?? []) + (makefileSettings?.diskFiles ?? []) +
(makefileSettings?.generatedResources.flatMap(\.inputs) ?? [])
let occupiedRoles = Set(otherRoles.map { $0.lowercased() })
for path in playtestDisks {
try CMOCProject.validateRelativePath(path)
guard ["dsk", "os9"].contains((path as NSString).pathExtension.lowercased()),
!occupiedRoles.contains(path.lowercased()),
!path.split(separator: "/").contains(where: { [".git", ".hg", ".svn"].contains($0.lowercased()) }) else {
throw CMOCBuildError.message("Additional playtest disks need distinct project-relative .dsk or .os9 output paths, separate from inputs and primary outputs.")
}
}
let exportPaths = [binary, diskImage, debugManifest].compactMap { $0 } + playtestDisks + exportOutputs
guard exportPaths.count <= 64,
Set(exportPaths.map { $0.lowercased() }).count == exportPaths.count else {
throw CMOCBuildError.message("Declare at most 64 distinct concrete delivery outputs.")
}
for path in exportOutputs {
try CMOCProject.validateRelativePath(path)
guard !occupiedRoles.contains(path.lowercased()), path.split(separator: "/").count <= 32,
!path.split(separator: "/").contains(where: { [".git", ".hg", ".svn"].contains($0.lowercased()) }) else {
throw CMOCBuildError.message("Delivery outputs must be concrete generated files, separate from project inputs.")
}
}
let lowerExportPaths = exportPaths.map { $0.lowercased() }
guard !lowerExportPaths.contains(where: { path in lowerExportPaths.contains(where: { $0.hasPrefix(path + "/") }) }) else {
throw CMOCBuildError.message("Delivery output paths cannot overlap directories and files.")
}
let concreteOutputs = ([binary, diskImage, debugManifest].compactMap { $0 } + playtestDisks + exportOutputs +
(makefileSettings?.generatedResources.flatMap(\.outputs) ?? [])).map { $0.lowercased() }
let ordinaryInputs = [entrySource, makefile, CMOCProject.configurationFilename] + resourceInputs
let explicitInputs = ordinaryInputs + generatedInputs
guard !explicitInputs.contains(where: { concreteOutputs.contains($0.lowercased()) }) else {
throw CMOCBuildError.message("A declared input cannot also be a generated binary, disk, manifest or resource output.")
}
if let debugManifest {
guard !([entrySource, makefile] + [binary, diskImage].compactMap { $0 }).contains(where: { $0.lowercased() == debugManifest.lowercased() }) else {
throw CMOCBuildError.message("The debug manifest needs its own generated output path.")
}
}
if !buildTarget.isEmpty { try Self.validateTarget(buildTarget) }
for target in [cleanTarget] + [diskTarget].compactMap({ $0 }) { try Self.validateTarget(target) }
guard (1...32).contains(jobs), !configurations.isEmpty, configurations.count <= 16,
Set(configurations.map(\.name)).count == configurations.count else {
throw CMOCBuildError.message("Project settings need 1–32 build jobs and uniquely named build configurations.")
}
for config in configurations {
guard !config.name.isEmpty, config.name.count <= 100, config.makeArguments.count <= 64 else {
throw CMOCBuildError.message("Invalid build configuration.")
}
for argument in config.makeArguments {
// Variables are passed as individual argv entries, never shell text.
let name = argument.prefix(while: { $0 != "=" })
guard argument.contains("="), !name.isEmpty,
name.allSatisfy({ $0.isASCII && ($0.isLetter || $0.isNumber || $0 == "_") }),
!argument.contains("\0"), !argument.contains("\n"), argument.count <= 8192 else {
throw CMOCBuildError.message("Build configuration arguments must be Make variable assignments such as OPTIM=-O0.")
}
}
}
try CMOCBundledLibrary.validate(bundledLibraries, configurations: configurations)
guard buildSupportDirectories.count <= 8,
Set(buildSupportDirectories.map { $0.lowercased() }).count == buildSupportDirectories.count else {
throw CMOCBuildError.message("Choose at most eight distinct sibling build-support folders.")
}
for path in buildSupportDirectories {
let name = String(path.dropFirst(3))
guard path.hasPrefix("../"), !name.isEmpty, name.utf8.count <= 100,
name.first?.isASCII == true,
name.first!.isLetter || name.first!.isNumber || name.first == "_",
name.allSatisfy({ $0.isASCII && ($0.isLetter || $0.isNumber || "_.-".contains($0)) }),
name.lowercased() != "project" else {
throw CMOCBuildError.message("Build-support folders must be named siblings such as ../tools; nested paths and project are not allowed.")
}
}
guard launchCommands.count <= 16, launchCommands.allSatisfy({ !$0.contains("\0") && $0.utf8.count <= 4096 }) else {
throw CMOCBuildError.message("Project launch commands are too large or invalid.")
}
return self
}
static func validateTarget(_ target: String) throws {
guard !target.isEmpty, !target.hasPrefix("-"), !target.contains("="), !target.contains("\0"),
!target.contains("\n"), target.utf8.count <= 512 else { throw CMOCBuildError.message("Choose a valid Make target name.") }
}
}
struct CMOCProjectFile: Identifiable, Equatable, Sendable {
let relativePath: String
let isEditable: Bool
var id: String { relativePath }
}
struct CMOCBuildSupportSnapshot: Equatable, Sendable {
let files: [String: Data]
let permissions: [String: Int]
var hashes: [String: String] {
var result = files.mapValues(CMOCProject.sha256)
for (path, mode) in permissions { result["@mode:" + path] = CMOCProject.sha256(Data(String(mode).utf8)) }
return result
}
}
/// Opening and enumerating an ordinary project never executes its Makefile.
struct CMOCProject: Equatable, Sendable {
static let maximumSourceBytes = 1_048_576
static let maximumMakefileBytes = 65_536
static let configurationFilename = "vccplus-project.json"
static let maximumFileBytes = 64 * 1024 * 1024
static let maximumProjectBytes = 512 * 1024 * 1024
let directory: URL
var configuration: CMOCProjectConfiguration
init(directory: URL, configuration: CMOCProjectConfiguration = .init()) {
self.directory = URL(fileURLWithPath: directory.standardizedFileURL.path, isDirectory: true)
self.configuration = configuration
}
var sourceURL: URL { directory.appendingPathComponent(configuration.entrySource) }
var makefileURL: URL { directory.appendingPathComponent(configuration.makefile) }
static let starterSource = DevelopmentStarterSource.planet(withExtension: "c")
?? "/* Reinstall VCC Plus to restore the Hello World starter. */\n"
static let starterMakefile = """
# Ordinary Makefile. VCC Plus supplies CMOC and Make on PATH.
CMOC ?= cmoc
LIBS ?= -ldecbfile
VCC_CONFIGURATION ?= Debug
ifeq ($(VCC_CONFIGURATION),Release)
OPTIM ?= -O2
else
OPTIM ?= -O0
DEBUG_FRAME ?= -fno-omit-frame-pointer
endif
.PHONY: build clean
build: main.bin
main.bin: main.c
\t"$(CMOC)" --coco $(OPTIM) $(DEBUG_FRAME) --intermediate -o main.bin main.c $(LIBS)
clean:
\trm -f main.bin main.o main.s main.lst main.map main.link
"""
static func create(at directory: URL) throws -> CMOCProject {
let project = CMOCProject(directory: directory.standardizedFileURL)
guard !FileManager.default.fileExists(atPath: project.directory.path) else {
throw CMOCBuildError.message("Choose a new folder for the C project; this folder already exists.")
}
try FileManager.default.createDirectory(at: project.directory, withIntermediateDirectories: false)
do {
try Data(starterSource.utf8).write(to: project.sourceURL, options: .atomic)
try Data(starterMakefile.utf8).write(to: project.makefileURL, options: .atomic)
} catch { try? FileManager.default.removeItem(at: project.directory); throw error }
return project
}
/// The installed sample is immutable. Each New Project action makes a new,
/// writable source-only copy and never reuses another project's files/media.
static func createHelloDisk(at directory: URL, templateDirectory: URL? = nil) throws -> CMOCProject {
try createTemplate(at: directory, named: "HelloDisk", required: Set(["main.c", "include/hello.h", "src/display.c", "src/disk.c", "assets/words.txt", "tools/build-data.pl", "Makefile", configurationFilename, "README.md", ".gitignore"]), templateDirectory: templateDirectory)
}
static func createTalkingLander(at directory: URL, templateDirectory: URL? = nil) throws -> CMOCProject {
try createTemplate(at: directory, named: "TalkingPlanetLander", required: ["main.c", "Makefile", configurationFilename, "README.md", ".gitignore"], templateDirectory: templateDirectory)
}
private static func createTemplate(at directory: URL, named name: String, required: Set, templateDirectory: URL?) throws -> CMOCProject {
guard let template = templateDirectory ?? Bundle.main.resourceURL?.appendingPathComponent("DevelopmentTemplates/" + name) else {
throw CMOCBuildError.message("The project template is unavailable in this build.")
}
let files = try Self.files(in: template)
guard Set(files.keys) == required else {
throw CMOCBuildError.message("The selected template is incomplete or contains unexpected files. Reinstall the app's source-only template.")
}
_ = try CMOCProject.open(at: template)
let manager = FileManager.default
guard !manager.fileExists(atPath: directory.path) else {
throw CMOCBuildError.message("Choose a new folder for the C project; this folder already exists.")
}
try manager.createDirectory(at: directory, withIntermediateDirectories: false)
do {
for (path, data) in files {
let destination = directory.appendingPathComponent(path)
try manager.createDirectory(at: destination.deletingLastPathComponent(), withIntermediateDirectories: true)
try data.write(to: destination, options: .atomic)
}
return try CMOCProject.open(at: directory)
} catch {
try? manager.removeItem(at: directory)
throw error
}
}
static func open(at directory: URL) throws -> CMOCProject {
var project = CMOCProject(directory: directory.standardizedFileURL)
let configURL = project.directory.appendingPathComponent(configurationFilename)
if FileManager.default.fileExists(atPath: configURL.path) {
let text = try readText(configURL, maximumBytes: maximumMakefileBytes)
project.configuration = try JSONDecoder().decode(CMOCProjectConfiguration.self, from: Data(text.utf8)).validated()
} else {
if !FileManager.default.fileExists(atPath: project.makefileURL.path) {
if FileManager.default.fileExists(atPath: project.directory.appendingPathComponent("makefile").path) { project.configuration.makefile = "makefile" }
else if FileManager.default.fileExists(atPath: project.directory.appendingPathComponent("GNUmakefile").path) { project.configuration.makefile = "GNUmakefile" }
}
if !FileManager.default.fileExists(atPath: project.sourceURL.path) {
guard let entry = try project.fileEntries().first(where: { $0.relativePath.hasSuffix(".c") }) else {
throw CMOCBuildError.message("Choose a project folder containing a Makefile and C source, or provide vccplus-project.json with an entry source.")
}
project.configuration.entrySource = entry.relativePath
project.configuration.binary = URL(fileURLWithPath: entry.relativePath).deletingPathExtension().lastPathComponent + ".bin"
}
}
_ = try project.configuration.validated()
_ = try project.readSource()
_ = try readText(project.makefileURL, maximumBytes: maximumMakefileBytes)
return project
}
static func physicalURL(_ url: URL) throws -> URL {
guard let pointer = realpath(url.path, nil) else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .ENOENT) }
defer { free(pointer) }
return URL(fileURLWithPath: String(cString: pointer), isDirectory: true)
}
static func validateRelativePath(_ path: String) throws {
let components = path.split(separator: "/", omittingEmptySubsequences: false)
guard !path.isEmpty, !path.hasPrefix("/"), !path.contains("\\"), !path.contains("\0"), !path.contains("\n"),
!components.contains(where: { $0.isEmpty || $0 == "." || $0 == ".." }), path.utf8.count <= 4096 else {
throw CMOCBuildError.message("Project paths must stay inside the project folder: \(path)")
}
}
func fileURL(relativePath: String) throws -> URL {
try Self.validateRelativePath(relativePath)
var url = directory
for component in relativePath.split(separator: "/") {
url.appendPathComponent(String(component))
if FileManager.default.fileExists(atPath: url.path) {
let values = try url.resourceValues(forKeys: [.isSymbolicLinkKey])
guard values.isSymbolicLink != true else { throw CMOCBuildError.message("Project files cannot traverse symbolic links: \(relativePath)") }
}
}
return url
}
func fileEntries() throws -> [CMOCProjectFile] {
try CMOCProjectInputManifest.capture(project: self, approvedSupportDirectories: []).files.keys.sorted()
.map { CMOCProjectFile(relativePath: $0, isEditable: Self.isEditable($0)) }
}
/// Build inputs, excluding conventional compiler products left by an external
/// Make invocation. Prebuilt archives and standalone assembly/data are inputs.
static func filteredInputs(_ files: [String: Data], configuration: CMOCProjectConfiguration) -> [String: Data] {
var excluded = Set()
if let binary = configuration.binary {
excluded.insert(binary.lowercased())
let stem = (binary as NSString).deletingPathExtension
for ext in ["map", "link"] { excluded.insert((stem + "." + ext).lowercased()) }
}
if let disk = configuration.diskImage { excluded.insert(disk.lowercased()) }
excluded.formUnion((configuration.playtestDisks + configuration.exportOutputs).map { $0.lowercased() })
if let manifest = configuration.debugManifest { excluded.insert(manifest.lowercased()) }
if let recipe = configuration.makefileSettings {
for path in recipe.generatedResources.flatMap(\.outputs) { excluded.insert(path.lowercased()) }
for source in recipe.sources {
let stem = "obj/" + (source as NSString).deletingPathExtension
for ext in ["o", "d", "s", "lst"] { excluded.insert((stem + "." + ext).lowercased()) }
}
}
let keys = Set(files.keys.map { $0.lowercased() })
return files.filter { path, _ in
let key = path.lowercased(), stem = (key as NSString).deletingPathExtension
let ext = (key as NSString).pathExtension
if configuration.makefileSettings != nil && key.hasPrefix("obj/vcc-dos-boot/") { return false }
if excluded.contains(key) || ["o", "d", "lst", "map", "link"].contains(ext) { return false }
if ext == "s" && (keys.contains(stem + ".c") || keys.contains(stem + ".o") || keys.contains(stem + ".lst")) { return false }
if ext == "bin" && (keys.contains(stem + ".c") || keys.contains(stem + ".asm")) { return false }
return true
}
}
func inputFiles(overlays: [String: String] = [:]) throws -> [String: Data] {
try CMOCProjectInputManifest.capture(project: self, overlays: overlays).files
}
/// The user must explicitly name these siblings in project settings. Keep
/// their paths outside ordinary project editing and include-file lookup.
func supportSnapshot() throws -> CMOCBuildSupportSnapshot {
_ = try configuration.validated()
let parent = try Self.physicalURL(directory).deletingLastPathComponent()
var files: [String: Data] = [:], permissions: [String: Int] = [:]
var total = 0
for relative in configuration.buildSupportDirectories {
let name = String(relative.dropFirst(3))
let root = parent.appendingPathComponent(name, isDirectory: true)
let info = try root.resourceValues(forKeys: [.isSymbolicLinkKey, .isDirectoryKey])
guard info.isSymbolicLink != true, info.isDirectory == true,
try Self.physicalURL(root) != Self.physicalURL(directory) else {
throw CMOCBuildError.message("Build-support folders must be separate regular sibling folders: \(relative)")
}
// A support root supplies reviewed files, not another project or
// authority to discover its siblings. Reuse the input classifier
// while ignoring any project configuration stored in that root.
var supportConfiguration = CMOCProjectConfiguration()
supportConfiguration.binary = nil
supportConfiguration.entrySource = "__vcc_support_input__"
supportConfiguration.makefile = "__vcc_support_make__"
let captured = try CMOCProjectInputManifest.capture(
project: CMOCProject(directory: root, configuration: supportConfiguration),
approvedSupportDirectories: [], readConfigurationFile: false, retainHostExecutables: true)
for (path, data) in captured.files {
let key = relative + "/" + path
total += data.count
guard files.count < 20_000, total <= Self.maximumProjectBytes else {
throw CMOCBuildError.message("Build-support folders exceed the 512 MB snapshot limit.")
}
guard let mode = captured.permissions[path] else {
throw CMOCBuildError.message("Build-support file permissions are unavailable: \(key)")
}
files[key] = data; permissions[key] = mode & 0o777
}
}
return CMOCBuildSupportSnapshot(files: files, permissions: permissions)
}
func supportFiles() throws -> [String: Data] { try supportSnapshot().files }
func supportFileHashes() throws -> [String: String] { try supportSnapshot().hashes }
static func isEditable(_ path: String) -> Bool {
let url = URL(fileURLWithPath: path)
return ["Makefile", "makefile", "GNUmakefile"].contains(url.lastPathComponent) ||
["c", "h", "s", "asm", "lwasm", "mk", "txt", "md", "json", "pl", "py", "sh", "rb", "bas", "cfg", "inc"].contains(url.pathExtension.lowercased())
}
static func isSource(_ path: String) -> Bool { ["c", "h", "s", "asm", "lwasm", "inc"].contains(URL(fileURLWithPath: path).pathExtension.lowercased()) }
/// Bounded regular-file enumeration. Build snapshots never follow project symlinks.
static func files(in root: URL) throws -> [String: Data] {
let manager = FileManager.default
let canonicalRoot = try physicalURL(root)
var enumerationError: Error?
guard let enumerator = manager.enumerator(at: canonicalRoot, includingPropertiesForKeys: [.isRegularFileKey, .isDirectoryKey, .isSymbolicLinkKey, .fileSizeKey], options: [], errorHandler: { _, error in enumerationError = error; return false }) else {
throw CMOCBuildError.message("The project folder could not be read.")
}
var result: [String: Data] = [:], total = 0
let excluded = Set([".git", ".svn", ".build", ".vccplus-build", ".DS_Store"])
while let url = enumerator.nextObject() as? URL {
if excluded.contains(url.lastPathComponent) { enumerator.skipDescendants(); continue }
let values = try url.resourceValues(forKeys: [.isRegularFileKey, .isDirectoryKey, .isSymbolicLinkKey, .fileSizeKey])
let relative = String(url.path.dropFirst(canonicalRoot.path.count + 1))
try validateRelativePath(relative)
guard values.isSymbolicLink != true else { throw CMOCBuildError.message("Copy linked resources into the project before building: \(relative)") }
if values.isDirectory == true { continue }
guard values.isRegularFile == true else { throw CMOCBuildError.message("Unsupported project file: \(relative)") }
guard let size = values.fileSize, size <= maximumFileBytes, result.count < 20_000, total + size <= maximumProjectBytes else {
throw CMOCBuildError.message("Project exceeds the 512 MB snapshot or 64 MB per-file limit.")
}
let data = try Data(contentsOf: url)
guard data.count <= maximumFileBytes, total + data.count <= maximumProjectBytes else { throw CMOCBuildError.message("Project changed size while it was being read.") }
total += data.count; result[relative] = data
}
if let enumerationError { throw enumerationError }
return result
}
func currentFileHashes(overlays: [String: String] = [:]) throws -> [String: String] {
let captured = try CMOCProjectInputManifest.capture(project: self, overlays: overlays)
return captured.files.mapValues(Self.sha256).merging(captured.support.hashes) { first, _ in first }
}
func readSource() throws -> String { try readText(relativePath: configuration.entrySource) }
func readText(relativePath: String) throws -> String {
try Self.readText(fileURL(relativePath: relativePath), maximumBytes: Self.maximumSourceBytes)
}
@discardableResult
func saveSource(_ source: String, replacingSHA256 expectedHash: String? = nil) throws -> String {
try saveText(source, relativePath: configuration.entrySource, replacingSHA256: expectedHash)
}
@discardableResult
func saveText(_ source: String, relativePath: String, replacingSHA256 expectedHash: String? = nil) throws -> String {
let url = try fileURL(relativePath: relativePath)
let bytes = try Self.sourceBytes(source)
if let expectedHash {
let disk = try Self.readText(url, maximumBytes: Self.maximumSourceBytes)
guard Self.sha256(Data(disk.utf8)) == expectedHash else {
throw CMOCBuildError.message("\(relativePath) changed outside this window. Reload it before replacing that version.")
}
}
try bytes.write(to: url, options: .atomic)
return Self.sha256(bytes)
}
static func sha256(_ data: Data) -> String { SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined() }
static func sourceBytes(_ source: String) throws -> Data {
let data = Data(source.utf8)
guard data.count <= maximumSourceBytes, !source.utf8.contains(0) else {
throw CMOCBuildError.message("Source must be UTF-8 text of at most 1 MB without NUL characters.")
}
return data
}
static func readText(_ url: URL, maximumBytes: Int) throws -> String {
let info = try url.resourceValues(forKeys: [.isRegularFileKey, .isSymbolicLinkKey])
guard info.isRegularFile == true, info.isSymbolicLink != true else {
throw CMOCBuildError.message("Choose a project containing regular source and Makefile files.")
}
let file = try FileHandle(forReadingFrom: url); defer { try? file.close() }
let data = try file.read(upToCount: maximumBytes + 1) ?? Data()
guard data.count <= maximumBytes, let text = String(data: data, encoding: .utf8), !data.contains(0) else {
throw CMOCBuildError.message("\(url.lastPathComponent) is too large or is not UTF-8 text.")
}
return text
}
}
/// Original output identity of an explicitly reviewed additional floppy image.
/// Mutable worker copies never overwrite this build receipt.
struct CMOCPlaytestDiskProduct: Codable, Equatable, Sendable {
static let maximumBytes = 512 * 1024
let relativePath: String
let sha256: String
let byteCount: Int
}
/// A concrete delivery product frozen at successful build completion.
struct CMOCBuildOutputProduct: Codable, Equatable, Sendable {
let relativePath: String
let byteCount: Int
let sha256: String
func identifier(artifactID: UUID) -> String {
CMOCProject.sha256(Data((artifactID.uuidString + "\n" + relativePath).utf8))
}
func fields(artifactID: UUID) -> [String: Any] {
["output_id": identifier(artifactID: artifactID), "path": relativePath,
"bytes": byteCount, "sha256": sha256]
}
}
struct CMOCBuildArtifact: Sendable {
let id: UUID
let directory: URL
let source: String
let sourceData: Data
let sourceSHA256: String
let binaryData: Data
let buildLog: String
let buildOutput: CMOCBuildOutput?
let sources: [String: Data]
let sourceHashes: [String: String]
let fileHashes: [String: String]
let compilationDirectory: URL
let entrySourcePath: String
let binaryRelativePath: String?
let diskRelativePath: String?
/// Digest captured from this build's output bytes, never recomputed from a
/// retained file that may subsequently have changed.
let diskSHA256: String?
let playtestDiskProducts: [CMOCPlaytestDiskProduct]
let debugManifestRelativePath: String?
let outputPaths: [String]
let exportProducts: [CMOCBuildOutputProduct]
let configurationName: String
let action: CMOCBuildAction
var hasBinary: Bool { binaryRelativePath != nil && !binaryData.isEmpty }
var hasDisk: Bool { diskRelativePath != nil }
var sourceURL: URL { fileURL(entrySourcePath) }
var binaryURL: URL { fileURL(binaryRelativePath ?? "main.bin") }
var diskURL: URL? { diskRelativePath.map(fileURL) }
var listingURL: URL { sourceURL.deletingPathExtension().appendingPathExtension("lst") }
var objectURL: URL { sourceURL.deletingPathExtension().appendingPathExtension("o") }
var mapURL: URL { binaryURL.deletingPathExtension().appendingPathExtension("map") }
var assemblyURL: URL { sourceURL.deletingPathExtension().appendingPathExtension("s") }
var linkScriptURL: URL { binaryURL.deletingPathExtension().appendingPathExtension("link") }
func fileURL(_ path: String) -> URL { directory.appendingPathComponent(path) }
init(id: UUID, directory: URL, source: String, sourceData: Data, sourceSHA256: String, binaryData: Data, buildLog: String,
sources: [String: Data]? = nil, fileHashes: [String: String]? = nil, compilationDirectory: URL? = nil,
entrySourcePath: String = "main.c", binaryRelativePath: String? = "main.bin", diskRelativePath: String? = nil,
outputPaths: [String] = [], configurationName: String = "Debug", action: CMOCBuildAction = .build,
debugManifestRelativePath: String? = nil, diskSHA256: String? = nil, buildOutput: CMOCBuildOutput? = nil,
playtestDiskProducts: [CMOCPlaytestDiskProduct] = [], exportProducts: [CMOCBuildOutputProduct] = []) {
self.id = id; self.directory = directory; self.source = source; self.sourceData = sourceData; self.sourceSHA256 = sourceSHA256
self.binaryData = binaryData; self.buildLog = buildLog; self.buildOutput = buildOutput; self.sources = sources ?? [entrySourcePath: sourceData]
self.sourceHashes = self.sources.mapValues(CMOCProject.sha256)
self.fileHashes = fileHashes ?? [entrySourcePath: sourceSHA256]
self.compilationDirectory = compilationDirectory ?? directory; self.entrySourcePath = entrySourcePath
self.binaryRelativePath = binaryRelativePath; self.diskRelativePath = diskRelativePath; self.outputPaths = outputPaths
self.debugManifestRelativePath = debugManifestRelativePath
self.diskSHA256 = diskSHA256
self.playtestDiskProducts = playtestDiskProducts
self.exportProducts = exportProducts
self.configurationName = configurationName; self.action = action
}
func matches(source: String) -> Bool { sourceSHA256 == CMOCProject.sha256(Data(source.utf8)) }
/// Only an immutable declared product from this build can supply bytes.
/// Walk from a no-follow directory descriptor, so a replaced parent or leaf
/// cannot redirect the read into another build or an arbitrary host file.
func playtestDiskData(for product: CMOCPlaytestDiskProduct) throws -> Data {
try CMOCProject.validateRelativePath(product.relativePath)
guard playtestDiskProducts.contains(product), outputPaths.contains(product.relativePath),
(1...CMOCPlaytestDiskProduct.maximumBytes).contains(product.byteCount) else {
throw CMOCBuildError.message("The selected playtest disk is not a declared product of this artifact.")
}
return try readPlaytestDisk(relativePath: product.relativePath, sha256: product.sha256, byteCount: product.byteCount)
}
func playtestPrimaryDiskData() throws -> Data {
guard let relativePath = diskRelativePath, let sha256 = diskSHA256,
outputPaths.contains(relativePath) else {
throw CMOCBuildError.message("The primary playtest disk is not a verified product of this artifact.")
}
return try readPlaytestDisk(relativePath: relativePath, sha256: sha256, byteCount: nil)
}
private func readPlaytestDisk(relativePath: String, sha256: String, byteCount: Int?) throws -> Data {
try CMOCProject.validateRelativePath(relativePath)
guard sha256.utf8.count == 64,
sha256.utf8.allSatisfy({ (48...57).contains($0) || (97...102).contains($0) }) else {
throw CMOCBuildError.message("The playtest disk has no valid original build hash.")
}
let path = directory.standardizedFileURL.path
// Only macOS's well-known /var and /tmp aliases are normalized. Other
// links, including a replaced artifact root, fail the descriptor walk.
let root = path == "/var" || path.hasPrefix("/var/") || path == "/tmp" || path.hasPrefix("/tmp/") ? "/private" + path : path
var parent = Darwin.open("/", O_RDONLY | O_DIRECTORY | O_CLOEXEC | O_NOFOLLOW)
guard parent >= 0 else { throw CMOCBuildError.message("The playtest artifact directory is unavailable.") }
defer { Darwin.close(parent) }
let components = root.split(separator: "/").map(String.init) + relativePath.split(separator: "/").map(String.init)
for component in components.dropLast() {
let next = openat(parent, component, O_RDONLY | O_DIRECTORY | O_CLOEXEC | O_NOFOLLOW)
guard next >= 0 else { throw CMOCBuildError.message("The declared playtest disk cannot traverse a replaced or symbolic directory.") }
Darwin.close(parent); parent = next
}
let descriptor = openat(parent, components.last!, O_RDONLY | O_CLOEXEC | O_NOFOLLOW | O_NONBLOCK)
guard descriptor >= 0 else { throw CMOCBuildError.message("The declared playtest disk is unavailable or has been replaced.") }
let handle = FileHandle(fileDescriptor: descriptor, closeOnDealloc: true)
defer { try? handle.close() }
var before = stat()
guard fstat(descriptor, &before) == 0, before.st_mode & S_IFMT == S_IFREG,
before.st_nlink == 1, before.st_size > 0, before.st_size <= off_t(CMOCPlaytestDiskProduct.maximumBytes),
byteCount == nil || before.st_size == off_t(byteCount!) else {
throw CMOCBuildError.message("The declared playtest disk is not the original bounded regular output.")
}
let data = try handle.read(upToCount: CMOCPlaytestDiskProduct.maximumBytes + 1) ?? Data()
var after = stat(), named = stat()
guard fstat(descriptor, &after) == 0, before.st_dev == after.st_dev, before.st_ino == after.st_ino,
before.st_size == after.st_size, before.st_mtimespec.tv_sec == after.st_mtimespec.tv_sec,
before.st_mtimespec.tv_nsec == after.st_mtimespec.tv_nsec,
fstatat(parent, components.last!, &named, AT_SYMLINK_NOFOLLOW) == 0,
named.st_mode & S_IFMT == S_IFREG, named.st_dev == after.st_dev, named.st_ino == after.st_ino,
data.count == Int(before.st_size), CMOCProject.sha256(data) == sha256 else {
throw CMOCBuildError.message("The declared playtest disk changed after this artifact was built.")
}
return data
}
func bankedDebugLayout() throws -> CMOCBankedDebugLayout? {
guard let path = debugManifestRelativePath else { return nil }
try CMOCProject.validateRelativePath(path)
guard let binaryRelativePath, outputPaths.contains(path) else {
throw CMOCSourceMap.Failure.invalid("the configured banked debug manifest was not produced by this build.")
}
let url = directory.resolvingSymlinksInPath().standardizedFileURL.appendingPathComponent(path)
guard url.resolvingSymlinksInPath().path == url.standardizedFileURL.path else {
throw CMOCSourceMap.Failure.invalid("banked manifest must not traverse symbolic links.")
}
let info = try url.resourceValues(forKeys: [.isRegularFileKey, .isSymbolicLinkKey, .fileSizeKey])
guard info.isRegularFile == true, info.isSymbolicLink != true, (info.fileSize ?? Int.max) <= 1024 * 1024 else {
throw CMOCSourceMap.Failure.invalid("banked manifest must be a bounded regular file.")
}
let handle = try FileHandle(forReadingFrom: url); defer { try? handle.close() }
let data = try handle.read(upToCount: 1024 * 1024 + 1) ?? Data()
return try CMOCBankedDebugLayout.parse(data: data, directory: directory, sources: sources, binary: binaryData,
binaryPath: binaryRelativePath, diskPath: diskRelativePath, allowedOutputs: outputPaths)
}
}
/// A single process's merged output. The runner cannot recover separate stdout
/// and stderr after sending both descriptors to the same pipe.
struct CMOCBuildOutput: Sendable {
let text: String
let byteCount: Int
let truncated: Bool
let workingDirectory: URL
var invocation: [String] = []
var exitCode: Int32? = nil
}
private struct CMOCBoundedBuildLog {
static let marker = "\n[Build output truncated; beginning and end retained.]\n"
static func limit(_ text: String, maximumBytes: Int) -> (text: String, truncated: Bool) {
let bytes = Array(text.utf8)
guard bytes.count > maximumBytes else { return (text, false) }
let body = max(0, maximumBytes - marker.utf8.count)
var first = Array(bytes.prefix(body / 2)), last = Array(bytes.suffix(body - body / 2))
// Input is valid UTF-8; only the two clipping boundaries can split a
// scalar. Remove those fragments rather than adding replacement bytes.
while !first.isEmpty && String(bytes: first, encoding: .utf8) == nil { first.removeLast() }
while !last.isEmpty && String(bytes: last, encoding: .utf8) == nil { last.removeFirst() }
return (String(decoding: first, as: UTF8.self) + marker + String(decoding: last, as: UTF8.self), true)
}
}
/// Bounded wire formatting shared by native build failures and assistant builds.
/// Parsed source diagnostics may accompany these fields; they never replace the
/// log, since fatal linker/Make lines often have no C source-file diagnostic.
/// Retained per-build evidence. The wire preview and page API share the same
/// redacted bytes; no page reads arbitrary files or reruns a compiler.
struct CMOCBuildReport: Sendable {
struct Diagnostic: Sendable {
let path: String?
let line: Int?
let column: Int?
let severity: String
let stage: String?
let message: String
let raw: String
var fields: [String: Any] {
["path": path as Any? ?? NSNull(), "line": line as Any? ?? NSNull(),
"column": column as Any? ?? NSNull(), "severity": severity,
"stage": stage as Any? ?? NSNull(), "message": message, "raw": raw]
}
}
let log: String
let exitCode: Int32?
let processOutputBytes: Int?
let processOutputTruncated: Bool
let failureKind: String?
let reason: String?
let invocation: [String]
let diagnostics: [Diagnostic]
let diagnosticsTruncated: Bool
let diagnosticsTotal: Int
let firstError: Diagnostic?
let failureStage: String?
let failingCommand: String?
private static let maximumRetainedLogBytes = 512 * 1024
init(error: Error, redacting roots: [URL] = [], visiblePaths: Set? = nil) {
var text = error.localizedDescription, code: Int32?, capture: CMOCBuildOutput?
var kind = "build_error", explanation = error.localizedDescription, stage: String? = "preparation"
if let build = error as? CMOCBuildError {
switch build {
case .failed(let status, let output, let details):
text = output; code = status; capture = details; kind = "process_exit"; stage = "make"
explanation = "Build failed (exit \(status))."
case .timedOut(let output, let details, let status):
text = output; code = status; capture = details; kind = "timeout"; stage = "make"
explanation = "The build exceeded its time limit and was stopped."
case .validation(let message, let output, let details):
text = message + (output.isEmpty ? "" : "\n" + output); capture = details
code = details?.exitCode; kind = "validation"; stage = "validation"; explanation = message
case .message(let message): text = message
}
}
self.init(text: text, capture: capture, code: code, kind: kind, reason: explanation,
fallbackStage: stage, roots: roots, visiblePaths: visiblePaths)
}
init(artifact: CMOCBuildArtifact, redacting roots: [URL] = [], visiblePaths: Set? = nil) {
self.init(text: artifact.buildLog, capture: artifact.buildOutput, code: 0, kind: nil, reason: nil,
fallbackStage: nil, roots: roots + [artifact.compilationDirectory, artifact.directory], visiblePaths: visiblePaths)
}
private init(text: String, capture: CMOCBuildOutput?, code: Int32?, kind: String?, reason: String?,
fallbackStage: String?, roots: [URL], visiblePaths: Set?) {
let allRoots = roots + [capture?.workingDirectory].compactMap { $0 }
let redacted = Self.redact(text, roots: allRoots)
let retained = CMOCBoundedBuildLog.limit(redacted, maximumBytes: Self.maximumRetainedLogBytes)
log = retained.text; exitCode = code; processOutputBytes = capture?.byteCount
processOutputTruncated = capture?.truncated == true || retained.truncated
failureKind = kind; self.reason = reason.map { Self.redact($0, roots: allRoots) }
invocation = (capture?.invocation ?? []).map { Self.redact($0, roots: allRoots) }
let parsed = Self.parseDiagnostics(log, visiblePaths: visiblePaths)
var rows = parsed.items, first = parsed.firstError
var total = parsed.total
if first == nil, let reason = self.reason, ["build_error", "validation", "timeout"].contains(kind ?? "") {
let clipped = CMOCBoundedBuildLog.limit(reason, maximumBytes: 4_096)
let diagnostic = Diagnostic(path: nil, line: nil, column: nil, severity: "error", stage: fallbackStage,
message: clipped.text, raw: clipped.text)
first = diagnostic; total += 1
if rows.count < 256 { rows.append(diagnostic) }
}
diagnostics = rows; firstError = first; diagnosticsTotal = total
diagnosticsTruncated = parsed.truncated || processOutputTruncated || total != rows.count
failureStage = kind == nil ? nil : first?.stage ?? fallbackStage
// An echoed, recognized compiler command is evidence, but the top-level
// Make invocation is not claimed as a hidden recipe's failing command.
failingCommand = kind == nil ? nil : Self.echoedFailingCommand(log)
}
func fields(maximumLogBytes: Int = 32_000, maximumDiagnostics: Int = 64) -> [String: Any] {
let limit = min(128 * 1024, max(256, maximumLogBytes))
let bounded = CMOCBoundedBuildLog.limit(log, maximumBytes: limit)
let boundedReason = reason.map { CMOCBoundedBuildLog.limit($0, maximumBytes: 2_048) }
var selected: [[String: Any]] = [], bytes = 0
for item in diagnostics.prefix(max(0, min(256, maximumDiagnostics))) {
let row = item.fields
guard let encoded = try? JSONSerialization.data(withJSONObject: row), bytes + encoded.count <= 24 * 1024 else { break }
selected.append(row); bytes += encoded.count
}
return ["exit_code": exitCode.map { NSNumber(value: $0) } as Any? ?? NSNull(),
"log": bounded.text, "log_truncated": bounded.truncated || processOutputTruncated,
"log_limit_bytes": limit, "log_retained_bytes": log.utf8.count,
"log_retrievable": true, "process_output_bytes": processOutputBytes as Any? ?? NSNull(),
"process_output_truncated": processOutputTruncated, "output_streams": "combined", "stdout": NSNull(), "stderr": NSNull(),
"failure_kind": failureKind as Any? ?? NSNull(), "reason": boundedReason?.text as Any? ?? NSNull(),
"reason_truncated": boundedReason?.truncated == true,
"failure_stage": failureStage as Any? ?? NSNull(), "invocation": invocation,
"failing_command": failingCommand as Any? ?? NSNull(),
"failing_command_evidence": failingCommand == nil ? "unavailable" : "echoed_before_first_retained_error",
"diagnostics": selected, "diagnostics_total": diagnosticsTotal,
"diagnostics_truncated": diagnosticsTruncated || selected.count != diagnostics.count,
"first_error": firstError?.fields as Any? ?? NSNull(),
"first_error_scope": processOutputTruncated ? "retained_output" : "complete_output"]
}
/// Offsets count UTF-8 bytes in the retained redacted log. A client follows
/// next_offset; a caller-supplied offset inside a scalar is refused.
func logPage(offset: Int, limit: Int = 16_384) throws -> [String: Any] {
let data = Data(log.utf8)
guard offset >= 0, offset <= data.count, (1...32_768).contains(limit),
offset == data.count || data[offset] & 0xc0 != 0x80 else { throw CMOCBuildError.message("invalid_log_page") }
var end = min(data.count, offset + min(limit, data.count - offset))
while end > offset && end < data.count && data[end] & 0xc0 == 0x80 { end -= 1 }
// At least one Unicode scalar fits, even for an unusually tiny limit.
if end == offset && offset < data.count {
end = offset + 1
while end < data.count && data[end] & 0xc0 == 0x80 { end += 1 }
}
return ["log": String(decoding: data[offset.. String {
var paths = Set()
for root in roots {
let path = root.standardizedFileURL.path
guard path.count > 1 else { continue }
paths.insert(path)
if path.hasPrefix("/private/var/") || path.hasPrefix("/private/tmp/") { paths.insert(String(path.dropFirst(8))) }
if path.hasPrefix("/var/") || path.hasPrefix("/tmp/") { paths.insert("/private" + path) }
}
var result = text
for path in paths.sorted(by: { $0.count > $1.count }) {
let url = URL(fileURLWithPath: path).absoluteString
for spelling in [url.hasSuffix("/") ? String(url.dropLast()) : url, path] {
result = result.replacingOccurrences(of: spelling, with: "")
}
}
return result
}
private static func stage(for raw: String, file: String?) -> String? {
let lower = raw.lowercased()
if lower.contains("lwlink") || lower.contains("undefined symbol") || lower.contains("undefined reference") ||
lower.hasPrefix("external symbol ") || lower.hasPrefix("local symbol ") || lower.hasPrefix("incomplete reference at ") { return "linker" }
if lower.contains("lwasm") { return "assembler" }
if lower.hasPrefix("make:") || lower.hasPrefix("make[") || file.map({ ($0 as NSString).lastPathComponent.lowercased().contains("makefile") }) == true { return "make" }
if let file {
let ext = (file as NSString).pathExtension.lowercased()
if ["s", "asm", "lwasm"].contains(ext) { return "assembler" }
if ["c", "h", "inc"].contains(ext) { return "compiler" }
}
if lower.contains("cmoc:") || lower.contains("cpp:") { return "compiler" }
return nil
}
private static let sourceDiagnostic = try! NSRegularExpression(pattern: #"^(.+?):([0-9]+)(?::([0-9]+))?:\s*(.+)$"#)
private static let assemblerDiagnostic = try! NSRegularExpression(pattern: #"^(.+)\(([0-9]+)\)\s*:\s*(.+)$"#)
private static let diagnosticSeverity = try! NSRegularExpression(pattern: #"^(?:[^:\n]+:\s*)?(fatal(?: error)?|error|warning|note)\s*:"#, options: .caseInsensitive)
private static func severity(_ message: String) -> String? {
let text = message.trimmingCharacters(in: .whitespaces), ns = text as NSString
if let match = diagnosticSeverity.firstMatch(in: text, range: NSRange(location: 0, length: ns.length)) {
let marker = ns.substring(with: match.range(at: 1)).lowercased()
return marker.hasPrefix("fatal") ? "error" : marker
}
let lower = text.lowercased()
if lower.hasPrefix("***") || ((lower.hasPrefix("make:") || lower.hasPrefix("make[")) && lower.contains("***")) ||
lower.hasPrefix("undefined symbol") || lower.hasPrefix("undefined reference") ||
((lower.hasPrefix("external symbol ") || lower.hasPrefix("local symbol ")) && lower.contains(" not found")) ||
lower.hasPrefix("incomplete reference at ") || lower.hasPrefix("can't open file ") || lower.hasPrefix("cannot open output file ") { return "error" }
return nil
}
private static func parseDiagnostics(_ text: String, visiblePaths: Set?) -> (items: [Diagnostic], firstError: Diagnostic?, total: Int, truncated: Bool) {
var rows: [Diagnostic] = [], firstError: Diagnostic?, total = 0, truncated = false, retainedBytes = 0
for rawLine in text.components(separatedBy: .newlines) where !rawLine.isEmpty {
// Make echoes these commands before their output. A quoted sample
// such as printf 'main.c:2: error: ...' is not a compiler diagnostic.
let trimmed = rawLine.trimmingCharacters(in: .whitespaces)
if trimmed.hasPrefix("printf ") || trimmed.hasPrefix("echo ") { continue }
let ns = rawLine as NSString
var file: String?, number: Int?, column: Int?, message = rawLine
if let match = sourceDiagnostic.firstMatch(in: rawLine, range: NSRange(location: 0, length: ns.length)) {
file = ns.substring(with: match.range(at: 1)); number = Int(ns.substring(with: match.range(at: 2)))
if match.range(at: 3).location != NSNotFound { column = Int(ns.substring(with: match.range(at: 3))) }
message = ns.substring(with: match.range(at: 4))
} else if let match = assemblerDiagnostic.firstMatch(in: rawLine, range: NSRange(location: 0, length: ns.length)) {
file = ns.substring(with: match.range(at: 1)); number = Int(ns.substring(with: match.range(at: 2)))
message = ns.substring(with: match.range(at: 3))
}
guard let severity = severity(message) else { continue }
total += 1
let resolved: String?
if let file, let visiblePaths {
resolved = visiblePaths.sorted().first { file == $0 || file.hasSuffix("/" + $0) }
} else if let file, !file.hasPrefix("/"), !file.hasPrefix("file:"), !file.hasPrefix("/") { resolved = file.hasPrefix("./") ? String(file.dropFirst(2)) : file }
else { resolved = nil }
let stage = stage(for: rawLine, file: file)
let clippedRaw = CMOCBoundedBuildLog.limit(rawLine, maximumBytes: 4_096)
let clippedMessage = CMOCBoundedBuildLog.limit(message, maximumBytes: 4_096)
let bytes = clippedRaw.text.utf8.count + clippedMessage.text.utf8.count
let diagnostic = Diagnostic(path: resolved, line: number, column: column, severity: severity, stage: stage,
message: clippedMessage.text, raw: clippedRaw.text)
if severity == "error", firstError == nil { firstError = diagnostic }
guard rows.count < 256, retainedBytes + bytes <= 128 * 1024 else { truncated = true; continue }
rows.append(diagnostic)
retainedBytes += bytes; truncated = truncated || clippedRaw.truncated || clippedMessage.truncated
}
return (rows, firstError, total, truncated)
}
private static func echoedFailingCommand(_ text: String) -> String? {
var lastCommand: String?
for line in text.components(separatedBy: .newlines) {
let trimmed = line.trimmingCharacters(in: .whitespaces)
if trimmed.range(of: #"^(?:(?:[^\s]+/)?(?:cmoc|cpp|lwasm|lwlink))\s+"#, options: .regularExpression) != nil {
lastCommand = CMOCBoundedBuildLog.limit(trimmed, maximumBytes: 2_048).text
}
if parseDiagnostics(line, visiblePaths: []).firstError != nil { return lastCommand }
}
return nil
}
}
enum CMOCBuildFailureReport {
static func fields(for error: Error, redacting roots: [URL] = [], maximumLogBytes: Int = 32_000) -> [String: Any] {
CMOCBuildReport(error: error, redacting: roots).fields(maximumLogBytes: maximumLogBytes)
}
}
enum CMOCBuildError: LocalizedError {
case message(String)
case failed(status: Int32, log: String, capture: CMOCBuildOutput? = nil)
case timedOut(log: String, capture: CMOCBuildOutput? = nil, exitCode: Int32? = nil)
case validation(message: String, log: String, capture: CMOCBuildOutput? = nil)
var errorDescription: String? {
switch self {
case .message(let value): return value
case .validation(let message, let log, _): return message + (log.isEmpty ? "" : "\n" + log)
case .failed(let status, let log, _): return "Build failed (exit \(status)).\n\(log)"
case .timedOut(let log, _, _): return "The build exceeded its time limit and was stopped.\n\(log)"
}
}
}
/// All compiler I/O occurs off the main actor. Builds consume an immutable editor
/// snapshot, never mutate the source project, and never load the emulator.
final class CMOCBuildService: @unchecked Sendable {
static let requiredExecutables = ["cmoc", "make", "cpp", "lwasm", "lwlink"]
let toolchain: URL
let buildRoot: URL
private let buildHistory: CMOCBuildHistory
private let lock = NSLock()
private var active: DevelopmentProcessControl?
private let timeout: TimeInterval
private var incrementalRoot: URL?
init(toolchain: URL, buildRoot: URL = FileManager.default.temporaryDirectory.appendingPathComponent("VCCPlus-OSS-CMOC-Builds"), timeout: TimeInterval = 120) {
self.toolchain = toolchain.standardizedFileURL
self.buildRoot = buildRoot.standardizedFileURL
self.buildHistory = CMOCBuildHistory(root: buildRoot)
self.timeout = timeout
}
deinit {
if let incrementalRoot { try? FileManager.default.removeItem(at: incrementalRoot) }
}
/// CMOC dependency files contain unescaped absolute source paths. Keep the
/// compiler's physical working path Make-safe even when a project/results
/// directory contains spaces. Each service owns a separate cache namespace,
/// so concurrent app instances cannot mutate one another's build workspace.
private func incrementalWorkspaceRoot() throws -> URL {
if let incrementalRoot { return incrementalRoot }
let root: URL
if buildRoot.path.allSatisfy({ $0.isASCII && ($0.isLetter || $0.isNumber || "_./-".contains($0)) }) {
root = buildRoot.appendingPathComponent(".workspaces").appendingPathComponent(UUID().uuidString)
try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true, attributes: [.posixPermissions: 0o700])
} else {
var template = Array("/private/tmp/vccplus-cmoc-\(getuid())-XXXXXX".utf8CString)
guard let result = mkdtemp(&template) else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) }
root = URL(fileURLWithPath: String(cString: result), isDirectory: true)
}
incrementalRoot = root
return root
}
/// Dependency files are Make programs, not a format we can safely repair.
/// Rebuild this disposable cache when generated dependencies escape its
/// captured inputs. Authored dependency inputs are deliberately excluded.
private static func dependencyCacheInvalidation(files: [String: Data], inputs: Set, allowedRoots: [URL]) -> String? {
var roots = Set()
for root in allowedRoots {
for url in [root.standardizedFileURL, root.resolvingSymlinksInPath().standardizedFileURL] {
let path = url.path
roots.insert(path)
if path.hasPrefix("/private/var/") || path.hasPrefix("/private/tmp/") { roots.insert(String(path.dropFirst(8))) }
if path.hasPrefix("/var/") || path.hasPrefix("/tmp/") { roots.insert("/private" + path) }
}
}
var inspected = 0
for (path, data) in files where !inputs.contains(path) && (path as NSString).pathExtension.lowercased() == "d" {
inspected += data.count
guard data.count <= 4 * 1024 * 1024, inspected <= 16 * 1024 * 1024,
let text = String(data: data, encoding: .utf8), !text.contains("\0"),
!text.contains("$"), !text.contains("`"), !text.contains("\""), !text.contains("'") else {
return "generated dependency syntax cannot be reused safely"
}
var tokens: [String] = [], token = "", escaped = false, comment = false
for character in text {
if comment {
if character == "\n" { comment = false }
continue
}
if escaped {
// Make continuations join lines; other escapes quote a
// filename character (including whitespace, # and colon).
if character != "\n" && character != "\r" { token.append(character) }
escaped = false
} else if character == "\\" {
escaped = true
} else if character == "#" {
if !token.isEmpty { tokens.append(token); token = "" }
comment = true
} else if character.isWhitespace || character == ":" {
if !token.isEmpty { tokens.append(token); token = "" }
} else { token.append(character) }
}
if escaped { return "generated dependency syntax cannot be reused safely" }
if !token.isEmpty { tokens.append(token) }
for token in tokens where token.hasPrefix("/") {
let dependency = URL(fileURLWithPath: token).standardizedFileURL.path
guard roots.contains(where: { dependency == $0 || dependency.hasPrefix($0 + "/") }) else {
return "generated dependencies refer outside the captured workspace"
}
guard FileManager.default.fileExists(atPath: dependency) else {
return "a generated absolute dependency is no longer available"
}
}
}
return nil
}
func history(project: URL, protectedIDs: Set = []) throws -> [CMOCBuildHistory.Entry] {
try buildHistory.entries(project: project, protectedIDs: protectedIDs)
}
func removeBuilds(ids: Set, project: URL, protectedIDs: Set) throws -> CMOCBuildHistory.Removal {
lock.lock(); defer { lock.unlock() }
guard active == nil else { throw CMOCBuildError.message("Wait for the current build to finish before cleaning up.") }
return try buildHistory.remove(ids: ids, project: project, protectedIDs: protectedIDs)
}
func cancel() { lock.lock(); let control = active; lock.unlock(); control?.cancel() }
private func begin(_ control: DevelopmentProcessControl) throws {
lock.lock(); defer { lock.unlock() }
guard active == nil else { throw CMOCBuildError.message("A build is already running.") }
active = control
}
private func end(_ control: DevelopmentProcessControl) {
lock.lock(); defer { lock.unlock() }
if active === control { active = nil }
}
func build(project: CMOCProject, source: String) async throws -> CMOCBuildArtifact {
let control = DevelopmentProcessControl()
try begin(control)
defer { end(control) }
return try await withTaskCancellationHandler {
try await withCheckedThrowingContinuation { continuation in
DispatchQueue.global(qos: .userInitiated).async { [self] in
do { continuation.resume(returning: try buildSynchronously(project: project, source: source, control: control)) }
catch { continuation.resume(throwing: error) }
}
}
} onCancel: { control.cancel() }
}
/// Multi-file entry point. Each project/configuration has an incremental cache;
/// each successful invocation returns a separate immutable build snapshot.
func build(project: CMOCProject, overlays: [String: String], action: CMOCBuildAction = .build,
configuration: String? = nil, target: String? = nil) async throws -> CMOCBuildArtifact {
let control = DevelopmentProcessControl()
try begin(control); defer { end(control) }
return try await withTaskCancellationHandler {
try await withCheckedThrowingContinuation { continuation in
DispatchQueue.global(qos: .userInitiated).async { [self] in
do { continuation.resume(returning: try buildProjectSynchronously(project: project, overlays: overlays, action: action,
configurationName: configuration, target: target, control: control)) }
catch { continuation.resume(throwing: error) }
}
}
} onCancel: { control.cancel() }
}
private func buildProjectSynchronously(project: CMOCProject, overlays: [String: String], action: CMOCBuildAction,
configurationName: String?, target: String?, control: DevelopmentProcessControl) throws -> CMOCBuildArtifact {
try control.checkCancellation()
let manager = FileManager.default
let capturedInputs = try CMOCProjectInputManifest.capture(project: project, overlays: overlays)
let inputs = capturedInputs.files, settings = capturedInputs.configuration
var supportProject = project
supportProject.configuration = settings
let support = capturedInputs.support
guard inputs.count + support.files.count <= 20_000,
inputs.values.reduce(0, { $0 + $1.count }) + support.files.values.reduce(0, { $0 + $1.count }) <= CMOCProject.maximumProjectBytes else {
throw CMOCBuildError.message("Project and build-support files exceed the 512 MB snapshot limit.")
}
guard !inputs.keys.contains(where: { $0 == CMOCBundledLibrary.stagingDirectory || $0.hasPrefix(CMOCBundledLibrary.stagingDirectory + "/") }) else {
throw CMOCBuildError.message(".vccplus-libraries is reserved for isolated bundled-library copies. Move project files outside that directory.")
}
guard let entry = inputs[settings.entrySource], let entryText = String(data: entry, encoding: .utf8), !entry.contains(0),
let makefile = inputs[settings.makefile], let makefileText = String(data: makefile, encoding: .utf8), !makefileText.contains("\0") else {
throw CMOCBuildError.message("The project needs readable UTF-8 entry source and Makefile files.")
}
let name = configurationName ?? settings.configurations[0].name
guard let configuration = settings.configurations.first(where: { $0.name == name }) else {
throw CMOCBuildError.message("Unknown build configuration: \(name)")
}
let chosenTarget: String
switch action {
case .build, .rebuild: chosenTarget = target ?? settings.buildTarget
case .clean: chosenTarget = settings.cleanTarget
case .disk:
guard let diskTarget = target ?? settings.diskTarget else { throw CMOCBuildError.message("Set diskTarget in vccplus-project.json before building a disk.") }
chosenTarget = diskTarget
case .custom:
guard let target else { throw CMOCBuildError.message("Enter a Make target.") }
chosenTarget = target
}
if !chosenTarget.isEmpty || (action != .build && action != .rebuild) {
try CMOCProjectConfiguration.validateTarget(chosenTarget)
}
let bin = toolchain.appendingPathComponent("bin")
for name in Self.requiredExecutables {
guard manager.isExecutableFile(atPath: bin.appendingPathComponent(name).path) else {
throw CMOCBuildError.message("The development toolchain is unavailable (missing \(name)). This build needs the bundled CMOC tools.")
}
}
let manifest = (try? Data(contentsOf: toolchain.appendingPathComponent("manifest.json"))) ?? Data()
let libraryEncoder = JSONEncoder(); libraryEncoder.outputFormatting = [.sortedKeys]
let libraryKey = CMOCProject.sha256(try libraryEncoder.encode(settings.bundledLibraries))
var supportIdentity = support.hashes
supportIdentity["@directories"] = settings.buildSupportDirectories.joined(separator: "\n")
let supportKey = CMOCProject.sha256(try libraryEncoder.encode(supportIdentity))
// A newly reviewed media declaration cannot inherit an incidental old
// image from an earlier cache. Empty declarations retain legacy keys.
let exportKey = settings.exportOutputs.isEmpty ? "" : "\nexport-outputs:" + CMOCProject.sha256(try libraryEncoder.encode(settings.exportOutputs))
let playtestMediaKey = settings.playtestDisks.isEmpty ? "" :
"\nplaytest-disks:" + CMOCProject.sha256(try libraryEncoder.encode(settings.playtestDisks))
let cacheKey = CMOCProject.sha256(Data((project.directory.resolvingSymlinksInPath().path + "\n" + name + "\n" +
configuration.makeArguments.joined(separator: "\n") + "\n" + libraryKey + "\n" + supportKey + "\n" + toolchain.path + "\n" + CMOCProject.sha256(manifest) + playtestMediaKey + exportKey).utf8))
let cache = try incrementalWorkspaceRoot().appendingPathComponent(cacheKey)
let workspace = cache.appendingPathComponent("project")
let indexURL = cache.appendingPathComponent("inputs.json")
try manager.createDirectory(at: workspace, withIntermediateDirectories: true)
// Do not preserve a possibly partially written object from a failed/cancelled build.
var succeeded = false
defer { if !succeeded { try? manager.removeItem(at: cache) } }
let decodedInputs = (try? Data(contentsOf: indexURL)).flatMap { try? JSONDecoder().decode([String: String].self, from: $0) }
let recordedInputs = decodedInputs.flatMap { values -> [String: String]? in
guard values.allSatisfy({ path, hash in
(try? CMOCProject.validateRelativePath(path)) != nil && hash.utf8.count == 64 &&
hash.utf8.allSatisfy { (48...57).contains($0) || (97...102).contains($0) }
}) else { return nil }
return values
}
var previous = recordedInputs ?? [:]
// Validate the old workspace before discarding anything; a recipe's
// symlink must not redirect input synchronization or cache cleanup.
let cachedFiles = try CMOCProject.files(in: workspace)
var cacheResetReason: String?
if !cachedFiles.isEmpty && (recordedInputs == nil || previous.isEmpty) {
cacheResetReason = "the previous input receipt is missing or invalid"
} else if previous.keys.contains(where: { inputs[$0] == nil }) {
cacheResetReason = "a previously captured input was removed"
} else {
cacheResetReason = Self.dependencyCacheInvalidation(files: cachedFiles, inputs: Set(inputs.keys), allowedRoots: [cache, toolchain])
}
if cacheResetReason != nil {
// The cache is an app-owned working copy. Never rewrite arbitrary
// Make dependencies or execute a user's clean target to repair it.
try manager.removeItem(at: cache)
try manager.createDirectory(at: workspace, withIntermediateDirectories: true)
previous = [:]
}
for path in previous.keys where inputs[path] == nil {
let url = workspace.appendingPathComponent(path)
if manager.fileExists(atPath: url.path) { try manager.removeItem(at: url) }
}
for (path, data) in inputs {
try control.checkCancellation()
let url = workspace.appendingPathComponent(path)
try manager.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
if (try? Data(contentsOf: url)) != data {
try data.write(to: url, options: .atomic)
}
// Shell helpers retain their executable bit; generated products are not copied back.
if let mode = capturedInputs.permissions[path] {
var copiedAttributes: [FileAttributeKey: Any] = [.posixPermissions: mode & 0o777]
// On the initial copy preserve source timestamp ordering for
// custom generated-resource rules. Later content changes always
// receive a fresh mtime so Make cannot miss an edited input.
if previous.isEmpty, !capturedInputs.overlayPaths.contains(path), let date = capturedInputs.modificationDates[path] {
copiedAttributes[.modificationDate] = date
}
try manager.setAttributes(copiedAttributes, ofItemAtPath: url.path)
}
}
// A declared ../tools remains a sibling inside this cache. Never copy
// the project's parent or allow a previous recipe's links to redirect it.
for relative in settings.buildSupportDirectories {
let root = workspace.appendingPathComponent(relative, isDirectory: true).standardizedFileURL
if manager.fileExists(atPath: root.path) {
let info = try root.resourceValues(forKeys: [.isSymbolicLinkKey, .isDirectoryKey])
guard info.isSymbolicLink != true, info.isDirectory == true else {
throw CMOCBuildError.message("The isolated build-support folder is invalid: \(relative)")
}
_ = try CMOCProject.files(in: root)
try manager.removeItem(at: root)
}
try manager.createDirectory(at: root, withIntermediateDirectories: true)
}
for (path, data) in support.files {
try control.checkCancellation()
let url = workspace.appendingPathComponent(path).standardizedFileURL
try manager.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
try data.write(to: url, options: .atomic)
try manager.setAttributes([.posixPermissions: support.permissions[path] ?? 0o644], ofItemAtPath: url.path)
if let date = try manager.attributesOfItem(atPath: project.directory.appendingPathComponent(path).path)[.modificationDate] {
try manager.setAttributes([.modificationDate: date], ofItemAtPath: url.path)
}
}
let libraryPayload = try CMOCBundledLibrary.stage(settings.bundledLibraries, runtime: toolchain, workspace: workspace)
var environment = ProcessInfo.processInfo.environment
environment["PATH"] = bin.path + ":/usr/bin:/bin"
environment["CMOC"] = "cmoc"
environment["VCC_TOOLCHAIN"] = toolchain.path
environment["LC_ALL"] = "C"
for key in ["MAKEFLAGS", "MFLAGS", "MAKELEVEL", "GNUMAKEFLAGS", "PERL5LIB", "PERLLIB", "PERL5OPT"] { environment.removeValue(forKey: key) }
var log = cacheResetReason.map { "Rebuilding isolated cache: \($0).\n" } ?? ""
var combinedOutput: CMOCBuildOutput?
func appendOutput(_ capture: CMOCBuildOutput) {
let retained = CMOCBoundedBuildLog.limit(log + capture.text, maximumBytes: 512 * 1024)
log = retained.text
combinedOutput = CMOCBuildOutput(text: log, byteCount: (combinedOutput?.byteCount ?? 0) + capture.byteCount,
truncated: combinedOutput?.truncated == true || capture.truncated || retained.truncated,
workingDirectory: capture.workingDirectory, invocation: capture.invocation, exitCode: capture.exitCode)
}
func invoke(_ target: String) throws {
try control.checkCancellation(log: log)
let args = ["--no-print-directory", "-f", settings.makefile, "-j\(settings.jobs)", "--output-sync=target"] +
(settings.bundledLibraries.isEmpty ? [] : ["-f", CMOCBundledLibrary.stagingDirectory + "/bindings.mk"]) +
settings.bundledLibraries.filter { !$0.directoryVariable.isEmpty }.map {
// Command-line variables are visible when Make expands prerequisites
// and propagate to recursive Make; a later include is too late.
$0.directoryVariable + "=" + workspace.appendingPathComponent(CMOCBundledLibrary.stagingDirectory).appendingPathComponent($0.library).path
} + configuration.makeArguments + ["MAKE=make", "--"] + (target.isEmpty ? [] : [target])
let output: (status: Int32, text: String)
do {
output = try control.run(executable: bin.appendingPathComponent("make"), arguments: args, directory: workspace,
environment: environment, timeout: timeout)
} catch CMOCBuildError.timedOut(let text, let capture, let status) {
if let capture { appendOutput(capture) }
else { log = CMOCBoundedBuildLog.limit(log + text, maximumBytes: 512 * 1024).text }
throw CMOCBuildError.timedOut(log: log, capture: combinedOutput, exitCode: status)
}
if let capture = control.capturedOutput { appendOutput(capture) }
else { log = CMOCBoundedBuildLog.limit(log + output.text, maximumBytes: 512 * 1024).text }
guard output.status == 0 else { throw CMOCBuildError.failed(status: output.status, log: log, capture: combinedOutput) }
}
if action == .rebuild { try invoke(settings.cleanTarget) }
try invoke(chosenTarget)
let products = try CMOCProject.files(in: workspace)
let builtSupport = try CMOCProject(directory: workspace, configuration: settings).supportSnapshot()
guard builtSupport == support else {
throw CMOCBuildError.validation(message: "The build modified its build-support files; source and recipe identity no longer match.", log: log, capture: combinedOutput)
}
guard try supportProject.supportSnapshot() == support else {
throw CMOCBuildError.validation(message: "Build-support files changed during the build. Rebuild the current project before running.", log: log, capture: combinedOutput)
}
for (path, bytes) in libraryPayload where products[path] != bytes {
throw CMOCBuildError.validation(message: "The build modified a bundled-library copy: \(path). Bundled libraries are prebuilt; keep library rebuild rules separate.", log: log, capture: combinedOutput)
}
for (path, data) in inputs {
guard products[path] == data else {
throw CMOCBuildError.validation(message: "The build modified \(path); its editor and source locations no longer match. Generate derived files under a separate name.", log: log, capture: combinedOutput)
}
}
// Custom targets can be utilities. Only normal/disk builds promise declared products.
let requiresProducts = action == .build || action == .rebuild || action == .disk
var binaryPath: String?, diskPath: String?
var playtestDiskProducts: [CMOCPlaytestDiskProduct] = []
if action != .clean && action != .custom {
if let path = settings.binary, let data = products[path], !data.isEmpty { binaryPath = path }
else if requiresProducts && settings.binary != nil { throw CMOCBuildError.validation(message: "Make succeeded but did not produce \(settings.binary!). Set Binary output in Project Settings to the executable created by this Makefile, or leave it empty for a build-only project.", log: log, capture: combinedOutput) }
if let path = settings.diskImage, let data = products[path], !data.isEmpty { diskPath = path }
else if action == .disk || (requiresProducts && settings.launchMode == .disk) {
throw CMOCBuildError.validation(message: "Make succeeded but did not produce the configured disk image.", log: log, capture: combinedOutput)
}
}
if requiresProducts {
for path in settings.playtestDisks {
guard let data = products[path], (1...CMOCPlaytestDiskProduct.maximumBytes).contains(data.count) else {
throw CMOCBuildError.validation(message: "Make succeeded but did not produce the declared playtest disk \(path) as a nonempty output of at most 512 KiB.", log: log, capture: combinedOutput)
}
playtestDiskProducts.append(CMOCPlaytestDiskProduct(relativePath: path,
sha256: CMOCProject.sha256(data), byteCount: data.count))
}
}
var exportProducts: [CMOCBuildOutputProduct] = []
if requiresProducts {
let declared = [binaryPath, diskPath, settings.debugManifest.flatMap { products[$0] == nil ? nil : $0 }].compactMap { $0 } + settings.playtestDisks + settings.exportOutputs
var total = 0
for path in declared {
guard let data = products[path], data.count <= CMOCProject.maximumFileBytes,
total <= 128 * 1024 * 1024 - data.count else {
throw CMOCBuildError.validation(message: "Make did not produce a bounded declared delivery file: " + path, log: log, capture: combinedOutput)
}
total += data.count
exportProducts.append(CMOCBuildOutputProduct(relativePath: path, byteCount: data.count, sha256: CMOCProject.sha256(data)))
}
}
try control.checkCancellation(log: log)
let id = UUID()
let result = buildRoot.appendingPathComponent(id.uuidString)
try manager.createDirectory(at: result, withIntermediateDirectories: true)
var frozen = false
defer { if !frozen { try? manager.removeItem(at: result) } }
for (path, data) in products {
try control.checkCancellation(log: log)
let url = result.appendingPathComponent(path)
try manager.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
try data.write(to: url, options: .atomic)
}
let projectHashes = inputs.mapValues(CMOCProject.sha256)
let hashes = projectHashes.merging(support.hashes) { first, _ in first }
try JSONEncoder().encode(projectHashes).write(to: indexURL, options: .atomic)
let physicalResult = try CMOCProject.physicalURL(result), physicalWorkspace = try CMOCProject.physicalURL(workspace)
let sources = products.filter { CMOCProject.isSource($0.key) && String(data: $0.value, encoding: .utf8) != nil && !$0.value.contains(0) }
let artifact = CMOCBuildArtifact(id: id, directory: physicalResult, source: entryText, sourceData: entry,
sourceSHA256: CMOCProject.sha256(entry), binaryData: binaryPath.flatMap { products[$0] } ?? Data(), buildLog: log,
sources: sources, fileHashes: hashes, compilationDirectory: physicalWorkspace, entrySourcePath: settings.entrySource,
binaryRelativePath: binaryPath, diskRelativePath: diskPath, outputPaths: products.keys.sorted(), configurationName: name, action: action,
debugManifestRelativePath: settings.debugManifest,
diskSHA256: diskPath.flatMap { products[$0] }.map(CMOCProject.sha256), buildOutput: combinedOutput,
playtestDiskProducts: playtestDiskProducts, exportProducts: exportProducts)
try buildHistory.record(artifact, project: project.directory)
frozen = true; succeeded = true
return artifact
}
private func buildSynchronously(project: CMOCProject, source: String, control: DevelopmentProcessControl) throws -> CMOCBuildArtifact {
let sourceData = try CMOCProject.sourceBytes(source)
let makefile = try CMOCProject.readText(project.makefileURL, maximumBytes: CMOCProject.maximumMakefileBytes)
let bin = toolchain.appendingPathComponent("bin")
for name in Self.requiredExecutables {
guard FileManager.default.isExecutableFile(atPath: bin.appendingPathComponent(name).path) else {
throw CMOCBuildError.message("The development toolchain is unavailable (missing \(name)). This build needs the bundled CMOC tools.")
}
}
try control.checkCancellation()
let id = UUID()
let directory = buildRoot.appendingPathComponent(id.uuidString)
try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
var succeeded = false
defer { if !succeeded { try? FileManager.default.removeItem(at: directory) } }
try sourceData.write(to: directory.appendingPathComponent("main.c"), options: .atomic)
try Data(makefile.utf8).write(to: directory.appendingPathComponent("Makefile"), options: .atomic)
var environment = ProcessInfo.processInfo.environment
// Deliberately exclude Homebrew and developer-tool paths from runtime lookup.
environment["PATH"] = bin.path + ":/usr/bin:/bin"
environment["CMOC"] = bin.appendingPathComponent("cmoc").path
environment["LC_ALL"] = "C"
environment.removeValue(forKey: "MAKEFLAGS")
environment.removeValue(forKey: "MFLAGS")
environment.removeValue(forKey: "MAKELEVEL")
for key in ["GNUMAKEFLAGS", "PERL5LIB", "PERLLIB", "PERL5OPT"] { environment.removeValue(forKey: key) }
let output = try control.run(executable: bin.appendingPathComponent("make"), arguments: ["--no-print-directory", "-f", "Makefile", "MAKE=make", "--"] + (project.configuration.buildTarget.isEmpty ? [] : [project.configuration.buildTarget]), directory: directory, environment: environment, timeout: timeout)
try control.checkCancellation(log: output.text)
guard output.status == 0 else { throw CMOCBuildError.failed(status: output.status, log: output.text, capture: control.capturedOutput) }
// A successful Makefile must produce all matching artifacts, not reuse an
// old executable. The fresh directory prevents stale-build fallback.
for name in ["main.bin", "main.o", "main.s", "main.lst", "main.map", "main.link"] {
let url = directory.appendingPathComponent(name)
let info = try? url.resourceValues(forKeys: [.isRegularFileKey, .isSymbolicLinkKey, .fileSizeKey])
guard info?.isRegularFile == true, info?.isSymbolicLink != true,
let size = info?.fileSize, size > 0, size <= 8 * 1024 * 1024 else {
throw CMOCBuildError.validation(message: "The build did not produce a valid \(name). Keep --intermediate enabled in the Makefile.", log: output.text, capture: control.capturedOutput)
}
}
// Protect mapping from a Makefile which rewrites its input before compiling.
guard try Data(contentsOf: directory.appendingPathComponent("main.c")) == sourceData else {
throw CMOCBuildError.validation(message: "The build modified main.c; its source locations cannot be verified.", log: output.text, capture: control.capturedOutput)
}
let binary = try Data(contentsOf: directory.appendingPathComponent("main.bin"))
// mcpp records the physical working directory (for example /private/tmp,
// not its /tmp symlink). Keep the exact snapshot identity for source maps.
guard let physicalPath = realpath(directory.path, nil) else {
throw CMOCBuildError.validation(message: "The build output folder could not be resolved.", log: output.text, capture: control.capturedOutput)
}
let physicalDirectory = URL(fileURLWithPath: String(cString: physicalPath), isDirectory: true)
free(physicalPath)
let artifact = CMOCBuildArtifact(id: id, directory: physicalDirectory, source: source,
sourceData: sourceData, sourceSHA256: CMOCProject.sha256(sourceData), binaryData: binary, buildLog: output.text, buildOutput: control.capturedOutput,
exportProducts: [CMOCBuildOutputProduct(relativePath: "main.bin", byteCount: binary.count, sha256: CMOCProject.sha256(binary))])
try control.checkCancellation()
try buildHistory.record(artifact, project: project.directory)
succeeded = true
return artifact
}
}
/// A separate process group lets cancellation stop make and its compiler children.
/// One pipe merges stdout/stderr; draining continues even after the retained log
/// reaches its cap, so compiler output cannot deadlock a full pipe.
final class DevelopmentProcessControl: @unchecked Sendable {
private let lock = NSLock()
private var pid: pid_t = 0
private var cancelled = false
private var timedOut = false
private static let maximumOutput = 512 * 1024
private var lastOutput: CMOCBuildOutput?
var capturedOutput: CMOCBuildOutput? {
lock.lock(); defer { lock.unlock() }
return lastOutput
}
func cancel(timedOut: Bool = false) {
lock.lock()
if timedOut && pid == 0 { lock.unlock(); return }
cancelled = true; self.timedOut = self.timedOut || timedOut
let current = pid
if current > 0 { Darwin.kill(-current, SIGTERM) }
lock.unlock()
if current > 0 {
DispatchQueue.global().asyncAfter(deadline: .now() + 0.5) { [weak self] in
guard let self else { return }
self.lock.lock(); defer { self.lock.unlock() }
if self.pid == current { Darwin.kill(-current, SIGKILL) }
}
}
}
func checkCancellation(log: String = "", capture: CMOCBuildOutput? = nil, exitCode: Int32? = nil) throws {
lock.lock(); let stop = cancelled, expired = timedOut; lock.unlock()
if expired { throw CMOCBuildError.timedOut(log: log, capture: capture, exitCode: exitCode) }
if stop { throw CancellationError() }
}
func run(executable: URL, arguments: [String], directory: URL, environment: [String: String], timeout: TimeInterval) throws -> (status: Int32, text: String) {
try checkCancellation()
var descriptors: [Int32] = [0, 0]
guard pipe(&descriptors) == 0 else { throw POSIXError(.EIO) }
var reader = descriptors[0], writer = descriptors[1]
defer { if reader >= 0 { close(reader) }; if writer >= 0 { close(writer) } }
var actions: posix_spawn_file_actions_t?
var attributes: posix_spawnattr_t?
guard posix_spawn_file_actions_init(&actions) == 0 else { throw POSIXError(.ENOMEM) }
defer { posix_spawn_file_actions_destroy(&actions) }
guard posix_spawnattr_init(&attributes) == 0 else { throw POSIXError(.ENOMEM) }
defer { posix_spawnattr_destroy(&attributes) }
posix_spawn_file_actions_adddup2(&actions, writer, STDOUT_FILENO)
posix_spawn_file_actions_adddup2(&actions, writer, STDERR_FILENO)
posix_spawn_file_actions_addclose(&actions, reader)
posix_spawn_file_actions_addclose(&actions, writer)
posix_spawn_file_actions_addopen(&actions, STDIN_FILENO, "/dev/null", O_RDONLY, 0)
let changeDirectory: Int32
if #available(macOS 26.0, *) {
changeDirectory = posix_spawn_file_actions_addchdir(&actions, directory.path)
} else {
changeDirectory = posix_spawn_file_actions_addchdir_np(&actions, directory.path)
}
guard changeDirectory == 0 else { throw POSIXError(POSIXErrorCode(rawValue: changeDirectory) ?? .EINVAL) }
posix_spawnattr_setflags(&attributes, Int16(POSIX_SPAWN_SETPGROUP))
posix_spawnattr_setpgroup(&attributes, 0)
let argv = ([executable.path] + arguments).map { strdup($0) } + [nil]
let envp = environment.sorted(by: { $0.key < $1.key }).map { strdup($0.key + "=" + $0.value) } + [nil]
defer { argv.forEach { free($0) }; envp.forEach { free($0) } }
var child: pid_t = 0
lock.lock()
if cancelled { lock.unlock(); try checkCancellation(); throw CancellationError() }
let result = argv.withUnsafeBufferPointer { a in envp.withUnsafeBufferPointer { e in
posix_spawn(&child, executable.path, &actions, &attributes, a.baseAddress!, e.baseAddress!)
} }
if result == 0 { pid = child }
lock.unlock()
guard result == 0 else { throw POSIXError(POSIXErrorCode(rawValue: result) ?? .EIO) }
close(writer); writer = -1
let deadline = DispatchWorkItem { [weak self] in self?.cancel(timedOut: true) }
DispatchQueue.global().asyncAfter(deadline: .now() + timeout, execute: deadline)
defer { deadline.cancel() }
var beginning = Data(), ending = Data(), total = 0
let firstLimit = Self.maximumOutput / 2, lastLimit = Self.maximumOutput - firstLimit
var buffer = [UInt8](repeating: 0, count: 8192)
while true {
let count = Darwin.read(reader, &buffer, buffer.count)
if count == 0 { break }
if count < 0 { if errno == EINTR { continue }; break }
total += count
let keep = min(count, max(0, firstLimit - beginning.count))
if keep > 0 { beginning.append(contentsOf: buffer.prefix(keep)) }
if count > keep {
ending.append(contentsOf: buffer[keep.. lastLimit { ending = Data(ending.suffix(lastLimit)) }
}
}
close(reader); reader = -1
var status: Int32 = 0
while waitpid(child, &status, 0) < 0 { if errno != EINTR { break } }
lock.lock(); pid = 0; lock.unlock()
let clipped = total > beginning.count + ending.count
let text: String
if clipped {
text = String(decoding: beginning, as: UTF8.self)
+ "\n[Build output truncated at 512 KB; \(total - beginning.count - ending.count) process bytes omitted between beginning and end.]\n"
+ String(decoding: ending, as: UTF8.self)
} else {
// The retention split may be in the middle of a UTF-8 scalar.
// Decode contiguous, untruncated output as one byte sequence.
text = String(decoding: beginning + ending, as: UTF8.self)
}
// Invalid process bytes can expand while decoding. Bound the rendered
// UTF-8 as well, and keep the late linker/Make failure visible.
let bounded = CMOCBoundedBuildLog.limit(text, maximumBytes: Self.maximumOutput)
let capture = CMOCBuildOutput(text: bounded.text, byteCount: total, truncated: clipped || bounded.truncated,
workingDirectory: directory, invocation: [executable.path] + arguments,
exitCode: status & 0x7f == 0 ? (status >> 8) & 0xff : 128 + (status & 0x7f))
lock.lock(); lastOutput = capture; lock.unlock()
// POSIX exit status encoding, including a recognizable signal failure.
let exitStatus = capture.exitCode!
try checkCancellation(log: capture.text, capture: capture, exitCode: exitStatus)
return (exitStatus, capture.text)
}
}