feat! Breaking API changes of NeCTI's LibCompiler and LibDebugger.

what:

- They've now become CompilerKit and DebuggerKit.
- Expanding XCoff for NeBoot PowerPC backend.

Signed-off-by: Amlal El Mahrouss <amlal@nekernel.org>

10 files changed, 569 insertions, 0 deletions

diff --git a/dev/DebuggerKit/CommonCLI.inl b/dev/DebuggerKit/CommonCLI.inl
new file mode 100644
index 0000000..325be23
--- /dev/null
+++ b/dev/DebuggerKit/CommonCLI.inl
@@ -0,0 +1,28 @@
+/***
+  DebuggerKit
+  (C) 2025 Amlal El Mahrouss
+  File: CommonCLI.inl
+  Purpose: Common Debugger symbols.
+*/
+
+#include <cstdint>
+#include <iostream>
+#include <string>
+
+#define kBlank "\e[0;30m"
+#define kRed "\e[0;31m"
+#define kWhite "\e[0;97m"
+
+#define kStdOut (std::cout << kRed << "dbg: " << kWhite)
+
+static BOOL kKeepRunning = false;
+
+#ifdef LD_NEKERNEL_DEBUGGER
+static DebuggerKit::NeKernel::NeKernelContract kKernelDebugger;
+#else
+static DebuggerKit::POSIX::POSIXMachContract kDebugger;
+#endif
+
+static DebuggerKit::ProcessID kPID           = 0L;
+static DebuggerKit::CAddress  kActiveAddress = nullptr;
+static std::string            kPath          = "";
diff --git a/dev/DebuggerKit/DebuggerContract.h b/dev/DebuggerKit/DebuggerContract.h
new file mode 100644
index 0000000..48c3603
--- /dev/null
+++ b/dev/DebuggerKit/DebuggerContract.h
@@ -0,0 +1,44 @@
+/***
+  (C) 2025 Amlal El Mahrouss
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <unordered_map>
+
+namespace DebuggerKit {
+class DebuggerContract;
+
+/// \brief Process ID
+typedef uint64_t ProcessID;
+
+/// \brief Address type, a la BSD.
+typedef char* CAddress;
+
+/// \brief Debugger contract class in C++, as per the design states.
+/// \author Amlal El Mahrouss
+class DebuggerContract {
+ public:
+  explicit DebuggerContract() = default;
+  virtual ~DebuggerContract() = default;
+
+ public:
+  DebuggerContract& operator=(const DebuggerContract&) = default;
+  DebuggerContract(const DebuggerContract&)            = default;
+
+ public:
+  virtual bool Attach(std::string path, std::string argv, ProcessID& pid) noexcept = 0;
+  virtual bool BreakAt(std::string symbol) noexcept                                = 0;
+  virtual bool Break() noexcept                                                    = 0;
+  virtual bool Continue() noexcept                                                 = 0;
+  virtual bool Detach() noexcept                                                   = 0;
+
+  virtual std::unordered_map<uintptr_t, uintptr_t>& Get() { return m_breakpoints; }
+
+ protected:
+  ProcessID                                m_pid;
+  std::unordered_map<uintptr_t, uintptr_t> m_breakpoints;
+};
+}  // namespace DebuggerKit
diff --git a/dev/DebuggerKit/NeKernelContract.h b/dev/DebuggerKit/NeKernelContract.h
new file mode 100644
index 0000000..9797639
--- /dev/null
+++ b/dev/DebuggerKit/NeKernelContract.h
@@ -0,0 +1,47 @@
+
+/***
+  (C) 2025 Amlal El Mahrouss
+ */
+
+#ifndef LD_NEKERNEL_CONTRACT_H
+#define LD_NEKERNEL_CONTRACT_H
+
+#ifdef LD_NEKERNEL_DEBUGGER
+
+#include <DebuggerKit/DebuggerContract.h>
+
+namespace DebuggerKit::NeKernel {
+class NeKernelContract;
+
+namespace Detail {
+  inline constexpr size_t kDebugCmdLen = 256U;
+  typedef char            rt_debug_cmd[kDebugCmdLen];
+}  // namespace Detail
+
+class NeKernelContract : public DebuggerContract {
+ public:
+  NeKernelContract();
+  ~NeKernelContract() override;
+
+ public:
+  NeKernelContract& operator=(const NeKernelContract&) = default;
+  NeKernelContract(const NeKernelContract&)            = default;
+
+  // Override additional methods from DebuggerContract
+
+ public:
+  bool Attach(std::string path, std::string arg_v, ProcessID& pid) noexcept override;
+  bool BreakAt(std::string symbol) noexcept override;
+  bool Break() noexcept override;
+  bool Continue() noexcept override;
+  bool Detach() noexcept override;
+
+ private:
+  std::string m_kernel_path;
+  int64_t     m_socket{0};
+};
+}  // namespace DebuggerKit::NeKernel
+
+#endif  // ifdef LD_NEKERNEL_DEBUGGER
+
+#endif  // LD_NEKERNEL_CONTRACT_H
\ No newline at end of file
diff --git a/dev/DebuggerKit/POSIXMachContract.h b/dev/DebuggerKit/POSIXMachContract.h
new file mode 100644
index 0000000..a2c49ce
--- /dev/null
+++ b/dev/DebuggerKit/POSIXMachContract.h
@@ -0,0 +1,158 @@
+/***
+  (C) 2025 Amlal El Mahrouss
+ */
+
+#pragma once
+
+#ifdef LD_MACH_DEBUGGER
+
+/// @file POSIXMachContract.h
+/// @brief POSIX Mach debugger.
+
+#include <CompilerKit/Defines.h>
+#include <DebuggerKit/DebuggerContract.h>
+
+#include <stdint.h>
+#include <sys/ptrace.h>
+#include <sys/types.h>
+#include <sys/user.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+#include <filesystem>
+#include <iostream>
+
+#include <dlfcn.h>
+#include <mach-o/dyld.h>
+#include <mach/mach.h>
+#include <mach/mach_error.h>
+#include <signal.h>
+
+LC_IMPORT_C kern_return_t mach_vm_write(vm_map_t target_task, mach_vm_address_t address,
+                                        vm_offset_t data, mach_msg_type_number_t dataCnt);
+
+LC_IMPORT_C kern_return_t mach_vm_protect(vm_map_t target_task, mach_vm_address_t address,
+                                          mach_vm_size_t size, boolean_t set_maximum,
+                                          vm_prot_t new_protection);
+
+#define PTRACE_ATTACH PT_ATTACHEXC
+#define PTRACE_DETACH PT_DETACH
+#define PTRACE_POKETEXT PT_WRITE_I
+#define PTRACE_CONT PT_CONTINUE
+#define PTRACE_PEEKTEXT PT_READ_I
+
+namespace DebuggerKit::POSIX {
+/// \brief POSIXMachContract engine interface class in C++
+/// \author Amlal El Mahrouss
+class POSIXMachContract : public DebuggerContract {
+ public:
+  explicit POSIXMachContract()  = default;
+  ~POSIXMachContract() override = default;
+
+ public:
+  POSIXMachContract& operator=(const POSIXMachContract&) = default;
+  POSIXMachContract(const POSIXMachContract&)            = default;
+
+ public:
+  BOOL Attach(std::string path, std::string argv, ProcessID& pid) noexcept override {
+    pid = fork();
+
+    if (pid == 0) {
+      if (argv.empty()) {
+        ptrace(PT_TRACE_ME, 0, nullptr, 0);
+        kill(getpid(), SIGSTOP);
+      }
+
+      std::vector<char*> argv_arr;
+
+      argv_arr.push_back(const_cast<char*>(path.c_str()));
+      argv_arr.push_back(const_cast<char*>(argv.c_str()));
+      argv_arr.push_back(nullptr);
+
+      execv(path.c_str(), argv_arr.data());
+
+      _exit(1);
+    }
+
+    m_path = path;
+    m_pid  = pid;
+
+    pid = this->m_pid;
+
+    return true;
+  }
+
+  void SetPath(std::string path) noexcept {
+    if (path.empty()) {
+      return;
+    }
+
+    m_path = path;
+  }
+
+  BOOL BreakAt(std::string symbol) noexcept override {
+    if (!m_path.empty() && std::filesystem::exists(m_path) &&
+        std::filesystem::is_regular_file(m_path)) {
+      auto handle = dlopen(m_path.c_str(), RTLD_LAZY);
+
+      if (handle == nullptr) {
+        return false;
+      }
+
+      auto addr = dlsym(handle, symbol.c_str());
+
+      if (addr == nullptr) {
+        return false;
+      }
+
+      task_read_t task;
+      task_for_pid(mach_task_self(), m_pid, &task);
+
+      uint32_t brk_inst = 0xD43E0000;
+
+      mach_vm_protect(task, (mach_vm_address_t) addr, sizeof(uint32_t), false,
+                      VM_PROT_READ | VM_PROT_WRITE | VM_PROT_EXECUTE);
+      mach_vm_write(task, (mach_vm_address_t) addr, (vm_offset_t) &brk_inst, sizeof(addr));
+
+      return true;
+    }
+
+    return false;
+  }
+
+  BOOL Break() noexcept override {
+    task_read_t task;
+    task_for_pid(mach_task_self(), m_pid, &task);
+
+    kern_return_t ret = task_suspend(task);
+
+    return ret == KERN_SUCCESS;
+  }
+
+  BOOL Continue() noexcept override {
+    task_read_t task;
+    task_for_pid(mach_task_self(), m_pid, &task);
+
+    kern_return_t ret = task_resume(task);
+
+    return ret == KERN_SUCCESS;
+  }
+
+  BOOL Detach() noexcept override {
+    this->Continue();
+
+    task_read_t task;
+    task_for_pid(mach_task_self(), m_pid, &task);
+
+    kern_return_t kr = mach_port_deallocate(mach_task_self(), task);
+
+    return kr = KERN_SUCCESS;
+  }
+
+ private:
+  ProcessID   m_pid{0};
+  std::string m_path;
+};
+}  // namespace DebuggerKit::POSIX
+
+#endif
diff --git a/dev/DebuggerKit/Version.h b/dev/DebuggerKit/Version.h
new file mode 100644
index 0000000..4159191
--- /dev/null
+++ b/dev/DebuggerKit/Version.h
@@ -0,0 +1,15 @@
+/* -------------------------------------------
+
+  Copyright (C) 2025 Amlal EL Mahrouss, all rights reserved
+
+------------------------------------------- */
+
+#pragma once
+
+#define kDistVersion "v0.0.1-libdebugger"
+#define kDistVersionBCD 0x0001
+
+#define ToString(X) Stringify(X)
+#define Stringify(X) #X
+
+#define kDistRelease ToString(kDistReleaseBranch)
diff --git a/dev/DebuggerKit/ld-nekernel.json b/dev/DebuggerKit/ld-nekernel.json
new file mode 100644
index 0000000..d2aeb24
--- /dev/null
+++ b/dev/DebuggerKit/ld-nekernel.json
@@ -0,0 +1,17 @@
+{
+  "compiler_path": "g++",
+  "compiler_std": "c++20",
+  "headers_path": [
+    "../DebuggerKit",
+    "../"
+  ],
+  "sources_path": ["src/*.cc"],
+  "output_name": "/usr/local/lib/libDebuggerKit.dylib",
+  "compiler_flags": ["-fPIC", "-shared"],
+  "cpp_macros": [
+    "__LIBCOMPILER__=202505",
+    "LC_USE_STRUCTS=1",
+    "LD_NEKERNEL_DEBUGGER",
+    "kDistReleaseBranch=$(git rev-parse --abbrev-ref HEAD)-$(uuidgen)"
+  ]
+}
diff --git a/dev/DebuggerKit/ld-osx.json b/dev/DebuggerKit/ld-osx.json
new file mode 100644
index 0000000..75b6cd8
--- /dev/null
+++ b/dev/DebuggerKit/ld-osx.json
@@ -0,0 +1,17 @@
+{
+  "compiler_path": "clang++",
+  "compiler_std": "c++20",
+  "headers_path": [
+    "../DebuggerKit",
+    "../"
+  ],
+  "sources_path": ["src/*.cc"],
+  "output_name": "/usr/local/lib/libDebuggerKit.dylib",
+  "compiler_flags": ["-fPIC", "-shared"],
+  "cpp_macros": [
+    "__LIBCOMPILER__=202505",
+    "LC_USE_STRUCTS=1",
+    "LD_MACH_DEBUGGER",
+    "kDistReleaseBranch=$(git rev-parse --abbrev-ref HEAD)-$(uuidgen)"
+  ]
+}
diff --git a/dev/DebuggerKit/src/NeKernelContract.cc b/dev/DebuggerKit/src/NeKernelContract.cc
new file mode 100644
index 0000000..d7a0393
--- /dev/null
+++ b/dev/DebuggerKit/src/NeKernelContract.cc
@@ -0,0 +1,48 @@
+/***
+  DebuggerKit
+  (C) 2025 Amlal El Mahrouss
+  File: NeKernelContract.cc
+  Purpose: NeKernel Debugger
+*/
+
+#ifdef LD_NEKERNEL_DEBUGGER
+
+#include <CompilerKit/Defines.h>
+#include <DebuggerKit/NeKernelContract.h>
+#include <ThirdParty/Dialogs.h>
+
+#include <sys/socket.h>
+#include <sys/types.h>
+#include <sys/un.h>
+#include <unistd.h>
+
+constexpr static UInt16 kDebugPort = 51820;
+
+using namespace DebuggerKit::NeKernel;
+
+NeKernelContract::NeKernelContract() = default;
+
+NeKernelContract::~NeKernelContract() = default;
+
+BOOL NeKernelContract::Attach(CompilerKit::STLString path, CompilerKit::STLString argv,
+                              ProcessID& pid) noexcept {
+  return NO;
+}
+
+BOOL NeKernelContract::BreakAt(CompilerKit::STLString symbol) noexcept {
+  return NO;
+}
+
+BOOL NeKernelContract::Break() noexcept {
+  return NO;
+}
+
+BOOL NeKernelContract::Continue() noexcept {
+  return NO;
+}
+
+BOOL NeKernelContract::Detach() noexcept {
+  return NO;
+}
+
+#endif  // LD_NEKERNEL_DEBUGGER
\ No newline at end of file
diff --git a/dev/DebuggerKit/src/NeKernelContractCLI.cc b/dev/DebuggerKit/src/NeKernelContractCLI.cc
new file mode 100644
index 0000000..9d078c8
--- /dev/null
+++ b/dev/DebuggerKit/src/NeKernelContractCLI.cc
@@ -0,0 +1,101 @@
+/***
+  DebuggerKit
+  (C) 2025 Amlal El Mahrouss
+  File: NeKernelContract.cc
+  Purpose: NeKernel Debugger CLI.
+*/
+
+#ifdef LD_NEKERNEL_DEBUGGER
+
+#include <CompilerKit/Defines.h>
+#include <DebuggerKit/NeKernelContract.h>
+#include <ThirdParty/Dialogs.h>
+#include <string>
+
+#include <DebuggerKit/CommonCLI.inl>
+
+using namespace DebuggerKit::NeKernel;
+
+static void dbgi_ctrlc_handler(std::int32_t _) {
+  if (!kPID || kPath.empty()) {
+    return;
+  }
+
+  kKernelDebugger.Break();
+
+  pfd::notify("Debugger Event", "Breakpoint hit!");
+
+  kKeepRunning = false;
+}
+
+LIBCOMPILER_MODULE(DebuggerNeKernel) {
+  pfd::notify("Debugger Event",
+              "NeKernel Debugger\n(C) 2025 Amlal El Mahrouss and NeKernel.org contributors, all rights reserved.");
+
+  if (argc >= 5 && std::string(argv[1]) == "-k" && argv[2] != nullptr &&
+      std::string(argv[3]) == "-ip" && argv[4] != nullptr) {
+    kPath = argv[2];
+    kPath += ":";
+    kPath += argv[4];
+
+    kStdOut << "[+] KIP (Kernel:IP) set to: " << kPath << "\n";
+
+    CompilerKit::install_signal(SIGINT, dbgi_ctrlc_handler);
+
+    kKernelDebugger.Attach(kPath, "", kPID);
+    kKernelDebugger.BreakAt("$HANDOVER_START");
+
+    while (YES) {
+      if (kKeepRunning) {
+        continue;
+      }
+
+      std::string cmd;
+      if (!std::getline(std::cin, cmd)) break;
+
+      if (cmd == "c" || cmd == "cont" || cmd == "continue") {
+        if (kKernelDebugger.Continue()) {
+          kKeepRunning = true;
+
+          kStdOut << "[+] Continuing...\n";
+
+          pfd::notify("Debugger Event", "Continuing...");
+        }
+      }
+
+      if (cmd == "d" || cmd == "detach") kKernelDebugger.Detach();
+
+      if (cmd == "start") {
+        kStdOut << "[?] Enter a argument to use: ";
+        std::getline(std::cin, cmd);
+
+        kKernelDebugger.Attach(kPath, cmd, kPID);
+      }
+
+      if (cmd == "exit") {
+        if (kPID > 0) kKernelDebugger.Detach();
+
+        break;
+      }
+
+      if (cmd == "break" || cmd == "b") {
+        kStdOut << "[?] Enter a symbol to break on: ";
+
+        std::getline(std::cin, cmd);
+
+        if (kKernelDebugger.BreakAt(cmd)) {
+          pfd::notify("Debugger Event", "Add BreakAt at: " + cmd);
+        }
+      }
+    }
+
+    return EXIT_SUCCESS;
+  }
+
+  kStdOut << "usage: " << argv[0] << " -k <kernel_path> -ip <ip4>\n";
+  kStdOut << "example: " << argv[0] << " -k /path/to/ne_kernel -ip 127.0.0.1\n";
+
+  return EXIT_FAILURE;
+}
+
+#endif  // LD_NEKERNEL_DEBUGGER
\ No newline at end of file
diff --git a/dev/DebuggerKit/src/POSIXMachContractCLI.cc b/dev/DebuggerKit/src/POSIXMachContractCLI.cc
new file mode 100644
index 0000000..11c05f8
--- /dev/null
+++ b/dev/DebuggerKit/src/POSIXMachContractCLI.cc
@@ -0,0 +1,94 @@
+/***
+  DebuggerKit
+  (C) 2025 Amlal El Mahrouss
+  File: POSIXMachContract.cc
+  Purpose: OS X/Darwin Debugger
+*/
+
+#ifdef LD_MACH_DEBUGGER
+
+#include <CompilerKit/Defines.h>
+#include <DebuggerKit/POSIXMachContract.h>
+#include <ThirdParty/Dialogs.h>
+#include <DebuggerKit/CommonCLI.inl>
+
+/// @internal
+/// @brief Handles CTRL-C signal on debugger.
+static void dbgi_ctrlc_handler(std::int32_t _) {
+  if (!kPID) {
+    return;
+  }
+
+  kDebugger.Break();
+
+  pfd::notify("Debugger Event", "Breakpoint hit!");
+
+  kKeepRunning = false;
+}
+
+LIBCOMPILER_MODULE(DebuggerMachPOSIX) {
+  pfd::notify("Debugger Event",
+              "Userland Debugger\n(C) 2025 Amlal El Mahrouss, all rights reserved.");
+
+  if (argc >= 3 && std::string(argv[1]) == "-p" && argv[2] != nullptr) {
+    kPath = argv[2];
+    kDebugger.SetPath(kPath);
+
+    kStdOut << "[+] Image set to: " << kPath << "\n";
+  } else {
+    kStdOut << "usage: " << argv[0] << " -p <path>\n";
+    kStdOut << "example: " << argv[0] << " -p /path/to/program\n";
+
+    return EXIT_FAILURE;
+  }
+
+  CompilerKit::install_signal(SIGINT, dbgi_ctrlc_handler);
+
+  while (YES) {
+    if (kKeepRunning) {
+      continue;
+    }
+
+    std::string cmd;
+    if (!std::getline(std::cin, cmd)) break;
+
+    if (cmd == "c" || cmd == "cont" || cmd == "continue") {
+      if (kDebugger.Continue()) {
+        kKeepRunning = true;
+
+        kStdOut << "[+] Continuing...\n";
+
+        pfd::notify("Debugger Event", "Continuing...");
+      }
+    }
+
+    if (cmd == "d" || cmd == "detach") kDebugger.Detach();
+
+    if (cmd == "start") {
+      kStdOut << "[?] Enter a argument to use: ";
+      std::getline(std::cin, cmd);
+
+      kDebugger.Attach(kPath, cmd, kPID);
+    }
+
+    if (cmd == "exit") {
+      if (kPID > 0) kDebugger.Detach();
+
+      break;
+    }
+
+    if (cmd == "break" || cmd == "b") {
+      kStdOut << "[?] Enter a symbol to break on: ";
+
+      std::getline(std::cin, cmd);
+
+      if (kDebugger.BreakAt(cmd)) {
+        pfd::notify("Debugger Event", "Add BreakAt at: " + cmd);
+      }
+    }
+  }
+
+  return EXIT_SUCCESS;
+}
+
+#endif
\ No newline at end of file