Restructure the library layers

src/os/allocators/arena/mem_arena.c

@@ -0,0 +1,146 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "mem_arena.h"
+#include "../../mem/mem_os.h"
+#include "../../../common/aliases/aliases.h"
+#include "../../../common/assert/assert.h"
+#include "../../../common/misc/misc_utils.h"
+#include "../../../base/mem/utils/mem_utils.h"
+#include <stdlib.h>
+#include <string.h>
+
+#ifndef DEFAULT_ALIGNMENT
+// Why 2 * sizeof(void *) instead of sizeof(void *)
+// https://handmade.network/forums/t/6860-alignment_arena_allocator
+#define DEFAULT_ALIGNMENT (2 * sizeof(void *))
+#endif /* ifndef DEFAULT_ALIGNMENT */
+
+#define ARENA_MINIMUM_CAPACITY KB(16) // Allocate minimum of 4 pages
+
+struct arena {
+  u8 *buf;
+  u8 *offset;
+  u64 capacity;
+  b8 committed;
+
+#ifdef WAPP_PLATFORM_WINDOWS
+  wapp_misc_utils_padding_size(sizeof(u8 *) * 2 + sizeof(u64) + sizeof(b8));
+#endif // ifdef WAPP_PLATFORM_WINDOWS
+};
+
+b8 wapp_mem_arena_init_custom(Arena **arena, u64 base_capacity, MemAllocFlags flags, b8 zero_buffer) {
+  if (!arena || *arena || base_capacity == 0) {
+    return false;
+  }
+
+  *arena = (Arena *)calloc(1, sizeof(Arena));
+  Arena *arena_ptr = *arena;
+  if (!arena_ptr) {
+    return false;
+  }
+
+  u64 arena_capacity = wapp_misc_utils_u64_round_up_pow2(
+      base_capacity >= ARENA_MINIMUM_CAPACITY ?
+      base_capacity :
+      ARENA_MINIMUM_CAPACITY
+  );
+
+  arena_ptr->buf = (u8 *)wapp_mem_util_alloc(NULL, arena_capacity, WAPP_MEM_ACCESS_READ_WRITE, flags,
+                                             zero_buffer ? WAPP_MEM_INIT_INITIALISED : WAPP_MEM_INIT_UNINITIALISED);
+
+  if (!(arena_ptr->buf)) {
+    wapp_mem_arena_destroy(arena);
+    return false;
+  }
+
+  arena_ptr->capacity  = arena_capacity;
+  arena_ptr->offset    = arena_ptr->buf;
+  arena_ptr->committed = (flags & WAPP_MEM_ALLOC_COMMIT) == WAPP_MEM_ALLOC_COMMIT;
+
+  return true;
+}
+
+void *wapp_mem_arena_alloc(Arena *arena, u64 size) {
+  return wapp_mem_arena_alloc_aligned(arena, size, DEFAULT_ALIGNMENT);
+}
+
+void *wapp_mem_arena_alloc_aligned(Arena *arena, u64 size, u64 alignment) {
+  wapp_debug_assert(arena != NULL, "`arena` should not be NULL");
+
+  u8 *alloc_start = arena->offset;
+
+  u8 *output = wapp_mem_util_align_forward((void *)alloc_start, alignment);
+  if (output + size >= arena->buf + arena->capacity) {
+    return NULL;
+  }
+
+  arena->offset = output + size;
+
+#ifdef WAPP_PLATFORM_WINDOWS
+  if (!(arena->committed)) {
+    wapp_mem_util_alloc(alloc_start, (uptr)(arena->offset) - (uptr)(alloc_start),
+                        WAPP_MEM_ACCESS_READ_WRITE, WAPP_MEM_ALLOC_COMMIT,
+                        WAPP_MEM_INIT_UNINITIALISED);
+  }
+#endif // ifdef WAPP_PLATFORM_WINDOWS
+
+  memset(output, 0, size);
+
+  return (void *)output;
+}
+
+void *wapp_mem_arena_realloc(Arena *arena, void *ptr, u64 old_size, u64 new_size) {
+  if ((u8*)ptr < arena->buf || (u8*)ptr > arena->offset ||
+      arena->offset + new_size >= arena->buf + arena->capacity) {
+    return NULL;
+  }
+
+  void *new_ptr = wapp_mem_arena_alloc(arena, new_size);
+  if (!new_ptr) {
+    return NULL;
+  }
+
+  u64 copy_size = new_size <= old_size ? new_size : old_size;
+  memcpy(new_ptr, ptr, copy_size);
+
+  return new_ptr;
+}
+
+void *wapp_mem_arena_realloc_aligned(Arena *arena, void *ptr, u64 old_size, u64 new_size, u64 alignment) {
+  if ((u8*)ptr < arena->buf || (u8*)ptr > arena->offset ||
+      arena->offset + new_size >= arena->buf + arena->capacity) {
+    return NULL;
+  }
+
+  void *new_ptr = wapp_mem_arena_alloc_aligned(arena, new_size, alignment);
+  if (!new_ptr) {
+    return NULL;
+  }
+
+  u64 copy_size = new_size <= old_size ? new_size : old_size;
+  memcpy(new_ptr, ptr, copy_size);
+
+  return new_ptr;
+}
+
+void wapp_mem_arena_clear(Arena *arena) {
+  wapp_debug_assert(arena != NULL, "`arena` should not be NULL");
+
+  memset(arena->buf, 0, arena->offset - arena->buf);
+  arena->offset = arena->buf;
+}
+
+void wapp_mem_arena_destroy(Arena **arena) {
+  wapp_debug_assert(arena != NULL && (*arena) != NULL, "`arena` double pointer is not valid");
+
+  Arena *arena_ptr = *arena;
+  if (arena_ptr->buf) {
+    wapp_mem_util_free(arena_ptr->buf, arena_ptr->capacity);
+  }
+
+  arena_ptr->buf = arena_ptr->offset = NULL;
+  arena_ptr->capacity = 0;
+
+  free(*arena);
+  *arena = NULL;
+}

src/os/allocators/arena/mem_arena.h

@@ -0,0 +1,42 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef MEM_ARENA_H
+#define MEM_ARENA_H
+
+#include "../../mem/mem_os.h"
+#include "../../../common/aliases/aliases.h"
+#include "../../../common/platform/platform.h"
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+typedef struct arena Arena;
+
+#define wapp_mem_arena_init(arena_dptr, base_capacity)                         \
+  (wapp_mem_arena_init_custom(arena_dptr, base_capacity, WAPP_MEM_ALLOC_RESERVE, false))
+#define wapp_mem_arena_init_commit(arena_dptr, base_capacity)                  \
+  (wapp_mem_arena_init_custom(arena_dptr, base_capacity, WAPP_MEM_ALLOC_RESERVE | WAPP_MEM_ALLOC_COMMIT, false))
+#define wapp_mem_arena_init_zero(arena_dptr, base_capacity)                    \
+  (wapp_mem_arena_init_custom(arena_dptr, base_capacity, WAPP_MEM_ALLOC_RESERVE, true))
+#define wapp_mem_arena_init_commit_and_zero(arena_dptr, base_capacity)         \
+  (wapp_mem_arena_init_custom(arena_dptr, base_capacity, WAPP_MEM_ALLOC_RESERVE | WAPP_MEM_ALLOC_COMMIT, true))
+
+/**
+ * Arena initialisation function. `wapp_mem_arena_init_custom` provides the most
+ * control over how the Arena is initialised. Wrapper macros are provided for
+ * easier use.
+ */
+b8  wapp_mem_arena_init_custom(Arena **arena, u64 base_capacity, MemAllocFlags flags, b8 zero_buffer);
+void *wapp_mem_arena_alloc(Arena *arena, u64 size);
+void *wapp_mem_arena_alloc_aligned(Arena *arena, u64 size, u64 alignment);
+void *wapp_mem_arena_realloc(Arena *arena, void *ptr, u64 old_size, u64 new_size);
+void *wapp_mem_arena_realloc_aligned(Arena *arena, void *ptr, u64 old_size, u64 new_size, u64 alignment);
+void wapp_mem_arena_clear(Arena *arena);
+void wapp_mem_arena_destroy(Arena **arena);
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !MEM_ARENA_H

src/os/allocators/arena/mem_arena_allocator.c

@@ -0,0 +1,59 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "mem_arena_allocator.h"
+#include "mem_arena.h"
+#include "../../mem/mem_os.h"
+#include "../../../common/aliases/aliases.h"
+
+wapp_intern inline void *mem_arena_alloc(u64 size, void *alloc_obj);
+wapp_intern inline void *mem_arena_alloc_aligned(u64 size, u64 alignment, void *alloc_obj);
+wapp_intern inline void *mem_arena_realloc(void *ptr, u64 old_size, u64 new_size, void *alloc_obj);
+wapp_intern inline void *mem_arena_realloc_aligned(void *ptr, u64 old_size, u64 new_size, u64 alignment,
+                                                void *alloc_obj);
+
+
+Allocator wapp_mem_arena_allocator_init_custom(u64 base_capacity, MemAllocFlags flags, b8 zero_buffer) {
+  Allocator allocator = {0};
+  b8 initialised = wapp_mem_arena_init_custom((Arena **)(&allocator.obj), base_capacity, flags, zero_buffer);
+  if (!initialised) {
+    return allocator;
+  }
+
+  allocator.alloc           = mem_arena_alloc;
+  allocator.alloc_aligned   = mem_arena_alloc_aligned;
+  allocator.realloc         = mem_arena_realloc;
+  allocator.realloc_aligned = mem_arena_realloc_aligned;
+
+  return allocator;
+}
+
+void wapp_mem_arena_allocator_clear(Allocator *allocator) {
+  wapp_mem_arena_clear((Arena *)(allocator->obj));
+}
+
+void wapp_mem_arena_allocator_destroy(Allocator *allocator) {
+  wapp_mem_arena_destroy((Arena **)(&(allocator->obj)));
+  *allocator = (Allocator){0};
+}
+
+
+wapp_intern inline void *mem_arena_alloc(u64 size, void *alloc_obj) {
+  Arena *arena = (Arena *)alloc_obj;
+  return wapp_mem_arena_alloc(arena, size);
+}
+
+wapp_intern inline void *mem_arena_alloc_aligned(u64 size, u64 alignment, void *alloc_obj) {
+  Arena *arena = (Arena *)alloc_obj;
+  return wapp_mem_arena_alloc_aligned(arena, size, alignment);
+}
+
+wapp_intern inline void *mem_arena_realloc(void *ptr, u64 old_size, u64 new_size, void *alloc_obj) {
+  Arena *arena = (Arena *)alloc_obj;
+  return wapp_mem_arena_realloc(arena, ptr, old_size, new_size);
+}
+
+wapp_intern inline void *mem_arena_realloc_aligned(void *ptr, u64 old_size, u64 new_size, u64 alignment,
+                                                void *alloc_obj) {
+  Arena *arena = (Arena *)alloc_obj;
+  return wapp_mem_arena_realloc_aligned(arena, ptr, old_size, new_size, alignment);
+}

src/os/allocators/arena/mem_arena_allocator.h

@@ -0,0 +1,43 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef MEM_ARENA_ALLOCATOR_H
+#define MEM_ARENA_ALLOCATOR_H
+
+#include "../../mem/mem_os.h"
+#include "../../../common/aliases/aliases.h"
+#include "../../../common/platform/platform.h"
+#include "../../../base/mem/allocator/mem_allocator.h"
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#define wapp_mem_arena_allocator_init(base_capacity)                           \
+  (wapp_mem_arena_allocator_init_custom(base_capacity, WAPP_MEM_ALLOC_RESERVE, false))
+#define wapp_mem_arena_allocator_init_commit(base_capacity)                    \
+  (wapp_mem_arena_allocator_init_custom(base_capacity, WAPP_MEM_ALLOC_RESERVE | WAPP_MEM_ALLOC_COMMIT, false))
+#define wapp_mem_arena_allocator_init_zero(base_capacity)                      \
+  (wapp_mem_arena_allocator_init_custom(base_capacity, WAPP_MEM_ALLOC_RESERVE, true))
+#define wapp_mem_arena_allocator_init_commit_and_zero(base_capacity)           \
+  (wapp_mem_arena_allocator_init_custom(base_capacity, WAPP_MEM_ALLOC_RESERVE | WAPP_MEM_ALLOC_COMMIT, true))
+
+/**
+ * Wraps an Arena in an Allocator object. It attempts to initialise the Arena
+ * and, if successful, defines the operations supported by it to be used by the
+ * Allocator.
+ *
+ * An Arena allocator only supports normal allocation and aligned allocation.
+ * Reallocation, aligned reallocation and freeing aren't implemented.
+ *
+ * The `wapp_mem_arena_allocator_init_custom` provides the most control over how
+ * the Arena is initialised. Wrapper macros are provided for easier use.
+ */
+Allocator wapp_mem_arena_allocator_init_custom(u64 base_capacity, MemAllocFlags flags, b8 zero_buffer);
+void wapp_mem_arena_allocator_clear(Allocator *allocator);
+void wapp_mem_arena_allocator_destroy(Allocator *allocator);
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !MEM_ARENA_ALLOCATOR_H

src/os/cpath/cpath.c

@@ -0,0 +1,135 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "cpath.h"
+#include "../allocators/arena/mem_arena_allocator.h"
+#include "../../common/aliases/aliases.h"
+#include "../../common/misc/misc_utils.h"
+#include "../../base/dbl_list/dbl_list.h"
+#include "../../base/mem/allocator/mem_allocator.h"
+#include "../../base/strings/str8/str8.h"
+#include <stdarg.h>
+#include <stdio.h>
+#include <string.h>
+
+u32 wapp_cpath_join_path(Str8 *dst, const Str8List *parts) {
+  if (!dst || !parts) {
+    return CPATH_JOIN_INVALID_ARGS;
+  }
+
+  if (parts->node_count == 0) {
+    return CPATH_JOIN_EMPTY_PARTS;
+  }
+
+  Str8 separator = wapp_str8_buf(4);
+  wapp_str8_push_back(&separator, WAPP_PATH_SEP);
+
+  u64 required_capacity = parts->node_count * separator.size + wapp_str8_list_total_size(parts);
+  if (dst->capacity < required_capacity) {
+    return CPATH_JOIN_INSUFFICIENT_DST_CAPACITY;
+  }
+
+  // Handle first node
+  const Str8Node *first_node = wapp_str8_list_get(parts, 0);
+  wapp_str8_copy_str8_capped(dst, first_node->item);
+
+  // NOTE (Abdelrahman): Uses a while loop instead of a for loop to get rid of
+  // MSVC Spectre mitigation warnings
+  const Str8Node *node = first_node;
+  u64 node_index       = 1;
+  b8 running          = node_index < parts->node_count;
+  while (running && node->next) {
+    node = node->next;
+    if (node->item->size == 0) {
+      continue;
+    }
+
+    if (dst->size > 0) {
+      char dst_last    = wapp_str8_get(dst, dst->size - 1);
+      char node_start  = wapp_str8_get(node->item, 0);
+      b8 add_path_sep = dst_last != WAPP_PATH_SEP && node_start != WAPP_PATH_SEP;
+
+      if (add_path_sep) {
+        wapp_str8_concat_capped(dst, &separator);
+      }
+    }
+
+    wapp_str8_concat_capped(dst, node->item);
+
+    ++node_index;
+    running = node_index < parts->node_count;
+  }
+
+  return CPATH_JOIN_SUCCESS;
+}
+
+Str8 *dirup(const Allocator *allocator, Str8RO *path, u64 levels) {
+  Str8 *output = NULL;
+  if (!allocator || !path) {
+    goto RETURN_DIRUP;
+  }
+
+  b8 absolute   = wapp_str8_get(path, 0) == WAPP_PATH_SEP;
+  Str8 separator = wapp_str8_buf(4);
+  wapp_str8_push_back(&separator, WAPP_PATH_SEP);
+
+  if (path->size == 0) {
+    output = wapp_str8_alloc_buf(allocator, 16);
+    if (!output) {
+      goto RETURN_DIRUP;
+    }
+
+    wapp_str8_push_back(output, absolute ? WAPP_PATH_SEP : '.');
+    goto RETURN_DIRUP;
+  }
+
+  if (levels < 1) {
+    output = wapp_str8_alloc_str8(allocator, path);
+    goto RETURN_DIRUP;
+  }
+
+  Allocator tmp_arena = wapp_mem_arena_allocator_init(MB(8));
+  if (wapp_mem_allocator_invalid(&tmp_arena)) {
+    goto RETURN_DIRUP;
+  }
+
+  Str8List *parts = wapp_str8_split(&tmp_arena, path, &separator);
+  if (!parts) {
+    goto RETURN_DIRUP;
+  }
+
+  if (levels >= parts->node_count) {
+    output = wapp_str8_alloc_buf(allocator, 16);
+    if (!output) {
+      goto LIST_CLEANUP_DIRUP;
+    }
+
+    wapp_str8_push_back(output, absolute ? WAPP_PATH_SEP : '.');
+  } else {
+    for (u64 i = 0; i < levels; ++i) {
+      wapp_str8_list_pop_back(parts);
+    }
+    
+    u64 alignment  = sizeof(void *) * 2;
+    u64 alloc_size = wapp_str8_list_total_size(parts) + parts->node_count * separator.size;
+    u64 modulo     = alloc_size & (alignment - 1);
+    alloc_size    += alignment - modulo;
+
+    output = wapp_str8_alloc_buf(allocator, alloc_size);
+    if (output) {
+      if (absolute) {
+        wapp_str8_push_back(output, WAPP_PATH_SEP);
+      }
+
+      Str8 *joined = wapp_str8_join(&tmp_arena, parts, &separator);
+      if (joined) {
+        wapp_str8_concat_capped(output, joined);
+      }
+    }
+  }
+
+LIST_CLEANUP_DIRUP:
+  wapp_mem_arena_allocator_destroy(&tmp_arena);
+
+RETURN_DIRUP:
+  return output;
+}

src/os/cpath/cpath.h

@@ -0,0 +1,45 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef CPATH_H
+#define CPATH_H
+
+#include "../../common/aliases/aliases.h"
+#include "../../common/platform/platform.h"
+#include "../../base/mem/allocator/mem_allocator.h"
+#include "../../base/strings/str8/str8.h"
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#ifdef WAPP_PLATFORM_POSIX
+#include <limits.h>
+#define WAPP_PATH_SEP '/'
+#define WAPP_PATH_MAX PATH_MAX
+#elif defined(WAPP_PLATFORM_WINDOWS)
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#define WAPP_PATH_SEP '\\'
+#define WAPP_PATH_MAX MAX_PATH
+#else
+#error "Unrecognised platform"
+#endif
+
+#define wapp_cpath_dirname(ALLOCATOR, PATH) dirup(ALLOCATOR, PATH, 1)
+#define wapp_cpath_dirup(ALLOCATOR, PATH, COUNT) dirup(ALLOCATOR, PATH, COUNT)
+
+enum {
+  CPATH_JOIN_SUCCESS = 0,
+  CPATH_JOIN_INVALID_ARGS,
+  CPATH_JOIN_EMPTY_PARTS,
+  CPATH_JOIN_INSUFFICIENT_DST_CAPACITY,
+};
+
+u32  wapp_cpath_join_path(Str8 *dst, const Str8List *parts);
+Str8 *dirup(const Allocator *allocator, Str8RO *path, u64 levels);
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !CPATH_H

src/os/file/file.c

@@ -0,0 +1,109 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "file.h"
+#include "../cpath/cpath.h"
+#include "../../common/assert/assert.h"
+#include "../../common/aliases/aliases.h"
+#include "../../base/array/array.h"
+#include "../../base/strings/str8/str8.h"
+#include <stdio.h>
+
+File *wapp_file_open(Str8RO *filepath, FileAccessMode mode) {
+  wapp_persist const char *modes[FILE_ACCESS_MODE_COUNT] = {
+    [WAPP_FA_MODE_R]      = "r",
+    [WAPP_FA_MODE_W]      = "w",
+    [WAPP_FA_MODE_A]      = "a",
+    [WAPP_FA_MODE_R_EX]   = "r+",
+    [WAPP_FA_MODE_W_EX]   = "w+",
+    [WAPP_FA_MODE_A_EX]   = "a+",
+    [WAPP_FA_MODE_RB]     = "rb",
+    [WAPP_FA_MODE_WB]     = "wb",
+    [WAPP_FA_MODE_AB]     = "ab",
+    [WAPP_FA_MODE_RB_EX]  = "rb+",
+    [WAPP_FA_MODE_WB_EX]  = "wb+",
+    [WAPP_FA_MODE_AB_EX]  = "ab+",
+    [WAPP_FA_MODE_WX]     = "wx",
+    [WAPP_FA_MODE_WX_EX]  = "wx+",
+    [WAPP_FA_MODE_WBX]    = "wbx",
+    [WAPP_FA_MODE_WBX_EX] = "wbx+",
+  };
+  wapp_persist c8 tmp[WAPP_PATH_MAX] = {0};
+  wapp_debug_assert(filepath->size < WAPP_PATH_MAX, "`filepath` exceeds max path limit.");
+
+  memset(tmp, 0, WAPP_PATH_MAX);
+  memcpy(tmp, filepath->buf, filepath->size);
+
+  return fopen((const char *)tmp, modes[mode]);
+}
+
+u64 wapp_file_get_current_position(File *file) {
+  wapp_debug_assert(file != NULL, "`file` should not be NULL.");
+  return (u64)ftell(file);
+}
+
+i32 wapp_file_seek(File *file, u64 offset, FileSeekOrigin origin) {
+  wapp_debug_assert(file != NULL, "`file` should not be NULL.");
+  // TODO (Abdelrahman): Revisit conversion to long
+  return fseek(file, (long)offset, origin);
+}
+
+u64 wapp_file_get_length(File *file) {
+  wapp_debug_assert(file != NULL, "`file` should not be NULL.");
+
+  u64 current = wapp_file_get_current_position(file);
+
+  wapp_file_seek(file, 0, WAPP_SEEK_END);
+
+  u64 output = ftell(file);
+
+  // Restore position
+  wapp_file_seek(file, current, WAPP_SEEK_START);
+
+  return output;
+}
+
+u64 wapp_file_read(Array *dst_buf, File *file, u64 item_count) {
+  wapp_debug_assert(dst_buf != NULL && file != NULL,
+                    "`dst_buf` and `file` should not be NULL.");
+
+  u64 file_length       = wapp_file_get_length(file);
+  u64 item_size         = dst_buf->item_size;
+  u64 dst_byte_capacity = dst_buf->capacity * item_size;
+  u64 req_byte_count    = item_count * item_size;
+  u64 copy_byte_count   = 0;
+
+  if (req_byte_count <= file_length && req_byte_count <= dst_byte_capacity) {
+    copy_byte_count = req_byte_count;
+  } else {
+    copy_byte_count = file_length <= dst_byte_capacity ? file_length : dst_byte_capacity;
+  }
+
+  u64 count = fread(dst_buf->items, sizeof(u8), copy_byte_count, file);
+  if (ferror(file)) { return 0; }
+
+  dst_buf->count = count / item_size;
+
+  return dst_buf->count;
+}
+
+u64 wapp_file_write(const Array *src_buf, File *file, u64 item_count) {
+  wapp_debug_assert(src_buf != NULL && file != NULL,
+                    "`src_buf` and `file` should not be NULL.");
+
+  u64 item_size      = src_buf->item_size;
+  u64 src_byte_count = src_buf->count * item_size;
+  u64 req_byte_count = item_count * item_size;
+  u64 to_copy        = req_byte_count <= src_byte_count ? req_byte_count : src_byte_count;
+
+  return fwrite(src_buf->items, sizeof(u8), to_copy, file);
+}
+
+i32 wapp_file_flush(File *file) {
+  wapp_debug_assert(file != NULL, "`file` should not be NULL.");
+  return fflush(file);
+}
+
+i32 wapp_file_close(File *file) {
+  wapp_debug_assert(file != NULL, "`file` should not be NULL.");
+  return fclose(file);
+}

src/os/file/file.h

@@ -0,0 +1,56 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef FILE_H
+#define FILE_H
+
+#include "../../common/aliases/aliases.h"
+#include "../../base/strings/str8/str8.h"
+#include <stdio.h>
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+typedef FILE File;
+
+typedef enum {
+  WAPP_FA_MODE_R,      // Equivalent to r
+  WAPP_FA_MODE_W,      // Equivalent to w
+  WAPP_FA_MODE_A,      // Equivalent to a
+  WAPP_FA_MODE_R_EX,   // Equivalent to r+
+  WAPP_FA_MODE_W_EX,   // Equivalent to w+
+  WAPP_FA_MODE_A_EX,   // Equivalent to a+
+  WAPP_FA_MODE_RB,     // Equivalent to rb
+  WAPP_FA_MODE_WB,     // Equivalent to wb
+  WAPP_FA_MODE_AB,     // Equivalent to ab
+  WAPP_FA_MODE_RB_EX,  // Equivalent to rb+
+  WAPP_FA_MODE_WB_EX,  // Equivalent to wb+
+  WAPP_FA_MODE_AB_EX,  // Equivalent to ab+
+  WAPP_FA_MODE_WX,     // Equivalent to wx
+  WAPP_FA_MODE_WX_EX,  // Equivalent to wx+
+  WAPP_FA_MODE_WBX,    // Equivalent to wbx
+  WAPP_FA_MODE_WBX_EX, // Equivalent to wbx+
+
+  FILE_ACCESS_MODE_COUNT,
+} FileAccessMode;
+
+typedef enum {
+  WAPP_SEEK_START   = SEEK_SET,
+  WAPP_SEEK_CURRENT = SEEK_CUR,
+  WAPP_SEEK_END     = SEEK_END,
+} FileSeekOrigin;
+
+File *wapp_file_open(Str8RO *filename, FileAccessMode mode);
+u64   wapp_file_get_current_position(File *file);
+i32   wapp_file_seek(File *file, u64 offset, FileSeekOrigin origin);
+u64   wapp_file_get_length(File *file);
+u64   wapp_file_read(Array *dst_buf, File *file, u64 item_count);
+u64   wapp_file_write(const Array *src_buf, File *file, u64 item_count);
+i32   wapp_file_flush(File *file);
+i32   wapp_file_close(File *file);
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !FILE_H

src/os/mem/mem_os.c

@@ -0,0 +1,30 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "mem_os.h"
+#include "mem_os_ops.h"
+#include "../../common/aliases/aliases.h"
+#include "../../common/platform/platform.h"
+#include <assert.h>
+#include <string.h>
+
+#if defined(WAPP_PLATFORM_WINDOWS)
+#include "win/mem_os_win.h"
+#elif defined(WAPP_PLATFORM_POSIX)
+#include "posix/mem_os_posix.h"
+#else
+#error "Unrecognised platform"
+#endif
+
+void *wapp_mem_util_alloc(void *addr, u64 size, MemAccess access, MemAllocFlags flags, MemInitType type) {
+  void *output = mem_util_allocate(addr, size, access, flags, type);
+
+  if (type == WAPP_MEM_INIT_INITIALISED) {
+    memset(output, 0, size);
+  }
+
+  return output;
+}
+
+void wapp_mem_util_free(void *ptr, u64 size) {
+  mem_util_free(ptr, size);
+}

src/os/mem/mem_os.h

@@ -0,0 +1,33 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef MEM_OS_H
+#define MEM_OS_H
+
+#include "../../common/aliases/aliases.h"
+#include "../../common/platform/platform.h"
+
+#include "mem_os_ops.h"
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#if defined(WAPP_PLATFORM_WINDOWS)
+#include "win/mem_os_win.h"
+#elif defined(WAPP_PLATFORM_POSIX)
+#include "posix/mem_os_posix.h"
+#else
+#error "Unrecognised platform"
+#endif
+
+void *wapp_mem_util_alloc(void *addr, u64 size, MemAccess access, MemAllocFlags flags, MemInitType type);
+void wapp_mem_util_free(void *ptr, u64 size);
+
+wapp_extern void *mem_util_allocate(void *addr, u64 size, MemAccess access, MemAllocFlags flags, MemInitType type);
+wapp_extern void mem_util_free(void *ptr, u64 size);
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !MEM_OS_H

src/os/mem/mem_os_ops.h

@@ -0,0 +1,30 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef MEM_OS_OPS_H
+#define MEM_OS_OPS_H
+
+#include "../../common/platform/platform.h"
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+typedef enum mem_access {
+  WAPP_MEM_ACCESS_NONE,
+  WAPP_MEM_ACCESS_READ_ONLY,
+  WAPP_MEM_ACCESS_EXEC_ONLY,
+  WAPP_MEM_ACCESS_READ_WRITE,
+  WAPP_MEM_ACCESS_READ_EXEC,
+  WAPP_MEM_ACCESS_READ_WRITE_EXEC,
+} MemAccess;
+
+typedef enum mem_init_type {
+  WAPP_MEM_INIT_UNINITIALISED,
+  WAPP_MEM_INIT_INITIALISED,
+} MemInitType;
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !MEM_OS_OPS_H

src/os/mem/posix/mem_os_posix.c

@@ -0,0 +1,36 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "../../../common/aliases/aliases.h"
+#include "../../../common/platform/platform.h"
+
+#ifdef WAPP_PLATFORM_POSIX
+
+#include "mem_os_posix.h"
+#include "../mem_os_ops.h"
+#include <sys/mman.h>
+
+wapp_intern const i32 access_types[] = {
+    [WAPP_MEM_ACCESS_NONE]            = PROT_NONE,
+    [WAPP_MEM_ACCESS_READ_ONLY]       = PROT_READ,
+    [WAPP_MEM_ACCESS_EXEC_ONLY]       = PROT_EXEC,
+    [WAPP_MEM_ACCESS_READ_WRITE]      = PROT_READ | PROT_WRITE,
+    [WAPP_MEM_ACCESS_READ_EXEC]       = PROT_READ | PROT_EXEC,
+    [WAPP_MEM_ACCESS_READ_WRITE_EXEC] = PROT_READ | PROT_WRITE | PROT_EXEC,
+};
+
+void *mem_util_allocate(void *addr, u64 size, MemAccess access, MemAllocFlags flags, MemInitType type) {
+  (void)type;
+  i32 alloc_flags = flags | MAP_ANON | MAP_PRIVATE;
+
+#if defined(WAPP_PLATFORM_LINUX) || defined(WAPP_PLATFORM_GNU) || defined(WAPP_PLATFORM_NET_BSD)
+  alloc_flags |= MAP_NORESERVE;
+#endif
+
+  return mmap(addr, size, access_types[access], alloc_flags, -1, 0);
+}
+
+void mem_util_free(void *ptr, u64 size) {
+  munmap(ptr, size);
+}
+
+#endif // !WAPP_PLATFORM_POSIX

src/os/mem/posix/mem_os_posix.h

@@ -0,0 +1,35 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef MEM_OS_POSIX_H
+#define MEM_OS_POSIX_H
+
+#include "../../../common/platform/platform.h"
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#ifdef WAPP_PLATFORM_POSIX
+
+#include <sys/mman.h>
+
+typedef enum mem_alloc_flags {
+#if defined(WAPP_PLATFORM_LINUX) || defined(WAPP_PLATFORM_GNU)
+  WAPP_MEM_ALLOC_RESERVE = 0,
+  WAPP_MEM_ALLOC_COMMIT  = MAP_POPULATE,
+#elif defined(WAPP_PLATFORM_FREE_BSD)
+  WAPP_MEM_ALLOC_RESERVE = 0,
+  WAPP_MEM_ALLOC_COMMIT  = MAP_PREFAULT_READ,
+#elif defined(WAPP_PLATFORM_BSD) || defined(WAPP_PLATFORM_UNIX) || defined(WAPP_PLATFORM_APPLE)
+  WAPP_MEM_ALLOC_RESERVE = 0,
+  WAPP_MEM_ALLOC_COMMIT  = 0,
+#endif
+} MemAllocFlags;
+
+#endif // !WAPP_PLATFORM_POSIX
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !MEM_OS_POSIX_H

src/os/mem/win/mem_os_win.c

@@ -0,0 +1,37 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "../../../common/aliases/aliases.h"
+#include "../../../common/platform/platform.h"
+
+#ifdef WAPP_PLATFORM_WINDOWS
+
+#include "mem_os_win.h"
+#include "../mem_os_ops.h"
+
+#define WIN32_LEAN_AND_MEAN
+#include <Windows.h>
+#include <memoryapi.h>
+
+wapp_intern const i32 access_types[] = {
+    [WAPP_MEM_ACCESS_NONE]            = PAGE_NOACCESS,
+    [WAPP_MEM_ACCESS_READ_ONLY]       = PAGE_READONLY,
+    [WAPP_MEM_ACCESS_EXEC_ONLY]       = PAGE_EXECUTE,
+    [WAPP_MEM_ACCESS_READ_WRITE]      = PAGE_READWRITE,
+    [WAPP_MEM_ACCESS_READ_EXEC]       = PAGE_EXECUTE_READ,
+    [WAPP_MEM_ACCESS_READ_WRITE_EXEC] = PAGE_EXECUTE_READWRITE,
+};
+
+void *mem_util_allocate(void *addr, u64 size, MemAccess access, MemAllocFlags flags, MemInitType type) {
+  // Ensure memory is committed if it's meant to be initialised
+  if (type == WAPP_MEM_INIT_INITIALISED) {
+    flags |= WAPP_MEM_ALLOC_COMMIT;
+  }
+
+  return VirtualAlloc(addr, (SIZE_T)size, flags, access_types[access]);
+}
+
+void mem_util_free(void *ptr, u64 size) {
+  VirtualFree(ptr, size, MEM_RELEASE);
+}
+
+#endif // !WAPP_PLATFORM_WINDOWS

src/os/mem/win/mem_os_win.h

@@ -0,0 +1,29 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef MEM_OS_WIN_H
+#define MEM_OS_WIN_H
+
+#include "../../../common/platform/platform.h"
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#ifdef WAPP_PLATFORM_WINDOWS
+
+#define WIN32_LEAN_AND_MEAN
+#include <Windows.h>
+#include <memoryapi.h>
+
+typedef enum mem_alloc_flags {
+  WAPP_MEM_ALLOC_RESERVE = MEM_RESERVE,
+  WAPP_MEM_ALLOC_COMMIT  = MEM_COMMIT,
+} MemAllocFlags;
+
+#endif // !WAPP_PLATFORM_WINDOWS
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !MEM_OS_WIN_H

src/os/shell/commander/commander.c

@@ -0,0 +1,101 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "commander.h"
+#include "commander_output.h"
+#include "../utils/shell_utils.h"
+#include "../../allocators/arena/mem_arena_allocator.h"
+#include "../../../common/aliases/aliases.h"
+#include "../../../common/misc/misc_utils.h"
+#include "../../../base/dbl_list/dbl_list.h"
+#include "../../../base/mem/allocator/mem_allocator.h"
+#include "../../../base/strings/str8/str8.h"
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define CMD_BUF_LEN 8192
+#define OUT_BUF_LEN 4096
+
+wapp_intern inline CMDResult execute_command(Str8RO *cmd, CMDOutHandling out_handling, Str8 *out_buf);
+wapp_intern inline CMDError get_command_output(FILE *fp, CMDOutHandling out_handling, Str8 *out_buf);
+
+CMDResult wapp_shell_commander_execute(CMDOutHandling out_handling, Str8 *out_buf, const Str8List *cmd) {
+  if (!cmd) {
+    return CMD_NO_EXIT(SHELL_ERR_INVALID_ARGS);
+  }
+
+  Allocator arena = wapp_mem_arena_allocator_init(KB(500));
+
+  Str8 *cmd_str = wapp_str8_join(&arena, cmd, &wapp_str8_lit_ro(" "));
+  if (!cmd_str) {
+    wapp_mem_arena_allocator_destroy(&arena);
+    return CMD_NO_EXIT(SHELL_ERR_ALLOCATION_FAIL);
+  }
+
+  // Redirect output
+  cmd_str = wapp_str8_alloc_concat(&arena, cmd_str, &wapp_str8_lit_ro(" 2>&1"));
+
+  CMDResult output = execute_command(cmd_str, out_handling, out_buf);
+
+  wapp_mem_arena_allocator_destroy(&arena);
+
+  return output;
+}
+
+wapp_intern inline CMDResult execute_command(Str8RO *cmd, CMDOutHandling out_handling, Str8 *out_buf) {
+  char cmd_buf[CMD_BUF_LEN] = {0};
+  wapp_str8_copy_to_cstr(cmd_buf, cmd, CMD_BUF_LEN);
+
+  FILE *fp = wapp_shell_utils_popen(cmd_buf, "r");
+  if (!fp) {
+    return CMD_NO_EXIT(SHELL_ERR_PROC_START_FAIL);
+  }
+
+  CMDResult output;
+
+  CMDError err = get_command_output(fp, out_handling, out_buf);
+  if (err > SHELL_ERR_NO_ERROR) {
+    output = CMD_NO_EXIT(err);
+    goto EXECUTE_COMMAND_CLOSE;
+  }
+
+  i32 st = EXIT_SUCCESS;
+  err = get_output_status(fp, &st);
+  if (err > SHELL_ERR_NO_ERROR) {
+    output = CMD_NO_EXIT(err);
+    goto EXECUTE_COMMAND_CLOSE;
+  }
+
+  // Process is already closed in get_output_status
+  fp = NULL;
+
+  output = (CMDResult){
+      .exited = true,
+      .exit_code = st,
+      .error = SHELL_ERR_NO_ERROR,
+  };
+
+EXECUTE_COMMAND_CLOSE:
+  if (fp) {
+    wapp_shell_utils_pclose(fp);
+  }
+  return output;
+}
+
+wapp_intern inline CMDError get_command_output(FILE *fp, CMDOutHandling out_handling, Str8 *out_buf) {
+  Str8 out = wapp_str8_buf(OUT_BUF_LEN);
+
+  out.size = fread((void *)out.buf, sizeof(u8), out.capacity, fp);
+  if (out_handling == SHELL_OUTPUT_CAPTURE && out_buf != NULL) {
+    if (out.size >= out_buf->capacity) {
+      return SHELL_ERR_OUT_BUF_FULL;
+    }
+
+    wapp_str8_concat_capped(out_buf, &out);
+  } else if (out_handling == SHELL_OUTPUT_PRINT) {
+    printf(WAPP_STR8_SPEC, wapp_str8_varg(out));
+  }
+
+  return SHELL_ERR_NO_ERROR;
+}

src/os/shell/commander/commander.h

@@ -0,0 +1,27 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef COMMANDER_H
+#define COMMANDER_H
+
+#include "commander_output.h"
+#include "../../../common/aliases/aliases.h"
+#include "../../../common/platform/platform.h"
+#include "../../../base/strings/str8/str8.h"
+#include <stdio.h>
+#include <stdlib.h>
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#define CMD_NO_EXIT(ERR) ((CMDResult){.exited = false, .exit_code = EXIT_FAILURE, .error = ERR})
+
+CMDResult wapp_shell_commander_execute(CMDOutHandling out_handling, Str8 *out_buf, const Str8List *cmd);
+
+wapp_extern CMDError get_output_status(FILE *fp, i32 *status_out);
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !COMMANDER_H

src/os/shell/commander/commander_output.h

@@ -0,0 +1,44 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef COMMANDER_OUTPUT_H
+#define COMMANDER_OUTPUT_H
+
+#include "../../../common/aliases/aliases.h"
+#include "../../../common/platform/platform.h"
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+typedef enum {
+  SHELL_OUTPUT_DISCARD,
+  SHELL_OUTPUT_PRINT,
+  SHELL_OUTPUT_CAPTURE,
+} CMDOutHandling;
+
+typedef enum {
+  SHELL_ERR_NO_ERROR,
+  SHELL_ERR_INVALID_ARGS,
+  SHELL_ERR_ALLOCATION_FAIL,
+  SHELL_ERR_PROC_START_FAIL,
+  SHELL_ERR_OUT_BUF_FULL,
+  SHELL_ERR_PROC_EXIT_FAIL,
+} CMDError;
+
+typedef struct commander_result CMDResult;
+struct commander_result {
+  i32 exit_code;
+  CMDError error;
+  b8 exited;
+
+#ifdef WAPP_PLATFORM_WINDOWS
+  #include "../../../../common/misc/misc_utils.h"
+  wapp_misc_utils_padding_size(sizeof(b8) + sizeof(i32) + sizeof(CMDError));
+#endif // !WAPP_PLATFORM_WINDOWS
+};
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !COMMANDER_OUTPUT_H

src/os/shell/commander/posix/commander_posix.c

@@ -0,0 +1,25 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "../../../../common/aliases/aliases.h"
+#include "../../../../common/platform/platform.h"
+
+#ifdef WAPP_PLATFORM_POSIX
+
+#include "../commander_output.h"
+#include "../../utils/shell_utils.h"
+#include <stdio.h>
+#include <stdlib.h>
+
+CMDError get_output_status(FILE *fp, i32 *status_out) {
+  *status_out = wapp_shell_utils_pclose(fp);
+
+  if (!WIFEXITED(*status_out)) {
+    return SHELL_ERR_PROC_EXIT_FAIL;
+  }
+
+  *status_out = WEXITSTATUS(*status_out);
+
+  return SHELL_ERR_NO_ERROR;
+}
+
+#endif // !WAPP_PLATFORM_POSIX

src/os/shell/commander/win/commander_win.c

@@ -0,0 +1,24 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "../../../../common/aliases/aliases.h"
+#include "../../../../common/platform/platform.h"
+
+#ifdef WAPP_PLATFORM_WINDOWS
+
+#include "../commander_output.h"
+#include "../../utils/shell_utils.h"
+#include <stdio.h>
+
+CMDError get_output_status(FILE *fp, i32 *status_out) {
+  if (!feof(fp)) {
+    // Ensure process is closed on failure
+    wapp_shell_utils_pclose(fp);
+    return SHELL_ERR_PROC_EXIT_FAIL;
+  }
+
+  *status_out = wapp_shell_utils_pclose(fp);
+
+  return SHELL_ERR_NO_ERROR;
+}
+
+#endif // !WAPP_PLATFORM_WINDOWS

src/os/shell/termcolour/posix/termcolour_posix.c

@@ -0,0 +1,36 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "../../../../common/aliases/aliases.h"
+#include "../../../../common/platform/platform.h"
+#include "../../../../base/strings/str8/str8.h"
+
+#ifdef WAPP_PLATFORM_POSIX
+
+#include "../terminal_colours.h"
+#include <stdio.h>
+
+wapp_intern Str8RO colours[COUNT_TERM_COLOUR] = {
+    [WAPP_TERM_COLOUR_FG_BLACK]      = wapp_str8_lit_ro_initialiser_list("\033[30m"),
+    [WAPP_TERM_COLOUR_FG_RED]        = wapp_str8_lit_ro_initialiser_list("\033[31m"),
+    [WAPP_TERM_COLOUR_FG_GREEN]      = wapp_str8_lit_ro_initialiser_list("\033[32m"),
+    [WAPP_TERM_COLOUR_FG_BLUE]       = wapp_str8_lit_ro_initialiser_list("\033[34m"),
+    [WAPP_TERM_COLOUR_FG_CYAN]       = wapp_str8_lit_ro_initialiser_list("\033[36m"),
+    [WAPP_TERM_COLOUR_FG_MAGENTA]    = wapp_str8_lit_ro_initialiser_list("\033[35m"),
+    [WAPP_TERM_COLOUR_FG_YELLOW]     = wapp_str8_lit_ro_initialiser_list("\033[33m"),
+    [WAPP_TERM_COLOUR_FG_WHITE]      = wapp_str8_lit_ro_initialiser_list("\033[37m"),
+    [WAPP_TERM_COLOUR_FG_BR_BLACK]   = wapp_str8_lit_ro_initialiser_list("\033[90m"),
+    [WAPP_TERM_COLOUR_FG_BR_RED]     = wapp_str8_lit_ro_initialiser_list("\033[91m"),
+    [WAPP_TERM_COLOUR_FG_BR_GREEN]   = wapp_str8_lit_ro_initialiser_list("\033[92m"),
+    [WAPP_TERM_COLOUR_FG_BR_BLUE]    = wapp_str8_lit_ro_initialiser_list("\033[94m"),
+    [WAPP_TERM_COLOUR_FG_BR_CYAN]    = wapp_str8_lit_ro_initialiser_list("\033[96m"),
+    [WAPP_TERM_COLOUR_FG_BR_MAGENTA] = wapp_str8_lit_ro_initialiser_list("\033[95m"),
+    [WAPP_TERM_COLOUR_FG_BR_YELLOW]  = wapp_str8_lit_ro_initialiser_list("\033[93m"),
+    [WAPP_TERM_COLOUR_FG_BR_WHITE]   = wapp_str8_lit_ro_initialiser_list("\033[97m"),
+    [WAPP_TERM_COLOUR_CLEAR]         = wapp_str8_lit_ro_initialiser_list("\033[0m"),
+};
+
+void print_coloured_text(Str8RO *text, TerminalColour colour) {
+  printf(WAPP_STR8_SPEC WAPP_STR8_SPEC, wapp_str8_varg(colours[colour]), wapp_str8_varg((*text)));
+}
+
+#endif // !WAPP_PLATFORM_POSIX

src/os/shell/termcolour/termcolour.c

@@ -0,0 +1,18 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "termcolour.h"
+#include "terminal_colours.h"
+#include "../../../base/strings/str8/str8.h"
+
+void wapp_shell_termcolour_print_text(Str8RO *text, TerminalColour colour) {
+  if (colour < WAPP_TERM_COLOUR_FG_BLACK || colour > WAPP_TERM_COLOUR_FG_BR_WHITE) {
+    return;
+  }
+
+  print_coloured_text(text, colour);
+}
+
+void wapp_shell_termcolour_clear_colour(void) {
+  Str8RO empty = wapp_str8_lit_ro("");
+  print_coloured_text(&empty, WAPP_TERM_COLOUR_CLEAR);
+}

src/os/shell/termcolour/termcolour.h

@@ -0,0 +1,24 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef TERM_COLOUR_H
+#define TERM_COLOUR_H
+
+#include "terminal_colours.h"
+#include "../../../common/aliases/aliases.h"
+#include "../../../common/platform/platform.h"
+#include "../../../base/strings/str8/str8.h"
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+void wapp_shell_termcolour_print_text(Str8RO *text, TerminalColour colour);
+void wapp_shell_termcolour_clear_colour(void);
+
+wapp_extern void print_coloured_text(Str8RO *text, TerminalColour colour);
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !TERM_COLOUR_H

src/os/shell/termcolour/terminal_colours.h

@@ -0,0 +1,39 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef TERMINAL_COLOURS_H
+#define TERMINAL_COLOURS_H
+
+#include "../../../common/aliases/aliases.h"
+#include "../../../common/platform/platform.h"
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+typedef enum {
+  WAPP_TERM_COLOUR_FG_BLACK,
+  WAPP_TERM_COLOUR_FG_RED,
+  WAPP_TERM_COLOUR_FG_GREEN,
+  WAPP_TERM_COLOUR_FG_BLUE,
+  WAPP_TERM_COLOUR_FG_CYAN,
+  WAPP_TERM_COLOUR_FG_MAGENTA,
+  WAPP_TERM_COLOUR_FG_YELLOW,
+  WAPP_TERM_COLOUR_FG_WHITE,
+  WAPP_TERM_COLOUR_FG_BR_BLACK,
+  WAPP_TERM_COLOUR_FG_BR_RED,
+  WAPP_TERM_COLOUR_FG_BR_GREEN,
+  WAPP_TERM_COLOUR_FG_BR_BLUE,
+  WAPP_TERM_COLOUR_FG_BR_CYAN,
+  WAPP_TERM_COLOUR_FG_BR_MAGENTA,
+  WAPP_TERM_COLOUR_FG_BR_YELLOW,
+  WAPP_TERM_COLOUR_FG_BR_WHITE,
+  WAPP_TERM_COLOUR_CLEAR,
+
+  COUNT_TERM_COLOUR,
+} TerminalColour;
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !TERMINAL_COLOURS_H

src/os/shell/termcolour/win/termcolour_win.c

@@ -0,0 +1,73 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#include "../../../../common/aliases/aliases.h"
+#include "../../../../common/platform/platform.h"
+#include "../../../../base/strings/str8/str8.h"
+
+#ifdef WAPP_PLATFORM_WINDOWS
+
+#include "../terminal_colours.h"
+#include "../../../../../common/misc/misc_utils.h"
+#include <stdio.h>
+
+#define WIN32_LEAN_AND_MEAN
+#include <Windows.h>
+
+typedef struct termcolour_data TermcolourData;
+struct termcolour_data {
+  HANDLE handle;
+  WORD   default_colour;
+  WORD   current_colour;
+
+  wapp_misc_utils_padding_size(sizeof(HANDLE) + sizeof(WORD) + sizeof(WORD));
+};
+
+wapp_intern void init_data(TermcolourData *data);
+
+wapp_intern WORD colours[COUNT_TERM_COLOUR] = {
+    [WAPP_TERM_COLOUR_FG_BLACK]      = 0,
+    [WAPP_TERM_COLOUR_FG_RED]        = FOREGROUND_RED,
+    [WAPP_TERM_COLOUR_FG_GREEN]      = FOREGROUND_GREEN,
+    [WAPP_TERM_COLOUR_FG_BLUE]       = FOREGROUND_BLUE,
+    [WAPP_TERM_COLOUR_FG_CYAN]       = FOREGROUND_GREEN | FOREGROUND_BLUE,
+    [WAPP_TERM_COLOUR_FG_MAGENTA]    = FOREGROUND_RED | FOREGROUND_BLUE,
+    [WAPP_TERM_COLOUR_FG_YELLOW]     = FOREGROUND_RED | FOREGROUND_GREEN,
+    [WAPP_TERM_COLOUR_FG_WHITE]      = FOREGROUND_RED | FOREGROUND_GREEN | FOREGROUND_BLUE,
+    [WAPP_TERM_COLOUR_FG_BR_BLACK]   = FOREGROUND_INTENSITY,
+    [WAPP_TERM_COLOUR_FG_BR_RED]     = FOREGROUND_RED | FOREGROUND_INTENSITY,
+    [WAPP_TERM_COLOUR_FG_BR_GREEN]   = FOREGROUND_GREEN | FOREGROUND_INTENSITY,
+    [WAPP_TERM_COLOUR_FG_BR_BLUE]    = FOREGROUND_BLUE | FOREGROUND_INTENSITY,
+    [WAPP_TERM_COLOUR_FG_BR_CYAN]    = FOREGROUND_GREEN | FOREGROUND_BLUE | FOREGROUND_INTENSITY,
+    [WAPP_TERM_COLOUR_FG_BR_MAGENTA] = FOREGROUND_RED | FOREGROUND_BLUE | FOREGROUND_INTENSITY,
+    [WAPP_TERM_COLOUR_FG_BR_YELLOW]  = FOREGROUND_RED | FOREGROUND_GREEN | FOREGROUND_INTENSITY,
+    [WAPP_TERM_COLOUR_FG_BR_WHITE]   = FOREGROUND_RED | FOREGROUND_GREEN | FOREGROUND_BLUE | FOREGROUND_INTENSITY,
+};
+
+void print_coloured_text(Str8RO *text, TerminalColour colour) {
+  wapp_persist TermcolourData data = {0};
+  if (data.handle == 0) {
+    init_data(&data);
+  }
+
+  if (colour == WAPP_TERM_COLOUR_CLEAR) {
+    data.current_colour = data.default_colour;
+  } else {
+    data.current_colour = colours[colour];
+  }
+
+  SetConsoleTextAttribute(data.handle, data.current_colour);
+  printf(WAPP_STR8_SPEC, wapp_str8_varg((*text)));
+}
+
+wapp_intern void init_data(TermcolourData *data) {
+  // create handle
+  data->handle = GetStdHandle(STD_OUTPUT_HANDLE);
+
+  // get console colour information
+  CONSOLE_SCREEN_BUFFER_INFO csbi;
+  GetConsoleScreenBufferInfo(data->handle, &csbi);
+  data->default_colour = csbi.wAttributes;
+  data->current_colour = data->default_colour;
+}
+
+#endif // !WAPP_PLATFORM_WINDOWS

src/os/shell/utils/shell_utils.h

@@ -0,0 +1,26 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef SHELL_UTILS_H
+#define SHELL_UTILS_H
+
+#include "../../../common/aliases/aliases.h"
+#include "../../../common/platform/platform.h"
+#include <stdio.h>
+
+#ifdef WAPP_PLATFORM_CPP
+BEGIN_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#ifdef WAPP_PLATFORM_WINDOWS
+  #define wapp_shell_utils_popen  _popen
+  #define wapp_shell_utils_pclose _pclose
+#else
+  #define wapp_shell_utils_popen  popen
+  #define wapp_shell_utils_pclose pclose
+#endif /* ifdef WAPP_PLATFORM_WINDOWS */
+
+#ifdef WAPP_PLATFORM_CPP
+END_C_LINKAGE
+#endif // !WAPP_PLATFORM_CPP
+
+#endif // !SHELL_UTILS_H

src/os/wapp_os.c

@@ -0,0 +1,22 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef WAPP_OS_C
+#define WAPP_OS_C
+
+#include "wapp_os.h"
+#include "file/file.c"
+#include "shell/termcolour/posix/termcolour_posix.c"
+#include "shell/termcolour/win/termcolour_win.c"
+#include "shell/termcolour/termcolour.c"
+#include "shell/commander/posix/commander_posix.c"
+#include "shell/commander/win/commander_win.c"
+#include "shell/commander/commander.c"
+#include "cpath/cpath.c"
+#include "allocators/arena/mem_arena.c"
+#include "allocators/arena/mem_arena_allocator.c"
+#include "mem/posix/mem_os_posix.c"
+#include "mem/win/mem_os_win.c"
+#include "mem/mem_os.c"
+#include "../base/wapp_base.c"
+
+#endif // !WAPP_OS_C

src/os/wapp_os.h

@@ -0,0 +1,22 @@
+// vim:fileencoding=utf-8:foldmethod=marker
+
+#ifndef WAPP_CORE_H
+#define WAPP_CORE_H
+
+#include "file/file.h"
+#include "shell/termcolour/termcolour.h"
+#include "shell/termcolour/terminal_colours.h"
+#include "shell/commander/commander.h"
+#include "shell/commander/commander_output.h"
+#include "shell/utils/shell_utils.h"
+#include "cpath/cpath.h"
+#include "allocators/arena/mem_arena.h"
+#include "allocators/arena/mem_arena_allocator.h"
+#include "mem/posix/mem_os_posix.h"
+#include "mem/win/mem_os_win.h"
+#include "mem/mem_os_ops.h"
+#include "mem/mem_os.h"
+#include "../common/wapp_common.h"
+#include "../base/wapp_base.h"
+
+#endif // !WAPP_CORE_H