Merge branch 'master' of https://gitea.pockle.world/john/prosperon

.github/workflows/build.yml

@@ -6,17 +6,12 @@ on:
   pull_request:
 
 jobs:
-  # ===============================================================
-  #  LINUX BUILD
-  # ===============================================================
   build-linux:
     runs-on: ubuntu-latest
     steps:
-      # 1) Check out code
       - name: Check Out Code
         uses: actions/checkout@v3
 
-      # 2) Install system dependencies + ccache
       - name: Install Dependencies
         run: |
           sudo apt-get update
@@ -27,33 +22,29 @@ jobs:
             libxi-dev libxinerama-dev libxss-dev \
             libegl1-mesa-dev libgl1-mesa-dev \
             cmake ninja-build git build-essential binutils mold meson pkg-config \
-            ccache
+            ccache          
 
-      # 3) Configure ccache
       - name: Configure ccache
         run: |
           echo "CMAKE_C_COMPILER_LAUNCHER=ccache" >> $GITHUB_ENV
-          echo "CMAKE_CXX_COMPILER_LAUNCHER=ccache" >> $GITHUB_ENV
+          echo "CMAKE_CXX_COMPILER_LAUNCHER=ccache" >> $GITHUB_ENV          
 
-      # 4) Cache ccache
       - name: Cache ccache
         uses: actions/cache@v3
         with:
           path: ~/.ccache
           key: ccache-linux-${{ hashFiles('**/*.c', '**/*.cpp', '**/*.h', '**/CMakeLists.txt', '**/meson.build') }}
           restore-keys: |
-            ccache-linux-
+            ccache-linux-            
 
-      # 5) Cache SDL3 (Linux)
       - name: Cache SDL3 (Linux)
         uses: actions/cache@v3
         with:
           path: |
             sdl3
-            sdl3-build
+            sdl3-build            
           key: sdl3-linux-${{ hashFiles('sdl3/CMakeLists.txt') }}
 
-      # 6) Build SDL3 (Linux)
       - name: Build SDL3 (Linux)
         run: |
           if [ ! -d "sdl3/.git" ]; then
@@ -71,134 +62,61 @@ jobs:
             -DSDL_SHARED=ON \
             -DSDL_STATIC=OFF
           ninja
-          ninja install
+          ninja install          
 
-      # 7) Build Prosperon (Linux)
       - name: Build Prosperon (Linux)
         run: |
           export PKG_CONFIG_PATH="${PWD}/sdl3-build/installed_sdl3/lib/pkgconfig:$PKG_CONFIG_PATH"
           meson setup build_dbg -Dbuildtype=release -Db_lto=true -Db_ndebug=true
           meson compile -C build_dbg
 
-      # 8) Create minimal artifact folder (Linux)
       - name: Create artifact folder (Linux)
         run: |
           mkdir _pack
           cp build_dbg/prosperon _pack/
           # Adjust wildcard if there's a versioned libSDL3. e.g. libSDL3-0.600.0.so
-          cp sdl3-build/installed_sdl3/lib/libSDL3.so _pack/
+          cp sdl3-build/installed_sdl3/lib/libSDL3.so _pack/          
 
-      # 9) Upload artifact (Linux)
       - name: Upload Artifact (Linux)
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: prosperon-artifacts-linux
           path: _pack
 
-  # ===============================================================
-  #  MACOS BUILD (Using Homebrew SDL3)
-  # ===============================================================
-  build-macos:
-    runs-on: macos-latest
-    steps:
-      # 1) Check out code
-      - name: Check Out Code
-        uses: actions/checkout@v3
-
-      # 2) Install dependencies (SDL3 via Homebrew) + ccache
-      - name: Install Dependencies (macOS)
-        run: |
-          brew update
-          brew install sdl3 ccache ninja meson
-
-      # 3) Configure ccache
-      - name: Configure ccache
-        run: |
-          echo "CMAKE_C_COMPILER_LAUNCHER=ccache" >> $GITHUB_ENV
-          echo "CMAKE_CXX_COMPILER_LAUNCHER=ccache" >> $GITHUB_ENV
-
-      # 4) Cache ccache
-      - name: Cache ccache
-        uses: actions/cache@v3
-        with:
-          path: ~/Library/Caches/ccache
-          key: ccache-macos-${{ hashFiles('**/*.c', '**/*.cpp', '**/*.h', '**/CMakeLists.txt', '**/meson.build') }}
-          restore-keys: |
-            ccache-macos-
-
-      # 5) Build Prosperon (macOS) linking against Homebrew's SDL3
-      - name: Build Prosperon (macOS)
-        run: |
-          # Ensure pkg-config can find Homebrew's SDL3 .pc files
-          export PKG_CONFIG_PATH="$(brew --prefix sdl3)/lib/pkgconfig:$PKG_CONFIG_PATH"
-          meson setup build_macos -Dbuildtype=release -Db_lto=true -Db_ndebug=true
-          meson compile -C build_macos
-
-      # 6) Copy SDL3 .dylib from Homebrew for packaging
-      - name: Copy SDL3 library for packaging
-        run: |
-          SDL3_PREFIX=$(brew --prefix sdl3)
-          mkdir -p sdl3-macos
-          # Copy all versions of the SDL3 dynamic library
-          cp -a "${SDL3_PREFIX}/lib/libSDL3*.dylib" sdl3-macos/ || echo "No .dylib found, ignoring"
-
-      # 7) Create minimal artifact folder (macOS)
-      - name: Create artifact folder (macOS)
-        run: |
-          mkdir _pack
-          cp build_macos/prosperon _pack/
-          cp sdl3-macos/libSDL3*.dylib _pack/ || echo "No .dylib found, ignoring"
-
-      # 8) Upload artifact (macOS)
-      - name: Upload Artifact (macOS)
-        uses: actions/upload-artifact@v4
-        with:
-          name: prosperon-artifacts-macos
-          path: _pack
-
-  # ===============================================================
-  #  WINDOWS BUILD (Cross-compiling on Ubuntu)
-  # ===============================================================
   build-windows:
     runs-on: ubuntu-latest
     steps:
-      # 1) Check out code
       - name: Check Out Code
         uses: actions/checkout@v3
 
-      # 2) Install dependencies (MinGW, etc.) + ccache
       - name: Install Dependencies (Windows Cross)
         run: |
           sudo apt-get update
           sudo apt-get install -y \
             mingw-w64 cmake ninja-build git build-essential \
-            binutils pkg-config meson ccache
+            binutils pkg-config meson ccache          
 
-      # 3) Configure ccache for cross-compiler
       - name: Configure ccache
         run: |
           echo "CMAKE_C_COMPILER_LAUNCHER=ccache" >> $GITHUB_ENV
-          echo "CMAKE_CXX_COMPILER_LAUNCHER=ccache" >> $GITHUB_ENV
+          echo "CMAKE_CXX_COMPILER_LAUNCHER=ccache" >> $GITHUB_ENV          
 
-      # 4) Cache ccache
       - name: Cache ccache
         uses: actions/cache@v3
         with:
           path: ~/.ccache
           key: ccache-win-${{ hashFiles('**/*.c', '**/*.cpp', '**/*.h', '**/CMakeLists.txt', '**/meson.build') }}
           restore-keys: |
-            ccache-win-
+            ccache-win-            
 
-      # 5) Cache SDL3 (Windows cross)
       - name: Cache SDL3 (Windows cross)
         uses: actions/cache@v3
         with:
           path: |
             sdl3-win
-            sdl3-build-win
+            sdl3-build-win            
           key: sdl3-win-${{ hashFiles('sdl3-win/CMakeLists.txt') }}
 
-      # 6) Build SDL3 (Windows cross)
       - name: Build SDL3 (Windows cross)
         run: |
           if [ ! -d "sdl3-win/.git" ]; then
@@ -221,55 +139,44 @@ jobs:
             -DSDL_STATIC=OFF
           ninja
           ninja install
-
+          
-      # 7) Expose local SDL3 (Windows cross) for pkg-config
       - name: Configure PKG_CONFIG_PATH (Windows cross)
         run: |
-          echo "PKG_CONFIG_PATH=${GITHUB_WORKSPACE}/sdl3-build-win/installed_sdl3_win/lib/pkgconfig:$PKG_CONFIG_PATH" >> $GITHUB_ENV
+          echo "PKG_CONFIG_PATH=${GITHUB_WORKSPACE}/sdl3-build-win/installed_sdl3_win/lib/pkgconfig:$PKG_CONFIG_PATH" >> $GITHUB_ENV          
 
-      # 8) Build Prosperon (Windows cross)
       - name: Build Prosperon (Windows cross)
         run: |
           meson setup -Dbuildtype=release -Db_lto=true -Db_ndebug=true --cross-file mingw32.cross build_win
           meson compile -C build_win
 
-      # 9) Create minimal artifact folder (Windows)
       - name: Create package folder
         run: |
           mkdir _pack
           cp build_win/prosperon.exe _pack/
-          cp sdl3-build-win/installed_sdl3_win/bin/SDL3.dll _pack/
+          cp sdl3-build-win/installed_sdl3_win/bin/SDL3.dll _pack/          
 
-      # 10) Upload artifacts (Windows cross)
       - name: Upload Artifact (Windows cross)
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: prosperon-artifacts-windows
           path: _pack
 
 
   package-dist:
-    # This job depends on the three builds completing successfully.
+    needs: [build-linux, build-windows]
-    needs: [build-linux, build-macos, build-windows]
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
         uses: actions/checkout@v3
         
       - name: Download Linux Artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v3
         with:
           name: prosperon-artifacts-linux
           path: linux_artifacts
 
-      - name: Download macOS Artifacts
-        uses: actions/download-artifact@v4
-        with:
-          name: prosperon-artifacts-macos
-          path: macos_artifacts
-
       - name: Download Windows Artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v3
         with:
           name: prosperon-artifacts-windows
           path: windows_artifacts
@@ -284,18 +191,16 @@ jobs:
 
           # Make subdirectories for each platform
           mkdir dist/linux
-          mkdir dist/macos
           mkdir dist/win
 
           # -------------------
           # Copy artifacts in
           # -------------------
           cp linux_artifacts/* dist/linux/
-          cp macos_artifacts/* dist/macos/
+          cp windows_artifacts/* dist/win/          
-          cp windows_artifacts/* dist/win/
 
       - name: Upload Final Dist
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: prosperon
-          path: dist
+          path: dist

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+
+jobs:
+  # Example #1: Build Linux, run tests, but don't package
+  build-test-linux:
+    uses: ./.github/workflows/build.yml
+    with:
+      platform: linux
+      run-tests: false
+      package-dist: false
+
+  # Example #2: Build Windows, no tests, but package artifacts
+  build-package-windows:
+    uses: ./.github/workflows/build.yml
+    with:
+      platform: windows
+      run-tests: false
+      package-dist: false
+
+  # You can add more calls here for different combos of 
+  # (run-tests, package-dist), or do matrix expansions, etc.

.github/workflows/macbuild.yml

@@ -0,0 +1,64 @@
+name: Build
+
+jobs:
+  # ===============================================================
+  #  MACOS BUILD (Using Homebrew SDL3)
+  # ===============================================================
+  build-macos:
+    runs-on: macos-latest
+    continue-on-error: true
+    steps:
+      # 1) Check out code
+      - name: Check Out Code
+        uses: actions/checkout@v3
+  
+      # 2) Install dependencies (SDL3 via Homebrew) + ccache
+      - name: Install Dependencies (macOS)
+        run: |
+          brew update
+          brew install sdl3 meson ninja cmake ccache
+  
+      # 3) Configure ccache
+      - name: Configure ccache
+        run: |
+          echo "CMAKE_C_COMPILER_LAUNCHER=ccache" >> $GITHUB_ENV
+          echo "CMAKE_CXX_COMPILER_LAUNCHER=ccache" >> $GITHUB_ENV
+  
+      # 4) Cache ccache
+      - name: Cache ccache
+        uses: actions/cache@v3
+        with:
+          path: ~/Library/Caches/ccache
+          key: ccache-macos-${{ hashFiles('**/*.c', '**/*.cpp', '**/*.h', '**/CMakeLists.txt', '**/meson.build') }}
+          restore-keys: |
+            ccache-macos-
+  
+      # 5) Build Prosperon (macOS) linking against Homebrew's SDL3
+      - name: Build Prosperon (macOS)
+        run: |
+          # Ensure pkg-config can find Homebrew's SDL3 .pc files
+          export PKG_CONFIG_PATH="$(brew --prefix sdl3)/lib/pkgconfig:$PKG_CONFIG_PATH"
+          meson setup build_macos -Dbuildtype=release -Db_lto=true -Db_ndebug=true
+          meson compile -C build_macos
+  
+      # 6) Copy SDL3 .dylib from Homebrew for packaging
+      - name: Copy SDL3 library for packaging
+        run: |
+          SDL3_PREFIX=$(brew --prefix sdl3)
+          mkdir -p sdl3-macos
+          # Copy all versions of the SDL3 dynamic library
+          cp -a "${SDL3_PREFIX}/lib/libSDL3*.dylib" sdl3-macos/ || echo "No .dylib found, ignoring"
+  
+      # 7) Create minimal artifact folder (macOS)
+      - name: Create artifact folder (macOS)
+        run: |
+          mkdir _pack
+          cp build_macos/prosperon _pack/
+          cp sdl3-macos/libSDL3*.dylib _pack/ || echo "No .dylib found, ignoring"
+  
+      # 8) Upload artifact (macOS)
+      - name: Upload Artifact (macOS)
+        uses: actions/upload-artifact@v3
+        with:
+          name: prosperon-artifacts-macos
+          path: _pack

README.md

@@ -4,4 +4,6 @@ Provided are prosperon builds for all available platforms, including SDL3 for ea
 
 To get started, take a dive into the provided example games in the examples folder. Just copy the prosperon executable for your platform, along with its SDL3 library, into any provided example folder, then run it!
 
+NOTE: For MacOS, SDL3 must first be installed with homebrew. After installing homebrew, run `brew install sdl3`. This will be fixed in a future release!
+
 You can take a look through the docs folder for the prosperon manual to learn all about it. The manual is available on the web at [docs.prosperon.dev](https://docs.prosperon.dev).

docs/api/modules/doc.md

@@ -1,5 +1,38 @@
 # doc
 
+
+Provides a consistent way to create documentation for prosperon elements. Objects are documented by adding docstrings directly to object-like things (functions, objects, ...), or to an object's own "doc object".
+
+Docstrings are set to the symbol `prosperon.DOC`
+
+```js
+// Suppose we have a module that returns a function
+function greet(name) { console.log("Hello, " + name) }
+
+// We can attach a docstring
+greet.doc = `
+Greets the user by name.
+`
+
+// A single function is a valid return!
+return greet
+```
+
+```js
+// Another way is to add a docstring object to an object
+var greet = {
+hello() { console.log('hello!') }
+}
+
+greet[prosperon.DOC] = {}
+greet[prosperon.DOC][prosperon.DOC] = 'An object full of different greeter functions'
+greet[prosperon.DOC].hello = 'A greeter that says, "hello!"'
+```
+
+
+**name**: The name of the person to greet.
+
+
 ### writeDocFile(obj, title) <sub>function</sub>
 
 Return a markdown string for a given obj, with an optional title.