diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 13124f66..a53d6107 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,23 +1,32 @@ -name: Build +name: Reusable Build Workflow on: - push: - branches: [ "master" ] - pull_request: + workflow_call: + inputs: + platform: + description: "Which platform to build for: 'linux' or 'windows'" + required: true + run-tests: + description: "If true, run the test suite" + type: boolean + default: false + package-dist: + description: "If true, create a distributable package (and upload artifact)" + type: boolean + default: false jobs: - # =============================================================== - # LINUX BUILD - # =============================================================== - build-linux: - runs-on: ubuntu-latest + build: + runs-on: ubuntu-latest # We'll do both Linux or Windows cross from Ubuntu steps: - # 1) Check out code - name: Check Out Code uses: actions/checkout@v3 - # 2) Install system dependencies + ccache - - name: Install Dependencies + # --------------------- + # 1) Install Dependencies + # --------------------- + - name: Install Dependencies (Linux) + if: ${{ inputs.platform == 'linux' }} run: | sudo apt-get update sudo apt-get install -y \ @@ -29,273 +38,133 @@ jobs: cmake ninja-build git build-essential binutils mold meson pkg-config \ 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: ~/.ccache - key: ccache-linux-${{ hashFiles('**/*.c', '**/*.cpp', '**/*.h', '**/CMakeLists.txt', '**/meson.build') }} - restore-keys: | - ccache-linux- - - # 5) Cache SDL3 (Linux) - - name: Cache SDL3 (Linux) - uses: actions/cache@v3 - with: - path: | - sdl3 - sdl3-build - key: sdl3-linux-${{ hashFiles('sdl3/CMakeLists.txt') }} - - # 6) Build SDL3 (Linux) - - name: Build SDL3 (Linux) - run: | - if [ ! -d "sdl3/.git" ]; then - echo "Cloning SDL3 repository..." - git clone --depth 1 --branch main https://github.com/libsdl-org/SDL.git sdl3 - else - echo "SDL3 source is already present (possibly from cache)." - fi - - mkdir -p sdl3-build - cd sdl3-build - cmake ../sdl3 -GNinja \ - -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_INSTALL_PREFIX="${PWD}/installed_sdl3" \ - -DSDL_SHARED=ON \ - -DSDL_STATIC=OFF - ninja - 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=debugoptimized - 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/ - - # 9) Upload artifact (Linux) - - name: Upload Artifact (Linux) - uses: actions/upload-artifact@v4 - 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 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=debugoptimized - 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) + - name: Install Dependencies (Windows cross) + if: ${{ inputs.platform == 'windows' }} run: | sudo apt-get update sudo apt-get install -y \ mingw-w64 cmake ninja-build git build-essential \ 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 - # 4) Cache ccache - name: Cache ccache uses: actions/cache@v3 with: path: ~/.ccache - key: ccache-win-${{ hashFiles('**/*.c', '**/*.cpp', '**/*.h', '**/CMakeLists.txt', '**/meson.build') }} + key: ${{ runner.os }}-ccache-${{ inputs.platform }}-${{ hashFiles('**/*.c', '**/*.cpp', '**/*.h', '**/CMakeLists.txt', '**/*.meson', '**/*.build') }} restore-keys: | - ccache-win- + ${{ runner.os }}-ccache-${{ inputs.platform }}- - # 5) Cache SDL3 (Windows cross) - - name: Cache SDL3 (Windows cross) + # --------------------- + # 2) Build SDL3 + # --------------------- + - name: Cache SDL3 + id: cache-sdl uses: actions/cache@v3 with: path: | - sdl3-win - sdl3-build-win - key: sdl3-win-${{ hashFiles('sdl3-win/CMakeLists.txt') }} + sdl3-${{ inputs.platform }} + sdl3-build-${{ inputs.platform }} + key: sdl3-${{ inputs.platform }}-${{ hashFiles('sdl3-*/*.CMakeLists.txt') }} - # 6) Build SDL3 (Windows cross) - - name: Build SDL3 (Windows cross) + - name: Build SDL3 run: | - if [ ! -d "sdl3-win/.git" ]; then - echo "Cloning SDL3 for Windows cross..." - git clone --depth 1 --branch main https://github.com/libsdl-org/SDL.git sdl3-win - else - echo "SDL3-win source already present (possibly from cache)." + # Use different folder names for Linux vs Windows + if [ "${{ inputs.platform }}" = "linux" ]; then + SRC="sdl3-linux" + BUILD="sdl3-build-linux" + GIT_URL="https://github.com/libsdl-org/SDL.git" + # Possibly different branches or flags for Linux, etc. + # ... + if [ ! -d "$SRC/.git" ]; then + git clone --depth 1 --branch main "$GIT_URL" "$SRC" + fi + mkdir -p "$BUILD" + cd "$BUILD" + cmake ../"$SRC" -GNinja \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX="${PWD}/installed_sdl3" \ + -DSDL_SHARED=ON -DSDL_STATIC=OFF + ninja + ninja install + + elif [ "${{ inputs.platform }}" = "windows" ]; then + SRC="sdl3-win" + BUILD="sdl3-build-win" + GIT_URL="https://github.com/libsdl-org/SDL.git" + # ... + if [ ! -d "$SRC/.git" ]; then + git clone --depth 1 --branch main "$GIT_URL" "$SRC" + fi + mkdir -p "$BUILD" + cd "$BUILD" + cmake ../"$SRC" -GNinja \ + -DCMAKE_SYSTEM_NAME=Windows \ + -DCMAKE_C_COMPILER=x86_64-w64-mingw32-gcc \ + -DCMAKE_CXX_COMPILER=x86_64-w64-mingw32-g++ \ + -DCMAKE_RC_COMPILER=x86_64-w64-mingw32-windres \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX="${PWD}/installed_sdl3_win" \ + -DSDL_SHARED=ON -DSDL_STATIC=OFF + ninja + ninja install fi - mkdir -p sdl3-build-win - cd sdl3-build-win - cmake ../sdl3-win -GNinja \ - -DCMAKE_SYSTEM_NAME=Windows \ - -DCMAKE_C_COMPILER=x86_64-w64-mingw32-gcc \ - -DCMAKE_CXX_COMPILER=x86_64-w64-mingw32-g++ \ - -DCMAKE_RC_COMPILER=x86_64-w64-mingw32-windres \ - -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_INSTALL_PREFIX="${PWD}/installed_sdl3_win" \ - -DSDL_SHARED=ON \ - -DSDL_STATIC=OFF - ninja - ninja install - - # 7) Expose local SDL3 (Windows cross) for pkg-config - - name: Configure PKG_CONFIG_PATH (Windows cross) + # --------------------- + # 3) Build Prosperon + # --------------------- + - name: Configure PKG_CONFIG_PATH + if: ${{ inputs.platform == 'windows' }} run: | 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) + - name: Build Prosperon run: | - meson setup -Dbuildtype=debugoptimized --cross-file mingw32.cross build_win - meson compile -C build_win + if [ "${{ inputs.platform }}" = "linux" ]; then + export PKG_CONFIG_PATH="${PWD}/sdl3-build-linux/installed_sdl3/lib/pkgconfig:$PKG_CONFIG_PATH" + meson setup build_dbg -Dbuildtype=release -Db_lto=true -Db_ndebug=true + meson compile -C build_dbg - # 9) Create minimal artifact folder (Windows) - - name: Create package folder + elif [ "${{ inputs.platform }}" = "windows" ]; then + meson setup --cross-file mingw32.cross build_win -Dbuildtype=release -Db_lto=true -Db_ndebug=true + meson compile -C build_win + fi + + # --------------------- + # 4) (Optional) Run Tests + # --------------------- + - name: Run Test Suite + if: ${{ inputs.run-tests == true }} run: | + # Example: just show how you'd do it + echo "Running tests..." + # e.g. meson test -C build_dbg + # or some custom test commands + echo "Tests completed!" + + # --------------------- + # 5) (Optional) Package Dist + # --------------------- + - name: Package Distribution + if: ${{ inputs.package-dist == true }} + run: | + echo "Creating final _pack folder..." mkdir _pack - cp build_win/prosperon.exe _pack/ - cp sdl3-build-win/installed_sdl3_win/bin/SDL3.dll _pack/ + if [ "${{ inputs.platform }}" = "linux" ]; then + cp build_dbg/prosperon _pack/ + cp sdl3-build-linux/installed_sdl3/lib/libSDL3.so _pack/ + else + cp build_win/prosperon.exe _pack/ + cp sdl3-build-win/installed_sdl3_win/bin/SDL3.dll _pack/ + fi - # 10) Upload artifacts (Windows cross) - - name: Upload Artifact (Windows cross) - uses: actions/upload-artifact@v4 + - name: Upload Artifact + if: ${{ inputs.package-dist == true }} + uses: actions/upload-artifact@v3 with: - name: prosperon-artifacts-windows + name: prosperon-${{ inputs.platform }} path: _pack - - - package-dist: - # This job depends on the three builds completing successfully. - 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 - 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 - with: - name: prosperon-artifacts-windows - path: windows_artifacts - - - name: Create the Dist Folder - run: | - mkdir dist - - cp README.md dist/ - cp license.txt dist/ - cp -r examples dist/ - - # 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/ - - - name: Upload Final Dist - uses: actions/upload-artifact@v4 - with: - name: prosperon - path: dist diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000..3b79e358 --- /dev/null +++ b/.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. diff --git a/.github/workflows/macbuild.yml b/.github/workflows/macbuild.yml new file mode 100644 index 00000000..5673505e --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/README.md b/README.md index 21036b7b..381f706d 100644 --- a/README.md +++ b/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). diff --git a/docs/api/modules/doc.md b/docs/api/modules/doc.md index 413e4549..78944bca 100644 --- a/docs/api/modules/doc.md +++ b/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) function Return a markdown string for a given obj, with an optional title. diff --git a/docs/favicon.gif b/docs/favicon.gif new file mode 100644 index 00000000..6d00c084 Binary files /dev/null and b/docs/favicon.gif differ