Brew formula

.github/workflows/brew.yaml

@@ -0,0 +1,98 @@
+# SPDX-FileCopyrightText: 2024 Duncan Greatwood
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# See:
+#   https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/choosing-the-runner-for-a-job
+#   https://github.com/actions/runner-images/blob/main/images/macos/macos-14-Readme.md
+
+name: Homebrew Formula
+
+on:
+  push:
+    branches:
+    - master
+  pull_request:
+    branches:
+    - master
+
+defaults:
+  run:
+    shell: sh
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  macos:
+    name: Homebrew Formula
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # Note: If you change the list of OS by adding a newer one,
+        # PLEASE UPDATE THE AUDIT PHASE to use the most recent macOS
+        # (See "runformula.sh --auditonly ..." later in this file)
+        os: [ 'macos-13', 'macos-14', 'macos-15' ]
+        compiler: [ 'clang' ]
+        sanitizer: [ 'none' ]
+        tls: [ 'true' ]
+        def_debug: [ 'false' ]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+        # Avoid doing "brew update" - the brew formulas that are
+        # preinstalled on the github runner image are likely
+        # consistent with the pre-installed software on the image. If
+        # we do "brew upate", and then install something new with
+        # brew, and the "something new" depends on pre-installed
+        # software on the image, and there are new versions of the
+        # pre-installed software revealed by doing "brew update", then
+        # when we install the "something new" brew may try and also
+        # install a new version of the pre-installed software on which
+        # the "something new" depends, but that attempt to install a
+        # new version of the pre-installed software can fail as a
+        # result of being blocked by the software that is already
+        # installed.
+
+    - uses: actions/checkout@v4
+      with:
+        submodules: true
+
+    - name: Test Homebrew
+      run: |
+        if [ ${{ matrix.compiler }} = gcc ]; then
+            gcc_lns=`brew list gcc | grep "bin/g++-[0-9][0-9]" | sort -r`
+            gcc_fstln=`echo "$gcc_lns" | head -1`
+            CXX=`basename $gcc_fstln`
+
+            gcc_lns=`brew list gcc | grep "bin/gcc-[0-9][0-9]" | sort -r`
+            gcc_fstln=`echo "$gcc_lns" | head -1`
+            CC=`basename $gcc_fstln`
+        else
+            CXX=clang++
+            CC=CXX
+        fi
+        export CXX
+        export CC
+        echo "CXX is $CXX; CC is $CC"
+
+        # This is a fine-grained personal access token restricted to a
+        # single repository and with all permissions left on "No
+        # Access". We set this token to avoid being blocked by the
+        # GitHub access rate limit for unauthenticated access
+        # (i.e. the rate limit for access with no token).
+        export HOMEBREW_GITHUB_API_TOKEN=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
+
+        homebrew/runformula.sh --skipaudit --force --HEAD
+        #   --skipaudit  Say "yes" to doing the brew audit
+        #   --force      Run even if pistache brew formula unchanged
+        #   --HEAD       Test with head of pistacheio/pistache master
+        #   branch
+
+        # if brew list pistache &>/dev/null; then brew remove pistache; fi
+        ## Use release (not HEAD), do audit (-y), and force even if pistache
+        ## formula unchanged
+        # homebrew/runformula.sh -y --force

.gitignore

@@ -73,5 +73,7 @@ repeatx86_*.sh
 !/subprojects/cpp-httplib
 !/subprojects/hinnant-date
 *.*~
+*.bak
+\#*\#
 
 /How To Run All Tests (README).txt

Building on macOS.txt

@@ -2,8 +2,8 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-Making Pistache on macOS
-========================
+Pistache on macOS
+=================
 
 Apple's clang compiler must be installed. It comes as part of
 Xcode. If not already installed, at terminal command line do:
@@ -13,7 +13,22 @@ Homebrew (also known as "brew") is required. If not already installed,
 follow the Homebrew instructions to install:
   In your browser: https://brew.sh/
 
-Then, install the necessary brew packages via terminal command line:
+The simplest way to install Pistache on macOS is to use brew. For the
+latest version of Pistache, do:
+  brew install --HEAD pistache
+For the most recent officially designated release, do:
+  brew install pistache
+We normally suggest using the most recent ("HEAD") Pistache version.
+In case of difficultly, please see later Troubleshooting note.
+
+
+Building Pistache from Source on macOS
+======================================
+
+If you prefer not to install with brew, Pistache can be built from
+source.
+
+Install the necessary brew packages via terminal command line:
   brew install meson
   brew install doxygen
   brew install googletest (skip this if installing with gcc - see later)
@@ -33,24 +48,70 @@ To test:
 To install:
   bldscripts/mesinstall.sh
 
-The meaning of each convenience script is as follows:
-  mesbuild.sh - build release version using meson
-  mestest.sh - test release version using meson
-  mesinstall.sh - install release version using meson
+See later section for more details on teh conveinence scripts.
+
+
+Troubleshooting brew install on Intel Macs
+------------------------------------------
+
+On some Intel-based MACs, when installing Pistache with brew you may
+see errors like:
+    ==> meson setup build ...
+    Traceback (most recent call last):
+      File "/usr/local/opt/meson/bin/meson", line 5, in <module>
+        from mesonbuild.mesonmain import main
+    ModuleNotFoundError: No module named 'mesonbuild'
+    ...
+    Error: Testing requires the latest version of pistache
+
+This a problem installing Python3, a dependency of meson. We found it
+could be fixed by:
+  sudo mkdir /usr/local/Frameworks
+  sudo chown <your-user-name> /usr/local/Frameworks
+  (Substituting your own macOS username for <your-user-name>)
+NB: This applies solely to Intel-based Macs. Homebrew uses a different
+location for files on Apple-silicon("M")/Arm-based MACs.
+
+
+Building with GCC
+-----------------
+
+By default, Pistache on macOS builds with clang, which is the default
+Apple compiler. If you prefer to use gcc, you can utilize the
+gccmacsetup.sh script provided by Pistache before doing the build,
+like this:
+  source bldscripts/gccmacsetup.sh
+  bldscripts/mesbuild.sh
+  bldscripts/mestest.sh
+  bldscripts/mesinstall.sh
+
+
+Convenience Scripts
+-------------------
+
+The following scripts cna be used in any environment except
+Windows. The meaning of each convenience script is as follows:
+  mesbuild.sh - build release version
+  mestest.sh - test release version
+  mesinstall.sh - install release version
 
-  mesbuilddebug.sh - build debug version using meson
+  mesbuilddebug.sh - build debug version
   mestestdebug.sh - test debug version with meson
-  mesinstalldebug.sh - install debug version using meson
+  mesinstalldebug.sh - install debug version
 
-  mesbuildflibev.sh - build version using meson forcing libevnet use
-  mestestflibev.sh - test version using meson with libevnet use
-  mesinstallflibev.sh - install version using meson with libevnet use
+Linux-only scripts. Note - all environments except Linux use libevent
+by default. libevent is optional on Linux:
+  mesbuildflibev.sh - build version forcing libevent use
+  mestestflibev.sh - test version with libevent use
+  mesinstallflibev.sh - install version with libevent use
 
-  mesbuildflibevdebug.sh - build debug ver using meson forcing libevnet use
-  mestestflibevdebug.sh - test debug ver using meson with libevnet use
-  mesinstallflibevdebug.sh - install debug ver using meson with libevnet use
+  mesbuildflibevdebug.sh - build debug version forcing libevent use
+  mestestflibevdebug.sh - test debug version with libevent use
+  mesinstallflibevdebug.sh - install debug version with libevent use
 
+Also:
   clean.sh - remove build directories
+  gccmacsetup.sh - configure for GCC build on macOS
 
 
 Building with GCC

README.md

@@ -81,6 +81,10 @@ If you have no need to modify the Pistache source, you are strongly recommended
 
 Pistache is available in the official repositories since Debian 12 and Ubuntu 23.10, under the package name `libpistache-dev`.
 
+### macOS
+
+Pistache can be installed using the Homebrew package manager. See *Building on macOS.txt* for specifics.
+
 #### Supported Architectures
 
 Currently Pistache is built and tested on a number of [architectures](https://wiki.debian.org/SupportedArchitectures). Some of these are suitable for desktop or server use and others for embedded environments. As of this writing we do not currently have any MIPS related packages that have been either built or tested.
@@ -93,7 +97,7 @@ Currently Pistache is built and tested on a number of [architectures](https://wi
 - riscv64
 - s390x
 
-#### Ubuntu PPA (Unstable)
+### Ubuntu PPA (Unstable)
 
 The project builds [daily unstable snapshots](https://launchpad.net/~pistache+team/+archive/ubuntu/unstable) in a separate unstable PPA. To use it, run the following:
 
@@ -103,9 +107,9 @@ $ sudo apt update
 $ sudo apt install libpistache-dev
 ```
 
-#### Ubuntu PPA (Stable)
+### Ubuntu PPA (Stable)
 
-Currently there are no stable release of Pistache published into the [stable](https://launchpad.net/~pistache+team/+archive/ubuntu/stable) PPA. However, when that time comes, run the following to install a stable package:
+From time to time, the project transfers release packages into the [stable](https://launchpad.net/~pistache+team/+archive/ubuntu/stable) PPA. Run the following to install a stable package:
 
 ```sh
 $ sudo add-apt-repository ppa:pistache+team/stable
@@ -205,8 +209,7 @@ To download the latest available release, clone the repository over GitHub.
 $ git clone https://github.com/pistacheio/pistache.git
 ```
 
-To build for macOS, you can follow the instructions in:
-    *Building on macOS.txt*
+To build on macOS, Windows, or BSD, see the respective files *Building on macOS.txt*, *Building on Windows.txt* or *Building on BSD.txt*.
 
 Continuing the Linux instructions: